@noemuch/bridge-ds 2.0.0

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

@@ -0,0 +1,351 @@
+# Onboarding — Guided Workflow
+
+> This file defines the guided flow that EVERY user follows. Each step blocks until its prerequisites are met. No shortcuts, no skipping — the output quality depends on it.
+
+---
+
+## Flow Overview
+
+```
+STEP 0  Setup check + Knowledge base
+   ↓
+STEP 1  Spec creation (component or screen)
+   ↓
+STEP 2  Spec validation (quality gates)
+   ↓
+STEP 3  New components check (screen mode only)
+   ↓      ↓ (if new components found)
+   ↓    STEP 3a  Spec component
+   ↓    STEP 3b  Design component
+   ↓    STEP 3c  Validate component → loop back to 3a if more
+   ↓      ↓
+STEP 4  Design (generate in Figma via figma_execute)
+   ↓
+STEP 5  Review (audit against spec + tokens)
+   ↓      ↓ (if issues found)
+   ↓    STEP 5a  Iterate → back to Review
+   ↓      ↓
+STEP 6  Done (archive + retro)
+```
+
+---
+
+## STEP 0 — Setup Check + Knowledge Base
+
+**Trigger**: any design-related request (spec, design, new component, new screen, setup, etc.)
+
+### 0a. Check figma-console-mcp
+
+| Check | How to verify | Block message if fail |
+|-------|--------------|----------------------|
+| figma-console-mcp available | Call `figma_get_status()` — should return connection info | "figma-console-mcp is not configured. Run: `claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN -- npx -y figma-console-mcp@latest`" |
+| Connected to Figma | `figma_get_status()` returns `setup.valid: true` | "Figma Desktop is not connected. Open your Figma file → Plugins → Development → Run the Desktop Bridge plugin." |
+| DS libraries enabled | Ask user to confirm | "Make sure your DS libraries are enabled in the target Figma file (Assets panel → Team → Enable). Confirm when done." |
+
+**Note:** Setup check can be deferred to just before STEP 4 (design) if the user only wants to write a spec first. But it MUST pass before any Figma generation.
+
+### 0b. Knowledge Base Check
+
+Check if `references/knowledge-base/registries/` contains JSON files.
+
+**If knowledge base exists:**
+```
+Setup OK. Knowledge base found ({N} components, {N} variables, {N} text styles).
+What do you want to design? (component or screen)
+```
+
+**If knowledge base is empty → build it:**
+
+#### KB Generation Flow
+
+1. **Ask the user for the DS library file key/URL** (the Figma file containing their design system)
+
+2. **Extract raw data via MCP tools:**
+   ```
+   figma_get_design_system_kit({ file_key: "...", format: "full" })
+   figma_get_variables({ file_key: "..." })
+   figma_get_styles({ file_key: "..." })
+   ```
+
+3. **Write registries** (raw JSON, deterministic):
+   - `registries/components.json` — component names, keys, variants, properties
+   - `registries/variables.json` — variable names, keys, types, values by mode
+   - `registries/text-styles.json` — text style names, keys, font specs
+
+4. **Generate intelligent guides** (Claude analyzes registries and writes):
+
+   **Token guides:**
+   - `guides/tokens/color-usage.md` — Group colors by semantic role, create decision tree (when to use which token)
+   - `guides/tokens/spacing-usage.md` — Map spacing values to UI contexts (form gaps, section gaps, card padding, etc.)
+   - `guides/tokens/typography-usage.md` — Map text styles to hierarchy (display > heading > body > caption)
+
+   **Component guides:**
+   - `guides/components/overview.md` — Decision tree: "I need X" → use component Y. Cover every component.
+   - `guides/components/{group}.md` — Per-group guides (actions, form-controls, data-display, feedback, navigation, layout) with: when to use, when NOT to use, props, variants, examples
+
+   **Asset guides (if icons/logos/illustrations exist):**
+   - `guides/assets/icons.md` — Categorized icon catalog
+   - `guides/assets/logos.md` — Logo catalog
+   - `guides/assets/illustrations.md` — Illustration catalog with usage contexts
+
+5. **Ask the user for product screenshots:**
+   ```
+   To document your layout patterns, add screenshots of your product's key screens
+   to: .claude/skills/design-workflow/references/knowledge-base/ui-references/screenshots/
+
+   Ideal screenshots:
+   - Dashboard / home page
+   - List / category page
+   - Detail / form page
+   - Settings page
+   - Modal / dialog
+   - Empty state
+   - Multi-step flow
+
+   Drop the PNG/JPG files and confirm when done.
+   ```
+
+6. **Generate pattern guides** (Claude analyzes screenshots):
+   - `guides/design-patterns.md` — Layout patterns catalogue with zone placement, proportions, density rules
+   - `guides/patterns/form-patterns.md` — Form field patterns, validation, conditional fields
+   - `guides/patterns/navigation-patterns.md` — Sidebar, tabs, breadcrumbs patterns
+   - `guides/patterns/feedback-patterns.md` — Success, error, warning, loading states
+   - `ui-references/ui-references-guide.md` — Which screenshot for which pattern type
+
+7. **Validation summary:**
+   ```
+   Knowledge base built:
+   - {N} components documented ({N} with variants)
+   - {N} variables ({N} colors, {N} spacing, {N} radius)
+   - {N} text styles
+   - {N} layout patterns extracted from {N} screenshots
+
+   Ready to design. Run: `spec {name}`
+   ```
+
+---
+
+## STEP 1 — Spec Creation
+
+**Trigger**: user describes what they want to design
+
+**Prerequisites:**
+- No conflicting active spec in `specs/active/` (if one exists, ask: "There's already an active spec: `{name}`. Continue it, drop it, or move to backlog?")
+
+**Guided questions (ask ONE BY ONE, not all at once):**
+
+### 1.1 Mode detection
+```
+Is this a DS component (Button, Card, Modal...) or a screen/page (dashboard, onboarding...)?
+```
+If unclear from context, ask explicitly. Do NOT assume.
+
+### 1.2 Core description
+```
+Describe in 2-3 sentences:
+- What is it? (what)
+- For whom / what user goal? (user goal)
+- In what context does it appear? (context)
+```
+
+### 1.3 Content & structure
+**Component mode:**
+```
+What are the elements of the component?
+- What props/variants? (size, state, style...)
+- What sub-elements? (icon, text, badge...)
+- What states? (default, hover, disabled, loading...)
+```
+
+**Screen mode:**
+```
+What are the sections of the screen?
+For each section:
+- What does it display?
+- What DS components does it use?
+- What realistic content?
+```
+
+### 1.4 References
+```
+Do you have references? (existing Figma URL, screenshot, mockup, PM spec...)
+```
+If Figma URL provided → use `figma_take_screenshot` + `figma_get_component` to analyze.
+
+### 1.5 Write the spec
+Using the gathered info + DS knowledge base, write the spec to `specs/active/{name}-spec.md`.
+Always use the appropriate template (`spec-template.md` or `screen-template.md`).
+
+**On completion:**
+```
+Spec written: specs/active/{name}-spec.md
+Let's validate it.
+```
+
+→ Auto-proceed to STEP 2.
+
+---
+
+## STEP 2 — Spec Validation
+
+**Prerequisites:** spec file exists in `specs/active/`
+
+**Run ALL quality gates from `quality-gates.md` (phases: spec → design).** Report as checklist.
+
+**If ANY blocking gate fails:**
+```
+The spec isn't ready yet. Missing:
+- {gate 1 that fails} → {concrete action to fix}
+- {gate 2 that fails} → {concrete action to fix}
+
+I'll fix it and we re-validate?
+```
+Fix the spec, then re-run validation. Loop until all gates pass.
+
+**If ALL gates pass:**
+```
+Spec validated. All quality gates OK.
+```
+
+→ Screen mode: proceed to STEP 3
+→ Component mode: proceed to STEP 4
+
+---
+
+## STEP 3 — New Components Check (screen mode only)
+
+**Prerequisites:** validated screen spec
+
+**Check the "New DS Components Required" section of the spec.**
+
+### If "None":
+```
+No new components to create. All patterns covered by existing DS.
+Let's proceed to design.
+```
+→ Proceed to STEP 4.
+
+### If new components listed:
+```
+{N} new component(s) identified in the spec:
+1. {ComponentName} — {short description}
+2. {ComponentName} — {short description}
+
+We need to create them before designing the screen.
+Starting with: {ComponentName 1}
+```
+
+→ For EACH new component, run the sub-cycle:
+
+### STEP 3a — Spec the component
+Run STEP 1 in component mode, pre-filled with context from the screen spec.
+
+### STEP 3b — Design the component
+Run STEP 4 for the component (create in Figma with all variants).
+
+### STEP 3c — Validate the component
+Run STEP 5 (review) for the component.
+On pass → `done` the component, then loop back to 3a for the next component.
+
+**When ALL new components are done:**
+```
+All new components created and validated:
+- {Component 1} → done
+- {Component 2} → done
+
+Now we can design the screen with real DS components.
+```
+→ Proceed to STEP 4 for the screen.
+
+---
+
+## STEP 4 — Design
+
+**Prerequisites (ALL must pass):**
+- [ ] Spec validated (STEP 2 passed)
+- [ ] New components created if needed (STEP 3 passed)
+- [ ] figma-console-mcp connected (STEP 0 check)
+- [ ] DS libraries enabled
+
+**If any prerequisite fails → block with specific message from Block Messages Reference.**
+
+**Before generating:** confirm scope with the user:
+```
+I'll generate:
+- Type: {component with N variants | screen with N sections}
+- Canvas: {1440px (web) | 390px (mobile) | 1024px (tablet)}
+- States: {list of states to generate}
+- Approach: atomic ({N} steps with screenshot verification between each)
+
+Ready? I'll start generating.
+```
+
+Wait for explicit user confirmation, then execute `actions/design.md`.
+
+**Atomic generation (MANDATORY):** Never generate in a single monolithic script. Split into 4-6 small sequential steps (~30-80 lines each). After EACH step, verify visually with `figma_take_screenshot`. Fix issues before moving to the next step.
+
+→ Proceed to STEP 5.
+
+---
+
+## STEP 5 — Review
+
+**Prerequisites:** design generated in Figma
+
+Execute `actions/review.md`. Present verdict:
+
+- **PASS** → "Review OK. Design is spec-compliant. Archive it?"
+- **NEEDS ITERATION** → fix issues via `figma_execute` scripts, re-review. Loop until PASS.
+
+→ Proceed to STEP 6 on user confirmation.
+
+---
+
+## STEP 6 — Done
+
+**Prerequisites:** review passed + user confirmation
+
+**Execute `actions/done.md`:**
+1. Move spec to `specs/shipped/`
+2. Update `specs/history.log`
+3. Brief retro (3 questions)
+
+```
+## Done: {name}
+
+Spec archived: specs/shipped/{name}-spec.md
+Figma: {url if available}
+
+### Quick retro
+- What went well: {positives}
+- What was friction: {improvements}
+- What was learned: {reusable learnings}
+
+Ready for the next design!
+```
+
+---
+
+## Block Messages Reference
+
+| Situation | Message |
+|-----------|---------|
+| No MCP server | "figma-console-mcp is not configured. Run: `claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN -- npx -y figma-console-mcp@latest`" |
+| Not connected | "Figma Desktop is not connected. Open: Plugins → Development → Desktop Bridge." |
+| Libraries not enabled | "Enable your DS libraries in the target Figma file: Assets → Team → Enable." |
+| No knowledge base | "Knowledge base not built yet. Run: `setup`" |
+| No active spec | "No active spec. Let's create one: component or screen?" |
+| Conflicting active spec | "There's already an active spec: `{name}`. Continue, drop, or backlog?" |
+| Spec gate failed | "The spec isn't ready. Missing: {list}. I'll fix it?" |
+| New components not created | "Component `{name}` doesn't exist in the DS yet. Let's create it first." |
+| Design not generated | "No Figma design yet. Start generating?" |
+| Review failed | "The design has {N} issue(s). I'll fix and re-review?" |
+
+---
+
+## Skip Policy
+
+Users CAN explicitly ask to skip a non-critical gate. When they do:
+1. Warn: "Sure? Skipping this step may impact quality."
+2. If confirmed: log the skip reason, proceed, flag it in the review as advisory
+3. **NEVER skip**: spec creation, spec validation, new components check, pattern matching, visual fidelity review, DS component reuse audit, pre-script element audit, registry loading

