@noemuch/bridge-ds 2.0.0

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

@@ -0,0 +1,128 @@
+# Action: spec {name}
+
+> Write or validate a specification. Auto-detects component vs screen mode.
+
+---
+
+## Procedure
+
+### 1. Determine mode
+
+Ask or infer from context:
+- **Component**: design system primitive, block, or composition (Button, Card, Tag...)
+- **Screen**: full interface or page (dashboard, settings, onboarding flow...)
+
+### 2. Gather context
+
+- **Load design patterns** (MANDATORY for screens, recommended for components):
+  - `references/knowledge-base/guides/design-patterns.md` → pattern catalogue
+  - Identify the **closest pattern** for this screen/component
+  - **Read the referenced screenshots** (min 2) from `references/knowledge-base/ui-references/screenshots/`
+  - Study: zones, proportions, density, hierarchy, navigation, card rhythm
+  - The spec's **layout structure and architecture diagram** MUST be based on these patterns, not invented from scratch
+
+- **Load DS knowledge base** — use these to make informed component and token choices:
+  - `references/knowledge-base/guides/components/overview.md` → component decision tree
+  - `references/knowledge-base/registries/components.json` → available components with Figma keys
+  - `references/knowledge-base/guides/tokens/spacing-usage.md` → spacing scale + usage contexts
+  - `references/knowledge-base/guides/tokens/color-usage.md` → color token decision tree
+  - `references/knowledge-base/guides/tokens/typography-usage.md` → type hierarchy + font families
+  - Load relevant pattern guides if screen mode (form-patterns.md, multi-step-flow.md, navigation-patterns.md, feedback-patterns.md)
+  - Load relevant component group guides based on the screen's needs
+
+- **Check knowledge base exists** — if `references/knowledge-base/registries/` is empty, tell the user: "Knowledge base not built yet. Run: `setup` first."
+
+- Check existing specs: `specs/active/`, `specs/backlog/`
+- Check existing DS components in `references/knowledge-base/registries/components.json`
+
+### 3. Write the spec
+
+Write to `specs/active/{name}-spec.md`.
+
+> For multi-screen flows with their own splitting rules (e.g., `specs/active/f1/rules.md`), read those rules first for folder structure and naming conventions.
+
+#### Component spec — mandatory sections:
+
+- **Description** (what, why, design principle)
+- **Architecture overview** (composition diagram)
+- **Component hierarchy** (levels: primitive → blocks → composition)
+- **Props API** (TypeScript interfaces, variant names matching Figma)
+- **Layout specs** (dimensions, gaps, alignment)
+- **Design tokens** (spacing, colors, typography, radius)
+- **Component properties** (TEXT, INSTANCE_SWAP, BOOLEAN — Figma)
+- **Reused DS components** (existing components from registry)
+- **Acceptance criteria** (checkboxes, testable)
+- **Open questions**
+
+Use template from `references/templates/spec-template.md`.
+
+#### Screen spec — mandatory sections:
+
+- **Description** (what screen, user goal, context)
+- **Visual reference** (pattern name, screenshots studied, key composition rules applied)
+- **Layout structure** (zones, grid, responsive behavior — MUST follow matched pattern)
+- **Sections breakdown** (header, content area, sidebar, footer...)
+- **DS components used** (EXHAUSTIVE list — every visible element must be accounted for with Figma keys from registry)
+- **Content structure** (real or realistic placeholder data)
+- **States** (empty, loading, populated, error)
+- **Design tokens** (background, spacing rhythm, elevation)
+- **Responsive rules** (breakpoints, layout shifts)
+- **Acceptance criteria** (checkboxes)
+- **Open questions**
+
+Use template from `references/templates/screen-template.md`.
+
+#### Component spec — visual reference (recommended):
+
+For components that appear in existing screens, also include:
+- **Visual reference** (which pattern/screenshot shows a similar component, composition rules)
+- This helps the `design` step match proportions and density
+
+### 3b. Identify new DS components (screen mode only)
+
+For each UI pattern described in the spec, check if it exists in `registries/components.json`:
+- If a pattern is covered by an existing DS component → reference it in "DS Components Used"
+- If a pattern is NOT covered → add it to the **"New DS Components Required"** section
+
+**This is a blocking gate.** If new components are identified:
+1. List them in the spec with: name, description, where they're used, and variants/states needed
+2. After the screen spec is validated, each new component triggers its own `spec {component}` → `design` → `done` cycle
+3. The screen `design` step is blocked until all new components exist in the DS
+
+**Common signals that a new component is needed:**
+- A card/tile with specific internal structure (icon + title + description + badge + CTA)
+- A custom indicator or status pattern not covered by Badge/Tag
+- A navigation pattern not covered by existing nav components
+- A data display pattern not covered by existing list/table components
+
+### 4. Validate
+
+**Token architecture:**
+- [ ] Every visual value references a design token (no hardcoded px/hex)
+- [ ] Tokens use semantic names, not visual (`danger` not `red`)
+- [ ] Aliasing depth ≤ 2 levels (primitive → semantic → component max)
+
+**Naming conventions:**
+- [ ] Variant names match Figma exactly
+- [ ] Props use DS naming conventions (camelCase, `is` prefix for booleans, `on` prefix for events)
+- [ ] Token references follow `{category}/{role}/{emphasis}` pattern
+
+**Component API** (component mode only):
+- [ ] Props surface area is minimal (composability over configuration)
+- [ ] Composition pattern appropriate (slots > mega-props)
+- [ ] Platform parity considered
+
+**General:**
+- [ ] Acceptance criteria are testable (not vague)
+- [ ] Reused DS components identified
+- [ ] Open questions are explicit
+
+### 5. Present for review
+
+Output the spec, flag assumptions, highlight open questions.
+
+---
+
+## Transition
+
+When spec is approved → suggest: "Spec approved. Run: `design`"

