diff --git a/plugins/compound-engineering/skills/ce-design/SKILL.md b/plugins/compound-engineering/skills/ce-design/SKILL.md new file mode 100644 index 00000000..7fa29add --- /dev/null +++ b/plugins/compound-engineering/skills/ce-design/SKILL.md @@ -0,0 +1,271 @@ +--- +name: ce:design +description: "Design frontend screens visually before implementation using available design tools (Paper, Pencil, Figma, Sketch, Penpot). Use between /ce:plan and /ce:work for any feature with UI, or when asked to design screens, create mockups, or get visual approval before building." +argument-hint: "[plan file path or feature description]" +--- + +# Design Frontend Screens + +## Quick Start + +Invoke with `/ce:design [plan-file-or-description]` between `/ce:plan` and `/ce:work`. Creates visual designs for user approval before implementation begins. Skip entirely for backend-only work. + +## Instructions + +### Input + + #$ARGUMENTS + +**If the input is empty**, use the native file-search/glob tool (e.g., Glob in Claude Code) to find recent plans matching `docs/plans/*-plan.md`. Ask which plan to design for, or what screens to design. + +Do not proceed until a feature description or plan reference is available. + +### Phase 0: Resume and Detect + +#### 0.1 Resume Existing Design Work + +Check for existing design artifacts related to the feature: +- Artboards in an open Paper document +- Open `.pen` file in Pencil +- Figma frames referenced in the plan +- Screenshots or exports in the project + +If prior design work exists, confirm: "Found existing designs for [topic]. Continue from these, or start fresh?" + +#### 0.2 Detect Available Design Tools + +Probe for available design MCP tools at runtime, in priority order: + +1. **Paper** -- Call `get_basic_info`. If it responds, Paper is available. +2. **Pencil** -- Call `get_editor_state`. If it responds, Pencil is available. +3. **Figma (Official)** -- Check for Figma MCP tools (e.g., `get_figma_data`). If present, official Figma MCP is available. +4. **Figma (Framelink)** -- Check for `get_file` tool from figma-context-mcp. If present, Framelink is available. +5. **Sketch** -- Check for `get_selection_as_image` tool. If present, Sketch MCP is available. +6. **Penpot** -- Check for Penpot MCP tools. If present, Penpot is available. + +Probe tools silently. Do not display errors from unavailable tools. + +#### 0.3 Select Design Tool + +**If one tool detected:** Use it. Announce: "Using [tool name] for design." + +**If multiple tools detected:** Ask using the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise present numbered options and wait for the user's reply. + +**Question:** "Multiple design tools available. Which to use?" +- List each detected tool with a one-line capability summary + +**If no tools detected:** Present fallback options: +1. **Text wireframes** -- Create ASCII/markdown wireframes for discussion +2. **Help set up a design tool** -- Guide through connecting Paper, Pencil, or another tool +3. **Skip to implementation** -- Proceed directly to `/ce:work` + +#### 0.4 Load Tool-Specific Workflow + +Load the corresponding reference file for the selected tool: + +| Tool | Reference | +|------|-----------| +| Paper | [paper-workflow.md](references/paper-workflow.md) | +| Pencil | [pencil-workflow.md](references/pencil-workflow.md) | +| Figma | [figma-workflow.md](references/figma-workflow.md) | +| Sketch | [sketch-workflow.md](references/sketch-workflow.md) | +| Penpot | [penpot-workflow.md](references/penpot-workflow.md) | + +Follow the loaded workflow for all tool-specific operations in subsequent phases. + +### Phase 1: Understand What to Design + +#### 1.1 Extract UI Requirements + +Read the plan or feature description. Extract: +- UI screens or views mentioned +- User flows described +- Components or layouts referenced +- Visual requirements or inspiration mentioned +- Target viewport (desktop 1440px, tablet, mobile 375px) + +#### 1.2 Confirm Screen List + +Present the screens to design: + +> "Based on the plan, I'll design these screens: [list]" +> "Does this look right? Any screens to add or skip?" + +Use the platform's blocking question tool when available. Otherwise present the list and wait for confirmation. + +#### 1.3 Gather Design References + +Ask once: "Do you have any references -- URLs, screenshots, or existing designs to draw from? Or should I start fresh based on the plan?" + +Accept any of these formats: +- **URLs** -- Figma links, live websites, Dribbble/Behance for inspiration. Fetch via web tools when available. +- **Image files** -- Screenshots, mockups, mood boards. Read via the native file-read tool (e.g., Read in Claude Code). +- **Existing designs** -- "Look at the current Figma file" or "use the open .pen file". Read via the detected design tool's MCP. +- **Text descriptions** -- "Like Stripe's dashboard" or "minimalist, dark mode". Incorporate into the design brief. +- **Nothing** -- Proceed from the plan's requirements alone. + +#### 1.4 Get Design Context + +If not already clear from the plan and references, clarify: +- App type (web app, mobile app, landing page, dashboard) +- Existing design system or style preferences +- Target viewport dimensions + +### Phase 2: Design Brief + +#### 2.1 Generate Brief + +Before any design work, generate a short design brief: +- **Color palette** -- 5-6 hex values with roles (background, surface, text, accent, muted, border) +- **Type choices** -- Font family, weight scale, size scale +- **Spacing rhythm** -- Section, group, and element gaps +- **Visual direction** -- One sentence describing the aesthetic + +#### 2.2 Share for Approval + +Present the brief to the user. Do not begin designing until the brief is approved or adjusted. + +If available, load the `frontend-design` skill and apply its aesthetic principles to strengthen the brief. + +### Phase 3: Create Designs + +Follow the tool-specific workflow loaded in Phase 0.4. The general pattern across all tools: + +#### 3.1 Set Up Canvas + +Create the artboard, frame, or file for each screen at the appropriate dimensions. + +#### 3.2 Design Incrementally + +Build each screen piece by piece -- one visual group at a time (a header, a card, a list row, a button group). Never batch an entire screen into a single operation. + +Use realistic content: actual labels, representative data, and copy that matches the feature. + +#### 3.3 Self-Review Checkpoints (Mandatory) + +After every 2-3 modifications, take a screenshot and evaluate: +- **Spacing** -- Uneven gaps, cramped groups, or areas that feel unintentionally empty? +- **Typography** -- Text too small, poor line-height, weak heading/body hierarchy? +- **Contrast** -- Low contrast text, elements blending into backgrounds? +- **Alignment** -- Elements that should share a vertical or horizontal lane but do not? +- **Clipping** -- Content cut off at container or artboard edges? + +Summarize each checkpoint into a one-line verdict. Fix issues before continuing. + +#### 3.4 Finish Each Screen + +Signal completion to the design tool (e.g., `finish_working_on_nodes` in Paper). Move to the next screen. + +### Phase 4: Review and Approve + +#### 4.1 Summarize + +Describe what was designed and the key decisions: + +> "Designs ready. Created [N] screens: +> - [Screen 1] -- [brief description of layout and visual approach] +> - [Screen 2] -- [brief description] +> +> Take a look and let me know how to proceed." + +#### 4.2 Present Options + +Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise present numbered options and wait for the user's reply. + +**Question:** "Review the designs. How would you like to proceed?" + +**Options:** +1. **Approved -- proceed to `/ce:work`** -- Designs look good, start building +2. **Changes needed** -- Describe what to change +3. **Redesign screen(s)** -- Specify which screens need a fresh take +4. **Share for review** -- Export or share designs for collaborative feedback +5. **Skip designs -- just build it** -- Abandon design review, go straight to code +6. **Save and pause** -- Keep designs for later + +#### 4.3 Handle Selected Option + +**Approved:** Proceed to Phase 6 (Handoff). + +**Changes needed:** Proceed to Phase 5 (Iterate). + +**Redesign screen(s):** Return to Phase 3 for the specified screens, keeping the design brief. + +**Share for review:** Export screenshots or generate a shareable link using available tools (Proof, Figma sharing, file export). Then return to the approval options. + +**Skip designs:** Proceed directly to handoff, noting that designs were skipped. + +**Save and pause:** Note the current state in the plan file and end the workflow. + +### Phase 5: Iterate + +When changes are requested: + +1. Read the feedback carefully +2. Check if the user has selected or highlighted specific elements in the design tool +3. Apply changes using the tool-specific workflow +4. Take a screenshot to verify the changes +5. Signal completion for modified elements +6. Return to Phase 4 (Review and Approve) + +Keep iterations fast. Small changes should appear quickly. + +### Phase 6: Handoff + +#### 6.1 Export Reference Artifacts + +Capture final screenshots or exports of approved designs for reference during implementation. + +#### 6.2 Update Plan File + +Add a design section to the plan file: + +```markdown +## Design +- **Status:** Approved +- **Tool:** [Paper / Pencil / Figma / Sketch / Penpot] +- **Screens:** [list of designed screens] +- **Key decisions:** [notable visual choices] +``` + +#### 6.3 Note Integration Points + +During `/ce:work`, these existing agents can verify implementation fidelity: +- `compound-engineering:design:design-implementation-reviewer` -- Compare implementation against designs +- `compound-engineering:design:figma-design-sync` -- Sync Figma designs to implementation (Figma users) +- `compound-engineering:design:design-iterator` -- Iteratively polish designs through screenshot-analyze-improve cycles + +#### 6.4 Suggest Next Step + +"Designs approved. Run `/ce:work [plan-file]` to start implementation." + +## When to Skip + +- Backend-only work (APIs, data processing, infrastructure) +- Trivial UI changes (copy updates, color tweaks) +- Existing design system with no new screens needed +- User explicitly says to skip design review + +## Success Criteria + +- User has reviewed and approved visual designs before implementation begins +- Plan file updated with design status and tool used +- Reference artifacts available for `/ce:work` implementation + +## Key Principles + +- **Live feedback** -- Where possible, the user watches designs appear in real-time +- **Design brief first** -- Catch misalignment before touching the canvas +- **Incremental creation** -- Small writes, frequent self-review +- **User decides** -- Never skip the approval step +- **Tool-agnostic core** -- All tool-specific logic lives in reference files +- **Realistic content** -- Use real labels and representative data, not lorem ipsum + +## Reference Files + +| File | Purpose | +|------|---------| +| [paper-workflow.md](references/paper-workflow.md) | Paper MCP design workflow (live HTML canvas) | +| [pencil-workflow.md](references/pencil-workflow.md) | Pencil MCP design workflow (.pen vector design) | +| [figma-workflow.md](references/figma-workflow.md) | Figma MCP workflows (official + Framelink) | +| [sketch-workflow.md](references/sketch-workflow.md) | Sketch MCP design workflow (macOS native) | +| [penpot-workflow.md](references/penpot-workflow.md) | Penpot MCP design workflow (open-source, design-as-code) | diff --git a/plugins/compound-engineering/skills/ce-design/references/figma-workflow.md b/plugins/compound-engineering/skills/ce-design/references/figma-workflow.md new file mode 100644 index 00000000..5c9956f1 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-design/references/figma-workflow.md @@ -0,0 +1,61 @@ +# Figma MCP Design Workflow + +Figma integration works through two possible MCP connections, each with different capabilities. The workflow adapts based on which is available. + +## Tool Detection + +**Official Figma MCP** -- Provides design reading, component extraction, and Code-to-Canvas capabilities. Detected by presence of Figma MCP tools like `get_figma_data`. + +**Framelink (figma-context-mcp)** -- Provides simplified design extraction for implementation. Detected by presence of `get_file` tool. Read-only. + +Both can be available simultaneously. Official Figma MCP takes priority for creation workflows. + +## Official Figma MCP Workflow + +### Reading Designs + +1. Extract design data from Figma files -- components, styles, layout, spacing +2. Use extracted data to inform the design brief and implementation +3. Read specific frames or components for reference + +### Code-to-Canvas (When Available) + +If Code-to-Canvas is supported: +1. Build the design as HTML/CSS locally or in another tool +2. Capture screenshots of the implementation +3. Push the captured design back to Figma for review and collaboration + +This enables a round-trip: Figma design context informs code, and code results can be pushed back for team review. + +### Design Tokens + +Extract design tokens (colors, typography, spacing) from Figma files to maintain consistency between design and implementation. + +## Framelink Workflow + +### Extracting Design Context + +1. Call `get_file` with the Figma file URL to get a simplified design representation +2. Call `get_images` to extract specific frame or component images +3. Use the extracted data as reference for the design brief + +### Working with Figma Links + +When the user provides a Figma URL: +1. Parse the file key and node IDs from the URL +2. Extract relevant frames and components +3. Use as visual reference for new designs or implementation + +## Integration with Existing Agents + +After designs are created (in Figma or any other tool): + +- `compound-engineering:design:figma-design-sync` can sync Figma designs to implementation code during `/ce:work` +- `compound-engineering:design:design-implementation-reviewer` can compare live implementation against Figma designs + +## Key Advantages + +- **Team collaboration** -- Figma's native sharing and commenting for design review +- **Design system access** -- Read existing components, tokens, and styles +- **Round-trip capability** -- Code-to-Canvas bridges the design-code gap +- **Wide adoption** -- Most design teams already use Figma diff --git a/plugins/compound-engineering/skills/ce-design/references/paper-workflow.md b/plugins/compound-engineering/skills/ce-design/references/paper-workflow.md new file mode 100644 index 00000000..8113dd53 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-design/references/paper-workflow.md @@ -0,0 +1,76 @@ +# Paper MCP Design Workflow + +Paper is a professional design tool with a live HTML canvas. Designs render in real-time as HTML/CSS, making them directly translatable to implementation code. The user watches designs appear element by element. + +## Setup + +1. Call `get_basic_info` to understand file structure, loaded fonts, and existing artboards +2. Note artboard dimensions to determine if designs are for mobile (375px), tablet, or desktop (1440px) +3. Call `get_selection` to see what the user is focused on (if anything) +4. Call `get_font_family_info` to confirm available fonts before writing styles -- this is mandatory before first use of typographic styles + +## Creating Designs + +### Create Artboard + +Use `create_artboard` with appropriate dimensions for the target viewport. + +### Write HTML Incrementally + +Each `write_html` call adds roughly ONE visual group: +- A header section +- A single list or table row +- A card shell +- A button group +- A footer + +Never batch an entire component or screen into one call. A card with a header, 4 rows, and a footer is 6+ separate `write_html` calls. + +### Self-Review Checkpoints + +After every 2-3 `write_html` calls, take a screenshot with `get_screenshot` (default 1x scale is sufficient for layout verification; use scale=2 only for reading small text). + +Evaluate against the review checklist: +- **Spacing** -- Uneven gaps, cramped groups, or areas that feel unintentionally empty? +- **Typography** -- Text too small to read, poor line-height, weak hierarchy? +- **Contrast** -- Low contrast text, elements blending into backgrounds? +- **Alignment** -- Elements that should share a vertical or horizontal lane but do not? +- **Clipping** -- Content cut off at edges? If content overflows, use `update_styles` to set the overflowing dimension to "fit-content" + +Summarize each checkpoint into a one-line verdict. Fix found issues before moving on. + +### Typographic Units + +- Use "px" for font sizes +- Use "em" for letter spacing +- Use "px" for line height (relative units acceptable if they do not produce subpixel sizes) + +### Finishing + +Call `finish_working_on_nodes` when done with each screen. This is mandatory. + +## Editing Existing Designs + +Use `get_tree_summary` to understand artboard structure, `get_node_info` to inspect specific nodes, and `get_children` to list direct children. + +Modify with: +- `write_html` -- Add new elements +- `update_styles` -- Change CSS properties +- `set_text_content` -- Update text +- `delete_nodes` -- Remove elements +- `duplicate_nodes` -- Clone and modify (efficient for repeated elements) + +Always call `finish_working_on_nodes` when done editing. + +## Extracting Code + +Use `get_jsx` to extract component structure. Each element has an `id` attribute for targeting specific nodes. + +Use `get_computed_styles` for precise CSS values (supports batching multiple nodeIds). + +## Key Advantages + +- **Live canvas** -- User watches designs appear in real-time +- **HTML/CSS native** -- Designs translate directly to implementation code +- **No export cycle** -- Designs are immediately visible on canvas, no screenshot/upload needed +- **Realistic rendering** -- Real browser rendering engine, not simulated diff --git a/plugins/compound-engineering/skills/ce-design/references/pencil-workflow.md b/plugins/compound-engineering/skills/ce-design/references/pencil-workflow.md new file mode 100644 index 00000000..050658cf --- /dev/null +++ b/plugins/compound-engineering/skills/ce-design/references/pencil-workflow.md @@ -0,0 +1,57 @@ +# Pencil MCP Design Workflow + +Pencil is a professional vector design tool. Its `.pen` files are encrypted and accessible only through Pencil MCP tools -- never use file-read or content-search tools on `.pen` files directly. + +## Setup + +1. Call `get_editor_state` to determine the currently active `.pen` file and user selection +2. If no file is open, call `open_document` with `"new"` to create an empty `.pen` file, or pass a specific file path +3. Call `get_guidelines` with the relevant topic (`web-app`, `mobile-app`, `landing-page`, `design-system`, `table`, `slides`) for design rules +4. Call `get_style_guide_tags` then `get_style_guide` to get design inspiration and a style system to follow + +## Creating Designs + +### Find Placement + +Call `find_empty_space_on_canvas` to determine where to place new designs without overlapping existing work. + +### Build with batch_design + +Use `batch_design` to execute insert, copy, update, replace, move, delete, and image operations. Each call supports up to 25 operations -- enough for meaningful progress without overwhelming the system. + +Operation syntax (each line is a single operation): +- `foo=I("parent", { ... })` -- Insert +- `baz=C("nodeid", "parent", { ... })` -- Copy +- `foo2=R("nodeid1/nodeid2", { ... })` -- Replace +- `U(foo+"/nodeid", { ... })` -- Update +- `D("dfFAeg2")` -- Delete +- `M("nodeid3", "parent", 2)` -- Move +- `G("baz", "ai", "...")` -- Generate image + +### Self-Review Checkpoints + +After every 2-3 batches of modifications, call `get_screenshot` to visually validate the design. + +Use `snapshot_layout` to examine computed layout rectangles and verify element positioning. + +### Variables and Themes + +Use `get_variables` to read current design tokens and themes. Use `set_variables` to add or update variables for consistent theming. + +## Editing Existing Designs + +1. Use `batch_get` with patterns or node IDs to discover and understand existing content +2. Use `search_all_unique_properties` to find all property values within a subtree +3. Use `replace_all_matching_properties` for bulk property updates (e.g., retheming) +4. Modify with `batch_design` operations (update, replace, delete, move) + +## Exporting + +Use `export_nodes` to export designs as PNG, JPEG, WEBP, or PDF for handoff artifacts and reference screenshots. + +## Key Advantages + +- **Professional vector design** -- Full-featured design tool with variables, themes, and components +- **Batch operations** -- Efficient multi-operation calls for fast design creation +- **Design tokens** -- Built-in variable and theme system for consistent design systems +- **Multiple export formats** -- PNG, JPEG, WEBP, PDF for various handoff needs diff --git a/plugins/compound-engineering/skills/ce-design/references/penpot-workflow.md b/plugins/compound-engineering/skills/ce-design/references/penpot-workflow.md new file mode 100644 index 00000000..c6986333 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-design/references/penpot-workflow.md @@ -0,0 +1,62 @@ +# Penpot MCP Design Workflow + +Penpot is an open-source design platform with a design-as-code philosophy. It supports multi-directional workflows: design informs code, and code informs design. Self-hostable with no paywalls. + +## Setup + +1. Verify Penpot MCP tools are available +2. Connect to the Penpot instance (cloud or self-hosted) +3. Open or create the target project and file + +## Creating Designs + +### Design-as-Code Approach + +Penpot's unique differentiator is treating designs as code artifacts: +- Design tokens map directly to CSS custom properties +- Components maintain semantic relationships +- Layout properties use standard CSS concepts (flex, grid) + +### Building Screens + +1. Create frames at the target viewport dimensions +2. Build incrementally -- add one visual group at a time +3. Use components and design tokens for consistency +4. Verify with screenshots between groups of modifications + +### Working with Components + +- Create reusable components for repeated UI patterns +- Use design tokens for colors, typography, and spacing +- Maintain a consistent component hierarchy + +## Reading Designs + +Extract design data through the Penpot API: +- File structure and page hierarchy +- Component definitions and instances +- Design tokens and style definitions +- Layout properties and constraints + +## Collaboration + +Penpot supports team collaboration: +- Share files for review and feedback +- Comment on specific design elements +- Version history for tracking changes + +## Exporting + +Export designs in multiple formats: +- SVG for vector assets +- PNG/JPEG for raster screenshots +- CSS for design token extraction +- Component specs for developer handoff + +## Key Advantages + +- **Open source** -- Self-hostable, no vendor lock-in, no paywalls +- **Design-as-code** -- Designs map directly to CSS and code concepts +- **Multi-directional** -- Both design-to-code and code-to-design workflows +- **Standards-based** -- Uses SVG natively, CSS layout concepts, web standards +- **Full API access** -- Complete file manipulation through open API diff --git a/plugins/compound-engineering/skills/ce-design/references/sketch-workflow.md b/plugins/compound-engineering/skills/ce-design/references/sketch-workflow.md new file mode 100644 index 00000000..d703c74b --- /dev/null +++ b/plugins/compound-engineering/skills/ce-design/references/sketch-workflow.md @@ -0,0 +1,57 @@ +# Sketch MCP Design Workflow + +Sketch MCP connects to the Sketch desktop app on macOS via a local HTTP server (localhost:31126). It provides both reading and scripted creation capabilities through the SketchAPI. + +## Requirements + +- macOS only +- Sketch desktop app running +- Sketch MCP server connected (local HTTP on port 31126) + +## Setup + +1. Call `get_selection_as_image` to verify the connection and see the current selection +2. Identify the current document and page context + +## Reading Designs + +Use `get_selection_as_image` to capture the current selection as an image for reference. + +Read existing designs to extract: +- Layout structure and spacing +- Color palette and typography +- Component patterns and visual language + +## Creating and Modifying Designs + +Use `run_code` with SketchAPI JavaScript to create or modify designs programmatically. + +SketchAPI enables: +- Creating new artboards, layers, and shapes +- Setting styles (fills, borders, shadows, text styles) +- Organizing layers and groups +- Duplicating and transforming elements +- Exporting slices and artboards + +### Scripted Creation Pattern + +```javascript +// Example: SketchAPI scripts run inside run_code +const sketch = require('sketch'); +const document = sketch.getSelectedDocument(); +const page = document.selectedPage; +// ... create and style elements +``` + +Build designs incrementally with multiple `run_code` calls, verifying with `get_selection_as_image` between modifications. + +## Exporting + +Use SketchAPI export functions within `run_code` to generate PNG, SVG, or PDF exports for handoff. + +## Key Advantages + +- **Full plugin API** -- Complete SketchAPI access enables complex automations +- **Native macOS design** -- Professional vector design with native performance +- **Scripted creation** -- Programmatic design creation and modification +- **Existing ecosystem** -- Access to Sketch's component libraries and plugins