package/skills/design-workflow/references/quality-gates.md

@@ -0,0 +1,127 @@
+# Quality Gates
+
+---
+
+## Phase: setup (STEP 0)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| figma-console-mcp available | Yes (before design) | `figma_get_status()` returns valid connection |
+| Connected to Figma Desktop | Yes (before design) | Status has `setup.valid: true` |
+| DS libraries enabled | Yes (before design) | User confirmation |
+| Knowledge base exists | Yes (before spec) | `registries/` has JSON files |
+
+---
+
+## Phase: spec → design (STEP 2)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| Spec has clear scope (component or screen) | Yes | Mode identified |
+| Spec has description (what, user goal, context) | Yes | Non-empty |
+| Spec has design tokens section | Yes | Tokens referenced |
+| Spec has acceptance criteria | Yes | At least 3 checkboxes |
+| Spec has Figma URL | No | Can be added later |
+
+### Component-specific
+| Gate | Blocking |
+|------|----------|
+| Props API defined | Yes |
+| Architecture diagram present | Yes |
+| Variant names listed | Yes |
+
+### Screen-specific
+| Gate | Blocking |
+|------|----------|
+| Layout structure defined | Yes |
+| Sections breakdown present | Yes |
+| DS components identified | Yes |
+| "New DS Components Required" section filled | Yes |
+
+---
+
+## Phase: new components resolution (STEP 3)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| All listed new components have been spec'd | Yes | Spec exists in `specs/shipped/` or `specs/active/` |
+| All listed new components have been designed in Figma | Yes | Design generated and reviewed |
+| All listed new components passed review | Yes | Review verdict = PASS |
+
+---
+
+## Phase: pattern matching (STEP 3b)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| Pattern identified from `design-patterns.md` | Yes | Pattern name logged |
+| Min 2 reference screenshots read and analyzed | Yes | Screenshot filenames logged |
+| Pattern rules extracted and documented | Yes | Bullet list of rules to apply |
+| If no pattern matches: user confirmed closest pattern | Yes | Explicit user choice |
+
+---
+
+## Phase: design generation (STEP 4)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| **Atomic generation** | **Yes** | Design split into 4-6 sequential scripts (~30-80 lines each), never one monolithic script |
+| **Screenshot verification between steps** | **Yes** | `figma_take_screenshot` called after EACH atomic step, issues fixed before proceeding |
+| **Pre-script element audit (Rule 18)** | **Yes** | Before EACH script: list every visual element, verify against registries. NEVER recreate a DS component as raw frame |
+| **Registry loaded before first script** | **Yes** | `components.json` and other registries read and available before writing any generation script |
+| **Zero hardcoded hex colors** | **Yes** | Every color uses `setBoundVariableForPaint` or `setBoundVariable` with registry variables |
+| **Canvas positioning (Rule 19)** | **Yes** | Components positioned with 80px+ gaps, never stacked at (0,0) |
+
+---
+
+## Phase: design → review (STEP 4 → 5)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| Figma design exists | Yes | Generated via figma_execute |
+| Canvas width correct | Yes | 1440px (web), 390px (mobile), 1024px (tablet) |
+| Component properties exposed | Yes (component mode) | All text = TEXT prop, all icons = INSTANCE_SWAP, optionals = BOOLEAN |
+| **No interaction state variants** | **Yes** | Hover/pressed/disabled handled via prototyping, NOT as separate variants |
+| **Variants arranged in grid** | **Yes (component mode)** | Variants positioned in readable grid after `combineAsVariants()`, not stacked |
+| **Zero raw elements (Rule 18)** | **Yes** | Every visible element checked against registries before creation. Raw frames/text only if justified. **FAIL if Avatar, Divider, Tag, Badge, or Button recreated as raw element** |
+| **Design follows matched pattern layout** | **Yes** | Zones, proportions match pattern rules |
+| **Content density matches reference** | **Yes** | Similar item count, whitespace balance |
+
+---
+
+## Phase: review — visual fidelity (STEP 5)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| **Layout match** | Yes | Zones in correct positions per pattern |
+| **Proportion match** | Yes | Relative widths/heights match pattern |
+| **Density match** | Yes | Information density similar to reference screenshots |
+| **Hierarchy match** | Yes | Visual weight of titles, sections, CTAs matches product patterns |
+| **Card pattern match** | Yes (if cards present) | Size, grid, rhythm, internal layout per design patterns |
+| **Navigation match** | Yes | Sidebar/stepper/tabs follow correct pattern |
+| **Section organization** | Yes | Consistent spacing between sections, titles properly placed |
+| **Whitespace balance** | Yes | Margins and breathing room consistent with product density |
+
+---
+
+## Phase: review → done (STEP 6)
+
+| Gate | Blocking | Check |
+|------|----------|-------|
+| All variants/sections in Figma | Yes | Matches spec list |
+| Tokens correctly applied | Yes | No arbitrary values, variables bound |
+| DS component instances (not raw frames) | Yes | Real instances from library |
+| Visual fidelity review passed | Yes | All visual gates = PASS |
+| User validated design | Yes | Explicit approval |
+| All acceptance criteria met | Yes | Checkboxes checked |
+
+---
+
+## Skip Policy
+
+- **Non-skippable (NEVER):** spec creation, spec validation, new components check, pattern matching, visual fidelity review, DS component reuse audit (Rule 18), pre-script element audit, registry loading
+- **Skippable with warning:** Figma URL in spec, individual structural review sub-checks
+- When skipping:
+  1. Warn user about quality impact
+  2. Log the skip reason
+  3. Flag in review as advisory issue

