Use when defining or extending design tokens and the shared component library — by product-designer when writing docs/13-design-tokens.md and docs/14-components.md, and by any IC about to add a component. Triggers the moment a value would be hardcoded instead of named, or a one-off component would be created instead of composed.
Installs into .claude/skills of the current project.
Are you the author of Design System?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/vmobifystudio-design-system)
---
name: design-system
description: Use when defining or extending design tokens and the shared component library — by product-designer when writing docs/13-design-tokens.md and docs/14-components.md, and by any IC about to add a component. Triggers the moment a value would be hardcoded instead of named, or a one-off component would be created instead of composed.
---
# Design system
A design system is not a document, it is a **constraint that holds at build time**. Tokens nobody is
forced to use are a colour list.
## Three layers, in this order
1. **Primitive** — the raw values. `blue-600 #2563EB`, `space-4 16`, `dur-fast 150ms`. No screen
ever references a primitive directly.
2. **Semantic** — what it means. `text/primary`, `surface/elevated`, `semantic/error`,
`motion/enter`. Screens reference these and only these.
3. **Component** — what a component uses. `button/primary/background` → `semantic/action`.
Skipping layer 2 is the failure: a dark mode, a rebrand or a contrast fix then edits every screen.
## The rules
- **A hardcoded colour, spacing, radius, duration or font size in a screen is a defect**, not a
style preference. Name it or use the token that already exists.
- **Every semantic token names its dark-mode value at the same time.** A token added light-only is a
dark-mode bug already merged.
- **A new component needs a reason the existing ones cannot compose it.** Write the reason in
`docs/14-components.md`. "It looked different in the mock" is not one.
- **Every component declares its states** — default, pressed, disabled, loading, error, empty where
applicable — and its minimum touch target (44pt iOS / 48dp Android).
- **Contrast is checked when the token is defined**, not when accessibility is audited. Text pairs
meet 4.5:1, large text and non-text 3:1. A token failing contrast never ships and is never
"fixed downstream".
## Extending versus forking
Before adding anything, in this order: use the existing component → extend it with a prop → compose
two existing ones → add a new one. Stop at the first that works. The third is where most teams stop
too early and the fourth is where design systems die.
## Output
Tokens go in `docs/13-design-tokens.md`, components in `docs/14-components.md`. Both are single-owner
files — `product-designer` writes them, everyone reads them. An IC that needs a change asks; it does
not edit.
