Design System
Build a source of truth that connects brand decisions to implementable components. Resolve skill-dir to this folder before running bundled scripts.
Architecture
Use three layers:
- Primitive tokens: raw palette, type, spacing, radius, elevation, and motion scales.
- Semantic tokens: intent such as surface, text, border, action, success, warning, and danger.
- Component tokens: component/part/state decisions that reference semantic tokens.
Never make components depend directly on arbitrary raw values when a semantic role exists.
Workflow
- Inventory existing styles, tokens, components, platforms, and brand constraints.
- Define naming rules and ownership before generating files.
- Build primitives, then semantic roles, then component mappings.
- Define default, hover, focus, active, disabled, loading, selected, error, and success states.
- Create light/dark or product themes by remapping semantic tokens, not duplicating components.
- Document component anatomy, variants, content rules, keyboard behavior, and responsive behavior.
- Migrate incrementally and keep compatibility aliases only with an explicit removal plan.
- Validate contrast, missing references, cycles, invalid values, and raw-value leakage.
Read the matching reference only when needed:
- references/token-architecture.md
- references/primitive-tokens.md
- references/semantic-tokens.md
- references/component-tokens.md
- references/component-specs.md
- references/states-and-variants.md
- references/tailwind-integration.md
Bundled tools
Use templates/design-tokens-starter.json as a starting structure, not unquestioned truth.
node "<skill-dir>/scripts/generate-tokens.cjs" --help
node "<skill-dir>/scripts/validate-tokens.cjs" <tokens-file>
python "<skill-dir>/scripts/html-token-validator.py" <html-file>
Run generators on a copy or preview path first. Inspect diffs before replacing user-owned token files.
Output contract
Provide token architecture, naming decisions, component/state coverage, migration impact, validation results, and remaining exceptions.
Guardrails
- Do not hardcode brand values inside components.
- Do not rename public tokens without a migration map.
- Do not generate a parallel design system when a working source of truth exists.
- Do not claim accessibility from token names alone; verify rendered combinations and states.
- Do not bind instructions to a provider, model, or host-specific path.
1---2name: design-system-23description: Design, implement, migrate, and validate scalable token and component systems with primitive, semantic, and component layers; themes; states; accessibility.4---56# Design System78Build a source of truth that connects brand decisions to implementable components. Resolve skill-dir to this folder before running bundled scripts.910## Architecture1112Use three layers:13141. Primitive tokens: raw palette, type, spacing, radius, elevation, and motion scales.152. Semantic tokens: intent such as surface, text, border, action, success, warning, and danger.163. Component tokens: component/part/state decisions that reference semantic tokens.1718Never make components depend directly on arbitrary raw values when a semantic role exists.1920## Workflow21221. Inventory existing styles, tokens, components, platforms, and brand constraints.232. Define naming rules and ownership before generating files.243. Build primitives, then semantic roles, then component mappings.254. Define default, hover, focus, active, disabled, loading, selected, error, and success states.265. Create light/dark or product themes by remapping semantic tokens, not duplicating components.276. Document component anatomy, variants, content rules, keyboard behavior, and responsive behavior.287. Migrate incrementally and keep compatibility aliases only with an explicit removal plan.298. Validate contrast, missing references, cycles, invalid values, and raw-value leakage.3031Read the matching reference only when needed:3233- references/token-architecture.md34- references/primitive-tokens.md35- references/semantic-tokens.md36- references/component-tokens.md37- references/component-specs.md38- references/states-and-variants.md39- references/tailwind-integration.md4041## Bundled tools4243Use templates/design-tokens-starter.json as a starting structure, not unquestioned truth.4445~~~text46node "<skill-dir>/scripts/generate-tokens.cjs" --help47node "<skill-dir>/scripts/validate-tokens.cjs" <tokens-file>48python "<skill-dir>/scripts/html-token-validator.py" <html-file>49~~~5051Run generators on a copy or preview path first. Inspect diffs before replacing user-owned token files.5253## Output contract5455Provide token architecture, naming decisions, component/state coverage, migration impact, validation results, and remaining exceptions.5657## Guardrails5859- Do not hardcode brand values inside components.60- Do not rename public tokens without a migration map.61- Do not generate a parallel design system when a working source of truth exists.62- Do not claim accessibility from token names alone; verify rendered combinations and states.63- Do not bind instructions to a provider, model, or host-specific path.
yigityildiz0