@atelier-ui/create-workspace 0.4.1 → 0.4.3

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 (27) hide show
  1. package/CHANGELOG.md +22 -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/design-contracts/bin/check-contracts.mjs +7 -2
  25. package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
  26. package/src/generators/preset/preset.js +52 -4
  27. package/src/generators/preset/preset.js.map +1 -1
@@ -0,0 +1,198 @@
1
+ # Component design
2
+
3
+ ## Required principles
4
+
5
+ A component library that an agent can use without improvising has to satisfy four properties. Every Build, Migrate, and Audit pass should treat these as hard requirements, not nice-to-haves. The audit checklist (`references/audit-checklist.md`) maps each one to a check ID so findings are mechanical to record.
6
+
7
+ 1. **Complete variant states** _(audit ID: CD7)_ — every interactive component covers all states an agent will need: `default`, `hover`, `focus`, `disabled`, `error`, `loading`. Gaps force the agent to improvise the missing variant, and improvisation is where drift starts. The agent fills the gap with something plausible-looking and the library quietly stops being the source of truth.
8
+ 2. **Annotated component descriptions** _(audit ID: CD6)_ — every component carries a usage note: when to use it, when not to, and what it signals to the user. Without intent, an agent picks by shape — a button that looks secondary gets used as a secondary button even when it was designed for a destructive action. The description is what tells the agent _why the component exists_.
9
+ 3. **Token-linked styles** _(audit ID: CD8)_ — colour, typography, spacing, and effects all bound to Variables (or Text/Effect Styles where Variables don't yet apply). No raw hex, no literal `16px`, no inline font sizes. The agent applies decisions through the token system; hardcoded values break propagation, and propagation is how the library stays consistent at scale.
10
+ 4. **Auto Layout throughout** _(audit ID: CD9)_ — components are built with Auto Layout so an agent can resize and reflow without breaking structure. Fixed frames produce fixed output: if the agent cannot stretch a Card to a column or grow a Button to a translated label, it either breaks the component or skips it.
11
+
12
+ These four are also the difference between a library a designer-only team can live with and one a code-gen agent can actually consume — the first three principles especially. Treat any Critical finding under CD6 / CD7 / CD8 / CD9 as a drift-source that will compound until it's fixed.
13
+
14
+ ## Component Properties default to visible (2026-03-23)
15
+
16
+ As of Figma's **2026-03-23 simplified-instances rollout**, every Component Property defined on a component is **default-visible** in the instance properties panel. The historic "hidden property" pattern — defining a property on the master and counting on Figma not to surface it — is no longer reliable.
17
+
18
+ Architectural consequence: **if a property shouldn't be exposed to designers, it shouldn't be a property at all.** Two correct shapes:
19
+
20
+ - Move the variation into a **separate Component** (`Button` and `IconButton`, not one Button with a hidden `variant=icon-only`).
21
+ - Move the structural piece into an **internal sub-component** prefixed with `_` or `.` (e.g. `_ButtonContent`), kept unpublished.
22
+
23
+ When auditing an existing file, every Component Property the team explicitly didn't want users to see is now a finding — pick one of the two shapes above.
24
+
25
+ ## Variation mechanisms — pick the right one
26
+
27
+ Figma offers four mechanisms to express variation in a component. Choosing the right one for each axis of variation is what separates a maintainable library from a 256-permutation Variant set that nobody can navigate.
28
+
29
+ The four mechanisms:
30
+
31
+ 1. **Variants** — multiple frames inside a Component Set, switched via Variant Properties.
32
+ 2. **Component Properties** — typed knobs on a single component: Boolean, Text, Instance Swap.
33
+ 3. **Nested Component Instances** — composing components inside other components.
34
+ 4. **Separate Components** — when something looks similar but is fundamentally a different thing.
35
+
36
+ ## When to use each
37
+
38
+ ### Variant — for visually distinct states/types
39
+
40
+ Use when:
41
+
42
+ - The visual difference is large enough that a designer benefits from seeing each option.
43
+ - The combinations are bounded and meaningful (e.g. `Type × State` where both axes have ≤4 values).
44
+ - The variations correspond to **enum-typed props** in the codebase (`type: 'primary' | 'secondary' | 'ghost'`).
45
+
46
+ Don't use for:
47
+
48
+ - Showing/hiding sub-elements (use a Boolean Property instead).
49
+ - Swapping an icon for a different icon (use Instance Swap).
50
+ - Hundreds of options like an icon set (use separate Components).
51
+
52
+ The bound to watch: **Variants × Variants × Variants explodes.** A component with `Type (4) × Size (3) × State (5) × Icon Position (3)` is 180 frames. Convert one of those axes to a Boolean or Instance Swap.
53
+
54
+ ### Boolean Property — for show/hide
55
+
56
+ Use when an element appears or doesn't appear without otherwise changing the component.
57
+
58
+ Examples:
59
+
60
+ - `Has Icon` — toggles whether an icon slot is rendered.
61
+ - `Has Helper Text` — input field with optional helper.
62
+ - `Loading` — toggles a spinner overlay.
63
+
64
+ Don't use Boolean Properties to encode mutually exclusive states (Default / Hover / Disabled). That's a Variant.
65
+
66
+ That Variant lives only on the Figma side, as its own `state` axis, curated rather than
67
+ crossed against every other axis. It has no analogue in the code contract: its variant type
68
+ never carries a state value — hover/focus/active/disabled stay CSS pseudo-classes and
69
+ attributes there. (Example from the Atelier repo, not a file a generated workspace has: the
70
+ contract there is `libs/spec/src/index.ts`, per its "states get a Figma axis" rule and
71
+ ADR-0114.)
72
+
73
+ ### Text Property — for editable strings
74
+
75
+ Use for any text content that designers will customize per instance: button labels, headings, helper text. The property exposes the text node directly, so designers can override without detaching.
76
+
77
+ Bind to a Variable when the string should come from a translation file or a token (`label/cta-default`). Otherwise leave it as plain text with a sensible default.
78
+
79
+ ### Instance Swap Property — for swappable nested components
80
+
81
+ Use when one component nests another and the inner component needs to vary per instance.
82
+
83
+ Examples:
84
+
85
+ - A Button has an Icon Property (Instance Swap pointing at the Icon library) so designers pick which icon.
86
+ - A Card has a Header Property that can be swapped between `CardHeader/Default` and `CardHeader/WithAvatar`.
87
+
88
+ This is also how you implement **slot patterns** — a Card's content area can be an Instance Swap pointing at a Frame the user composes elsewhere.
89
+
90
+ ### Nested Components — for composition without a property
91
+
92
+ Use when the inner component is fixed for that variant and shouldn't be designer-configurable. Example: a Modal contains a CloseButton that's always the same — nest it directly, don't expose it as a property.
93
+
94
+ ### Separate Components — when they're different things
95
+
96
+ Use when:
97
+
98
+ - There are too many options for a Variant to be browsable (icons — there's no visual preview in a Variant dropdown, so an "icon" Variant set with `Name` as a property is unusable).
99
+ - The components have different prop APIs in code. Don't force-fit a Variant if the code-side `<TextInput>` and `<Select>` have different props.
100
+
101
+ For a related family of separate components, use **slash naming** to group them in the asset panel: `Icon/16/Home`, `Icon/16/Settings`, etc.
102
+
103
+ ## Variant Property naming — match the code
104
+
105
+ Variant property names and values are a contract with engineering. Make them match the code component's prop API exactly.
106
+
107
+ | Code prop | Figma Variant property |
108
+ | ------------------------------ | ------------------------------ |
109
+ | `<Button size="sm" />` | `Size: sm` (not `Size: Small`) |
110
+ | `<Button variant="primary" />` | `Variant: primary` |
111
+ | `<Button isLoading />` | `Loading: true` (boolean) |
112
+ | `<Input state="error" />` | `State: error` |
113
+
114
+ Rules of thumb:
115
+
116
+ - Property names are **PascalCase or Title Case** in Figma (Figma's own UI uses Title Case) — unless the paired codebase's gate compares names as strings, in which case they match the code exactly (`variant`, `size`).
117
+ - Property values match the code value casing exactly (`sm`, not `Sm` or `Small`) — this is what gets read out by code-generation tools.
118
+ - Boolean properties end in a positive (`HasIcon`, `Disabled`, `Loading`) — never negative (`NoIcon`).
119
+
120
+ ### Interaction states map to CSS, not to props
121
+
122
+ A `State` axis is where variant sets explode (CD1) and where the picture stops matching the code. Hover, focus, active and friends are pseudo-classes in every framework; `disabled`, `loading`, `selected` are attributes or Boolean props. When a master carries a `State` axis, this is what each value becomes in code — and it is the table `figma_analyze_component_set` uses to emit its `cssMapping`:
123
+
124
+ | Figma state value | Code |
125
+ | ------------------------ | --------------------------------------------------------------------- |
126
+ | `hover` | `:hover` |
127
+ | `focus`, `focus-visible` | `:focus-visible` |
128
+ | `active`, `pressed` | `:active` |
129
+ | `disabled` | `:disabled`, `[aria-disabled="true"]` — a Boolean prop, not a variant |
130
+ | `error`, `invalid` | `[aria-invalid="true"]` |
131
+ | `selected` | `[aria-selected="true"]` |
132
+ | `checked` | `:checked` |
133
+ | `loading` | `[aria-busy="true"]` — a Boolean prop |
134
+ | `open` / `closed` | `[aria-expanded="true | false"]` |
135
+ | `filled` | `.has-value` (or the codebase's equivalent) |
136
+
137
+ Draw the states designers need to _see_ (a hover frame is a legitimate documentation artefact), but keep them off the axis the code gate compares — or the gate will look for a `hover` prop that never existed. `figma_analyze_component_set` detects the axis heuristically by name (`state`, `status`, `interaction`); an axis called anything else yields an empty mapping, which is itself a finding.
138
+
139
+ ## Component Properties via high-level CRUD
140
+
141
+ The figma-console-mcp exposes typed CRUD tools for Component Properties — prefer them over hand-rolling `componentPropertyDefinitions` inside a `figma_execute` payload.
142
+
143
+ | Tool | Use when… |
144
+ | --------------------------------- | -------------------------------------------------------------- |
145
+ | `figma_add_component_property` | Defining a new Boolean / Text / Instance Swap property. |
146
+ | `figma_edit_component_property` | Renaming, changing default value, or retyping a property. |
147
+ | `figma_delete_component_property` | Removing a property. Breaking — coordination protocol applies. |
148
+
149
+ Why prefer them: typed inputs (you can't smuggle a malformed property shape past the API), atomic per-property updates, and far less Plugin-API boilerplate to read in chat. Reach for `figma_execute` only when defining a property must happen alongside other mutations in one atomic step (e.g. "add `HasIcon` AND set every variant's icon-slot Instance Swap default in one go").
150
+
151
+ When changing instance values (not the master definition), use `figma_set_instance_properties` — it understands the `#nodeId`-suffix that Component Property keys carry on instances. Bare `figma_set_text` against an instance child fails silently.
152
+
153
+ ## Atomic composition
154
+
155
+ Build atomic sub-components and nest them. Don't paste the same set of layers across every Variant.
156
+
157
+ Example: a Button has many variants. Inside, the icon should be an instance of an `Icon/*` component, not a directly-drawn vector. Why:
158
+
159
+ - Icon swap costs nothing — it's just changing an Instance Swap.
160
+ - A change to the icon style propagates to every button automatically.
161
+ - The Button file size stays small — duplicate vectors blow up file weight fast.
162
+
163
+ Apply this all the way down: a Button contains an Icon and a Text node, a Card contains a CardHeader (which contains an Avatar and a Title) and a CardBody. Each level is a component.
164
+
165
+ ## Slot pattern
166
+
167
+ A "slot" is a property on a component that accepts an arbitrary instance — the equivalent of `children` in React.
168
+
169
+ Implementation:
170
+
171
+ 1. Inside the parent component, place an instance of a placeholder component (e.g. `_Slot/Default` — note the `_` prefix marks it as unpublished).
172
+ 2. Expose that nested instance as an Instance Swap Property.
173
+ 3. Designers using the parent can swap the slot's instance to anything they need.
174
+
175
+ This is what makes a Card actually reusable for many content shapes without ballooning into a 50-Variant set.
176
+
177
+ ### Native Slot property (Figma, open beta since 2026-03)
178
+
179
+ Figma now ships a fifth component-property type that does the above without the placeholder dance: a **Slot** is a region inside a component where any layer can be dropped without detaching. Figma's own framing: use it for components that appear on many screens and have accumulated excessive variants — dialogs, menus, modals, cards, panels — where "structure stays consistent but content changes frequently". The payoff the system owner cares about: fewer variants, less maintenance, and the main reason designers detach instances is gone.
180
+
181
+ Limit to design around: **component properties cannot be applied to layers inside a slot** — an instance dropped into a slot keeps its own properties, but the parent cannot expose new ones on slot contents. `figma_create_slot`, `figma_get_slots`, `figma_append_to_slot`, `figma_reset_slot` and `figma_add_slot_property` drive it (Desktop Bridge). Prefer the native Slot for new work; keep the Instance-Swap pattern above for libraries that must stay compatible with clients that do not have the feature.
182
+
183
+ ## Don't-do list
184
+
185
+ | Anti-pattern | Fix |
186
+ | ------------------------------------------------------------- | ----------------------------------------------------------------------- |
187
+ | One Variant set per icon, with `Name` as the Variant property | Make every icon a separate Component, group with slash naming. |
188
+ | State (hover/disabled) modeled with separate Components | Combine into a Variant set with `State` property. |
189
+ | `IconLeft`, `IconRight`, `IconBoth` as separate Variants | One Boolean `HasIcon` plus a Variant `IconPosition: left | right`. |
190
+ | Detached instance to "fix" a one-off — committed to the file | Surface the missing variant as a real Variant or Property. |
191
+ | Variant Property names that differ from the code prop names | Rename Figma to match code. The code is the source of truth here. |
192
+ | Component without a description | `figma_set_description` after creation. Always. |
193
+ | All-caps Component names (`BUTTON`) | Match the engineering naming exactly (typically PascalCase). |
194
+ | 100+ frames in a single Variant set | Decompose: one or more axes should become Properties or sub-components. |
195
+
196
+ ## Atomic-design vocabulary — optional
197
+
198
+ Some teams adopt Brad Frost's vocabulary (Atoms / Molecules / Organisms / Templates / Pages). It's fine if it works for the team, but don't impose it. Figma's primitives don't care, and codebases rarely follow this vocabulary literally. The important thing is that the **levels of nesting** match between Figma and code, regardless of what they're called.
@@ -0,0 +1,262 @@
1
+ # Decision heuristics
2
+
3
+ The recurring forks in Figma workspace architecture. Each section gives a recommendation, the reasoning, and the alternative path with its trade-off.
4
+
5
+ In Decide mode, find the matching question, give the recommendation in the first sentence, the reasoning in the second, and the alternative in the third. Don't lecture — the user is at a fork, not a seminar.
6
+
7
+ ## Variant vs. Component Property vs. Instance Swap vs. separate Components
8
+
9
+ **Use a Variant when:**
10
+
11
+ - The visual difference is meaningful and a designer benefits from seeing each option.
12
+ - The values correspond to an enum-typed prop in code (`variant: 'primary' | 'secondary'`).
13
+ - The total Variant count stays manageable (under ~30 frames in the set).
14
+
15
+ **Use a Boolean Property when:**
16
+
17
+ - An element appears or doesn't appear, with no other change.
18
+ - Examples: `HasIcon`, `Loading`, `Disabled`.
19
+
20
+ **Use an Instance Swap when:**
21
+
22
+ - A nested component varies per instance (an Icon, an Avatar, a sub-component).
23
+ - This is also how slot patterns are implemented (the slot is an Instance Swap).
24
+
25
+ **Use separate Components when:**
26
+
27
+ - There are too many options for a Variant picker to be browsable (icons — 50+ options).
28
+ - The components have genuinely different prop APIs in code.
29
+ - Group them with slash naming for asset-panel folders.
30
+
31
+ **Decision tree:**
32
+
33
+ ```
34
+ Is the variation an enum the code uses? → Variant
35
+ Is it just show/hide? → Boolean Property
36
+ Is a nested component varying per instance? → Instance Swap
37
+ Are there 30+ options with no shared structure? → separate Components
38
+ Is text content varying? → Text Property
39
+ ```
40
+
41
+ If two of these apply, often you need a combination — e.g. Button has Variant `Type` AND Boolean `HasIcon` AND Instance Swap `Icon`. That's correct.
42
+
43
+ ## Primitive vs. Semantic vs. Component Token
44
+
45
+ **Primitive when:**
46
+
47
+ - The variable holds a raw value (color hex, pixel number, font size).
48
+ - The name describes _what it is_, not _what it's for_ (`color/blue/500`, `space/4`).
49
+ - It will be aliased by Semantics, never referenced directly by components.
50
+
51
+ **Semantic when:**
52
+
53
+ - The variable describes _purpose_ (`color/text/primary`, `space/inline/md`).
54
+ - The variable aliases a Primitive — it doesn't hold raw values.
55
+ - It carries Modes (Light/Dark, Brand-A/Brand-B).
56
+ - Components reference these.
57
+
58
+ **Component when:**
59
+
60
+ - The token is specific to one component (`button/primary/background-default`).
61
+ - There are enough state-driven values that maintaining them centrally beats inline overrides.
62
+ - Most teams skip this layer in Figma and keep it on the code side.
63
+
64
+ **Default recommendation:** **Two tiers (Primitive + Semantic) only.** Add a Component tier only if the team explicitly wants it and has a clear use case.
65
+
66
+ **Decision tree:**
67
+
68
+ ```
69
+ Does the value describe what it is, or what it's for?
70
+ → "what it is" → Primitive
71
+ → "what it's for" → Semantic
72
+
73
+ Does only one component use this purpose?
74
+ → Yes, and the team wants centralization → Component
75
+ → Yes, but inline overrides are fine → Skip the Component tier
76
+ ```
77
+
78
+ ## New Mode vs. New Collection
79
+
80
+ A Mode is appropriate when **the same Semantic token resolves to a different value in a different context**.
81
+
82
+ **Use a Mode when:**
83
+
84
+ - Light vs. Dark — same token (`color/text/primary`) resolves differently per theme.
85
+ - Brand-A vs. Brand-B in a multi-tenant product — same token, different brand value.
86
+ - Density Comfortable vs. Compact — same `space/inline/md`, different value.
87
+
88
+ **Use a new Collection when:**
89
+
90
+ - The values represent a fundamentally different category (`Color` collection vs. `Layout` collection).
91
+ - The variables don't share consumers — Layout consumers don't care about Color modes and vice versa.
92
+ - A new tier is being added (Component tokens get their own collection).
93
+
94
+ **Don't use a Mode for:**
95
+
96
+ - States like hover/disabled — those are Variant Properties.
97
+ - Different sizes of the same component — those are Variant Properties.
98
+ - Different platforms (iOS / Android / Web) where the design language genuinely differs — that's a separate Library.
99
+
100
+ A Variant Property here is a Figma-side axis (`state`), curated rather than fully
101
+ crossed against every other axis — not a licence to let a state value reach the code
102
+ side. The corresponding code contract never carries a state; hover/focus/active/disabled stay
103
+ CSS pseudo-classes and attributes there. (In the Atelier repo that is `Atl*Variant` in
104
+ `libs/spec/src/index.ts`, per its "states get a Figma axis" rule and ADR-0114 — an example
105
+ from that repo, not a file a generated workspace has.)
106
+
107
+ **Default:** modes for theming/branding, separate collections for separate categories. Modes on the **Semantic** tier only.
108
+
109
+ ## Nested Component vs. Slot
110
+
111
+ **Use a nested component when:**
112
+
113
+ - The inner component is fixed for that variant — designers shouldn't be able to swap it.
114
+ - Example: a Modal contains a fixed CloseButton.
115
+
116
+ **Use a slot (Instance Swap Property) when:**
117
+
118
+ - The inner area should be configurable per instance.
119
+ - Example: a Card's content area, where designers compose different content.
120
+ - Example: a Notification's action area, where the action button can be a Button, IconButton, or Link.
121
+
122
+ **Implementation of a slot:**
123
+
124
+ 1. Create a placeholder component, prefixed `_Slot/Default` (the `_` keeps it unpublished).
125
+ 2. Inside the parent, place an instance of the slot placeholder.
126
+ 3. Expose the nested instance as an Instance Swap Property.
127
+
128
+ **Default:** if you find yourself making 5+ Variants of the same parent component just to vary one nested area, that area should be a slot.
129
+
130
+ ## Single Library vs. Multiple Libraries
131
+
132
+ **Use a single Library when:**
133
+
134
+ - The team is small, one product, one platform.
135
+ - The total component count is manageable (<150).
136
+ - Tokens, components, patterns can coexist on different pages within one file.
137
+
138
+ **Split into multiple Libraries when:**
139
+
140
+ - File size approaches Figma's 2GB per-file limit.
141
+ - Different teams own different parts (e.g. Foundations team owns tokens, UI team owns components).
142
+ - Different publishing cadences are needed (tokens stable, components move fast).
143
+ - Web vs. Mobile have separate prop APIs and concerns.
144
+
145
+ **Common splits:**
146
+
147
+ - **Foundations** (tokens, type, color) — consumed by everything.
148
+ - **Components** — consumed by product files.
149
+ - **Brand** (logo, brand colors, marketing illustrations) — consumed by marketing files too.
150
+
151
+ **Don't split prematurely.** Each split is a maintenance cost. A monolithic library that works is better than three libraries that drift apart.
152
+
153
+ ## Variables vs. Styles
154
+
155
+ **Use Variables for:**
156
+
157
+ - Colors (Variables support modes, Styles don't).
158
+ - Numbers (spacing, radius, sizing).
159
+ - Strings (font family/style, locale-specific text).
160
+ - Booleans (visibility toggles).
161
+
162
+ **Still use Styles for:**
163
+
164
+ - Effect Styles (shadows, blurs) — Variables don't fully cover effects yet.
165
+ - Text Styles — though typography is increasingly possible with Variables (font-size, weight, line-height as variables); the text-style wrapper is still useful.
166
+
167
+ **Default:** new work goes on Variables. Don't migrate existing Styles aggressively unless modes are actually needed — Styles continue to work fine.
168
+
169
+ ## Code-side mapping — naming alignment is the bridge
170
+
171
+ This skill explicitly does not recommend Figma's official Dev-Mode MCP or Code Connect. The toolchain is figma-console-mcp only, and the bridge to code is **naming alignment**:
172
+
173
+ - Component names match code component names exactly.
174
+ - Variant Property names and values match code prop API exactly.
175
+ - Variable names match codebase token names.
176
+
177
+ When alignment is tight, code-gen tools infer the mapping with high accuracy without an explicit Code Connect file. When alignment drifts, no mapping config recovers it.
178
+
179
+ **Default:** invest the maintenance effort in keeping names in lockstep, not in setting up a parallel mapping system. If the user asks about Code Connect or the official Figma Dev-Mode MCP, say it is out of scope for this skill — figma-console-mcp doesn't implement it and we don't run a second MCP for it.
180
+
181
+ ## `figma_execute` vs. high-level Component Property tools
182
+
183
+ When defining or modifying a Component Property (Boolean / Text / Instance Swap), prefer the typed CRUD tools over hand-rolling Plugin API in `figma_execute`.
184
+
185
+ **Use `figma_add_component_property` / `figma_edit_component_property` / `figma_delete_component_property` when:**
186
+
187
+ - The change is a single property definition.
188
+ - The atomicity boundary is "one property, valid or rolled back".
189
+ - The agent or a future reader benefits from typed inputs (no malformed `componentPropertyDefinitions` shapes possible).
190
+
191
+ **Use `figma_execute` when:**
192
+
193
+ - The property change must happen alongside other mutations atomically (e.g. add `HasIcon` AND set every variant's icon-slot Instance Swap default in one go).
194
+ - The script involves walking the component tree to derive the property's allowed values from existing variants.
195
+
196
+ **Default:** start with the high-level tool. Escalate to `figma_execute` when the atomic boundary genuinely needs the wider scope.
197
+
198
+ ## Section vs. Frame as container
199
+
200
+ Sections and Frames look similar but carry different layout primitives. Pick the right one — using a Section where a Frame belongs breaks downstream layout assumptions.
201
+
202
+ **Use a Section when:**
203
+
204
+ - The container is **page-level grouping** of unrelated artifacts (e.g. "Tokens", "Components", "Patterns" as sections on a page).
205
+ - You want to mark the entire grouping **Ready for dev** in one go.
206
+ - Designers should be able to navigate it as a labeled region but it doesn't constrain its contents.
207
+
208
+ **Use a Frame when:**
209
+
210
+ - Anything **inside** a component — every variant frame, every nested layout box.
211
+ - Auto Layout is needed (Sections don't have it).
212
+ - Constraints, clip-content, corner radius, fills, or strokes are needed (Sections don't have these).
213
+ - The container will live inside another Frame (Sections cannot nest inside Frames).
214
+
215
+ **Decision tree:**
216
+
217
+ ```
218
+ Is this the inside of a component / variant? → Frame
219
+ Does this container need Auto Layout / fills? → Frame
220
+ Does this container need to live inside a Frame? → Frame
221
+ Is it a page-level "this is the Components area" grouping? → Section
222
+ ```
223
+
224
+ **Default:** Frame. Sections are a small, specialized tool for organizational labeling — most "container" needs in a design system are Frames.
225
+
226
+ ## Component Tokens — yes or no?
227
+
228
+ Component-tier tokens (`button/primary/background-default`) sit between Semantic tokens and the component itself.
229
+
230
+ **Pros:**
231
+
232
+ - Centralizes per-component values; changing one place updates all instances.
233
+ - Useful when state values (hover, active, disabled) are complex.
234
+
235
+ **Cons:**
236
+
237
+ - Adds a third tier — more variables, more discoverability cost.
238
+ - Often duplicates what's already in Semantics (`button/primary/background-default` → `color/action/primary`, the `button` prefix adds nothing).
239
+ - Most code-side design systems handle component tokens in code, not in Figma.
240
+
241
+ **Default recommendation: skip Component tokens in Figma.** Reach for them only when:
242
+
243
+ - A component has many state-driven values that aren't expressible as direct Semantic references.
244
+ - The team explicitly wants Figma to own the component-token layer (rare).
245
+
246
+ If unsure: skip. You can always add the layer later.
247
+
248
+ ## When to ask the user vs. decide yourself
249
+
250
+ Ask the user when:
251
+
252
+ - The decision depends on team conventions, codebase, or product roadmap that you can't infer.
253
+ - Multiple reasonable answers exist and the trade-offs matter (e.g. "do you need dark mode now or in 6 months?").
254
+ - The decision is destructive (rename, delete, restructure).
255
+
256
+ Decide yourself when:
257
+
258
+ - One option is clearly correct given general best practices and the file's existing state.
259
+ - The cost of being wrong is low (renames are reversible, additions are reversible).
260
+ - Asking would interrupt a flow the user explicitly delegated.
261
+
262
+ A useful test: "Will the user regret it if I pick the wrong one?" If yes, ask. If it's reversible and a sensible default exists, decide and document the choice in the build summary so the user can override.
@@ -0,0 +1,150 @@
1
+ # Iconography
2
+
3
+ Icons are the most-multiplied asset in any design system. A workspace with 200 icons each set up wrong is harder to navigate than one with 200 components, because the asset panel shows them all and the consumer can't tell which is the canonical version. Get the architecture right early; retrofitting it later means renaming every instance.
4
+
5
+ ## When this reference applies
6
+
7
+ - Setting up an icon library or icon collection from scratch.
8
+ - Auditing an existing icon set and deciding what to flag.
9
+ - Deciding whether a one-off SVG should be promoted to a Component.
10
+ - Splitting icons out of a main library into a separate Icon Library.
11
+
12
+ ## Size system
13
+
14
+ Pick **one** set of size stops and use it across the whole library. The standard set:
15
+
16
+ | Stop | Use for | Stroke (outlined) | Pixel grid alignment |
17
+ | ----- | -------------------------------------------------- | ----------------- | ------------------------------------------------ |
18
+ | 12 px | Inline in dense UI (badges, breadcrumb separators) | 1 px | Whole-pixel only; no half-px |
19
+ | 16 px | Standard inline (buttons, menu items, form fields) | 1.5 px | Whole-pixel for axes, half allowed for diagonals |
20
+ | 20 px | Larger inline (tabs, prominent buttons) | 1.5 px | Whole-pixel preferred |
21
+ | 24 px | Standalone (icon buttons, list items, toolbars) | 2 px | Whole-pixel preferred |
22
+
23
+ `32` and `48` exist but they are usually **illustrations**, not icons — different aesthetic, different drawing rules, different naming. Keep them separate.
24
+
25
+ ### One master vs optical-size variants
26
+
27
+ A single 24px master scaled down to 12px usually loses fidelity at the small end (lines blur, details collapse). Two paths:
28
+
29
+ - **One master + scale.** Pragmatic. Acceptable for outlined icons with simple geometry. Document that the master is drawn at 24 and the others are scaled.
30
+ - **Optical sizes — separate masters per stop.** Required when icons have detail that has to be redrawn at small sizes (filled icons, icons with text, icons with multiple lines close together). Costs ~3× the drawing time but reads correctly at every size.
31
+
32
+ Heuristic: if the design includes 12 px AND filled glyphs, you need optical sizes. If everything is outlined and 16 px or larger, one master is fine.
33
+
34
+ ## Internal layout — the boxed model
35
+
36
+ Every icon Component is a **square frame** with a **glyph inside**. The frame defines the bounding box and the touch / hit target; the glyph is the visible shape, optically padded inside the frame.
37
+
38
+ ```
39
+ ┌────────────┐ ← frame (e.g. 24×24, the size stop)
40
+ │ ┌──────┐ │
41
+ │ │ │ │ ← glyph (e.g. ~20×20, leaves ~2 px optical padding)
42
+ │ │ ✓ │ │
43
+ │ │ │ │
44
+ │ └──────┘ │
45
+ └────────────┘
46
+ ```
47
+
48
+ Rules:
49
+
50
+ - **Frame stays square** at the size stop. Never resize the frame to hug content.
51
+ - **Optical padding is judgment.** Some glyphs (a chevron) feel right with more breathing room; others (a filled circle) need less. Aim for visual balance, not pixel-equal margins.
52
+ - **Don't let the glyph touch the frame edge.** Looks cramped especially at 12 / 16 px.
53
+ - **Center on whole-pixel grid** at small sizes. A glyph centered at x=8.5 in a 16-px frame anti-aliases blurry on most screens.
54
+
55
+ ## Style: filled, outlined, or both
56
+
57
+ Library-wide commitment, made once:
58
+
59
+ - **Outlined-only.** Cleaner, easier to maintain, works at small sizes. Default choice.
60
+ - **Filled-only.** Stronger visual weight, often used for status / brand icons. Harder to read at 12 px.
61
+ - **Both** — use a Variant Property `style: 'outlined' | 'filled'`. Doubles the draw work; only worth it when both styles are actually needed for state communication (e.g., outlined = inactive, filled = active in tab bars).
62
+
63
+ A library that has outlined icons everywhere and one filled "warning" icon is inconsistent. Make the choice intentionally.
64
+
65
+ ## Color binding — never hardcode
66
+
67
+ Icon color is a Variable binding. Single-color icons:
68
+
69
+ ```
70
+ fill → Variable: color/icon (semantic, scoped to TEXT_FILL + STROKE_COLOR)
71
+ ```
72
+
73
+ `color/icon` aliases to the appropriate primitive in each Mode (e.g. `primitive/slate/700` in Light, `primitive/slate/200` in Dark).
74
+
75
+ Multi-color icons (rare, usually status icons like a coloured warning triangle):
76
+
77
+ ```
78
+ fill 1 → color/icon (the neutral part)
79
+ fill 2 → color/icon-accent (the coloured part — typically danger / warning / success)
80
+ ```
81
+
82
+ Pure brand logos / illustrations are the exception — they carry their own brand colors and are NOT bound to UI tokens. Keep them out of the standard icon set; they go in a separate `Brand` collection or page.
83
+
84
+ ### Anti-pattern: variants per color
85
+
86
+ Don't make `icon/check-success`, `icon/check-warning`, `icon/check-danger`. The variant explosion is real and the consumer should change the icon color via the Variable, not by switching to a different icon Component.
87
+
88
+ ## Component vs raw vector — when does an SVG earn promotion
89
+
90
+ Heuristic:
91
+
92
+ | Condition | Decision |
93
+ | --------------------------------------------- | ------------------------------------------------------------------ |
94
+ | Used 1× in the whole file | Vector layer, not a Component |
95
+ | Used 2× and unlikely to grow | Vector layer; revisit if it spreads |
96
+ | Used ≥3× **or** likely to spread | **Promote to Component** |
97
+ | Needs Variant Property (style / state / size) | Component, regardless of usage count |
98
+ | Shared across files / libraries | Component, in the canonical library |
99
+ | Brand logo with its own color rules | Component, but in a `Brand` collection — not the standard icon set |
100
+
101
+ The heuristic exists because **every Component shows up in the asset panel**. A library with 50 single-use icons-as-Components is unusable; designers can't find anything. Be conservative.
102
+
103
+ ### Common icons that earn promotion despite single-use
104
+
105
+ - Navigation glyphs: chevron, caret, arrow (left / right / up / down). Even if they only appear in one component today, they will recur.
106
+ - System glyphs: ✕ (close), ✓ (check), – (collapse), + (expand), ⋯ (more). Always Components.
107
+ - File-type / status icons used only in one place but in a context where the consumer might want to swap — accept Component overhead for the optionality.
108
+
109
+ ## Naming
110
+
111
+ `icon/<category>/<name>` is the long-term-maintainable form. Categories make the asset panel browsable when the set grows past ~30 icons.
112
+
113
+ | Category | What lives here |
114
+ | ------------ | ------------------------------------------------------------------------------------- |
115
+ | `navigation` | chevrons, arrows, carets, hamburger, close, back |
116
+ | `system` | settings, search, filter, sort, copy, edit, delete, more / overflow, pin, eye |
117
+ | `status` | check, error, warning, info, sync, loading-spinner |
118
+ | `content` | document, image, video, audio, code, link |
119
+ | `social` | external service logos (twitter, github, linkedin) when needed for share / login UI |
120
+ | `brand` | own product logo and variants — separate from `social` because they have brand colors |
121
+
122
+ ### Anti-patterns
123
+
124
+ - **Flat naming** (`icon/check`, `icon/x-circle`, `icon/arrow-right`) past ~30 icons. Eventually you cluster them by category mentally; do it explicitly in the file.
125
+ - **Premature category** (one icon per category, eight categories). Wait for ~3+ icons per category before splitting; merge sparse categories under `icon/system`.
126
+ - **`icon-1`, `icon-2`, `icon-new-3`.** Numbers in icon names mean nobody knows what they mean. The name has to be reachable from "what do I want to convey".
127
+ - **Style baked into name** (`icon/check-bold`, `icon/check-light`). Prefer a Variant Property `weight: 'regular' | 'bold'` on a single Component named `icon/check`.
128
+
129
+ ## Library boundaries — when to split icons out
130
+
131
+ Three signals to start a separate Icon Library:
132
+
133
+ 1. **>100 icons.** The main library starts feeling icon-heavy; component browsing slows.
134
+ 2. **Second consumer product.** A different app needs the same icon set independently of your component library. Splitting lets it import icons without inheriting components it doesn't use.
135
+ 3. **Different release cadence.** Icon set updates monthly; component library is on a quarterly release. Bundling them couples the cadence — split.
136
+
137
+ Until then, keep icons in the main library on a dedicated `Icons` page. See `naming-and-file-structure.md` for the page-layout convention (`Cover / Tokens / Icons / Components / Patterns`).
138
+
139
+ ## Audit checklist for icons
140
+
141
+ When auditing an existing icon set, walk in this order:
142
+
143
+ 1. **Size system.** How many distinct sizes exist in the file? If >4, why? Reduce.
144
+ 2. **Color binding.** How many icons have hardcoded fills? Each one is a theming break. Promote to `color/icon`.
145
+ 3. **Component vs vector.** How many icons are vector-only? Survey usage; promote anything ≥3-use to Component.
146
+ 4. **Naming.** Random sample 10 icons — can you reach them by typing what you want? If not, the names are wrong.
147
+ 5. **Library boundaries.** Are icons clogging the main library's asset panel? If yes, split.
148
+ 6. **Variant explosion.** Any icon with >4 variants is suspicious. Is it really 4 distinct icons (split), or color baked in (use Variable instead)?
149
+
150
+ Tag findings with the standard severity: Blocker / Critical / Warning / Suggestion. Color-binding violations are typically Critical (they break theming silently); naming inconsistencies are Warning; size-system drift is usually Critical because it blocks any future style refactor.