@atelier-ui/create-workspace 0.4.1 → 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.
- package/CHANGELOG.md +11 -0
- package/package.json +1 -1
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
- package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
- package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
- package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
- package/src/generators/preset/preset.js +52 -4
- package/src/generators/preset/preset.js.map +1 -1
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
# Build workflow
|
|
2
|
+
|
|
3
|
+
The Build mode loop in detail. Always run all six phases — skipping Discovery is the single most common cause of duplicate or conflicting tokens, and skipping Validate is how silent breakage ships.
|
|
4
|
+
|
|
5
|
+
> **Local Mode required.** All write operations need NPX or Local Git installation with the Desktop Bridge plugin running. If `figma_get_status` shows the bridge isn't connected, stop and fix that first — never try to "build offline" by emitting code without execution.
|
|
6
|
+
|
|
7
|
+
## Phase 1 — Discovery
|
|
8
|
+
|
|
9
|
+
Goal: know what already exists before adding anything.
|
|
10
|
+
|
|
11
|
+
Always start with:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
figma_get_status
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Confirm the bridge is connected and the right file is open.
|
|
18
|
+
|
|
19
|
+
Then, depending on what you're building:
|
|
20
|
+
|
|
21
|
+
| Building… | Run… |
|
|
22
|
+
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
23
|
+
| A token system from scratch | `figma_get_variables` to confirm there's nothing there yet |
|
|
24
|
+
| Adding tokens to existing | `figma_get_variables` — read every existing collection and mode |
|
|
25
|
+
| A new component | `figma_search_components` (does it already exist?), then `figma_get_file_data` and `figma_get_component` on related ones |
|
|
26
|
+
| An icon set | `figma_get_file_data` — find the existing Icons page if one exists |
|
|
27
|
+
| Restructuring a library | `figma_get_design_system_kit` (one-call snapshot) or `figma_get_file_data` + `figma_get_variables` |
|
|
28
|
+
|
|
29
|
+
**Search-then-instantiate over rebuild.** When the user describes a component that probably exists somewhere, run `figma_search_components` first. If a match comes back, `figma_instantiate_component` it into the target page rather than rebuilding from scratch. Re-creation is the most common cause of duplicate-component drift.
|
|
30
|
+
|
|
31
|
+
Output a brief inventory back to the user before proceeding: "I see your file has X collections (Y modes total) and Z components organized as ABC. I'm planning to add/change DEF — confirm?"
|
|
32
|
+
|
|
33
|
+
This isn't bureaucracy — it's the moment to catch "wait, we already have a `Color/Brand` collection, you don't need to make a new one."
|
|
34
|
+
|
|
35
|
+
## Phase 2 — Decide
|
|
36
|
+
|
|
37
|
+
Resolve all architectural questions before any write tool runs. Use `decision-heuristics.md` for the recurring forks.
|
|
38
|
+
|
|
39
|
+
Common decisions in a build:
|
|
40
|
+
|
|
41
|
+
- **For tokens:** Three-tier (Primitive / Semantic / Component) or two-tier? Modes at which tier? Which scopes per variable type?
|
|
42
|
+
- **For components:** Variant property axes — which become Variants, which become Boolean / Instance Swap properties? What's the slot strategy?
|
|
43
|
+
- **For naming:** Match an existing codebase convention or introduce one? PascalCase or kebab-case for variable paths?
|
|
44
|
+
|
|
45
|
+
If a decision genuinely depends on context only the user has, **ask** rather than guess. Reasonable questions to ask up front:
|
|
46
|
+
|
|
47
|
+
1. "Is there a code-side component library this should match? If yes, share the prop API of the relevant components."
|
|
48
|
+
2. "Will this need dark mode? Brand variants? Multi-tenant?"
|
|
49
|
+
3. "What's the canonical naming convention for tokens — camelCase, kebab-case, slash-separated?"
|
|
50
|
+
4. "Are there token names you've already committed to in code I should mirror?"
|
|
51
|
+
|
|
52
|
+
Don't ask everything — only what you can't infer.
|
|
53
|
+
|
|
54
|
+
## Phase 3 — Map tools
|
|
55
|
+
|
|
56
|
+
Translate the decisions into a tool sequence before running anything. Reference `tool-map.md` for the full menu. The most common builds:
|
|
57
|
+
|
|
58
|
+
### Build A — Bootstrap a token system
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
1. figma_setup_design_tokens → creates collection + modes + variables atomically
|
|
62
|
+
2. figma_execute → set scopes on each variable (Plugin API)
|
|
63
|
+
3. figma_take_screenshot → confirm visually
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`figma_setup_design_tokens` is preferred over orchestrating `figma_create_variable_collection` + `figma_add_mode` + `figma_batch_create_variables` separately — it's atomic, so a partial failure doesn't leave a half-built collection.
|
|
67
|
+
|
|
68
|
+
### Build B — Add a Mode (e.g. Dark) to existing tokens
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
1. figma_get_variables → read all current variables and aliases
|
|
72
|
+
2. figma_add_mode → add the new mode to each affected collection
|
|
73
|
+
3. figma_batch_update_variables → set values for the new mode
|
|
74
|
+
4. figma_take_screenshot → confirm a sample component switches modes correctly
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Build C — Add a new Component
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
1. figma_get_component → on a similar existing component for reference
|
|
81
|
+
2. figma_execute → create base frame with Auto Layout, fonts loaded
|
|
82
|
+
3. figma_execute → create each variant frame
|
|
83
|
+
4. figma_arrange_component_set → arrange variants into a proper Component Set
|
|
84
|
+
5. figma_set_description → markdown description with usage notes
|
|
85
|
+
6. figma_take_screenshot → confirm visually
|
|
86
|
+
7. figma_check_design_parity → if a code implementation already exists
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Build D — Refactor naming across a library
|
|
90
|
+
|
|
91
|
+
This is destructive. Confirm with the user explicitly first.
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
1. figma_get_variables → full inventory (export to chat for user review)
|
|
95
|
+
2. figma_get_file_data → component inventory
|
|
96
|
+
3. figma_rename_variable → one at a time (preserves aliases — safer than delete + recreate)
|
|
97
|
+
4. figma_execute → component renames via Plugin API node.name = "..."
|
|
98
|
+
5. figma_take_screenshot → spot check
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Phase 4 — Execute
|
|
102
|
+
|
|
103
|
+
Run the writes. Two non-negotiable rules:
|
|
104
|
+
|
|
105
|
+
1. **Every `figma_execute` payload that creates or mutates nodes must `return` all affected node IDs.** Subsequent calls reference those IDs. The agent only sees what's `return`ed; `console.log` output is invisible. Standard return shape:
|
|
106
|
+
|
|
107
|
+
```js
|
|
108
|
+
return { createdNodeIds: [...], mutatedNodeIds: [...], summary: "..." };
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
2. **Work incrementally — small steps, not one giant payload.** A 200-line `figma_execute` script that fails atomically (Figma's `figma_execute` is atomic — failed scripts make no changes) wastes time. Build in chunks: create the structure, validate, then populate.
|
|
112
|
+
|
|
113
|
+
Common gotchas (general Plugin API knowledge — out of scope here, but the agent must respect them):
|
|
114
|
+
|
|
115
|
+
- Colors are 0–1 range, not 0–255.
|
|
116
|
+
- `await figma.loadFontAsync(...)` before any text mutation.
|
|
117
|
+
- `await` every Promise.
|
|
118
|
+
- `parent.appendChild(child)` before setting `layoutSizingHorizontal/Vertical = 'FILL'`.
|
|
119
|
+
- New top-level frames default to (0,0) — position them away from existing content.
|
|
120
|
+
- Page context resets between `figma_execute` calls — use `await figma.setCurrentPageAsync(page)` at the top of each one if needed.
|
|
121
|
+
|
|
122
|
+
## Phase 5 — Validate
|
|
123
|
+
|
|
124
|
+
After every meaningful write step, take a screenshot. Don't wait until the end.
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
figma_take_screenshot
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Look for:
|
|
131
|
+
|
|
132
|
+
- **Cropped or clipped text** — line heights or fixed sizing cutting off characters.
|
|
133
|
+
- **Overlapping elements** — usually means an `appendChild` happened before sizing was set, or an Auto Layout direction was missed.
|
|
134
|
+
- **Placeholder text still visible** — "Heading", "Title", "Button" should have been replaced with the real defaults.
|
|
135
|
+
- **Wrong colors** — usually a missing or incorrect variable alias. Hover the layer in the screenshot panel and compare to the intended token.
|
|
136
|
+
- **Picker pollution** — if an audit follow-up is feasible, sample a property picker via `figma_execute` to confirm scopes are working (a color token shouldn't appear in a spacing picker).
|
|
137
|
+
|
|
138
|
+
If any issue is found, fix it with a **targeted** `figma_execute` call — don't rebuild from scratch. Atomic-ness is your friend: a small fix script that fails leaves the working state intact.
|
|
139
|
+
|
|
140
|
+
## Phase 6 — Document
|
|
141
|
+
|
|
142
|
+
Documentation is part of the build, not a follow-up. A component without a description is invisible to designers in the asset panel.
|
|
143
|
+
|
|
144
|
+
For every Component and Component Set created:
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
figma_set_description
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Use markdown. Recommended template:
|
|
151
|
+
|
|
152
|
+
```markdown
|
|
153
|
+
**Purpose.** One-line description of what it's for.
|
|
154
|
+
|
|
155
|
+
**Props.**
|
|
156
|
+
|
|
157
|
+
- `Variant` — primary | secondary | ghost
|
|
158
|
+
- `Size` — sm | md | lg
|
|
159
|
+
- `Disabled` — boolean
|
|
160
|
+
- `HasIcon` — boolean
|
|
161
|
+
|
|
162
|
+
**Use when.** Bullet list of valid use cases.
|
|
163
|
+
|
|
164
|
+
**Don't use when.** Bullet list of misuses or alternatives.
|
|
165
|
+
|
|
166
|
+
**Code.** `<Button variant="primary" size="md">` (mirrors the engineering API).
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Set descriptions on **shared Styles** too if you've created any — Effect Styles especially benefit from documentation.
|
|
170
|
+
|
|
171
|
+
For Variables, descriptions aren't typically per-variable (it would be too noisy). Instead, ensure the **collection** has a clear name and the variable **path** itself is self-documenting (`color/text/primary` needs no description; `color/c1/v3` needs a lot of explanation, and the right fix is renaming, not describing).
|
|
172
|
+
|
|
173
|
+
## Phase 7 — Annotate
|
|
174
|
+
|
|
175
|
+
Component descriptions explain the big picture; **annotations** carry the surgical handoff details that an engineer needs while implementing — and they surface in Dev Mode's Inspect panel, not in the asset panel. Set them after the description is in place.
|
|
176
|
+
|
|
177
|
+
Run for every non-trivial interactive component:
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
figma_set_annotations
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Anchor each annotation to the specific node it describes — the focus ring on the focus variant, the loading spinner on the loading variant, the tap-target padding on the surface frame. Examples of annotation content:
|
|
184
|
+
|
|
185
|
+
- _"Focus ring delivered via drop-shadow (4px primary outer + 2px surface gap), not stroke. Stroke contrast measures ~1.2:1 by design — see `code-verify.md`."_
|
|
186
|
+
- _"Tap target extends 8 px past visible border on every side. The visible component is 32 × 32; hit-area is 48 × 48."_
|
|
187
|
+
- _"Loading spinner uses `cubic-bezier(0.4, 0, 0.2, 1)` over 1.2 s. Reduce-motion users get a static dot — bound to `feature/reduce-motion`."_
|
|
188
|
+
|
|
189
|
+
Use `figma_get_annotation_categories` first to learn the categories defined for the file (different teams set different category sets).
|
|
190
|
+
|
|
191
|
+
When a Component description already says it, don't duplicate in an annotation. Annotations are for things that **only matter at the implementation spot**.
|
|
192
|
+
|
|
193
|
+
## Phase 8 — Mark Ready for Dev
|
|
194
|
+
|
|
195
|
+
The final step. Without it, downstream agents and the Dev-Mode UI treat the new content as work-in-progress and skip it.
|
|
196
|
+
|
|
197
|
+
```js
|
|
198
|
+
// figma_execute payload
|
|
199
|
+
const node = await figma.getNodeByIdAsync('123:456'); // the Section/Frame/Component just built
|
|
200
|
+
node.devStatus = { type: 'READY_FOR_DEV' };
|
|
201
|
+
return { id: node.id, devStatus: node.devStatus };
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
What to mark:
|
|
205
|
+
|
|
206
|
+
- The containing **Section** when an entire grouping is shipped together.
|
|
207
|
+
- The **Component** or **Component Set** when shipping individually.
|
|
208
|
+
- The **Frame** when shipping a screen or pattern that consumers should treat as canonical.
|
|
209
|
+
|
|
210
|
+
Don't mark the whole page Ready-for-dev — too coarse. Mark the artifact at the smallest stable scope.
|
|
211
|
+
|
|
212
|
+
## Optional — Inventory generation (sub-mode)
|
|
213
|
+
|
|
214
|
+
When the build's deliverable includes a visual catalog of the library — or the user explicitly asks to _generate inventory, build a gallery, library catalog, stickersheet, library overview_ — run the Inventory sub-mode after Validate (so the gallery only shows shipped components) and before Document.
|
|
215
|
+
|
|
216
|
+
The sub-mode is self-contained and lives in `references/inventory-generation.md`. Seven phases: Discover (one read-only call) → Group (pure JS) → Scaffold (one call) → Populate (one call **per top-level Section**, chunked in groups of 25 with `setTimeout(0)` yields) → Card builder (inside Populate) → Mark Ready + TOC (one call) → Validate (one screenshot per Section).
|
|
217
|
+
|
|
218
|
+
Hard rules — do not bundle multiple Sections into one `figma_execute`. Do not load every component's metadata in Phase 1 (only `id`, `name`, `type`). For Sections with more than 150 components, split across multiple calls passing the same `innerId`. The full batching contract is in `references/inventory-generation.md` § _Batching contract_.
|
|
219
|
+
|
|
220
|
+
## Pre-publish checklist
|
|
221
|
+
|
|
222
|
+
Before the user (or the agent) runs Library Publish, confirm:
|
|
223
|
+
|
|
224
|
+
- [ ] `figma_get_design_changes` shows no broken Variable / Component references introduced during the session.
|
|
225
|
+
- [ ] Every new Component has a description (`figma_set_description`) AND annotations on non-obvious spots.
|
|
226
|
+
- [ ] Slash naming consistent — Library Swap re-binds **by name match**; one typo desyncs every consumer file.
|
|
227
|
+
- [ ] Containing Section/Frame on Ready-for-dev.
|
|
228
|
+
- [ ] `figma_audit_design_system` ran at least once and the score was logged for trend tracking.
|
|
229
|
+
- [ ] Cover-page changelog entry drafted: what changed, why, who.
|
|
230
|
+
- [ ] If on **Branching** (Org/Enterprise), the work happened on a branch — publishing is from main only. Merge before publishing.
|
|
231
|
+
|
|
232
|
+
## Build summary — what to return to the user
|
|
233
|
+
|
|
234
|
+
After the loop completes, return a concise summary. Don't bury what was actually done.
|
|
235
|
+
|
|
236
|
+
Format:
|
|
237
|
+
|
|
238
|
+
```markdown
|
|
239
|
+
## Built
|
|
240
|
+
|
|
241
|
+
- 1 collection: `Brand Colors` (modes: Light, Dark)
|
|
242
|
+
- 24 variables (12 primitive + 12 semantic, all aliased)
|
|
243
|
+
- 3 components: `Button/Primary`, `Button/Secondary`, `Button/Ghost`
|
|
244
|
+
- 9 variants total (3 components × 3 states)
|
|
245
|
+
|
|
246
|
+
## Validated
|
|
247
|
+
|
|
248
|
+
- Screenshots taken: 4 (after token setup, after each component)
|
|
249
|
+
- All variables scoped (`FRAME_FILL` / `TEXT_FILL` / `STROKE_COLOR` per type)
|
|
250
|
+
- Descriptions set on all 3 components
|
|
251
|
+
|
|
252
|
+
## Not done
|
|
253
|
+
|
|
254
|
+
- Code-side mapping beyond naming alignment — figma-console-mcp doesn't implement Code Connect, and this skill explicitly does not recommend the official Figma MCP. Naming alignment is the bridge; if it's tight, code-gen tools infer the rest.
|
|
255
|
+
- Patterns / composition examples — recommend a follow-up to add a `Patterns` page.
|
|
256
|
+
|
|
257
|
+
## Notes
|
|
258
|
+
|
|
259
|
+
- Renamed `color/c1/v3` → `color/text/primary` during the process; references preserved.
|
|
260
|
+
```
|
package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
# Code-sync — Figma Variables ↔ code tokens
|
|
2
|
+
|
|
3
|
+
A workspace where Figma is in sync with the codebase is rarer than it should be. Most setups drift the moment a designer renames a Variable or a developer hardcodes a hex value "just for now". This file covers the architectural choices that determine whether a system stays in lockstep — not the mechanics of any specific exporter.
|
|
4
|
+
|
|
5
|
+
> **Out of scope here:** end-to-end Style Dictionary tutorials, Token Studio configuration UI walkthroughs, or platform-specific code-gen (iOS XML, Android Compose, etc.). Pick the sync direction and approach in this file; defer the wiring to the exporter's own docs.
|
|
6
|
+
|
|
7
|
+
## Pick a direction first
|
|
8
|
+
|
|
9
|
+
Bidirectional sync is the trap. Two systems both trying to be authoritative produce constant conflicts and force a manual reconciliation step that nobody wants to own.
|
|
10
|
+
|
|
11
|
+
| Direction | Choose when… | Cost |
|
|
12
|
+
| ----------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
|
|
13
|
+
| **Figma → code** | Design-led shop. Designers iterate in Figma; engineering consumes. Default for most product teams. | Need an export pipeline. Engineers can't tweak tokens directly. |
|
|
14
|
+
| **Code → Figma** | Engineering-led shop or token system originated in code (e.g. a tokens.json shipped with the lib). | Designers can't iterate freely. Updates require a PR. |
|
|
15
|
+
| **Bidirectional** | Almost never the right answer. Two sources fight every change. | Constant conflicts; reconciliation overhead. |
|
|
16
|
+
|
|
17
|
+
Pick one and **enforce** it: the non-canonical side is read-only. If both sides need write access, you have a process problem disguised as a tooling problem.
|
|
18
|
+
|
|
19
|
+
## Approaches
|
|
20
|
+
|
|
21
|
+
Four common ways to keep the two in lockstep, ordered by complexity.
|
|
22
|
+
|
|
23
|
+
### 1. Manual sync — only at very small scale
|
|
24
|
+
|
|
25
|
+
If you have ~30 tokens across one mode and one designer + one engineer who talk daily, manual sync via PR review is fine. The moment you cross 100 tokens, modes, or contributors, retire it.
|
|
26
|
+
|
|
27
|
+
Anti-pattern: pretending you have manual sync when you actually have **no sync** — the value drifted six weeks ago and nobody noticed.
|
|
28
|
+
|
|
29
|
+
### 2. Style Dictionary — recommended default for Figma → code
|
|
30
|
+
|
|
31
|
+
Reasonable choice for greenfield. Workflow:
|
|
32
|
+
|
|
33
|
+
1. Source-of-truth JSON tokens are committed to the repo (e.g. `tokens.source.json`).
|
|
34
|
+
2. A Figma export plugin/script writes the JSON from Figma Variables.
|
|
35
|
+
3. Style Dictionary transforms the JSON into per-platform outputs (CSS custom properties, Sass, JS, iOS, Android).
|
|
36
|
+
4. CI fails if the JSON drifts from the Figma file (re-export and diff).
|
|
37
|
+
|
|
38
|
+
Fits Figma → code. Modes map to Style Dictionary's "themes" or to nested keys per mode.
|
|
39
|
+
|
|
40
|
+
Trade-off: Style Dictionary doesn't read Figma directly — you still need an exporter (the `figma-console-mcp` `figma_get_variables` is one option; Token Studio exports another). Style Dictionary handles the _transformation_ layer, not the _extraction_ layer.
|
|
41
|
+
|
|
42
|
+
### 3. Token Studio — most popular for design-led teams
|
|
43
|
+
|
|
44
|
+
Figma plugin that stores Variables as JSON in a Git repo. Designers edit in Figma; the plugin commits the JSON. CI runs Style Dictionary (or similar) on the committed JSON to produce code outputs.
|
|
45
|
+
|
|
46
|
+
Strengths:
|
|
47
|
+
|
|
48
|
+
- Designers stay in their tool.
|
|
49
|
+
- Git history is the audit log.
|
|
50
|
+
- Free Studio version covers most needs.
|
|
51
|
+
|
|
52
|
+
Trade-offs:
|
|
53
|
+
|
|
54
|
+
- The Figma plugin has its own model; you trade the native Figma Variables editor for the plugin's UI in some workflows.
|
|
55
|
+
- Aliases inside Figma may export differently than expected; verify after first sync.
|
|
56
|
+
|
|
57
|
+
### 4. Custom export via `figma-console-mcp`
|
|
58
|
+
|
|
59
|
+
When Style Dictionary and Token Studio are too heavyweight or impose constraints you don't want, write a small script that calls `figma_get_variables`, walks the resulting tree, and writes platform outputs directly.
|
|
60
|
+
|
|
61
|
+
Sketch:
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
// figma-tokens-export.mjs
|
|
65
|
+
import fs from 'node:fs/promises';
|
|
66
|
+
const data = await getVariablesFromMcp(); // figma_get_variables
|
|
67
|
+
const cssLines = [];
|
|
68
|
+
for (const collection of data.meta.variableCollections) {
|
|
69
|
+
for (const mode of collection.modes) {
|
|
70
|
+
const selector = mode.name === 'Light' ? ':root' : `[data-theme="${mode.name.toLowerCase()}"]`;
|
|
71
|
+
cssLines.push(`${selector} {`);
|
|
72
|
+
for (const variable of Object.values(data.meta.variables)) {
|
|
73
|
+
if (variable.variableCollectionId !== collection.id) continue;
|
|
74
|
+
const value = resolveValue(variable.valuesByMode[mode.modeId], data);
|
|
75
|
+
cssLines.push(` --${cssNameFor(variable.name)}: ${formatValue(value, variable.resolvedType)};`);
|
|
76
|
+
}
|
|
77
|
+
cssLines.push('}');
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
await fs.writeFile('tokens.css', cssLines.join('\n'));
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Use this when:
|
|
84
|
+
|
|
85
|
+
- The token shape is unusual (e.g. multi-tier with aliases that flatten in Token Studio).
|
|
86
|
+
- You only target one platform (CSS) and the full Style Dictionary pipeline is overkill.
|
|
87
|
+
- You want CI to fail on drift and have full control over the diff.
|
|
88
|
+
|
|
89
|
+
Trade-off: you own the exporter forever. Plan for ~50 LOC to start, ~200 LOC after the first edge cases.
|
|
90
|
+
|
|
91
|
+
## Mode mapping — the most common bug
|
|
92
|
+
|
|
93
|
+
Most drift is silent because Modes are handled wrong. The mapping must be explicit.
|
|
94
|
+
|
|
95
|
+
| Figma Mode example | CSS pattern | JSON pattern |
|
|
96
|
+
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
97
|
+
| `Light` / `Dark` | `:root { … }` for Light; `[data-theme="dark"] { … }` and `@media (prefers-color-scheme: dark) { … }` for Dark | `{ "color": { "primary": { "light": "#…", "dark": "#…" } } }` |
|
|
98
|
+
| Density (`Comfortable` / `Compact`) | `[data-density="compact"] { … }` | Per-mode key, same shape as themes |
|
|
99
|
+
| Brand (`Brand A` / `Brand B`) | Per-brand selector or per-app build | Per-brand key |
|
|
100
|
+
|
|
101
|
+
Test: change a Variable's value in only one Mode in Figma; re-export; verify only one selector / key changed in code. If both changed, the exporter is collapsing modes.
|
|
102
|
+
|
|
103
|
+
## Annotations as a code-handoff layer
|
|
104
|
+
|
|
105
|
+
Variables carry the _static value_ contract; **annotations** carry the _implementation-detail_ contract — animation easings, focus-ring delivery mechanism, tap-target extensions, A11y notes. Treat them as a first-class part of code-sync, not as designer marginalia.
|
|
106
|
+
|
|
107
|
+
| Direction | What to do with annotations |
|
|
108
|
+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
+
| **Figma → code** | Pull annotations via `figma_get_annotations` after each export. Surface them in the same place as token diffs (PR description, Style Dictionary metadata, story `parameters.design`). |
|
|
110
|
+
| **Code → Figma** | When code-side specs change (e.g. animation tokens migrate to a new easing curve), write the new spec back into the relevant component's annotations via `figma_set_annotations`. The Figma file should never lag the code on implementation details a designer cares about. |
|
|
111
|
+
|
|
112
|
+
Annotation content that should round-trip:
|
|
113
|
+
|
|
114
|
+
- Focus-ring delivery (drop-shadow vs. stroke) — see `code-verify.md` for why this matters.
|
|
115
|
+
- Animation/easing tokens that are not Variables (because Figma can't bind effect-curves yet).
|
|
116
|
+
- Tap-target / safe-area extensions beyond the visible frame.
|
|
117
|
+
- A11y exceptions (e.g. "non-color cue delivered via inset shadow on fill" — common in danger buttons).
|
|
118
|
+
|
|
119
|
+
## Cross-file Variable resolution — linked libraries
|
|
120
|
+
|
|
121
|
+
A common architecture is **one Tokens file** (Primitive + Semantic Variables) consumed by **N Component files** as a linked library. The patterns below cover what to expect.
|
|
122
|
+
|
|
123
|
+
### What links cleanly
|
|
124
|
+
|
|
125
|
+
- **Variables**. Component files reference Tokens-library Variables by ID — values resolve at consume-time. Mode switches in the consuming file follow the local mode mapping.
|
|
126
|
+
- **Components**. Library components instantiate by `componentKey`; `figma_search_components` and `figma_get_library_components` find them across files.
|
|
127
|
+
|
|
128
|
+
### What does NOT auto-link
|
|
129
|
+
|
|
130
|
+
- **Mode names**. Library Swap matches Modes by **exact name**. If the Tokens file has `Light`/`Dark` and a consuming file has `light`/`dark`, the swap leaves bindings unresolved. Standardize casing across all files.
|
|
131
|
+
- **Variant Property values**. Same exact-name match rule. `Size: Small` in one file and `Size: small` in another won't merge cleanly.
|
|
132
|
+
|
|
133
|
+
### Cross-file discovery tools
|
|
134
|
+
|
|
135
|
+
| Tool | Use when… |
|
|
136
|
+
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
137
|
+
| `figma_get_library_components` | List a linked library's published components — what's available to instantiate. |
|
|
138
|
+
| `figma_get_design_system_kit` | Fetch tokens + components + styles from any file in one call. Useful when the agent needs to compare a Component file against the Tokens file. |
|
|
139
|
+
| `figma_search_components` | Find a component by name across the file or a linked library. |
|
|
140
|
+
|
|
141
|
+
### Audit signal — local Variables that should consume
|
|
142
|
+
|
|
143
|
+
A Component file that defines its own `color/*` Variables (instead of consuming the Tokens-library Variables) is a Critical drift source. In a properly linked setup, the Component file's Variable list should contain only **component-tier** Variables (if any) plus inherited library references. Local Primitive or Semantic Variables in a Component file mean someone built the file before linking the library, or the link broke.
|
|
144
|
+
|
|
145
|
+
## Closing the sync — `figma_check_design_parity`
|
|
146
|
+
|
|
147
|
+
End every Sync run with a parity check. Schema:
|
|
148
|
+
|
|
149
|
+
```jsonc
|
|
150
|
+
// Input — codeSpec (one block per axis you want compared)
|
|
151
|
+
{
|
|
152
|
+
"visual": {/* fills, strokes, opacity, radius */},
|
|
153
|
+
"spacing": {/* padding, gap, margins */},
|
|
154
|
+
"typography": {/* font family, size, weight, line-height, letter-spacing */},
|
|
155
|
+
"tokens": {/* expected Variable bindings */},
|
|
156
|
+
"componentAPI": {/* prop names + values */},
|
|
157
|
+
"accessibility": {/* roles, labels, contrast minimums */},
|
|
158
|
+
"metadata": {/* description text, slash-name shape */},
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Output:
|
|
163
|
+
|
|
164
|
+
```jsonc
|
|
165
|
+
{
|
|
166
|
+
"score": 0–100,
|
|
167
|
+
"discrepancies": [ /* per-axis diffs, severity-tagged */ ],
|
|
168
|
+
"actionItems": [ /* concrete fix steps */ ]
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Use `figma_scan_code_accessibility` (axe-core against rendered HTML, no Figma needed) to seed the `accessibility` axis before calling `figma_check_design_parity` — the `mapToCodeSpec` option produces input compatible with the parity tool.
|
|
173
|
+
|
|
174
|
+
Optional: when parity fails on a component the team needs to see in-Figma, drop a comment via `figma_post_comment` on the affected frame so the next designer who opens the file sees the drift even if they skim the chat output.
|
|
175
|
+
|
|
176
|
+
## Common drift sources
|
|
177
|
+
|
|
178
|
+
Add these to the Audit checklist's "Engineering-Sync Readiness" category — they are the failure modes to expect.
|
|
179
|
+
|
|
180
|
+
- **Variable scope mismatch.** A Variable with `ALL_SCOPES` (the default) shows up in property pickers it doesn't belong in. The export pipeline doesn't know the difference; designers will use the wrong token. Fix: set Scopes explicitly via `figma_execute` after creation. See `token-architecture.md`.
|
|
181
|
+
- **Renamed Variable not picked up.** Most exporters key by _name_, not ID. A rename = a delete + recreate from the exporter's view. Mitigation: enforce a `rename → run export → review diff` ritual.
|
|
182
|
+
- **Mode added in Figma, not propagated.** The exporter only knows about modes it has seen before. New mode = new branch in the output structure. Often forgotten.
|
|
183
|
+
- **Hardcoded fallbacks in CSS.** `color: var(--ui-color-primary, #007070);` — the fallback hex _was_ the Figma value six months ago. Now the Figma value is `#0a8080` but the fallback is still `#007070` and silently wins when the Variable is undefined. Fix: drop fallbacks, or enforce a CI check that fallbacks match the resolved Variable value.
|
|
184
|
+
- **Aliases flattened in export.** Figma supports `--ui-color-primary → primitive/teal/600`. Some exporters resolve the alias and emit only the leaf value, losing the semantic layer. Fix: emit both or document the choice explicitly.
|
|
185
|
+
- **Manual edits to the generated file.** Someone tweaks `tokens.css` directly. Next export overwrites it. Fix: top-of-file banner saying `/* AUTO-GENERATED — do not edit. Source: Figma Variables. */` and a CI check that the file is committed unchanged after a fresh export.
|
|
186
|
+
|
|
187
|
+
## Example from the Atelier UI repo (does not apply to a generated workspace)
|
|
188
|
+
|
|
189
|
+
_This section describes the Atelier monorepo itself, as a worked example of the "pick a
|
|
190
|
+
direction" question above. The paths, scripts and ADRs it names exist only in that repo, not in
|
|
191
|
+
a workspace generated from it; skip it there._
|
|
192
|
+
|
|
193
|
+
Token _value_ ownership across Figma, the framework libs, and the artboard/skill copies is
|
|
194
|
+
mapped by axis in ADR-0115 — read that first for the full picture. This section is that
|
|
195
|
+
map's instance of the "pick a direction" question above, for this repo specifically. (An
|
|
196
|
+
earlier version of this section named the pre-ADR-0030 state — the superseded `UI Tokens`
|
|
197
|
+
collection, a bidirectional/manual model — and has been corrected below.)
|
|
198
|
+
|
|
199
|
+
- **Code owns the value.** The canonical file is
|
|
200
|
+
`libs/styles/src/tokens.css`. Every other
|
|
201
|
+
`tokens.css`-shaped file — `libs/{angular,react,vue}/src/styles/tokens.css`, the scaffold seed,
|
|
202
|
+
`skills/atelier-design/assets/colors_and_type.css` — is a generated, byte-identical
|
|
203
|
+
projection of it (`tools/scripts/sync-tokens.mjs`, gated by `npm run check:tokens`).
|
|
204
|
+
`libs/create-workspace/src/generators/preset/files/styles/tokens.css` (the scaffold seed)
|
|
205
|
+
is one of those projections too. `docs/src/styles/tokens.css` isn't a copy at all; it
|
|
206
|
+
`@import`s the source live.
|
|
207
|
+
- **Figma's `Library Tokens` Variable Collection is also a generated projection, not an
|
|
208
|
+
independent source** (ADR-0030 — the docs site's own brand system is a separate
|
|
209
|
+
collection, renamed `Docs Brand Tokens` in that same decision, and out of scope here).
|
|
210
|
+
`tools/scripts/gen-figma-library-tokens.mjs` parses the canonical file above into
|
|
211
|
+
variable definitions, and `npm run figma:sync-tokens` pushes them into Figma — one-way,
|
|
212
|
+
code → Figma. Editing the Variable directly in Figma is drift by definition (ADR-0030's
|
|
213
|
+
Decision §1), not a legitimate entry point.
|
|
214
|
+
- What genuinely stays a manual, PR-reconciled step — the "very small scale" case from §1
|
|
215
|
+
above — is _triggering_ that push: `figma:sync-tokens` needs Figma Desktop with the
|
|
216
|
+
Bridge plugin open, so it is not part of `check:all`, and nothing pulls a Figma-side edit
|
|
217
|
+
back into code at all. Approach #4's export half already shipped this way; its CI-checked
|
|
218
|
+
half (`check:tokens`) only watches the code-side copies, not the Figma side.
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# Code-side visual verification
|
|
2
|
+
|
|
3
|
+
When a token, variant, or component change in Figma has a downstream visual effect in the consuming code repo, verify it actually renders the way the new spec promises — _before_ declaring the change done.
|
|
4
|
+
|
|
5
|
+
This is a manual recipe, not an automated submode. It runs in ~5–15 minutes per change and catches the class of bug where Figma and code are individually correct but their handoff (CSS variable name, mode-aware override, theme-toggle wiring) is broken.
|
|
6
|
+
|
|
7
|
+
## When to run this recipe
|
|
8
|
+
|
|
9
|
+
Trigger it after any of these changes touch a token / component that has a paired code-side artifact:
|
|
10
|
+
|
|
11
|
+
- **Token consolidation or rename** (e.g. dropping `--ui-color-on-primary`, folding semantics into `--ui-color-text-on-primary`). Mode-aware overrides are the most common silent break.
|
|
12
|
+
- **Mode-value change** on a Semantic-tier variable (Light + Dark must both render correctly).
|
|
13
|
+
- **Variant Property rename or value change** that the code's prop API relies on — verify the component still renders for each value.
|
|
14
|
+
- **A11y fix** that depends on a computed contrast ratio (loading spinner color, focus ring) — eyeball is not enough; read computed values.
|
|
15
|
+
|
|
16
|
+
Skip it for:
|
|
17
|
+
|
|
18
|
+
- Pure-Figma changes with no code-side artifact (icon-set additions, page reorganization, Component descriptions).
|
|
19
|
+
- Code changes whose effect is covered by an existing visual regression test.
|
|
20
|
+
|
|
21
|
+
## Pre-flight
|
|
22
|
+
|
|
23
|
+
Before starting, confirm:
|
|
24
|
+
|
|
25
|
+
1. **Repo has Storybook** (or an equivalent component-rendering target — Histoire, Ladle, or a component-demo Vite app). If not, fall back to running the consuming app and navigating to a page using the affected component.
|
|
26
|
+
2. **Browser-automation MCP is available** (`claude-in-chrome` or equivalent). If not, the agent reports computed values manually by asking the user to paste them — slower but workable.
|
|
27
|
+
3. **Theme switching mechanism is known** for the target setup. Check the Storybook `preview.ts` decorator or the consuming app's theme provider:
|
|
28
|
+
- URL parameter (`?theme=dark`)
|
|
29
|
+
- HTML attribute (`data-theme="dark"` on `<html>` or `<body>`)
|
|
30
|
+
- Decorator-driven via `globals.backgrounds.value` (Storybook's default)
|
|
31
|
+
- JS callable (`setTheme('dark')`)
|
|
32
|
+
|
|
33
|
+
Note the mechanism — different setups need different "switch to dark mode" steps.
|
|
34
|
+
|
|
35
|
+
## Recipe
|
|
36
|
+
|
|
37
|
+
### 1. Start the rendering target
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
# Storybook
|
|
41
|
+
nx run <framework>:storybook # Nx repos
|
|
42
|
+
npm run storybook # plain repos
|
|
43
|
+
|
|
44
|
+
# Or the consuming app
|
|
45
|
+
nx serve <app-name>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Background the process (don't block the chat). Capture the local URL (`http://localhost:4400` or similar).
|
|
49
|
+
|
|
50
|
+
### 2. Open the relevant story / page in the browser
|
|
51
|
+
|
|
52
|
+
For Storybook:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
http://localhost:<port>/?path=/story/<category>-<component>--<story>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The story ID matches the file's title hierarchy (e.g. `title: 'Components/Inputs/LlmButton'`, story name `Primary` → `components-inputs-llmbutton--primary`). When the URL guess fails, navigate to the Storybook root and click through the sidebar.
|
|
59
|
+
|
|
60
|
+
### 3. Switch the theme
|
|
61
|
+
|
|
62
|
+
Use the setup-appropriate mechanism. Two common patterns:
|
|
63
|
+
|
|
64
|
+
**URL-based (cleanest, no JS hacking):**
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
?path=...&globals=backgrounds.value:dark
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**JS-direct (when the URL parameter doesn't bind to the right state):**
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
const iframe = document.querySelector('#storybook-preview-iframe');
|
|
74
|
+
const doc = iframe.contentDocument;
|
|
75
|
+
doc.documentElement.setAttribute('data-theme', 'dark');
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Trap:** Storybook's `backgrounds.value` may or may not propagate through to your `data-theme` attribute, depending on the decorator. Check `preview.ts` — many decorators have a stale comparison (`=== '#1a1a2e'` when the value is now the option key like `'dark'`). If the visual doesn't change after the URL toggle, the decorator is broken — fix that first.
|
|
79
|
+
|
|
80
|
+
### 4. Read computed values for the affected token / element
|
|
81
|
+
|
|
82
|
+
In claude-in-chrome:
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
(() => {
|
|
86
|
+
const iframe = document.querySelector('#storybook-preview-iframe');
|
|
87
|
+
const doc = iframe.contentDocument;
|
|
88
|
+
const win = iframe.contentWindow;
|
|
89
|
+
const target = doc.querySelector('<your selector — e.g. .llm-button.variant-primary or llm-button>');
|
|
90
|
+
const cs = win.getComputedStyle(target);
|
|
91
|
+
return {
|
|
92
|
+
htmlTheme: doc.documentElement.getAttribute('data-theme'),
|
|
93
|
+
bg: cs.backgroundColor,
|
|
94
|
+
color: cs.color,
|
|
95
|
+
// Add any other property that the change is supposed to affect
|
|
96
|
+
};
|
|
97
|
+
})();
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The result tells you the real rendered values. Convert RGB → hex if you need to compare to Figma values:
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
rgb(0, 208, 208) → #00d0d0
|
|
104
|
+
rgb(15, 23, 42) → #0f172a
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### 5. Compare against the spec
|
|
108
|
+
|
|
109
|
+
Run the same query in light mode (`data-theme="light"`). Compare:
|
|
110
|
+
|
|
111
|
+
| Property | Light expected | Light actual | Dark expected | Dark actual |
|
|
112
|
+
| ---------- | -------------- | ------------ | ------------- | ----------- |
|
|
113
|
+
| background | `#007070` | `#007070` | `#00d0d0` | `#00d0d0` |
|
|
114
|
+
| color | `#ffffff` | `#ffffff` | `#0f172a` | `#0f172a` |
|
|
115
|
+
|
|
116
|
+
**Pass:** all four cells match.
|
|
117
|
+
**Fail:** any mismatch — the token consolidation, mode-override, or theme-toggle wiring is broken; investigate before declaring done.
|
|
118
|
+
|
|
119
|
+
### 6. Optional: screenshot for the report
|
|
120
|
+
|
|
121
|
+
If the change is being shipped as a PR or audit-follow-up, capture a screenshot in each mode using `figma_capture_screenshot` (Figma side) and the browser-automation tool's `screenshot` action (code side). Place them side-by-side in the PR description.
|
|
122
|
+
|
|
123
|
+
### 7. Optional: round-trip check via `figma_scan_code_accessibility` + `figma_check_design_parity`
|
|
124
|
+
|
|
125
|
+
Before manual computed-value reading, run axe-core on the rendered HTML — it catches a class of issues (missing roles, contrast at unrendered focus states, label/aria mismatches) that is hard to spot by eye.
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
figma_scan_code_accessibility
|
|
129
|
+
url: http://localhost:<port>/?path=/story/<story-id>
|
|
130
|
+
mapToCodeSpec: true
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The `mapToCodeSpec: true` option emits the result in the shape `figma_check_design_parity` consumes for its `accessibility` axis. Pipe the two:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
1. figma_scan_code_accessibility (mapToCodeSpec: true) → codeSpec
|
|
137
|
+
2. figma_check_design_parity (codeSpec, figmaComponentId) → score + discrepancies
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
If parity score < 100, the discrepancies list is the work; tag each as a Figma-side fix or a code-side fix and proceed.
|
|
141
|
+
|
|
142
|
+
### 8. Tear down
|
|
143
|
+
|
|
144
|
+
Stop the dev-server background task. The recipe is complete.
|
|
145
|
+
|
|
146
|
+
## Common traps
|
|
147
|
+
|
|
148
|
+
- **Storybook decorator's theme-value comparison is stale.** Compare against the option _key_ (e.g. `'dark'`), not the hex value (`'#1a1a2e'`). Storybook 10 surfaces the key in `globals.backgrounds.value`. If the decorator was written before this convention, fix it as part of the verification step.
|
|
149
|
+
- **Iframe access is blocked by sensitive-key protection** in some browser-automation setups. Read computed values via the iframe's own `contentWindow.getComputedStyle`, not by reading inline `style` attributes (which may not exist when values come from CSS variables).
|
|
150
|
+
- **Component is a Web Component / custom element** (e.g. Angular's `<llm-button>`). The default `querySelector('button')` will miss it. Use the actual custom-element tag name from the framework.
|
|
151
|
+
- **Caching of CSS variables across HMR.** If a token rename doesn't visually update after a hot reload, hard-reload the iframe (`location.reload()` inside the preview iframe). Vite's HMR sometimes preserves stale `:root` definitions.
|
|
152
|
+
- **No visible change despite correct token values.** The token may be set correctly but no element binds to it — confirm that the component CSS actually uses `var(--<token>)` and not a hardcoded fallback.
|