package/skills/design-workflow/references/figma-api-rules.md

@@ -0,0 +1,453 @@
+# Figma Plugin API — Mandatory Rules
+
+> **This file MUST be read before writing ANY Figma generation script.**
+> Every rule here was learned from real bugs. Breaking them = broken layout.
+>
+> **Note:** Variable keys, text style keys, and component keys vary per design system.
+> Always load them from your project's `knowledge-base/registries/` directory.
+
+---
+
+## Rule 1: FILL after appendChild (CRITICAL)
+
+`layoutSizingHorizontal = "FILL"` and `layoutSizingVertical = "FILL"` **ONLY work on children of auto-layout frames**. Setting FILL before `appendChild()` throws an error.
+
+```js
+// WRONG — crashes
+child.layoutSizingHorizontal = "FILL";
+parent.appendChild(child);
+
+// CORRECT
+parent.appendChild(child);
+child.layoutSizingHorizontal = "FILL";
+```
+
+**Helper:**
+```js
+function appendFill(parent, child, fillH, fillV) {
+  parent.appendChild(child);
+  if (fillH) child.layoutSizingHorizontal = "FILL";
+  if (fillV) child.layoutSizingVertical = "FILL";
+}
+```
+
+---
+
+## Rule 2: Absolute positioning after appendChild
+
+`layoutPositioning = "ABSOLUTE"` requires the node to already be inside an auto-layout parent.
+
+```js
+// CORRECT
+parent.appendChild(circle);
+circle.layoutPositioning = "ABSOLUTE";
+circle.x = 100; circle.y = 50;
+```
+
+---
+
+## Rule 3: FILL + AUTO parent = collapsed layout
+
+A child with `FILL` inside a parent with `primaryAxisSizingMode = "AUTO"` collapses to 0px. The parent must be FIXED for FILL children.
+
+```js
+// CORRECT
+root.primaryAxisSizingMode = "FIXED";
+root.resize(1440, 900);
+// then after appendChild:
+mainArea.layoutSizingVertical = "FILL";
+```
+
+---
+
+## Rule 4: resize() overrides sizing modes (CRITICAL)
+
+`resize(width, height)` forces **both** axes to `"FIXED"`. Set sizing modes AFTER resize.
+
+```js
+// CORRECT
+frame.resize(700, 10);
+frame.primaryAxisSizingMode = "AUTO";
+frame.counterAxisSizingMode = "FIXED";
+```
+
+---
+
+## Rule 5: counterAxisAlignItems for cross-axis centering
+
+| Layout mode | primaryAxisAlignItems controls | counterAxisAlignItems controls |
+|-------------|-------------------------------|-------------------------------|
+| VERTICAL | Vertical alignment | Horizontal alignment |
+| HORIZONTAL | Horizontal alignment | Vertical alignment |
+
+```js
+// Center children horizontally in a vertical layout
+container.layoutMode = "VERTICAL";
+container.counterAxisAlignItems = "CENTER";
+```
+
+---
+
+## Rule 6: Always bind spacing variables (NEVER hardcode px)
+
+Every padding, gap, and radius value MUST use `setBoundVariable()` with a spacing token from the registry.
+
+**Load spacing keys from `registries/variables.json`.** Look for variables with names like `layout/spacing/*` and `layout/radius/*`.
+
+```js
+// Load spacing vars once at script start (keys from your registries/variables.json)
+var spLarge = await figma.variables.importVariableByKeyAsync("YOUR_SPACING_LARGE_KEY");
+var spMedium = await figma.variables.importVariableByKeyAsync("YOUR_SPACING_MEDIUM_KEY");
+var radMedium = await figma.variables.importVariableByKeyAsync("YOUR_RADIUS_MEDIUM_KEY");
+
+// Bind to frame
+frame.setBoundVariable('itemSpacing', spMedium);
+frame.setBoundVariable('paddingTop', spLarge);
+frame.setBoundVariable('paddingBottom', spLarge);
+frame.setBoundVariable('paddingLeft', spLarge);
+frame.setBoundVariable('paddingRight', spLarge);
+```
+
+**Helper:**
+```js
+function bindPadding(frame, top, right, bottom, left) {
+  if (top) frame.setBoundVariable("paddingTop", top);
+  if (right) frame.setBoundVariable("paddingRight", right);
+  if (bottom) frame.setBoundVariable("paddingBottom", bottom);
+  if (left) frame.setBoundVariable("paddingLeft", left);
+}
+
+function bindRadius(frame, radiusVar) {
+  frame.setBoundVariable("topLeftRadius", radiusVar);
+  frame.setBoundVariable("topRightRadius", radiusVar);
+  frame.setBoundVariable("bottomLeftRadius", radiusVar);
+  frame.setBoundVariable("bottomRightRadius", radiusVar);
+}
+```
+
+---
+
+## Rule 7: Colors via setBoundVariableForPaint (not setBoundVariable)
+
+Fills and strokes use a **different API** than layout properties.
+
+```js
+// WRONG
+frame.setBoundVariable('fills', colorVar);
+
+// CORRECT
+function mf(colorVar) {
+  var p = figma.util.solidPaint("#000000");
+  p = figma.variables.setBoundVariableForPaint(p, "color", colorVar);
+  return [p];
+}
+frame.fills = mf(myColorVar);
+```
+
+**Load color keys from `registries/variables.json`.** Look for variables with names like `color/background/*`, `color/text/*`, `color/border/*`.
+
+---
+
+## Rule 8: Text styles via importStyleByKeyAsync (NEVER hardcode fonts)
+
+Never set `fontName`, `fontSize`, or `lineHeight` manually. Always use text styles from the library.
+
+```js
+// WRONG
+text.fontName = { family: "Inter", style: "Bold" };
+text.fontSize = 32;
+
+// CORRECT (key from registries/text-styles.json)
+var style = await figma.importStyleByKeyAsync("YOUR_TEXT_STYLE_KEY");
+text.textStyleId = style.id;
+```
+
+**Load text style keys from `registries/text-styles.json`.**
+
+---
+
+## Rule 9: Component properties — add, bind, and override
+
+### 9a. addComponentProperty AFTER combineAsVariants
+
+```js
+var compSet = figma.combineAsVariants(components, figma.currentPage);
+compSet.addComponentProperty('title', 'TEXT', 'Default title');
+```
+
+### 9b. Bind TEXT properties to text nodes
+
+```js
+var titlePropKey = Object.keys(compSet.componentPropertyDefinitions)
+  .find(k => compSet.componentPropertyDefinitions[k].type === "TEXT" && k.startsWith("title"));
+
+for (var i = 0; i < compSet.children.length; i++) {
+  var variant = compSet.children[i];
+  var titleNode = variant.findOne(n => n.name === "title" && n.type === "TEXT");
+  if (titleNode && titlePropKey) {
+    titleNode.componentPropertyReferences = { characters: titlePropKey };
+  }
+}
+```
+
+### 9c. Override TEXT properties on instances
+
+```js
+var instance = variant.createInstance();
+var propDefs = compSet.componentPropertyDefinitions;
+for (var key in propDefs) {
+  if (key.startsWith("title") && propDefs[key].type === "TEXT") {
+    instance.setProperties({ [key]: "My custom title" });
+  }
+}
+```
+
+### 9d. INSTANCE_SWAP properties for icons
+
+```js
+compSet.addComponentProperty('icon', 'INSTANCE_SWAP', defaultIconId);
+var iconPropKey = Object.keys(compSet.componentPropertyDefinitions)
+  .find(k => k.startsWith("icon") && compSet.componentPropertyDefinitions[k].type === "INSTANCE_SWAP");
+
+for (var i = 0; i < compSet.children.length; i++) {
+  var variant = compSet.children[i];
+  var iconNode = variant.findOne(n => n.name === "icon" && n.type === "INSTANCE");
+  if (iconNode && iconPropKey) {
+    iconNode.componentPropertyReferences = { mainComponent: iconPropKey };
+  }
+}
+```
+
+### 9e. BOOLEAN properties for visibility
+
+```js
+compSet.addComponentProperty('showButton', 'BOOLEAN', true);
+var btnPropKey = Object.keys(compSet.componentPropertyDefinitions)
+  .find(k => k.startsWith("showButton"));
+
+for (var i = 0; i < compSet.children.length; i++) {
+  var variant = compSet.children[i];
+  var btnNode = variant.findOne(n => n.name === "button");
+  if (btnNode && btnPropKey) {
+    btnNode.componentPropertyReferences = { visible: btnPropKey };
+  }
+}
+```
+
+---
+
+## Rule 10: Property keys include hash suffix
+
+`componentPropertyDefinitions` returns keys like `title#9311:226`. Use the **full key** (with hash).
+
+```js
+function findPropKey(compSet, prefix, type) {
+  var defs = compSet.componentPropertyDefinitions;
+  return Object.keys(defs).find(function(k) {
+    return k.startsWith(prefix) && defs[k].type === type;
+  });
+}
+var titleKey = findPropKey(compSet, "title", "TEXT");
+```
+
+---
+
+## Rule 11: importComponentSetByKeyAsync vs importComponentByKeyAsync
+
+| What | API |
+|------|-----|
+| Component with variants (Button, Tag) | `importComponentSetByKeyAsync` |
+| Single component (icon, logo) | `importComponentByKeyAsync` |
+
+Check `registries/components.json` — entries with `variantCount > 1` are component sets.
+
+---
+
+## Rule 12: textAutoResize in auto-layout
+
+Set characters FIRST, append, FILL, then textAutoResize:
+
+```js
+var t = figma.createText();
+t.characters = "Long text...";
+parent.appendChild(t);
+t.layoutSizingHorizontal = "FILL";
+t.textAutoResize = "HEIGHT";
+```
+
+**GOTCHA:** `textAutoResize = "HEIGHT"` before the node has width → 0-width vertical text.
+
+---
+
+## Rule 13: strokeAlign INSIDE for cards
+
+```js
+card.strokes = mf(borderVar);
+card.strokeWeight = 1;
+card.strokeAlign = "INSIDE";
+```
+
+Always use `"INSIDE"` for cards, panels, inputs.
+
+---
+
+## Rule 14: Cannot add children to instances
+
+Component instances are sealed. Use `setProperties()` or `swapComponent()`.
+
+```js
+// WRONG
+inst.appendChild(extraFrame); // crashes
+
+// CORRECT
+inst.setProperties({ [titleKey]: "New title" });
+```
+
+---
+
+## Rule 15: Variant grid layout after combineAsVariants
+
+Variants stack at (0,0) after `combineAsVariants()`. Arrange in a grid:
+
+```js
+var cols = 4;
+for (var i = 0; i < compSet.children.length; i++) {
+  var child = compSet.children[i];
+  child.x = (i % cols) * (child.width + 40);
+  child.y = Math.floor(i / cols) * (child.height + 40);
+}
+```
+
+---
+
+## Rule 16: loadFontAsync before ANY text operation
+
+Every script that creates or modifies text MUST load fonts first:
+
+```js
+await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+await figma.loadFontAsync({ family: "Inter", style: "Medium" });
+await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
+await figma.loadFontAsync({ family: "Inter", style: "Bold" });
+```
+
+Load the fonts used in YOUR design system. Check `registries/text-styles.json` for font families.
+
+---
+
+## Rule 17: Script structure
+
+Every script executed via `figma_execute` MUST follow this structure:
+
+```js
+return (async function() {
+  // 1. Load fonts
+  // 2. Import variables + styles + components (keys from registries)
+  // 3. Define helpers (mf, appendFill, bindPadding, bindRadius)
+  // 4. Build layout tree (create → configure → append → FILL)
+  // 5. Return summary
+  return { success: true };
+})();
+```
+
+The `return` before the IIFE is mandatory — without it, the Promise is lost.
+
+---
+
+## Rule 18: DS component reuse — NEVER recreate existing components
+
+**This is the most critical rule. Violations require script rewrite.**
+
+Before creating ANY visual element, check the registries:
+1. `registries/components.json` → Buttons, Tags, Inputs, Avatars, Dividers, etc.
+2. `registries/icons.json` → Icons (if exists)
+3. `registries/logos.json` → Logos (if exists)
+4. `registries/illustrations.json` → Illustrations (if exists)
+
+**NEVER:**
+- Create a raw frame/ellipse for an Avatar → import the DS component
+- Create a raw rectangle for a Divider → import the DS component
+- Create a raw frame with text for a Tag/Badge → import the DS component
+- Hardcode hex colors → always bind variables
+
+**Pre-script checklist (mandatory):**
+```
+Elements in this step:
+- Avatar → components.json key: xxx ✓
+- Divider → components.json key: xxx ✓
+- Label → raw text (no DS component for this) ✓
+```
+
+---
+
+## Rule 19: Canvas positioning — never stack components
+
+- **NEVER** leave multiple components at (0, 0)
+- **Minimum gap**: 80px between components on the canvas
+- **Sub-components**: horizontal row at the top
+- **Main component**: 400px below sub-components
+
+```js
+var currentX = 0;
+for (var i = 0; i < subComponents.length; i++) {
+  subComponents[i].x = currentX;
+  subComponents[i].y = 0;
+  currentX += subComponents[i].width + 80;
+}
+mainComponent.x = 0;
+mainComponent.y = 400;
+```
+
+---
+
+## Standard Script Boilerplate
+
+```js
+return (async function() {
+
+  // ─── FONTS ───
+  // Load fonts used by your DS (check registries/text-styles.json for families)
+  await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+  await figma.loadFontAsync({ family: "Inter", style: "Medium" });
+  await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
+  await figma.loadFontAsync({ family: "Inter", style: "Bold" });
+
+  // ─── VARIABLES (from registries/variables.json) ───
+  // Load spacing, radius, and color variables by key
+  // var spLarge = await figma.variables.importVariableByKeyAsync("YOUR_KEY");
+  // var radMedium = await figma.variables.importVariableByKeyAsync("YOUR_KEY");
+  // var bgColor = await figma.variables.importVariableByKeyAsync("YOUR_KEY");
+
+  // ─── HELPERS ───
+  function mf(colorVar) {
+    var p = figma.util.solidPaint("#000000");
+    p = figma.variables.setBoundVariableForPaint(p, "color", colorVar);
+    return [p];
+  }
+
+  function appendFill(parent, child, fillH, fillV) {
+    parent.appendChild(child);
+    if (fillH) child.layoutSizingHorizontal = "FILL";
+    if (fillV) child.layoutSizingVertical = "FILL";
+  }
+
+  function bindPadding(frame, top, right, bottom, left) {
+    if (top) frame.setBoundVariable("paddingTop", top);
+    if (right) frame.setBoundVariable("paddingRight", right);
+    if (bottom) frame.setBoundVariable("paddingBottom", bottom);
+    if (left) frame.setBoundVariable("paddingLeft", left);
+  }
+
+  function bindRadius(frame, radiusVar) {
+    frame.setBoundVariable("topLeftRadius", radiusVar);
+    frame.setBoundVariable("topRightRadius", radiusVar);
+    frame.setBoundVariable("bottomLeftRadius", radiusVar);
+    frame.setBoundVariable("bottomRightRadius", radiusVar);
+  }
+
+  // ─── BUILD ───
+  // ... your design code here ...
+
+  return { success: true };
+})();
+```

