@noemuch/bridge-ds 2.0.0

package/skills/design-workflow/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: design-workflow
+description: >
+  Spec-first workflow for designers who use Claude Code to design in Figma.
+  Covers components and full interfaces/screens. Use when a designer wants to:
+  (1) write or review a component or screen spec, (2) generate a Figma design via MCP,
+  (3) review and iterate on a design, (4) close or abandon work.
+  Triggers: "spec", "design", "screen", "review", "done", "drop", "status",
+  "setup", "workflow", "what's next", "new component", "new screen", or any design request.
+---
+
+# Design Workflow
+
+> Spec-first workflow for designers using Claude Code to design in Figma.
+> Powered by [figma-console-mcp](https://github.com/southleft/figma-console-mcp) as transport.
+> **All output in the user's language.**
+
+---
+
+## Philosophy
+
+1. **Spec-first** — No design without a validated specification
+2. **Figma is the output** — Everything ends as native Figma layers
+3. **DS-native** — Every visual element uses design system tokens and components, never hardcoded
+4. **Composability over configuration** — Simple building blocks > mega-components
+5. **Iterative** — Design → review → refine until right
+6. **Atomic** — Small sequential scripts with visual verification between each step
+
+---
+
+## Commands
+
+| Command | Purpose | Action file |
+|---------|---------|-------------|
+| `setup` | Extract DS + build knowledge base | `references/onboarding.md` (STEP 0) |
+| `spec {name}` | Write a component or screen specification | `references/actions/spec.md` |
+| `design` | Generate Figma design from active spec | `references/actions/design.md` |
+| `review` | Validate design against spec, tokens, and visual fidelity | `references/actions/review.md` |
+| `done` | Archive spec and close | `references/actions/done.md` |
+| `drop` | Abandon with preserved learnings | `references/actions/drop.md` |
+| `status` | Show current state and suggest next action | *(inline below)* |
+
+---
+
+## Two Modes
+
+### Component mode
+Design system components (Button, Card, Modal...):
+```
+spec {component}  →  design  →  review  →  done
+```
+Spec includes: architecture, props API, variants, tokens, Figma link.
+
+### Screen mode
+Full interfaces (dashboard, settings, onboarding...):
+```
+spec {screen}
+  → if new DS components identified:
+      spec {component}  →  design {component}  →  done {component}
+  → design {screen}  →  review  →  done
+```
+Spec includes: layout, sections, components used, content structure, responsive rules.
+**If the spec identifies UI patterns not covered by existing DS components**, they are flagged as new components. Each new component gets its own spec → design → done cycle before the screen design proceeds.
+
+The `spec` action auto-detects the mode from context, or asks the user.
+
+---
+
+## Full Workflow
+
+```
+setup (first time only)
+  → Extract DS via figma-console-mcp
+  → Build knowledge base (registries + guides)
+  ↓
+spec {name}
+  │
+  ├─ [screen mode] → new components check
+  │     └─ spec {component} → design → done → back to screen
+  │
+  ▼
+design
+  │
+  ├─ STEP A: Pattern Matching ← BLOCKING
+  │     1. Identify screen type
+  │     2. Load design-patterns.md
+  │     3. Read min 2 reference screenshots
+  │     4. Extract: layout zones, proportions, density, hierarchy
+  │     5. Gate: pattern matched and documented
+  │
+  ├─ STEP B: Atomic Generation via figma_execute
+  │     1. Split into small sequential scripts (~30-80 lines each)
+  │     2. After each step: verify with figma_take_screenshot
+  │     3. Fix issues before proceeding to next step
+  │     4. Generate states (clone + modify)
+  │
+  ▼
+review
+  │
+  ├─ Structural review (spec compliance, tokens, completeness)
+  │
+  ├─ Visual fidelity review ← BLOCKING
+  │     1. Compare with reference screenshots
+  │     2. Check: layout, density, hierarchy, card patterns, navigation
+  │     3. Verdict: PASS / FAIL with identified gaps
+  │
+  ▼
+done
+```
+
+---
+
+## Action Router
+
+Detect intent from user input and **read the action file BEFORE executing**:
+
+| User says | Route to |
+|-----------|----------|
+| "setup", "extract DS", "build knowledge base", "onboard" | `references/onboarding.md` (STEP 0) |
+| "spec", "write spec", "new component", "new screen" | `references/actions/spec.md` |
+| "design", "figma", "generate", "push to figma" | `references/actions/design.md` |
+| "review", "check", "validate", "audit" | `references/actions/review.md` |
+| "done", "finish", "complete", "close", "ship" | `references/actions/done.md` |
+| "drop", "abandon", "cancel" | `references/actions/drop.md` |
+| "status", "workflow", "what's next", "what now" | *(status logic below)* |
+
+---
+
+## Project Structure
+
+```
+specs/
+  active/          ← Current work (0-1 specs)
+  backlog/         ← Queued specs
+  shipped/         ← Completed & archived
+  dropped/         ← Abandoned with learnings
+  history.log      ← One-line per design shipped
+```
+
+---
+
+## Status Logic (inline)
+
+Detect state by checking:
+1. Does the knowledge base exist? (`references/knowledge-base/registries/` has JSON files)
+2. Does `specs/active/` contain a spec?
+3. Has a Figma design been generated for it?
+
+| State | Suggestion |
+|-------|------------|
+| No knowledge base | "Run: `setup` to extract and document your DS" |
+| No spec | "Ready. Run: `spec {name}`" |
+| Active spec, no Figma design | "Spec ready. Run: `design`" |
+| Active spec + Figma done | "Design ready. Run: `review`" |
+| Review passed | "Run: `done`" |
+
+---
+
+## Quality Gates
+
+Full definitions: `references/quality-gates.md` (read before any phase transition).
+
+---
+
+## Guided Mode (DEFAULT)
+
+**Read `references/onboarding.md` BEFORE any action.** It defines the step-by-step flow with blocking gates.
+
+**Non-negotiable rules:**
+- NEVER skip spec creation, validation, or new components check
+- NEVER skip pattern matching (no design without studying screenshots)
+- ALWAYS read the action file BEFORE executing
+- ALWAYS read `references/figma-api-rules.md` BEFORE writing any Figma script
+- ALWAYS wait for user confirmation before generating in Figma
+
+---
+
+## References
+
+| Reference | Path |
+|-----------|------|
+| Quality gates | `references/quality-gates.md` |
+| Figma API rules | `references/figma-api-rules.md` |
+| Onboarding flow | `references/onboarding.md` |
+| Spec template (component) | `references/templates/spec-template.md` |
+| Spec template (screen) | `references/templates/screen-template.md` |
+| Design patterns | `references/knowledge-base/guides/design-patterns.md` |
+| UI reference screenshots | `references/knowledge-base/ui-references/screenshots/` |
+
+---
+
+## MCP Tools Used
+
+Bridge uses [figma-console-mcp](https://github.com/southleft/figma-console-mcp) for all Figma operations:
+
+| Tool | Usage |
+|------|-------|
+| `figma_execute` | Run Figma Plugin API code (create frames, import components, bind variables) |
+| `figma_take_screenshot` | Visual verification between atomic steps |
+| `figma_get_design_system_kit` | Extract full DS (tokens + components + styles) during setup |
+| `figma_get_variables` | Extract design tokens/variables |
+| `figma_get_component` | Get component specs and properties |
+| `figma_get_styles` | Get text, color, effect styles |
+| `figma_search_components` | Find components by name |
+| `figma_get_status` | Check Figma connection |

package/skills/design-workflow/references/actions/design.md

@@ -0,0 +1,207 @@
+# Action: design
+
+> Generate a Figma design from the active spec via figma-console-mcp.
+
+---
+
+## Prerequisites
+
+- Active spec in `specs/active/` (abort if missing: "No active spec. Run: `spec {name}`")
+- figma-console-mcp MCP server available (check with `figma_get_status`)
+- **If screen spec lists "New DS Components Required"**: all listed components MUST be spec'd and designed first. Abort and prompt: "New component `{name}` needs to be created first. Run: `spec {name}`"
+
+---
+
+## Procedure
+
+### 1. Read the active spec + DS knowledge base
+
+Parse from spec:
+- Mode (component or screen)
+- All variants/sections/states
+- Design tokens (colors, spacing, typography, radius)
+- DS components used (with Figma component keys from registry)
+- Content/data examples
+
+**Load knowledge base registries (CRITICAL — must load before any script):**
+- `registries/components.json` → component keys
+- `registries/variables.json` → variable names and keys
+- `registries/text-styles.json` → text style keys
+- `registries/icons.json` → icon component keys (if exists)
+- `registries/logos.json` → logo component keys (if exists)
+- `registries/illustrations.json` → illustration component keys (if exists)
+
+**Load token guides:**
+- `guides/tokens/color-usage.md` → color token decision tree
+- `guides/tokens/spacing-usage.md` → spacing scale + usage
+- `guides/tokens/typography-usage.md` → font families, hierarchy
+
+**Load relevant component/pattern guides** (based on spec content):
+- `guides/components/overview.md` → component decision tree
+- Specific group guides as needed (actions.md, form-controls.md, etc.)
+- Pattern guides as needed (form-patterns.md, multi-step-flow.md, etc.)
+
+**Load Figma API rules (CRITICAL — read before writing any script):**
+- `references/figma-api-rules.md` → all API patterns, variable binding, boilerplate
+
+All paths relative to `.claude/skills/design-workflow/references/knowledge-base/`.
+
+### 1b. Pattern Matching (BLOCKING)
+
+**This step is MANDATORY. No design generation without completing it.**
+
+1. Load `guides/design-patterns.md`
+2. Identify the screen type and find matching pattern(s)
+3. Read at least 2 reference screenshots from `ui-references/screenshots/`
+4. Extract pattern rules: layout zones, proportions, density, hierarchy, card patterns
+5. Confirm pattern match before proceeding:
+```
+Pattern match: {pattern name}
+Screenshots studied: {list}
+Key rules applied: {bullet list}
+```
+
+**GATE: If no pattern matches**, ask the user which existing pattern is closest.
+
+### 1c. Canvas dimensions
+
+- **Web**: 1440px wide
+- **Mobile**: 390px wide
+- **Tablet**: 1024px wide
+
+### 2. Ask target
+
+Ask the user:
+- **Which Figma file?** (URL or fileKey)
+- **Which page?** (or create a new page)
+
+Verify connection:
+```
+figma_get_status()
+```
+
+**Library activation check:** Verify DS libraries are **enabled** in the target file. `importComponentByKeyAsync` only works with published AND enabled libraries.
+
+### 3. Generate the design — Atomic Steps
+
+Write and execute Figma Plugin API scripts via `figma_execute`.
+
+**Before writing any script, read `references/figma-api-rules.md`.** It contains:
+- Mandatory patterns (FILL after appendChild, variable binding, font loading)
+- DS component reuse rules (Rule 18) and canvas positioning (Rule 19)
+- Standard script boilerplate with helpers
+
+**Script execution via MCP:**
+```
+figma_execute({
+  code: "return (async function() { ... your Plugin API code ... return { success: true }; })();"
+})
+```
+
+The `return` before the IIFE is mandatory — without it, the Promise is lost.
+
+**Atomic generation (MANDATORY approach):**
+
+Never generate a full design in a single script. Split into small, sequential steps (~30-80 lines each). Each step:
+1. Does ONE thing (structure, populate a section, override instances...)
+2. Returns node IDs needed by subsequent steps
+3. Is verified with a screenshot before moving on
+
+**CRITICAL — Pre-script element audit (BLOCKING, Rule 18):**
+
+Before writing EACH script, list every visual element it will create and verify against registries:
+```
+Elements in this step:
+- Avatar → components.json key: xxx ✓
+- Divider → components.json key: xxx ✓
+- Label text → raw text (layout frame label, no DS component) ✓
+```
+If an element exists in `components.json`, it MUST be imported via `importComponentByKeyAsync`. NEVER recreate as raw frame/text/shape. NEVER hardcode hex colors — always bind variables.
+
+**Standard steps for a screen:**
+
+| Step | What | Lines | Returns |
+|------|------|-------|---------|
+| 1. Structure | Root frame + major section frames (empty) | ~40-60 | rootId, sectionIds |
+| 2. Top bar / Nav | Populate nav with DS component instances | ~20-30 | — |
+| 3. Content sections | One step per major section (header, cards, etc.) | ~40-60 | sectionId |
+| 4. Footer / minor | Populate footer, labels, secondary elements | ~20-30 | — |
+| 5. Instance overrides | Set TEXT/ICON props on all instances | ~30-50 | — |
+| 6. States | Clone root + modify for additional states | ~30-50 | stateIds |
+
+**Standard steps for a component:**
+
+| Step | What | Lines | Returns |
+|------|------|-------|---------|
+| 1. Build variants | Create component frames with structure | ~60-80 | variantIds |
+| 2. Combine + props | `combineAsVariants` + `addComponentProperty` | ~30-40 | compSetId |
+| 3. Bind props | `componentPropertyReferences` on all nodes | ~30-40 | — |
+| 4. Refinements | Adjust spacing, sizing, visual polish | ~20-30 | — |
+
+**After each step:** verify visually with `figma_take_screenshot` before proceeding:
+```
+figma_take_screenshot({ node_id: "{rootOrSectionId}", file_key: "{fileKey}" })
+```
+Compare the screenshot against the spec and reference patterns. If something is wrong, fix it before moving to the next step.
+
+### 3b. Component Properties (component mode)
+
+When generating a **component**, expose all properties defined in the spec:
+1. `addComponentProperty()` AFTER `combineAsVariants()` — see `figma-api-rules.md` Rule 9a
+2. **Bind TEXT props** to text nodes via `componentPropertyReferences` — Rule 9b
+3. **Bind INSTANCE_SWAP props** to icon/sub-component instances — Rule 9d
+4. **Bind BOOLEAN props** to optional elements — Rule 9e
+
+### 3c. Instance Overrides (screen mode)
+
+When placing component instances in a **screen**, override properties to show specific content:
+- Use `instance.setProperties({ [propKey]: value })` for TEXT overrides — Rule 9c
+- Use `instance.setProperties({ [propKey]: componentId })` for INSTANCE_SWAP overrides
+- Each instance should show unique, realistic content (not default placeholder text)
+
+### 3d. Zero Raw Elements Rule
+
+Before creating ANY visual element, check registries:
+1. `components.json` — Buttons, Tags, Inputs, etc.
+2. `icons.json` — All utility icons
+3. `logos.json` — All brand logos
+4. `illustrations.json` — Illustrations
+
+Only create raw elements for pure layout frames or when no DS component exists (document why).
+
+### 4. Multi-state generation
+
+1. Create the base state first
+2. Clone the root frame for each additional state
+3. Modify each clone (swap variants, update text, change progress)
+4. Add state labels above each frame
+
+### 5. Final naming cleanup
+
+Verify all layers have semantic names (no "Frame", "Rectangle", "Group").
+
+---
+
+## Output
+
+```
+Design created in Figma.
+
+File: {figma_url}
+Created:
+  - {n} frames with auto-layout
+  - {n} variables bound (colors + spacing + radius)
+  - {n} DS component instances
+  - States: {list}
+
+Warnings:
+  - {any issues}
+
+Next: review the design in Figma, then run: `review`
+```
+
+---
+
+## Transition
+
+When design is in Figma → suggest: "Run: `review`"

package/skills/design-workflow/references/actions/done.md

@@ -0,0 +1,48 @@
+# Action: done
+
+> Archive the spec and close the work.
+
+---
+
+## Procedure
+
+### 1. Final check
+
+- [ ] Figma design exists and matches spec
+- [ ] All acceptance criteria from spec are met
+- [ ] User has validated the design
+
+### 2. Archive
+
+```bash
+mv specs/active/{name}-spec.md specs/shipped/{name}-spec.md
+```
+
+### 3. Update history log
+
+Append to `specs/history.log`:
+
+```
+{date} | {name} | {component|screen} | {figma_url} | {author}
+```
+
+### 4. Brief retro
+
+- **What went well?** (patterns to repeat)
+- **What was friction?** (improvements for the workflow)
+- **What was learned?** (reusable knowledge)
+
+### 5. Cleanup
+
+Delete any remaining temp files if not already done.
+
+---
+
+## Output
+
+```
+## Done: {name}
+
+Figma: {url}
+Spec archived: specs/shipped/{name}-spec.md
+```

package/skills/design-workflow/references/actions/drop.md

@@ -0,0 +1,38 @@
+# Action: drop
+
+> Abandon the current work while preserving learnings.
+
+---
+
+## Procedure
+
+### 1. Confirm
+
+Ask: "Sure you want to drop {name}?"
+
+### 2. Document learnings
+
+Add to the spec:
+
+```markdown
+## Drop Notes
+**Dropped**: {date}
+**Reason**: {reason}
+**Learnings**: {what was discovered, what blocked, what to do differently}
+```
+
+### 3. Archive
+
+```bash
+mv specs/active/{name}-spec.md specs/dropped/{name}-spec.md
+```
+
+### 4. Update history
+
+```
+{date} | {name} | DROPPED | {reason}
+```
+
+### 5. Cleanup
+
+Delete temp files if any.

package/skills/design-workflow/references/actions/review.md

@@ -0,0 +1,149 @@
+# Action: review
+
+> Validate the Figma design against the spec. Check structure, tokens, and completeness.
+
+---
+
+## Prerequisites
+
+- Active spec in `specs/active/`
+- Figma design generated
+
+---
+
+## Procedure
+
+### 1. Gather artifacts + DS knowledge base
+
+- Read the active spec
+- Load knowledge base registries for validation:
+  - `references/knowledge-base/registries/components.json` → verify component instances match registry
+  - `references/knowledge-base/registries/variables.json` → verify variable bindings use correct names
+- Inspect Figma design via MCP:
+  ```
+  figma_take_screenshot({ node_id: "{nodeId}", file_key: "{fileKey}" })
+  figma_get_variables({ file_key: "{fileKey}" })
+  ```
+
+### 2. Review checklist
+
+#### A. Spec Compliance
+
+- [ ] All variants/sections from spec are represented in Figma
+- [ ] Architecture/layout matches spec diagram
+- [ ] Content matches spec examples (or realistic equivalents)
+
+#### B. Design Token Alignment
+
+- [ ] Colors match spec tokens (no arbitrary hex values)
+- [ ] Spacing follows token scale strictly (no off-scale values)
+- [ ] Typography uses correct styles from the typography scale
+- [ ] Radius values match tokens
+- [ ] Token naming is semantic (`danger` not `red`, `moderate` not `gray`)
+- [ ] Aliasing depth ≤ 2 levels
+- [ ] **Variables are bound** (not hardcoded hex/px) — check via Figma inspect
+- [ ] Variable names match `registries/variables.json` exactly
+- [ ] **ZERO hardcoded hex colors** — every color must use a bound variable (Rule 18)
+
+#### B2. DS Component Reuse Audit (BLOCKING — Rule 18)
+
+Cross-reference every visual element in the design against `registries/components.json`:
+- [ ] **Avatars** are DS Avatar instances (not raw ellipses/frames)
+- [ ] **Dividers/Separators** are DS Divider instances (not raw rectangles)
+- [ ] **Tags/Badges** are DS instances (not raw frames with text)
+- [ ] **Buttons** are DS Button instances (not raw frames with text)
+- [ ] **Icons** are DS Icon instances (not raw vectors)
+- [ ] **Logos** are DS Logo instances
+- [ ] Any raw frame is justified with a `// NO DS COMPONENT: {reason}` comment in the script
+
+**If ANY DS component was recreated as raw elements → FAIL. Must be fixed before PASS.**
+
+#### C. Completeness
+
+**Component mode:**
+- [ ] All sizes represented
+- [ ] All states shown (default, hover, pressed, disabled if applicable)
+- [ ] All optional prop combinations demonstrated
+- [ ] Advanced compositions shown
+
+**Screen mode:**
+- [ ] All sections from spec present
+- [ ] All states captured (empty, loading, populated, error)
+- [ ] Responsive breakpoints if specified
+- [ ] DS components are **real instances** (not placeholder rectangles)
+- [ ] No `[MISSING]` placeholder frames remain
+
+#### D. Design Quality
+
+- [ ] Visual hierarchy is clear
+- [ ] Spacing rhythm is consistent (follows token scale)
+- [ ] Layer naming is semantic in Figma (not "Frame 42" or "Group 1")
+- [ ] No orphan or misaligned elements
+- [ ] Naming follows DS conventions: `{category}/{role}/{emphasis}`
+
+#### E. Visual Fidelity (BLOCKING)
+
+**Load before checking:**
+- `references/knowledge-base/guides/design-patterns.md`
+- The reference screenshots used during design generation
+
+**Compare the generated design with the reference screenshots and pattern rules:**
+
+- [ ] **Layout match** — Zones are in the correct positions (sidebar, content, header, footer)
+- [ ] **Proportion match** — Relative widths/heights of zones match the pattern
+- [ ] **Density match** — Information density is similar (not too sparse, not too crammed)
+- [ ] **Hierarchy match** — Visual weight of title, sections, CTAs matches product's existing hierarchy
+- [ ] **Card patterns match** — Card size, grid rhythm, gaps, internal layout follow the design patterns
+- [ ] **Navigation match** — Sidebar/stepper/tabs follow the correct pattern for this screen type
+- [ ] **Section organization** — Consistent spacing between sections, titles properly placed
+- [ ] **Whitespace balance** — Margins and breathing room consistent with product density
+
+**If any check fails:** identify the specific gap, reference the pattern rule that was violated, and suggest the fix.
+
+#### F. Component API Quality (component mode)
+
+- [ ] Is the composition pattern the right one? (slots vs config vs compound)
+- [ ] Could the props surface be smaller?
+- [ ] Is the component reusable beyond its primary use case?
+
+### 3. Report
+
+```markdown
+## Review: {name}
+
+### Spec Compliance: {OK / ISSUES}
+{findings}
+
+### Token Alignment: {OK / ISSUES}
+{findings}
+
+### Completeness: {OK / ISSUES}
+{missing items}
+
+### Design Quality: {OK / ISSUES}
+{findings}
+
+### Visual Fidelity: {OK / ISSUES}
+Pattern matched: {pattern name}
+Screenshots compared: {list}
+{findings — specific gaps with pattern rule references}
+
+### Verdict: PASS / NEEDS ITERATION
+
+### Iteration needed:
+1. {what to fix}
+```
+
+### 4. Iterate if needed
+
+If NEEDS ITERATION:
+1. Fix issues via `figma_execute` scripts (read `references/figma-api-rules.md` for patterns)
+2. Re-review only the fixed areas
+
+Repeat until PASS.
+
+---
+
+## Transition
+
+When review passes → suggest: "Review passed. Run: `done`"