@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.
Files changed (26) hide show
  1. package/CHANGELOG.md +11 -0
  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/tools/scripts/preflight.mjs +1 -1
  25. package/src/generators/preset/preset.js +52 -4
  26. package/src/generators/preset/preset.js.map +1 -1
@@ -0,0 +1,462 @@
1
+ # Audit checklist
2
+
3
+ The architectural deep-audit. Run this **after** the figma-console-mcp Design System Dashboard MCP App (it covers breadth, including A11y and Coverage). This file covers depth in five categories that the dashboard does not reach.
4
+
5
+ ## Severity definitions
6
+
7
+ Use these consistently. The audit report priority list ranks findings by severity, then by effort to fix.
8
+
9
+ | Severity | Definition |
10
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | **Blocker** | Breaks the system's ability to function: dark mode is impossible, file won't open, library can't publish. Fix immediately. |
12
+ | **Critical** | Causes daily friction or guarantees future rework: wrong scopes, naming mismatches with code, no semantic layer. Fix this sprint. |
13
+ | **Warning** | Adds maintenance debt: loose conventions, missing descriptions, anti-patterns that work but don't scale. Fix when you touch the area. |
14
+ | **Suggestion** | Nice-to-have: cosmetic, polish, or "consider this convention". Optional. |
15
+
16
+ A finding's severity is a function of (a) how much breakage it causes and (b) how hard it is to undo later. Naming mistakes propagate everywhere and are painful to undo — they're usually Critical even if they "work today".
17
+
18
+ ## Inputs
19
+
20
+ Before running through the categories, gather:
21
+
22
+ ```
23
+ figma_get_status → confirm bridge connected
24
+ figma_get_file_data → file structure, pages, top-level frames; capture `lastModified`
25
+ figma_get_variables → all collections, modes, variables
26
+ figma_get_styles → legacy styles still in use
27
+ figma_get_component on samples → spot-check a few representative components
28
+ ```
29
+
30
+ If a Design System Dashboard run is available (MCP App), include its overall score and category scores in the audit context.
31
+
32
+ ### Pin the snapshot
33
+
34
+ Audits go stale fast. Before writing the report, capture two pins so a later reader (including future-you) can tell whether findings still apply:
35
+
36
+ - **Git SHA** — if there's a paired code repo, run `git rev-parse --short HEAD` in it and put the value into the report's `Generated against` line.
37
+ - **Figma `lastModified`** — from `figma_get_file_data`, in the same line.
38
+
39
+ If either pin moves before someone acts on a finding, that finding needs re-verification, not blind execution.
40
+
41
+ ### Cross-source check (when there's a paired code repo)
42
+
43
+ Token-architecture findings often look very different once you check the code side. Two cheap, high-signal greps before writing TA, N, or ES findings:
44
+
45
+ - For each Variable named in a finding (e.g. `color/on-primary`), grep the repo's token CSS / SCSS / TS / JSON for the matching code-side identifier (`--ui-color-on-primary`, `colorOnPrimary`, etc.). A "duplicate Figma variable" with zero code references is a different fix than one with active code usage and _different mode behavior_.
46
+ - For each Component-Set Variant Property value (e.g. `variant=outline`), grep for the literal in component source (`variant: 'outline'`, `<LlmButton variant="outline">`). Mismatch is an N1 / ES2 finding even if both sides individually look fine.
47
+
48
+ Treat the grep result as part of the finding's State block — at minimum a count of matches and one representative path.
49
+
50
+ ## Category 1 — Token Architecture
51
+
52
+ Two rules for every finding in this category, learned the expensive way:
53
+
54
+ - **"Unused" and "duplicate" are claims about consumers, and consumers span files.** Before a
55
+ finding says a collection or variable is dead, enumerate who binds to it — the
56
+ docs-site collection, a second library file, `codeSyntax` bindings, aliases from
57
+ another collection — and name the tool call that proved it (`figma_get_variables`
58
+ with `resolveAliases`, `figma_get_library_variables`). An audit of this repo's own file
59
+ once called a primitives collection "a dead duplicate, zero risk to delete" without
60
+ reading the docs collection it fed.
61
+ - **The fix column never says "delete" or "rebind" alone.** Deleting or renaming a
62
+ Variable, Collection or Mode, or rebinding consumers, is a Migrate operation with a
63
+ safety class from `migration-playbook.md` — Breaking ones carry the additive
64
+ coordination protocol. Write the fix as "Migrate: <recipe>", not as a one-liner.
65
+
66
+ ### TA1 — Tier separation
67
+
68
+ Check: are Primitives, Semantics, and (optionally) Component tokens in **separate Collections**?
69
+
70
+ | State | Severity | Fix |
71
+ | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
72
+ | All variables in one collection | Critical | Split into Primitive + Semantic collections. Move raw values to Primitives, aliases to Semantics. |
73
+ | Two collections but mixed: Primitives contain semantics or vice versa | Critical | Re-classify each variable; raw values to Primitives, purpose-named ones to Semantics. |
74
+ | Three+ collections, cleanly separated | (pass) | — |
75
+
76
+ ### TA2 — Mode placement
77
+
78
+ Check: where do Modes live?
79
+
80
+ | State | Severity | Fix |
81
+ | ---------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
82
+ | Modes on the Primitive collection | Critical | Modes belong on Semantics. Move them. Primitives should be single-mode. |
83
+ | Modes on Semantic collection (Light/Dark, Brand-A/Brand-B) | (pass) | — |
84
+ | No modes at all but the product needs theming | Blocker (if dark mode is on roadmap), else Warning | Introduce a Light/Dark mode pair on the Semantic collection. |
85
+ | Mode names are vague: "Theme 1", "Default" | Warning | Rename to "Light", "Dark", "Brand-A", etc. |
86
+
87
+ ### TA3 — Aliasing
88
+
89
+ Check: do Semantic variables alias Primitives, or hold raw values?
90
+
91
+ | State | Severity | Fix |
92
+ | ----------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
93
+ | Semantic variables hold raw hex / numeric values | Critical | Create the missing Primitive, then re-point the Semantic to alias it. |
94
+ | Alias chains longer than 1 hop (Semantic → Semantic → Primitive) | Warning | Collapse: Semantic should alias Primitive directly. |
95
+ | Some Semantics alias correctly, others hold values inconsistently | Critical | Audit each Semantic variable; alias all of them. |
96
+
97
+ ### TA4 — Variable Scopes
98
+
99
+ Check: are scopes set per variable, or is everything `ALL_SCOPES`?
100
+
101
+ **Exclude from this check:** `BOOLEAN` variables (typically feature flags like `feature/reduce-motion`). They are never bound into design properties, so `ALL_SCOPES` on them is a no-op, not a finding. Filter `resolvedType === 'BOOLEAN'` out of the count before reporting.
102
+
103
+ | State | Severity | Fix |
104
+ | ------------------------------------------------------- | -------- | ------------------------------------------------------------------------- |
105
+ | All non-BOOLEAN variables default-scoped (`ALL_SCOPES`) | Critical | Set scopes per variable purpose. See `token-architecture.md` scope table. |
106
+ | Color tokens appear in spacing pickers (or vice versa) | Critical | Scope mismatch. Re-scope the offending variables. |
107
+ | Scopes set deliberately, no cross-contamination | (pass) | — |
108
+
109
+ ### TA5 — Coverage of Variables vs. Styles
110
+
111
+ Check: is the system on Variables, or still on legacy Styles?
112
+
113
+ | State | Severity | Fix |
114
+ | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------ |
115
+ | Color and number tokens still on Styles, not migrated to Variables | Critical | Migrate. Variables support modes; Styles don't. New work should be Variable-first. |
116
+ | Mixed: some on Styles, some on Variables, no clear policy | Warning | Pick one (Variables for color/number/string/boolean; Styles only for text/effect for now). |
117
+ | Effect Styles for shadows | (pass) | Variables don't fully replace effect styles yet — Styles is still the right place. |
118
+
119
+ ### TA6 — Variable mode count vs. plan tier
120
+
121
+ Check: how many Modes does each Collection have, relative to the team's plan tier limit (Free=1, Pro=4, Org=10, Enterprise=40)?
122
+
123
+ | State | Severity | Fix |
124
+ | --------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
125
+ | Mode count = tier ceiling | Blocker | Cannot add another mode without paid upgrade or restructure. Lift one axis (e.g. Brand) into a separate library file consuming a shared Foundations library. |
126
+ | Mode count = tier ceiling − 1 | Warning | Next axis exhausts the budget. Discuss before agreeing to a new mode. |
127
+ | Plan tier unknown but designs assume ≥4 modes | Suggestion | Confirm tier with the user; default planning assumption is Pro (4). |
128
+ | Mode count comfortably below ceiling | (pass) | — |
129
+
130
+ ## Category 2 — Component Design
131
+
132
+ ### CD1 — Variant axis explosion
133
+
134
+ Check: any Variant set with > ~30 frames? Identify which axis is over-populated.
135
+
136
+ | State | Severity | Fix |
137
+ | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
138
+ | Variant set has 100+ frames | Critical | One axis should be a Boolean Property or Instance Swap, not a Variant. Identify the axis with the most values that isn't a meaningful enum and convert it. |
139
+ | Variant set has 30–100 frames | Warning | Same as above, less urgent. Consider splitting. |
140
+ | Variant set < 30 frames | (pass) | — |
141
+
142
+ ### CD2 — Variant Property naming vs. code
143
+
144
+ Check: do Variant Property names and values match the code-side prop API?
145
+
146
+ | State | Severity | Fix |
147
+ | -------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
148
+ | Property values use friendly casing (`Small`) where code uses snake (`sm`) | Critical | Rename. The values flow through to code-gen tools verbatim. |
149
+ | Property names mismatched (`Type` in Figma, `variant` in code) | Critical | Rename. `type` is reserved in some frameworks; align to `variant` if that's the code name. |
150
+ | Boolean property names with negative phrasing (`NoIcon`) | Warning | Flip to positive (`HasIcon`). Boolean defaults read clearer that way. |
151
+
152
+ ### CD3 — Show/hide encoded as Variants
153
+
154
+ Check: any Variant set where two variants differ only by an element being present vs. absent?
155
+
156
+ | State | Severity | Fix |
157
+ | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
158
+ | Variants `WithIcon` / `NoIcon` with otherwise identical structure | Warning | Convert to a Boolean Property `HasIcon`. Halves the variant count, doubles maintainability. |
159
+
160
+ ### CD4 — Icons modeled as Variants
161
+
162
+ Check: is there a single component named `Icon` with a `Name` Variant Property?
163
+
164
+ | State | Severity | Fix |
165
+ | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
166
+ | Yes — one Icon component, Name as Variant | Critical | Variant pickers don't show previews. Designers can't browse icons. Convert each to a separate Component. |
167
+
168
+ ### CD5 — Composition / atomic structure
169
+
170
+ Check: are common pieces (Icon, Avatar, Badge) directly drawn inside other components, or are they instances?
171
+
172
+ | State | Severity | Fix |
173
+ | --------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
174
+ | Vector icons drawn directly inside Button frames | Warning | Replace with instances of the Icon library. Update the Button to use Instance Swap if the icon should vary. |
175
+ | Same Avatar shape redrawn in three different places | Warning | Extract to an Avatar component, instance it where used. |
176
+
177
+ ### CD6 — Component description content (intent + use)
178
+
179
+ Check: do Components have descriptions in the asset panel, _and_ do the descriptions tell an agent **when to use** the component, **when not to use** it, and **what it signals** to the user?
180
+
181
+ A description that only repeats the component's name doesn't fix the underlying drift problem: an agent that picks by shape rather than by intent will misuse a destructive button as a generic secondary, or grab a Toast for a modal flow. The description is what tells the agent _why the component exists_.
182
+
183
+ | State | Severity | Fix |
184
+ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
185
+ | 0% of components have descriptions | Critical | Set descriptions for every Component. Bulk operation via `figma_set_description`. |
186
+ | <50% have descriptions | Warning | Fill gaps; require descriptions for new components going forward. |
187
+ | Descriptions exist but only restate the component name | Critical | Rewrite using the template in `build-workflow.md`. The description must surface intent — without it, an agent picks components by shape, not by purpose, and library-as-source-of-truth slowly erodes. |
188
+ | Descriptions list props but no usage guidance | Warning | Add `Use when…`, `Don't use when…`, `Signals…` sentences. Two lines is enough for most components. |
189
+ | Descriptions are markdown but inconsistent in shape | Suggestion | Adopt one structure across all components: 1-line summary → bullet list of props → `Use when` → `Don't use when` → `Signals`. |
190
+ | Non-trivial interactive component has zero **Dev-Mode annotations** on implementation-detail spots (focus-ring delivery, tap-target extension, animation easing, A11y exceptions) | Warning | Add annotations via `figma_set_annotations`. Description = big picture; annotations = surgical implementation details surfaced in Inspect panel. |
191
+
192
+ ### CD7 — Complete interactive-state variant coverage
193
+
194
+ **Tool:** `figma_analyze_component_set` extracts the variant state-machine + cross-variant diffs + CSS pseudo-class mapping. It's the right tool for this check — it surfaces which states exist, which are missing, and which differ only cosmetically vs. semantically.
195
+
196
+ Check: does every interactive component cover all the states an agent will need to compose a real screen — **default, hover, focus, disabled, error, loading**?
197
+
198
+ Gaps in the state matrix force an agent to improvise the missing variant. Improvisation is where drift starts: the agent fills the gap with something that looks plausible, and the library quietly stops being the source of truth.
199
+
200
+ This check applies to **interactive** components only (Button, Input, Select, Combobox, Checkbox, Radio, Toggle, Tabs, Table-row, Stepper-step, etc.). Pure display components (Badge, Avatar, Skeleton, Card, Alert, Toast) need fewer states — apply judgement.
201
+
202
+ | State | Severity | Fix |
203
+ | ---------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
204
+ | An interactive component has only `state=default` | Critical | Add the missing `state=hover`, `state=focus`, `state=disabled`, `state=error`, `state=loading` variants. Match the visual treatment to the code-side rendering. |
205
+ | Interactive component covers some states (e.g. default + disabled) but not all of {hover, focus, error, loading} | Critical | Fill the gaps. List the missing ones explicitly in the report so the fix is mechanical. |
206
+ | Variant Property uses non-standard names (`state=on/off`, `state=invalid`) for conceptually-equivalent states | Warning | Rename to the standard vocabulary (`default / hover / focus / disabled / error / loading`). Cuts down on audit-tool false-positives — see false-positives section below. |
207
+ | All six states present, named per the standard vocabulary | (pass) | — |
208
+
209
+ Edge cases:
210
+
211
+ - **Hover** is a no-op on touch devices but still required in Figma — the `state=hover` variant is what agents and code-gen tools read to render the desktop hover.
212
+ - **Focus** must be a visible difference, not only a stroke that the audit tool reads as ~1.2:1 (see false-positives below). If focus is delivered via drop-shadow, document that in the description.
213
+ - **Loading** is sometimes redundant with a separate `Loading: boolean` Component Property — that's fine if the Boolean is what code uses. Pick one and cross-link in the description.
214
+
215
+ ### CD8 — Token-linked styles (no hardcoded values)
216
+
217
+ Check: every fill, stroke, text style, spacing, and effect on a Component bound to a Variable — _not_ a hardcoded hex / px / number?
218
+
219
+ Hardcoded values break propagation: a primary-color tweak should ripple through every component that uses `color/primary`. If a component declares `#006470` directly, the propagation stops there and the library drifts every time tokens move. Same for spacing (`16px` vs `space/md`) and typography (a literal font-size vs a `text/body-md` style).
220
+
221
+ Sample 5–8 representative Components per category. Every node with a fill/stroke/text/spacing/effect must show `boundVariables` on `figma_get_component_for_development_deep` (or the equivalent property in `figma_get_component`).
222
+
223
+ | State | Severity | Fix |
224
+ | -------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
225
+ | Hardcoded fill / stroke colors on a Component (e.g. raw hex on a node, no `boundVariables.fills`) | Critical | Bind via `figma_set_fills` / `figma_set_strokes` referencing the matching Semantic Variable. Rebuild any node that's still using a legacy Style if the system has migrated to Variables. |
226
+ | Hardcoded text properties (font-size / line-height / font-family) where a Text Style or Variable exists | Critical | Apply the corresponding Text Style. If the team still uses Variables for typography, bind via `boundVariables.textProperties`. |
227
+ | Hardcoded spacing on Auto Layout (literal `padding: 16` instead of `padding: {spaceMd}`) | Critical | Bind padding / itemSpacing to spacing Variables. This is what lets density modes work later. |
228
+ | Hardcoded values on _demo_ / decoration nodes (placeholder swatches, mock charts, in-component examples) | Warning | Bind these too if the goal is reusable demo content. Mark the section as decorative if the values are intentionally one-off. |
229
+ | Mode-aware Variables used everywhere, no raw values | (pass) | — |
230
+
231
+ Cross-check signal: if the file declares Light + Dark modes but switching modes produces visible artefacts on a Component (a hardcoded `#fff` showing on a dark surface), that Component is failing CD8 — even if every _other_ fill is bound.
232
+
233
+ ### CD9 — Auto Layout adoption
234
+
235
+ Check: are Component frames built with Auto Layout (`layoutMode: HORIZONTAL` or `VERTICAL`), or are they fixed positions?
236
+
237
+ Fixed frames produce fixed output. If the agent cannot resize a component to fit its context — a button label that grows to a translated string twice as long, a card stretched to fill a column — it either breaks the component (overflowing children) or skips it and inlines an ad-hoc replacement. Auto Layout is the mechanism that lets components reflow, and reflow is what keeps a library composable.
238
+
239
+ This check applies to **container** components (Card, Section, ListRow, TableCell, Alert, Dialog/Drawer surfaces) and to interactive components whose internal padding/gap should track typography (Button, Input, Select, Combobox).
240
+
241
+ | State | Severity | Fix |
242
+ | --------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
243
+ | Component root frames have `layoutMode: NONE` (no Auto Layout at all) | Critical | Convert to Auto Layout. `figma_execute` payload that walks COMPONENT_SET children and sets `layoutMode = 'HORIZONTAL'` (or `'VERTICAL'`) plus appropriate `primaryAxisSizingMode` / `counterAxisSizingMode`. |
244
+ | Auto Layout enabled at the root but inner content nodes are absolutely positioned | Critical | Re-parent inner nodes into Auto Layout sub-frames so they participate in resize. |
245
+ | Auto Layout used but with `*_AXIS_SIZING_MODE: FIXED` in places that should hug content | Warning | Switch the offending axis to `AUTO`. A common cause of "this card stretches funny when the title is long". |
246
+ | Auto Layout throughout, with sensible Hug / Fill choices | (pass) | — |
247
+
248
+ Effort: Auto-Layout retrofits are typically L (multi-day) on existing libraries because every Variant frame needs the conversion. Don't propose this as a same-sprint fix unless the component count is small.
249
+
250
+ ## Category 3 — Naming
251
+
252
+ ### N1 — Component names match engineering
253
+
254
+ Check: do Component names match the code-side component names exactly?
255
+
256
+ | State | Severity | Fix |
257
+ | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
258
+ | Figma `BTN`, code `Button` | Critical | Rename to match engineering. The code name is canonical. |
259
+ | Figma `Primary Button`, code `Button` (with `variant=primary`) | Critical | Convert to Variant set: `Button/Primary`, `Button/Secondary`, etc. |
260
+
261
+ ### N2 — Variable path conventions
262
+
263
+ Check: are variable paths consistent across collections?
264
+
265
+ | State | Severity | Fix |
266
+ | ------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------- |
267
+ | Mixed casing — `color/Primary`, `color/secondary` | Warning | Pick a casing (typically lowercase-with-hyphens or camelCase). Stick to it. |
268
+ | Inconsistent depth — `color/text/primary` and `space-md` | Warning | Apply consistent depth: `space/inline/md` or whatever convention the team picks. |
269
+ | Mixing T-shirt and numeric scales (`size: sm` and `size: 4`) | Warning | Pick one. Match what code uses. |
270
+
271
+ ### N3 — Slash naming for Variants
272
+
273
+ Check: are component names well-segmented for the picker?
274
+
275
+ | State | Severity | Fix |
276
+ | ------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
277
+ | Components named `Button-Primary`, `Button-Secondary` (hyphen, not slash) | Warning | Rename with slashes; this groups them in the asset panel. |
278
+ | Variant Property values in the layer name (`Button/Primary` after Variant conversion) | Warning | Once converted, properties live in the panel — remove from layer names. |
279
+
280
+ ## Category 4 — File Structure
281
+
282
+ ### FS1 — Working designs in the library file
283
+
284
+ Check: does the library file contain in-progress designs?
285
+
286
+ | State | Severity | Fix |
287
+ | ---------------------------------------------- | -------- | ----------------------------------------------------------------- |
288
+ | Library file has product screens / WIP designs | Warning | Move to a separate working file. Library = published assets only. |
289
+
290
+ ### FS2 — Page organization
291
+
292
+ Check: is each component category on its own page? Is there a Cover page?
293
+
294
+ | State | Severity | Fix |
295
+ | -------------------------------------------- | ---------- | ---------------------------------------------------------- |
296
+ | Single page named "Page 1" with everything | Critical | Adopt the page layout from `naming-and-file-structure.md`. |
297
+ | No Cover page | Suggestion | Add one with library name, version, last-updated. |
298
+ | No Tokens / Icons / Patterns reference pages | Warning | Add at least Tokens (visual swatch documentation). |
299
+
300
+ ### FS3 — Sub-components polluting the asset panel
301
+
302
+ Check: are atomic sub-components (slot placeholders, internal pieces) publishing as if they were user-facing?
303
+
304
+ | State | Severity | Fix |
305
+ | --------------------------------------------------------------- | -------- | --------------------------------------------------------- |
306
+ | `_Slot/Default` shows up in the asset panel for designers | Warning | Confirm the `_` prefix is set; Figma should auto-exclude. |
307
+ | Internal helpers (`ButtonContent`, `CardShell`) are publishable | Warning | Prefix with `_` or `.` to exclude from publishing. |
308
+
309
+ ### FS4 — Sections vs. Frames misuse
310
+
311
+ Check: are component-internal layouts built inside Sections instead of Frames?
312
+
313
+ Sections are organizational only — no Auto Layout, no constraints, no clip, can't nest inside Frames. Frames carry the actual layout primitives. Using a Section as an internal layout container breaks every reflow assumption downstream.
314
+
315
+ | State | Severity | Fix |
316
+ | -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
317
+ | Component / variant inner content lives inside a Section | Critical | Convert to a Frame with `layoutMode: HORIZONTAL` or `VERTICAL`. Sections are for page-level grouping only. |
318
+ | Sections used at the page level for grouping (correct) | (pass) | — |
319
+ | Sections nested inside Frames | Warning | Inverted hierarchy. Sections cannot live inside Frames; lift them out or replace with a Frame. |
320
+
321
+ ### FS5 — "Ready for dev" coverage
322
+
323
+ Check: do published components / patterns / sections carry a `devStatus = READY_FOR_DEV` marker?
324
+
325
+ Without it, downstream Dev-Mode UI and code-gen agents treat the artifact as work-in-progress and skip it. The agent that consumes the library can't tell "draft" from "shipped".
326
+
327
+ | State | Severity | Fix |
328
+ | ---------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
329
+ | 0% of published components / sections marked Ready for dev | Warning | Set `devStatus` on each shipped Section / Component via `figma_execute`. See `build-workflow.md` Phase 8. |
330
+ | Mixed coverage with no policy | Suggestion | Adopt the rule: any shipped artifact gets the marker before publish. |
331
+ | Whole pages marked Ready for dev (too coarse) | Suggestion | Mark at the Section / Component scope, not the page. Pages are organizational. |
332
+
333
+ ## Category 5 — Engineering-Sync Readiness
334
+
335
+ ### ES1 — Token names match codebase
336
+
337
+ Check: do Variable names match the token names in code?
338
+
339
+ | State | Severity | Fix |
340
+ | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
341
+ | Figma `color/text/primary`, code `--text-primary-color` (different shape) | Critical | Pick one transformation rule and document it. Or rename one side to match the other. The closer they are, the less drift. |
342
+ | Figma uses friendly names, code uses generated short names | Warning | If the team has a token-pipeline tool (Tokens Studio, Style Dictionary), confirm the export config produces the codebase names. |
343
+
344
+ ### ES2 — Component prop API matches code
345
+
346
+ Check: do Variant Property names/values match code prop names/values?
347
+
348
+ | State | Severity | Fix |
349
+ | --------------------------------------------------- | -------- | --------------------------- |
350
+ | Mismatched (Figma `Size: Small`, code `size: 'sm'`) | Critical | Rename Figma to match code. |
351
+
352
+ ### ES3 — Naming-alignment as the code bridge
353
+
354
+ This skill explicitly does **not** recommend Figma's official Dev-Mode MCP or Code Connect. The bridge to code in this toolchain is **naming alignment** alone — Component names, Variant Property names/values, and Variable names matching the codebase exactly. When alignment is tight, code-gen tools infer the rest.
355
+
356
+ Check: is naming alignment hard enough that an agent could map Figma↔code without an explicit Code Connect file?
357
+
358
+ | State | Severity | Fix |
359
+ | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
360
+ | Components and Variant Properties match code exactly (CD2 + N1 pass) | (pass) | Naming alignment is the mapping. No further action. |
361
+ | Some misalignment in Variant Property values (e.g. `Small` vs `sm`) | Critical | Rename in Figma to match code. See CD2. |
362
+ | Component names abbreviated or stylized differently than code | Critical | Rename. See N1. |
363
+ | User asks about Code Connect / Dev-Mode MCP | (info) | Out of scope for this skill. Use figma-console-mcp; rely on naming alignment. Don't pretend the official MCP is being recommended here. |
364
+
365
+ ### ES4 — Documentation handoff
366
+
367
+ Check: does the library produce useful documentation for engineering?
368
+
369
+ | State | Severity | Fix |
370
+ | ------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
371
+ | No component docs anywhere | Warning | Use `figma_generate_component_doc` per component to produce Markdown handoff. |
372
+ | Component descriptions exist in Figma but aren't surfaced elsewhere | Suggestion | If the team uses zeroheight, Storybook MDX, or similar, mirror descriptions there. |
373
+
374
+ ### ES5 — Branching workflow (Org / Enterprise)
375
+
376
+ Check: when migrations are planned on a file with Branching available, do they happen on a branch or directly on main?
377
+
378
+ Library Publishing only happens from main; landing risky structural changes directly on main means there's no review buffer. Branching is the buffer.
379
+
380
+ | State | Severity | Fix |
381
+ | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
382
+ | Recent migrations landed directly on main (Org+ team) | Warning | Adopt the migration-playbook branching step. Run additive coordination on a branch, merge, then publish from main. |
383
+ | Branching not available (Free / Pro) | (n/a) | — |
384
+ | Branches in use, merged before publish | (pass) | — |
385
+
386
+ ### ES6 — Library analytics review (Enterprise)
387
+
388
+ Check: is the team correlating component-insertion analytics against the library to spot dead components?
389
+
390
+ Figma Library Analytics (Enterprise REST API) reports per-component insertion / detachment counts. Components with zero insertions over 90 days are deprecation candidates; high detachment rates are a design-debt signal that the component doesn't fit real use cases.
391
+
392
+ | State | Severity | Fix |
393
+ | --------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
394
+ | No regular review (Enterprise team) | Suggestion | Run `figma_audit_design_system` monthly + pull insertion counts via the REST API. Flag zero-insertion components for deprecation. |
395
+ | Regular review in place | (pass) | — |
396
+ | Free / Pro / Org team (no Library Analytics access) | (n/a) | — |
397
+
398
+ The skill doesn't itself integrate Library Analytics — it only flags this as a process recommendation when the team has the access.
399
+
400
+ ## Audit run order
401
+
402
+ 1. Run the **Design System Dashboard MCP App** (covers breadth incl. A11y, Coverage) — or, without MCP Apps, `figma_audit_design_system_report`, the same six weighted scores as JSON (Naming 25 %, Tokens 20 %, Components 20 %, Consistency 15 %, A11y 10 %, Coverage 10 %). For per-component depth on accessibility, `figma_audit_component_accessibility` scores six categories — state coverage, focus-indicator quality, non-colour differentiation, target size (default 24 px; pass 44 for mobile), annotation completeness, colour-blind simulation — weighted by whether the component is interactive or presentational, so a badge is not penalised for lacking a focus state.
403
+ 2. Run the inputs (`figma_get_status`, `figma_get_file_data`, `figma_get_variables`, `figma_get_styles`, sample `figma_get_component`).
404
+ 3. Walk through Categories 1–5 above. For each finding, record:
405
+ - Category and check ID (e.g. `TA4`).
406
+ - Current state (one line).
407
+ - Severity tag.
408
+ - Fix (one line, actionable).
409
+ - Effort estimate: S (single tool call), M (a few coordinated calls), L (multi-day refactor).
410
+ 4. Compile the priority list: all Blockers, then all Criticals (sorted by effort, low first), then Warnings, then Suggestions.
411
+ 5. Output via `assets/audit-report-template.md`.
412
+
413
+ A good audit produces ~15–40 findings on a real-world library. Fewer than 10 means you skipped categories; more than 60 means you're listing things that should be condensed.
414
+
415
+ ## Known audit-tool false-positives
416
+
417
+ The figma-console-mcp `figma_audit_component_accessibility` tool has a small
418
+ set of recurring false-positives. Recognise these patterns instead of
419
+ re-flagging items as real issues — they waste designer time and make audit
420
+ diffs look noisier than they are.
421
+
422
+ ### Focus indicator delivered via drop-shadow reads as ~1.2:1 stroke contrast
423
+
424
+ The audit tool measures focus-ring contrast on the _stroke_ of the focus
425
+ variant. When the design uses a `--ui-focus-ring`-style **drop-shadow**
426
+ (double-ring surface gap + primary outer ring), the stroke itself is often
427
+ just the component's normal border, which can be ~1.2:1 against the surface.
428
+ The actual rendered ring is delivered by the drop-shadow effect at ~6:1+,
429
+ which the audit tool doesn't read.
430
+
431
+ **Action:** if the component has a `state=focus` variant whose focus ring
432
+ is implemented as a drop-shadow (not a stroke), tag the finding as
433
+ _"audit-tool false positive — drop-shadow delivers ~6:1 actual"_ in the
434
+ report. Don't fix in Figma; verify in code with `references/code-verify.md`
435
+ instead. Common offenders historically: TabGroup, Select, Combobox.
436
+
437
+ ### Variant `state=default` / `state=error` flagged missing when names differ
438
+
439
+ The audit tool maps interactive-state coverage to a fixed vocabulary
440
+ (`default`, `hover`, `focus`, `disabled`, `error`, `active`, `loading`).
441
+ Components whose Variants use names like `state=off|on`, `state=disabled-off`,
442
+ or `state=invalid` will be reported as missing `default` and/or `error`,
443
+ even when the conceptually-equivalent variants exist.
444
+
445
+ **Action:** check the Variant Property values. If equivalents exist under
446
+ different names, tag as _"variant-naming mismatch with audit-tool vocabulary
447
+ — equivalent variants exist as `state=<name>`"_ and propose a one-time
448
+ rename to align with the standard names (this is a Migrate operation,
449
+ not a Build one). Common offenders historically: Toggle, Checkbox,
450
+ RadioGroup.
451
+
452
+ ### Hardcoded inset shadow on a fill is _not_ a stroke fail
453
+
454
+ Some components use a 1px `inset` shadow inside a fill to deliver
455
+ non-color differentiation (WCAG 1.4.1) — for example, a danger button's
456
+ silhouette in greyscale/protanopia. The audit tool only reads explicit
457
+ strokes and may report "no border" or low contrast on the silhouette.
458
+
459
+ **Action:** confirm the inset-shadow approach via `figma_get_component`
460
+ on a representative variant. If present, tag _"non-color cue delivered
461
+ via inset shadow on fill (audit tool reads strokes only)"_ and skip.
462
+ Common offenders: Button (danger variant), Toast (variant border-left).