package/skills/design-workflow/references/knowledge-base/README.md

@@ -0,0 +1,52 @@
+# Knowledge Base
+
+This directory contains your design system's complete documentation, generated by Claude during `/design-workflow setup`.
+
+## Structure
+
+```
+knowledge-base/
+  registries/                    ← Raw DS data (auto-extracted from Figma)
+    components.json              ← Component names, keys, variants, properties
+    variables.json               ← Variable names, keys, types, values by mode
+    text-styles.json             ← Text style names, keys, font specs
+    icons.json                   ← Icon component keys (optional)
+    logos.json                   ← Logo component keys (optional)
+    illustrations.json           ← Illustration keys (optional)
+
+  guides/                        ← Intelligent documentation (generated by Claude)
+    design-patterns.md           ← Layout patterns extracted from product screenshots
+    tokens/
+      color-usage.md             ← Color token decision tree
+      spacing-usage.md           ← Spacing scale + usage contexts
+      typography-usage.md        ← Type hierarchy + font families
+    components/
+      overview.md                ← Component decision tree (what to use when)
+      {group}.md                 ← Per-group guides (actions, form-controls, etc.)
+    patterns/
+      form-patterns.md           ← Form field patterns, validation
+      navigation-patterns.md     ← Sidebar, tabs, breadcrumbs
+      feedback-patterns.md       ← Success, error, warning, loading states
+      multi-step-flow.md         ← Stepper, progress, module flows
+    assets/
+      icons.md                   ← Categorized icon catalog
+      logos.md                   ← Logo catalog
+      illustrations.md           ← Illustration catalog + usage
+
+  ui-references/                 ← Product screenshots for pattern extraction
+    screenshots/                 ← PNG/JPG files of your product's key screens
+    ui-references-guide.md       ← Which screenshot for which pattern type
+```
+
+## How to populate
+
+Run `/design-workflow setup` in Claude Code. Claude will:
+
+1. **Extract** your DS from Figma via `figma_get_design_system_kit`
+2. **Analyze** the raw data and write intelligent guides
+3. **Ask for screenshots** of your product's key screens
+4. **Generate** layout pattern documentation from the screenshots
+
+## How to update
+
+When your DS evolves (new components, changed tokens), run `/design-workflow setup` again. Claude will detect existing registries and offer to update them incrementally.