@atelier-ui/create-workspace 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +27 -3
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
  4. package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
  5. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
  6. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
  7. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
  8. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
  9. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
  10. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
  11. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
  12. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
  13. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
  14. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
  15. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
  16. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
  17. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
  18. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
  19. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
  20. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
  21. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
  22. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
  23. package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
  24. package/src/generators/preset/files/contracts/README.md +6 -6
  25. package/src/generators/preset/files/contracts/types.ts.template +9 -10
  26. package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/check-contracts.mjs +236 -223
  27. package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/figma-snapshot-contracts.mjs +107 -92
  28. package/src/generators/preset/files/tools/design-contracts/src/codespec.mjs +234 -0
  29. package/src/generators/preset/files/tools/design-contracts/src/config.mjs +63 -0
  30. package/src/generators/preset/files/tools/{scripts/lib → design-contracts/src}/docgen.mjs +78 -98
  31. package/src/generators/preset/files/tools/{scripts/lib/ts-eval.js → design-contracts/src/ts-eval.cjs} +3 -4
  32. package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
  33. package/src/generators/preset/preset.js +79 -15
  34. package/src/generators/preset/preset.js.map +1 -1
@@ -0,0 +1,161 @@
1
+ # Naming and file structure
2
+
3
+ If a designer can't find a component in 30 seconds, they'll build a duplicate. Naming and file structure are what prevent that.
4
+
5
+ ## Slash naming convention
6
+
7
+ Figma turns every `/` in a name into a hierarchy level — in the asset panel picker, in the layer panel, and in the instance-swap menu. Use this deliberately.
8
+
9
+ ### For Components
10
+
11
+ ```
12
+ {ComponentName}/{Variant1}/{Variant2}
13
+ ```
14
+
15
+ Examples:
16
+
17
+ - `Button/Primary/Default`
18
+ - `Button/Primary/Hover`
19
+ - `Input/Text/Error`
20
+ - `Card/WithImage`
21
+
22
+ The first segment is the engineering component name — it's what designers and developers both use as the canonical reference. **Match it exactly to the code-side component name** (typically PascalCase: `Button`, `TextInput`, `IconButton`). Don't use `BTN` or `Btn` — use `Button`.
23
+
24
+ When the component is a Variant Set, the segments after the first are converted into Variant Properties at conversion time. Once converted, the segments live in the Properties panel, not in the layer name. Don't reintroduce them in the name post-conversion — that's a corrupted-variant bug.
25
+
26
+ ### For Variables
27
+
28
+ ```
29
+ {category}/{purpose}/{variant}/{state?}
30
+ ```
31
+
32
+ See `token-architecture.md` for examples and rules. Variables and Components both use `/`, but they live in separate panels — there's no conflict.
33
+
34
+ ### For Icons
35
+
36
+ Icons are **separate Components**, never a single Variant set with a `Name` property (Variant pickers don't show previews — an icon Variant set is unusable past 5 icons).
37
+
38
+ ```
39
+ Icon/{size}/{name}
40
+ ```
41
+
42
+ Examples:
43
+
44
+ - `Icon/16/Home`
45
+ - `Icon/16/Settings`
46
+ - `Icon/24/Home`
47
+ - `Icon/24/Settings`
48
+
49
+ The size segment makes sizes browsable as folders. If there's only one size, drop it: `Icon/Home`.
50
+
51
+ ### Sub-components — `_` and `.` prefix
52
+
53
+ Components prefixed with `_` or `.` are **excluded from publishing** — they're library-internal building blocks. Use this for:
54
+
55
+ - Slot placeholders (`_Slot/Default`)
56
+ - Internal sub-pieces designers shouldn't drag onto a canvas directly (e.g. `_ButtonContent`, `_CardShell`)
57
+ - Work-in-progress components not yet ready for the team
58
+
59
+ The user-facing library should only show the components designers should use. Atomic sub-components that are only useful inside other components should be hidden.
60
+
61
+ ## File / page structure for a Library file
62
+
63
+ A library file is **only for publishable components and reference material**. Working designs do not belong in the library file — they go in product files that consume the library.
64
+
65
+ The recommended page layout for a library file:
66
+
67
+ ```
68
+ 📐 Cover — the file thumbnail; library name, version, last-updated date
69
+ 🎨 Tokens — visual documentation of Variables: color swatches with names, type scale, spacing, shadows
70
+ 🔣 Icons — the icon set, browsable as folders
71
+ 🧩 Components/Actions — buttons, links, IconButton
72
+ 🧩 Components/Inputs — TextInput, Select, Checkbox, Radio, Toggle, Combobox
73
+ 🧩 Components/Feedback — Toast, Alert, Badge, Spinner
74
+ 🧩 Components/Overlays — Modal, Drawer, Popover, Tooltip
75
+ 🧩 Components/Navigation — NavBar, Sidebar, Tabs, Breadcrumb, Pagination
76
+ 🧩 Components/DataDisplay — Table, Card, Avatar, List
77
+ 🧩 Components/Layout — Divider, Container, Stack, Grid
78
+ 📋 Patterns — annotated reference designs (NOT publishable components)
79
+ 🧪 Playground — a sandbox for trying compositions; nothing here is published or linked
80
+ 🗄 Deprecated — retired masters kept visible with a "do not use" banner until analytics show zero insertions
81
+ 🚧 _Internal — sub-components prefixed with _ or .; not visible to consumers
82
+ 📝 Changelog — major updates, version notes
83
+ --------------------- — a hyphen-named spacer page divides sections in the page list
84
+ ```
85
+
86
+ Notes:
87
+
88
+ - **One page per category** scales well for libraries with 30+ components. A small library can collapse all components onto one `Components` page.
89
+ - **The Cover page** is what shows up as the file thumbnail. Figma's own minimum is name and a one-line description; a cover that earns its place adds version, status (draft / stable / deprecated tiers), owners, last-updated date, and links to the Storybook and docs site. Designers see it in the file browser; agents read it as the file's README.
90
+ - **Pages are a workflow, not a taxonomy.** Figma's guidance keeps signed-off work physically separate from work in flux — a "ready for dev" section or page, so nobody ships the wrong asset — and imposes the hierarchy once the direction has settled, not while exploring.
91
+ - **Documentation frames beside each component** — purpose, anatomy callouts, a properties table with defaults, do/don't, accessibility requirements, the Storybook link. Where the _canonical_ doc lives is contested (large orgs run an external site; Figma's Storybook plugin treats the two as co-equal); what every source agrees on is that a doc bound to live objects (descriptions, annotations that reference Variables) decays slower than prose, and that documentation is gated by a linter, not by trust.
92
+ - **Patterns** are not components. They're reference designs (e.g. "how to compose an empty state"). Don't publish them.
93
+ - **Deprecated** keeps the old master where designers will still find it, wearing its warning, until library analytics show zero insertions — deleting on a schedule breaks files; deleting on evidence doesn't.
94
+ - The page emoji is there for human navigability, not Figma's structure. It's optional but appreciated.
95
+
96
+ ## Sections vs. Frames — when to use which container
97
+
98
+ Both group children, but they serve different roles. Mixing them up is a recurring audit finding (FS4).
99
+
100
+ | Aspect | Section | Frame |
101
+ | ---------------------- | ----------------- | ----- |
102
+ | Auto Layout | ❌ | ✅ |
103
+ | Constraints | ❌ | ✅ |
104
+ | Clip content | ❌ | ✅ |
105
+ | Fills / strokes | ❌ | ✅ |
106
+ | Can nest in a Frame | ❌ | ✅ |
107
+ | `Ready for dev` marker | ✅ | ✅ |
108
+ | Asset-panel grouping | Page-level region | n/a |
109
+
110
+ **Rule:**
111
+
112
+ - **Page-level grouping** (e.g. "Tokens reference area", "All Buttons here", "Patterns gallery") → Section. Mark the Section Ready for dev when the group ships together.
113
+ - **Anything inside a component** — every variant frame, every nested layout container — → Frame. No exceptions.
114
+
115
+ A Section nested inside a Frame is invalid hierarchy and must be lifted out. A component built around a Section instead of a Frame loses every reflow guarantee.
116
+
117
+ ## File / page structure for a working file
118
+
119
+ A product / feature file is for current design work, not the library. Recommended pages:
120
+
121
+ ```
122
+ 📐 Cover — thumbnail, project name, status
123
+ 📊 Flow — user flows, IA diagrams
124
+ 🎨 Designs — current high-fidelity designs (one screen / state per frame)
125
+ 🧪 Exploration — earlier ideas, alternatives kept for reference
126
+ 💬 Feedback — review notes, comments anchored to specific designs
127
+ 💻 Handoff — final specs, often a mirror of Designs but cleaner
128
+ ```
129
+
130
+ Working files **consume** library components, but they don't define new ones. If a need for a new component arises during product work, sketch it on the Exploration page — when ready, promote it to the library file.
131
+
132
+ ## When to split into multiple library files
133
+
134
+ A single Figma file can hold a lot, but at some point splitting helps. Common splits:
135
+
136
+ - **Foundations / Tokens** in their own file. Components live in a separate file that consumes Foundations as a library. Allows tokens to be versioned and consumed independently of components.
137
+ - **Web vs. Mobile** components. Different prop APIs, different responsive concerns, different teams.
138
+ - **Brand library separate from product library.** Logo, brand colors, marketing illustrations live in Brand. Product UI components live in the product library. Brand is consumed by both product files and marketing files.
139
+
140
+ Don't split prematurely. The cost is real: more files to publish, more libraries to enable per project, more drift opportunities — designers "annoyed by having to enable too many libraries" is the practitioner phrase for it. Split when a concrete symptom appears, never on a schedule:
141
+
142
+ - The file has crossed the 2GB Figma limit or canvas rendering has visibly degraded, or
143
+ - Different teams own different parts and need independent publishing cadences, or
144
+ - A clear consumer/dependency boundary exists (foundations consumed by everything, components consumed by product files only).
145
+
146
+ Whatever you split, **keep every Variable collection in one parent file**: an alias cannot cross a file boundary, so a split that separates a semantic collection from the primitives it aliases breaks the tier model at the seam. Figma's own materials assume a multi-library reality for teams past a certain size (platform libraries, old and new system side by side during a migration); the single well-organised file is the right answer until one of the symptoms above shows up.
147
+
148
+ ## Audit signals for naming / structure
149
+
150
+ | Signal | Severity |
151
+ | ----------------------------------------------------------------------------------------- | ---------- |
152
+ | Component name doesn't match the engineering component name | Critical |
153
+ | `BTN`, `TXT`, abbreviated names | Warning |
154
+ | Variant Property values use casing that differs from code (`Small` vs `sm`) | Critical |
155
+ | Working designs found inside a published library file | Warning |
156
+ | Atomic sub-components are publishable (no `_` prefix) and clutter the asset panel | Warning |
157
+ | Icons modeled as a Variant set instead of separate Components | Critical |
158
+ | File has a single page named "Page 1" with everything on it | Critical |
159
+ | Cover page is empty or generic | Suggestion |
160
+ | No Patterns page or any reference for composition examples | Suggestion |
161
+ | Inconsistent slash depth across components (some `Button/Primary`, some `Button-Primary`) | Warning |
@@ -0,0 +1,79 @@
1
+ # Plugin API gotchas — what bit this repo through `figma_execute`
2
+
3
+ Load this before any `figma_execute` payload that creates, resizes or re-parents frames,
4
+ or edits text. Each item cost a real session: the first nine were recorded in
5
+ `tasks/lessons.md` between 2026-04 and 2026-09 while building 39 masters; the tool-level
6
+ traps at the end come from figma-console-mcp's own tool descriptions (v1.40.0). General
7
+ Plugin API knowledge (colours 0–1, `loadFontAsync`, `appendChild` order) is assumed —
8
+ this file is only the part that knowledge gets wrong.
9
+
10
+ ## Auto layout and sizing
11
+
12
+ - **`node.resize(w, h)` flips auto-layout axis sizing to FIXED on both axes.** To keep a
13
+ frame auto-sizing its height (`primaryAxisSizingMode = 'AUTO'`) after setting a width,
14
+ set the mode _after_ `.resize()`, not before; otherwise the frame collapses to the
15
+ resized height regardless of children. Hit in Progress body, Combobox panel/wrapper,
16
+ CodeBlock wrapper/body and Table inner container — all clipped or collapsed silently.
17
+ - **Setting `layoutMode` _after_ `.resize()` reverts both axes to AUTO.** The frame
18
+ shrink-wraps its children — a 32×32 circle with a "1" inside becomes a narrow pill.
19
+ Either set `layoutMode` first and size last, or re-assert `primaryAxisSizingMode` and
20
+ `counterAxisSizingMode` to `FIXED` and call `.resize()` once more.
21
+ - **`primaryAxisAlignItems = 'SPACE_BETWEEN'` with a single child centres it.** Hit the
22
+ CodeBlock `no-copy` header and every Combobox option row without a checkmark. Use
23
+ `'MIN'` plus `layoutGrow = 1` on the first child to push later items to the end.
24
+ - **`counterAxisAlignItems` is `'MIN' | 'MAX' | 'CENTER' | 'BASELINE'`** — `'START'` and
25
+ `'END'` throw a validation error.
26
+ - **`layoutPositioning = 'ABSOLUTE'` needs a parent whose `layoutMode !== 'NONE'`.**
27
+ Parent first (`parent.appendChild(node)`), then set positioning; on an unparented or
28
+ NONE-layout child it throws.
29
+
30
+ ## Sections and coordinates
31
+
32
+ - **Moving a SECTION does not move its children.** Section children sit in page-absolute
33
+ coordinates. After changing `section.y`, apply the same delta to every child
34
+ (`child.y += deltaY`), or reposition the component set explicitly
35
+ (`(sec.x + 24, sec.y + 92)` is the offset the Components page uses).
36
+
37
+ ## Text
38
+
39
+ - **Text in a fixed-width container will not wrap until `textAutoResize = 'HEIGHT'`.**
40
+ The default is `WIDTH_AND_HEIGHT`, so long strings overflow and get clipped by a
41
+ parent's `clipsContent`. Set HEIGHT, then resize the text width to the content-area
42
+ width.
43
+ - **Text edits on an INSTANCE through `figma_execute` fail silently.** The tool
44
+ description says so itself: use `figma_set_instance_properties` for instance text and
45
+ Booleans; touch text nodes directly only inside a COMPONENT or a plain FRAME.
46
+
47
+ ## Node ids and URLs
48
+
49
+ - **Node ids in URLs use `-`, the API uses `:`.** `?node-id=420-87` is node `420:87`.
50
+ `parameters.design` links in stories follow the URL form.
51
+ - **Ids are stable within a file and differ across duplicates.** A participant's
52
+ duplicate of the Atelier file has its own ids; resolve with `figma_search_components`
53
+ in the file you are actually editing, and remember the search also matches
54
+ _description_ text, so an unrelated component can surface.
55
+
56
+ ## Connection modes and REST
57
+
58
+ - **REST-backed tools (`figma_take_screenshot`, `figma_get_component_image`, variables
59
+ via the REST Variables API) 403 without `FIGMA_ACCESS_TOKEN` or on a non-Enterprise
60
+ plan for variables.** The Desktop Bridge channel still creates and modifies; read
61
+ `fills`, `boundVariables` and dimensions structurally via `figma_execute` when REST is
62
+ unavailable. `figma_get_variables` falls back Bridge → REST → styles on its own.
63
+ - **`figma_take_screenshot` (REST) can be cache-stale right after a write.** Use
64
+ `figma_capture_screenshot` (live) for the first look after a mutation.
65
+ - **`figma_execute` housekeeping the tool itself asks for:** screenshot before and after,
66
+ place new nodes inside a Section or Frame (never on bare canvas), delete orphaned nodes
67
+ from a failed attempt before retrying, return every created or mutated node id so the
68
+ next call can reference it. Default timeout 5 s, configurable to 30 s — split large
69
+ builds (the Inventory pipeline chunks at 25 components per call for this reason).
70
+ - **`figma_navigate({ lock: true })`** pins the target file so a reconnect or the human
71
+ clicking elsewhere cannot redirect later calls.
72
+
73
+ ## Batch limits
74
+
75
+ - `figma_batch_create_variables` / `figma_batch_update_variables`: 100 per call.
76
+ - `figma_create_component_set`: 100 variants hard cap, timeout scales ~1.2 s per variant;
77
+ split anything above ~40.
78
+ - Responses over 500 KB are auto-compressed or downgraded to summaries
79
+ (`figma_get_library_component_by_key`, `figma_get_design_system_kit`).
@@ -0,0 +1,279 @@
1
+ # Scaffold sub-mode — one-shot starter file
2
+
3
+ A sub-mode of Build for the case where the user wants a **lauffähiges Anfangsfile** in one turn, not a guided iterative build. Triggers on phrases like _scaffold, template, starter, quickstart, bootstrap a new file_.
4
+
5
+ The scaffold produces a **skeleton** — Cover + Tokens + Components pages with placeholder content that the user is expected to replace. It is not a finished design system; it is the structural decision-set, materialized.
6
+
7
+ ## When to use the scaffold sub-mode
8
+
9
+ ✅ Use it when the user says:
10
+
11
+ - "Set up a new Figma file from scratch"
12
+ - "Bootstrap our token system + a starter component"
13
+ - "I want a starter / template / scaffold for a new design system"
14
+
15
+ ❌ Don't use it when:
16
+
17
+ - The user already has a file and wants additions — that's the regular Build loop, with discovery first.
18
+ - The user wants a _finished_ design system — the scaffold is intentionally placeholder-quality.
19
+ - The user has specific brand values to seed — run the regular Build loop and use the user's values; don't paste over them with placeholders.
20
+
21
+ The trade-off is speed vs. specificity. The scaffold gets to a working file in one turn but bakes generic placeholder values; the regular Build loop produces specific values but takes 4–6 turns of dialogue.
22
+
23
+ ## What the scaffold produces
24
+
25
+ After running the recipe below, the file contains:
26
+
27
+ ```
28
+ Page: Cover
29
+ - Title text + author/date placeholders
30
+ - "Edit this skeleton" callout pointing at the next steps
31
+
32
+ Page: Tokens
33
+ - Variable Collection: "UI Tokens"
34
+ - Modes: Light, Dark
35
+ - Variables (12 placeholders):
36
+ primitive/teal/600 color, both modes
37
+ primitive/teal/700 color, both modes
38
+ primitive/slate/100 color, both modes
39
+ primitive/slate/700 color, both modes
40
+ color/primary semantic, alias to primitive/teal/600
41
+ color/primary-hover semantic, alias to primitive/teal/700
42
+ color/text semantic, alias to primitive/slate/700 (Light) / primitive/slate/100 (Dark)
43
+ color/surface semantic, alias to white (Light) / primitive/slate/700 (Dark)
44
+ color/border semantic, alias to primitive/slate/100 (Light) / primitive/slate/700 (Dark)
45
+ spacing/2 / spacing/4 / spacing/6 float, mode-invariant
46
+ radius/md float, mode-invariant
47
+
48
+ Page: Components
49
+ - One Component Set: ExampleButton
50
+ - 3 variants × 2 sizes = 6 frames, arranged with figma_arrange_component_set
51
+ - Fills bound to color/primary; text bound to a constant white for the demo
52
+ - Description on the set: "Replace with your real Button. This is a structural placeholder."
53
+ ```
54
+
55
+ Total writes: ~25 Variables, 1 Component Set, 3 page descriptions, 1 set description. ≈10 seconds end-to-end.
56
+
57
+ ## The recipe — three tool calls
58
+
59
+ ### Call 1 — `figma_setup_design_tokens`
60
+
61
+ Bootstraps the tokens in one atomic operation. Payload:
62
+
63
+ ```json
64
+ {
65
+ "collectionName": "UI Tokens",
66
+ "modes": ["Light", "Dark"],
67
+ "variables": [
68
+ { "name": "primitive/teal/600", "type": "COLOR", "scopes": ["FRAME_FILL", "SHAPE_FILL", "TEXT_FILL", "STROKE_COLOR"], "valuesByMode": { "Light": "#007070", "Dark": "#0a8080" } },
69
+ { "name": "primitive/teal/700", "type": "COLOR", "scopes": ["FRAME_FILL", "SHAPE_FILL", "TEXT_FILL", "STROKE_COLOR"], "valuesByMode": { "Light": "#005858", "Dark": "#0a6868" } },
70
+ { "name": "primitive/slate/100", "type": "COLOR", "scopes": ["FRAME_FILL", "SHAPE_FILL", "TEXT_FILL", "STROKE_COLOR"], "valuesByMode": { "Light": "#f1f5f9", "Dark": "#334155" } },
71
+ { "name": "primitive/slate/700", "type": "COLOR", "scopes": ["FRAME_FILL", "SHAPE_FILL", "TEXT_FILL", "STROKE_COLOR"], "valuesByMode": { "Light": "#334155", "Dark": "#cbd5e1" } },
72
+ { "name": "color/primary", "type": "COLOR", "scopes": ["FRAME_FILL", "SHAPE_FILL", "STROKE_COLOR"], "valuesByMode": { "Light": { "alias": "primitive/teal/600" }, "Dark": { "alias": "primitive/teal/600" } } },
73
+ { "name": "color/primary-hover", "type": "COLOR", "scopes": ["FRAME_FILL", "SHAPE_FILL", "STROKE_COLOR"], "valuesByMode": { "Light": { "alias": "primitive/teal/700" }, "Dark": { "alias": "primitive/teal/700" } } },
74
+ { "name": "color/text", "type": "COLOR", "scopes": ["TEXT_FILL"], "valuesByMode": { "Light": { "alias": "primitive/slate/700" }, "Dark": { "alias": "primitive/slate/100" } } },
75
+ { "name": "color/surface", "type": "COLOR", "scopes": ["FRAME_FILL", "SHAPE_FILL"], "valuesByMode": { "Light": "#ffffff", "Dark": { "alias": "primitive/slate/700" } } },
76
+ { "name": "color/border", "type": "COLOR", "scopes": ["STROKE_COLOR"], "valuesByMode": { "Light": { "alias": "primitive/slate/100" }, "Dark": { "alias": "primitive/slate/700" } } },
77
+ { "name": "spacing/2", "type": "FLOAT", "scopes": ["GAP", "WIDTH_HEIGHT"], "valuesByMode": { "Light": 8, "Dark": 8 } },
78
+ { "name": "spacing/4", "type": "FLOAT", "scopes": ["GAP", "WIDTH_HEIGHT"], "valuesByMode": { "Light": 16, "Dark": 16 } },
79
+ { "name": "spacing/6", "type": "FLOAT", "scopes": ["GAP", "WIDTH_HEIGHT"], "valuesByMode": { "Light": 24, "Dark": 24 } },
80
+ { "name": "radius/md", "type": "FLOAT", "scopes": ["CORNER_RADIUS"], "valuesByMode": { "Light": 8, "Dark": 8 } }
81
+ ]
82
+ }
83
+ ```
84
+
85
+ Notes about the choices:
86
+
87
+ - **Two primitives per family** is the minimum that makes the alias layer demonstrate value. A real system has 8–10 stops per family; the scaffold ships 2 to keep the example readable.
88
+ - **`color/text` etc. are semantic.** Note the inverted aliasing in Dark mode — same Variable, different alias per mode. This is the canonical Mode pattern; the scaffold demonstrates it intentionally.
89
+ - **Scopes are tightened on every semantic.** `color/text` is `TEXT_FILL` only — won't appear in stroke pickers, won't appear in spacing pickers. Default `ALL_SCOPES` is the most-common architectural mistake; the scaffold sets the right example.
90
+ - **`spacing/*` and `radius/md` are mode-invariant.** Most spacing systems are. Modes are reserved for theming axes.
91
+
92
+ ### Call 2 — `figma_execute` for pages + example Component
93
+
94
+ Creates Cover / Tokens / Components pages, builds the example Button variant frames, and binds their fills.
95
+
96
+ ```js
97
+ // figma_execute payload
98
+ await figma.loadAllPagesAsync();
99
+ await figma.loadFontAsync({ family: 'Inter', style: 'Medium' });
100
+ await figma.loadFontAsync({ family: 'Inter', style: 'Semi Bold' });
101
+
102
+ // 1. Pages — create if not present
103
+ function ensurePage(name) {
104
+ let page = figma.root.children.find((p) => p.name === name);
105
+ if (!page) {
106
+ page = figma.createPage();
107
+ page.name = name;
108
+ }
109
+ return page;
110
+ }
111
+ const cover = ensurePage('Cover');
112
+ const tokens = ensurePage('Tokens');
113
+ const components = ensurePage('Components');
114
+
115
+ // 2. Cover page — title + edit-me callout
116
+ figma.currentPage = cover;
117
+ const title = figma.createText();
118
+ title.fontName = { family: 'Inter', style: 'Semi Bold' };
119
+ title.fontSize = 64;
120
+ title.characters = 'Design system — replace this title';
121
+ title.x = 80;
122
+ title.y = 80;
123
+ cover.appendChild(title);
124
+
125
+ const note = figma.createText();
126
+ note.fontName = { family: 'Inter', style: 'Medium' };
127
+ note.fontSize = 16;
128
+ note.characters = 'This file is a scaffold. Replace the placeholder primary colour, ' + 'the example Button component, and this title with your real values.';
129
+ note.x = 80;
130
+ note.y = 200;
131
+ note.resize(640, note.height);
132
+ cover.appendChild(note);
133
+
134
+ // 3. Components page — build a 3×2 ExampleButton variant grid
135
+ figma.currentPage = components;
136
+
137
+ const primaryVar = figma.variables.getLocalVariables('COLOR').find((v) => v.name === 'color/primary');
138
+ const primaryHoverVar = figma.variables.getLocalVariables('COLOR').find((v) => v.name === 'color/primary-hover');
139
+ const radiusVar = figma.variables.getLocalVariables('FLOAT').find((v) => v.name === 'radius/md');
140
+
141
+ const variantConfigs = [
142
+ { variant: 'primary', size: 'sm', fillVar: primaryVar, padX: 12, padY: 6, fontSize: 13 },
143
+ { variant: 'primary', size: 'md', fillVar: primaryVar, padX: 16, padY: 8, fontSize: 14 },
144
+ { variant: 'secondary', size: 'sm', fillVar: null, padX: 12, padY: 6, fontSize: 13 },
145
+ { variant: 'secondary', size: 'md', fillVar: null, padX: 16, padY: 8, fontSize: 14 },
146
+ { variant: 'outline', size: 'sm', fillVar: null, padX: 12, padY: 6, fontSize: 13 },
147
+ { variant: 'outline', size: 'md', fillVar: null, padX: 16, padY: 8, fontSize: 14 },
148
+ ];
149
+
150
+ const variantNodes = [];
151
+ for (const cfg of variantConfigs) {
152
+ const frame = figma.createFrame();
153
+ frame.name = `variant=${cfg.variant}, size=${cfg.size}`;
154
+ frame.layoutMode = 'HORIZONTAL';
155
+ frame.layoutSizingHorizontal = 'HUG';
156
+ frame.layoutSizingVertical = 'HUG';
157
+ frame.primaryAxisAlignItems = 'CENTER';
158
+ frame.counterAxisAlignItems = 'CENTER';
159
+ frame.paddingLeft = frame.paddingRight = cfg.padX;
160
+ frame.paddingTop = frame.paddingBottom = cfg.padY;
161
+ frame.itemSpacing = 8;
162
+ frame.cornerRadius = 8;
163
+
164
+ // Bind corner radius to radius/md
165
+ if (radiusVar) frame.setBoundVariable('topLeftRadius', radiusVar);
166
+
167
+ // Bind fill or stroke per variant
168
+ if (cfg.variant === 'primary' && cfg.fillVar) {
169
+ const fill = { type: 'SOLID', color: { r: 0, g: 0.44, b: 0.44 } };
170
+ frame.fills = [figma.variables.setBoundVariableForPaint(fill, 'color', cfg.fillVar)];
171
+ } else if (cfg.variant === 'secondary') {
172
+ frame.fills = [{ type: 'SOLID', color: { r: 0.27, g: 0.33, b: 0.42 } }];
173
+ } else {
174
+ frame.fills = []; // outlined
175
+ frame.strokes = [{ type: 'SOLID', color: { r: 0, g: 0.44, b: 0.44 } }];
176
+ frame.strokeWeight = 1;
177
+ }
178
+
179
+ // Label
180
+ const label = figma.createText();
181
+ label.fontName = { family: 'Inter', style: 'Medium' };
182
+ label.characters = 'Button';
183
+ label.fontSize = cfg.fontSize;
184
+ label.fills = [
185
+ {
186
+ type: 'SOLID',
187
+ color: cfg.variant === 'outline' ? { r: 0, g: 0.44, b: 0.44 } : { r: 1, g: 1, b: 1 },
188
+ },
189
+ ];
190
+ frame.appendChild(label);
191
+
192
+ // Promote to Component
193
+ const component = figma.createComponentFromNode(frame);
194
+ variantNodes.push(component.id);
195
+ }
196
+
197
+ return { variantNodeIds: variantNodes, coverPageId: cover.id, tokensPageId: tokens.id, componentsPageId: components.id };
198
+ ```
199
+
200
+ ### Call 3 — `figma_arrange_component_set` + `figma_set_description`
201
+
202
+ Wrap the variant frames as a proper Component Set, then attach the documentation. Without these, the set looks like a flat group and won't surface in the asset panel correctly.
203
+
204
+ ```
205
+ figma_arrange_component_set(componentNodeIds: <variantNodeIds from call 2>)
206
+
207
+ figma_set_description(
208
+ componentSetId: <returned set ID>,
209
+ description: """
210
+ ExampleButton — placeholder
211
+
212
+ This component is part of the workspace scaffold. Use it as a starting point;
213
+ replace its visual design with your actual button. The Variant Property
214
+ structure (variant × size) is the recommended shape.
215
+
216
+ When replacing:
217
+ - Keep the Variant Property names (`variant`, `size`).
218
+ - Bind the primary fill to `color/primary` (already done).
219
+ - Bind the corner radius to `radius/md` (already done).
220
+ - Add states (hover / active / disabled) as a third Variant Property called `state`.
221
+ """
222
+ )
223
+ ```
224
+
225
+ ### Call 4 (optional) — Annotations + Ready-for-Dev marker
226
+
227
+ Make the skeleton **demo-ready** instead of just rendered. One short `figma_set_annotations` call on the `ExampleButton` plus a Ready-for-dev marker on the Components Section turns the scaffold into something the user can immediately hand to engineering for orientation.
228
+
229
+ ```
230
+ figma_set_annotations
231
+ nodeId: <ExampleButton component-set ID>
232
+ body: """
233
+ Replace this placeholder before publishing. Architectural shape (variant × size) is
234
+ intentional; visuals are not. Bind real fills to color/primary; add a `state` Variant
235
+ Property covering default / hover / focus / disabled / error / loading.
236
+ """
237
+ ```
238
+
239
+ Then mark the Components Section Ready-for-dev so the skeleton announces itself in Dev Mode:
240
+
241
+ ```js
242
+ // figma_execute payload — small, atomic
243
+ const componentsPage = figma.root.children.find((p) => p.name === 'Components');
244
+ const section = componentsPage?.children?.find((n) => n.type === 'SECTION');
245
+ if (section) section.devStatus = { type: 'READY_FOR_DEV' };
246
+ return { sectionId: section?.id, devStatus: section?.devStatus };
247
+ ```
248
+
249
+ Skip Call 4 when the user only wants the bare-bones rendering. Include it when the next person opening the file should see "this is a scaffold, here's the shape, here's where to start".
250
+
251
+ ## After the scaffold — what the user has to do
252
+
253
+ Hand back this checklist verbatim:
254
+
255
+ 1. **Replace the primary colour.** Open the Variables panel, find `primitive/teal/600` and `primitive/teal/700`, change the values to your brand palette. The semantic `color/primary` automatically follows the alias.
256
+ 2. **Add real spacing stops.** The scaffold ships only `spacing/2 / 4 / 6`. Add the rest of your scale (typically `0.5, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24` × 4px = your full system).
257
+ 3. **Replace the ExampleButton.** It is a placeholder. Use it as a structural template (variant × size), but redraw the visuals to match your actual design.
258
+ 4. **Add Modes if needed beyond Light / Dark.** Density modes (Comfortable / Compact), brand modes (Brand A / Brand B), or platform modes (Web / iOS / Android) are common.
259
+ 5. **Set the file's Cover with your real title, owners, and link to your spec / Storybook.**
260
+
261
+ The scaffold is intentionally sparse — every additional placeholder is a future cleanup task.
262
+
263
+ ## Variations the user might ask for
264
+
265
+ - **"Make it dark-mode-only."** Drop the `Light` mode entry from the `figma_setup_design_tokens` modes array; everything else stays.
266
+ - **"Add a `Brand A / Brand B` mode."** Extend the modes array to `['Light', 'Dark', 'Brand A']`. Note: the agent must seed values for every Variable in the new mode — the alias structure helps because most semantics already track via primitives.
267
+ - **"No example component, just tokens."** Skip Call 2's Components-page section and Call 3 entirely.
268
+ - **"Use Inter Bold instead of Semi Bold."** Single font change in the loadFontAsync calls and the title.
269
+
270
+ Decline (politely) if the user asks for the scaffold to ship "their full system, ready to go". The scaffold is a structural decision-set, not a finished system; pretending otherwise wastes both sides' time.
271
+
272
+ ## Validate after the scaffold
273
+
274
+ 1. `figma_take_screenshot` of the Components page bounding box.
275
+ 2. `figma_get_variables` and confirm 13 Variables exist with correct scopes (semantic ones tightened, primitives broad).
276
+ 3. Verify `color/primary` aliases through to `primitive/teal/600` in both modes.
277
+ 4. Switch the file's Mode to Dark and re-screenshot — confirm the example Button changes color (it should, because its fill is bound to `color/primary` which aliases to a primitive that has both mode values).
278
+
279
+ If the Mode switch doesn't change the color, the alias chain broke and the agent must re-bind. Most-common cause: the alias was set with a string value instead of `{ alias: '...' }`.
@@ -0,0 +1,98 @@
1
+ # Sync workflow
2
+
3
+ Sync mode handles **value drift after one side has moved**. Code-as-truth (token values, dimensions from spec) → push to Figma. Design-as-truth (frame dimensions only) → push to code. Different from Migrate: Migrate plans a coordinated structural change; Sync catches up on existing shape.
4
+
5
+ > **Bail to Migrate** the moment the diff includes adds / removes / renames rather than value updates only. Sync's batch-and-script approach won't apply the additive coordination protocol that downstream consumers need.
6
+
7
+ ## When to load this file
8
+
9
+ Load it when the user says any of:
10
+
11
+ - _"propagate to Figma"_, _"sync the lib tokens"_, _"keep Figma and code in lockstep"_
12
+ - _"the code just changed X, update Figma"_
13
+ - _"make Figma match the new spec"_
14
+
15
+ If the user is planning a _structural_ change (rename, split, deprecate), use `references/migration-playbook.md` instead.
16
+
17
+ ## The four steps
18
+
19
+ ### 1. Establish direction
20
+
21
+ Which side is the source of truth for _this_ change?
22
+
23
+ - Token values from CSS / JSON / spec file → **code-as-truth** (most common — design-led shop has the values in Figma; engineering-led shop has them in code).
24
+ - Figma frame dimensions → **design-as-truth** (rarer, but real for spec-defined widths/heights).
25
+ - Bidirectional → almost never the right answer. Pick one and enforce it.
26
+
27
+ Get this wrong and you'll overwrite real work on the other side. If the user is unclear, ask.
28
+
29
+ ### 2. Diff
30
+
31
+ Read the target side and list the deltas. Useful tools:
32
+
33
+ - `figma_get_variables` — Variable values per Mode.
34
+ - `figma_get_file_data` / `figma_get_design_system_kit` — full snapshot in one call.
35
+ - `figma_search_components` — locate the components affected.
36
+
37
+ Classify each delta into one of three buckets:
38
+
39
+ | Delta type | Approach in Sync |
40
+ | ----------------------------------------- | ------------------------------------------- |
41
+ | Variable value update (one or more modes) | Cheap, batch-able. Group into one call. |
42
+ | Frame dimension change (per-variant) | Per-variant, scripted. One `figma_execute`. |
43
+ | Structural change (rename, add, remove) | **Bail out** — switch to Migrate. |
44
+
45
+ If any delta is a structural change, stop here and run the migration playbook. Sync continues only if the diff is value-update + dimension-update only.
46
+
47
+ ### 3. Plan
48
+
49
+ Group similar deltas into the smallest number of atomic calls.
50
+
51
+ - **Variable updates:** one `figma_batch_update_variables` call per ~50–100 variables. The tool is atomic per call, so 200 updates = 2–4 calls, not 200.
52
+ - **Dimension changes:** one `figma_execute` script that walks the variants and resizes them. Returns the per-variant before/after dims for the report. See `references/code-sync.md` for the mass-resize recipe.
53
+ - **Annotations sync:** if code-side specs change in ways Figma should reflect (new easing curve, updated A11y note), use `figma_set_annotations` to write them back. Annotations are part of the value-drift surface, not just the structure surface.
54
+
55
+ Direction-of-truth patterns and code-side exporter integration live in `references/code-sync.md`.
56
+
57
+ ### 4. Execute, then validate
58
+
59
+ Run the batch + scripts, then re-audit:
60
+
61
+ - `figma_audit_component_accessibility` on the touched components.
62
+ - `figma_audit_design_system` on the file overall — capture the score for the summary.
63
+ - `figma_check_design_parity` against a `codeSpec` (schema in `references/code-sync.md`) — closes the loop. If parity score < 100, the discrepancies list is the next work; classify each as Figma-side or code-side fix.
64
+
65
+ The audit + parity check is the closing-the-loop check. If scores drop after Sync, you have new work — not a finished sync.
66
+
67
+ ### 5. Document
68
+
69
+ Output a Sync summary (see SKILL.md "Output expectations"). One small table beats prose:
70
+
71
+ ```markdown
72
+ | Direction | Count | Detail |
73
+ | ------------------ | ----- | ---------------------------------------------------------- |
74
+ | Variables updated | 47 | 23 in Light, 24 in Dark; 0 broken aliases |
75
+ | Frames resized | 18 | Button (6 variants) + Input (12 variants) |
76
+ | Components touched | 4 | Button, IconButton, Input, Select |
77
+ | Audit scores | | DS 76 → 82 (+6); A11y unchanged at 91 |
78
+ | Parity score | | 94/100 — 1 typography discrepancy on Input/sm |
79
+ | Left undone | | Code-side parity for Input/sm font-size — opens new ticket |
80
+ ```
81
+
82
+ ## When to escalate to Migrate
83
+
84
+ Stop Sync immediately and switch modes when the diff turns out to include:
85
+
86
+ - A **rename** on either side (matched-by-name swap will break consumers).
87
+ - An **add** or **remove** affecting published library shape.
88
+ - A **Variant Property value change** (existing instances reset to default).
89
+ - A **Mode rename** (library swap matches modes by exact name).
90
+
91
+ Migrate's additive coordination protocol exists exactly because batch-update can't safely cover these.
92
+
93
+ ## Common Sync traps
94
+
95
+ - **Mode-name casing mismatch.** Tokens-library has `Light` / `Dark`; consumer file has `light` / `dark`. Library swap matches by exact name — bindings break silently. Standardize before sync.
96
+ - **Hardcoded fallbacks in CSS.** `var(--ui-color-primary, #007070)` — old hex still wins when the Variable is undefined. After Sync, grep for the old hex in code; drop fallbacks or update them.
97
+ - **Aliases flattened in export.** Some exporters resolve aliases and emit only the leaf value. Sync the values; verify the exporter still preserves the semantic layer if you need it.
98
+ - **Annotations forgotten.** Variable values changed but the implementation note (animation curve, focus-ring delivery) didn't update. Catches up on `figma_set_annotations` are part of Sync, not a follow-up.