package/skills/design-workflow/references/templates/screen-template.md

@@ -0,0 +1,127 @@
+# {ScreenName}
+
+## Description
+
+{What screen, user goal, context of use.}
+
+**Figma:** {figma_url}
+
+---
+
+## Visual Reference
+
+> Identifies which design pattern this screen follows.
+> The layout structure below MUST be based on these references.
+
+| | |
+|---|---|
+| **Pattern** | {pattern name from `design-patterns.md`} |
+| **Screenshots studied** | {list of screenshot filenames, min 2} |
+| **Key composition rules** | {bullet list of specific rules from the pattern that apply} |
+
+**Composition notes:**
+{What was observed in the screenshots that informs this spec's layout: zone proportions, content density, visual hierarchy, navigation pattern, card rhythm, etc.}
+
+---
+
+## Layout Structure
+
+> Based on the matched pattern above. The diagram MUST reflect the pattern's zone placement and proportions.
+
+```
+┌─────────────────────────────────────────┐
+│  Header                                 │
+├───────────┬─────────────────────────────┤
+│  Sidebar  │  Content Area               │
+│           │                             │
+│           │                             │
+├───────────┴─────────────────────────────┤
+│  Footer                                 │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Sections
+
+### {SectionName}
+- **Purpose**: {what this section shows}
+- **DS Components used**: {Component (variant, size)}
+- **Content**: {what data is displayed}
+- **Behavior**: {interactions, scroll, collapse...}
+
+---
+
+## States
+
+| State | Description |
+|-------|-------------|
+| Empty | {what shows when no data} |
+| Loading | {skeleton, spinner...} |
+| Populated | {normal state with data} |
+| Error | {error message, retry action} |
+
+---
+
+## DS Components Used
+
+> Look up component keys in `knowledge-base/registries/components.json`.
+> Use `knowledge-base/guides/components/overview.md` decision tree to choose the right component.
+
+| Component | Variant/Size | Figma Key | Location |
+|-----------|-------------|-----------|----------|
+| `{Name}` | {variant} | {key from registry} | {section} |
+
+---
+
+## New DS Components Required
+
+> List any UI patterns in this screen that are NOT covered by existing DS components.
+> Each one will need its own `spec {component}` → `design` → `done` cycle BEFORE this screen is designed.
+> If none, write "None — all patterns covered by existing DS components."
+
+| Component Name | Used in Section | Description | Variants Needed |
+|---------------|----------------|-------------|-----------------|
+| `{Name}` | {section} | {what it does, why existing components don't cover it} | {list of variants/states} |
+
+---
+
+## Content Structure
+
+{Realistic data examples for each section}
+
+---
+
+## Design Tokens
+
+### Layout
+| Token | Value | Usage |
+|-------|-------|-------|
+| `{token}` | {value} | {usage} |
+
+### Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `{token}` | {value} | {usage} |
+
+---
+
+## Responsive Rules
+
+| Breakpoint | Layout change |
+|-----------|---------------|
+| Desktop (>1024px) | {layout} |
+| Tablet (768-1024px) | {layout} |
+| Mobile (<768px) | {layout} |
+
+---
+
+## Acceptance Criteria
+
+- [ ] {criterion}
+
+---
+
+## Open Questions
+
+1. {question}