How this skill is triggered — by the user, by Claude, or both
Slash command
/designer:design-systems-craftThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
How a designer builds and scales a design system. One rule underpins all of it: **favor the smallest token, variant, and component set that solves the problem.** Every layer below earns its place only when reuse demands it — never speculatively.
How a designer builds and scales a design system. One rule underpins all of it: favor the smallest token, variant, and component set that solves the problem. Every layer below earns its place only when reuse demands it — never speculatively.
Three layers, each referencing the one above. Components consume the bottom layer, never raw values.
blue/500 = #3b82f6, gray/900, size/16. A palette and a scale. Never applied directly to a design.color.text.primary, color.bg.surface, color.border.default, space.md, radius.lg. Maps to primitives. This is the layer themes swap.button.bg = color.accent. Add only when a component genuinely diverges.| Layer | Example | Who consumes it |
|---|---|---|
| Primitive | blue/500, gray/50, size/16 | Semantic tokens only |
| Semantic | color.text.primary, space.md | Components, designs |
| Component | button.bg, card.shadow | One component |
Why semantic naming beats raw values. color.text.primary survives a rebrand; #111827 does not. Change a primitive once or remap a semantic per theme, and every consumer updates — no find-and-replace across files.
Light/dark via semantic aliasing. Primitives stay fixed; only the semantic → primitive mapping flips.
| Semantic token | Light → primitive | Dark → primitive |
|---|---|---|
color.bg.surface | gray/50 | gray/900 |
color.text.primary | gray/900 | gray/50 |
color.accent | blue/600 | blue/400 |
In Figma, this is a variable collection with Light and Dark modes; the semantic variable points at different primitives per mode. Components bound to semantics re-theme with zero per-component work.
Prefer one component with properties over many near-identical components. Figma exposes four property types:
| Property type | Use for | Example |
|---|---|---|
| Variant | Mutually exclusive visual states | Type = Primary / Secondary, Size = SM / MD / LG |
| Boolean | Optional, independent elements | Has Icon, Disabled |
| Instance swap | Replaceable nested instance | Icon = ChevronRight |
| Text | Editable copy | Label = "Save" |
Single component vs separate components. Keep one component when items share structure and differ only by property (a button's type and size). Split into separate components when structure differs fundamentally (a Button vs a Checkbox) — forcing them together creates a tangled variant set nobody can navigate.
Organize variants in a matrix. Lay variant properties on two axes so every combination is visible and gaps are obvious.
| Default | Hover | Disabled | |
|---|---|---|---|
| Primary | ✓ | ✓ | ✓ |
| Secondary | ✓ | ✓ | ✓ |
Default + states. Mark one variant as the default (the first, cleanest combination). Model interaction states (hover, focus, active, disabled) as variant values so designs can show real states instead of redrawing them.
Brad Frost's five-stage mental model for composing an interface from the smallest parts up.
| Stage | What it is | Library example |
|---|---|---|
| Atoms | Smallest indivisible UI | Button, Input, Label, Icon |
| Molecules | A few atoms bonded into a unit | Search field (Input + Button) |
| Organisms | Molecules + atoms into a section | Header, Card, Form |
| Templates | Page-level structure, no real content | Dashboard layout, article skeleton |
| Pages | Templates with real content | Settings page, signed-in home |
Mapping to a component library. Atoms and molecules are your reusable components. Organisms are composed patterns. Templates and pages live closer to product work. The boundaries are a thinking aid, not a filing law — do not agonize over whether something is a molecule or an organism.
Composition over duplication. Build a molecule by nesting existing atom instances, not by redrawing them. When an atom changes, every molecule and organism that nests it inherits the change. Duplication is the thing atomic design exists to prevent.
Names are the system's API. Consistency here makes the library searchable and the handoff clean.
Button/Primary/Large, Icon/Chevron/Right. The slashes build a folder tree in the assets panel automatically.Title Case for component names, lowercase.dot for tokens (color.text.primary). Do not mix.label, icon-leading, container) — never ship Frame 427 or Rectangle 12. Clean layers make instances legible and code generation accurate.Button/Primary should map to the coded <Button variant="primary">. Aligned names are the cheapest defense against design–code drift.Document next to the component, as a single source of truth — not in a separate deck that rots.
For each component, capture:
| Field | Captures |
|---|---|
| When to use / when not | Intent and boundaries |
| Anatomy | Named parts of the component |
| Props | Variants and options |
| States | Interactive and validation states |
| A11y | Contrast, focus, labels, keyboard |
Keep docs where the component lives (component page, or a tool like ZeroHeight bound to the library) so updating the component and its docs is one motion. Separate docs drift out of sync the moment the component changes.
A design system is a product with internal users. Govern it like one (the Design That Scales mindset).
| Lever | What good looks like |
|---|---|
| Contribution model | A clear path for product teams to propose and add components |
| Versioning | Semantic versions; communicate what changed and why |
| Deprecation | Mark deprecated, give a migration path, then remove — never yank silently |
| Core team | A small, dedicated group owns quality and direction |
| Adoption metrics | Track detach rate, % screens on library components, token coverage |
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
npx claudepluginhub shoto290/shoto --plugin designer