| license | Apache-2.0 |
| name | design-system-creator |
| description | Builds comprehensive design systems and design bibles with production-ready CSS. Expert in design tokens, component libraries, CSS architecture. Use for design system creation, token architecture, component documentation, style guide generation. Activate on "design system", "design tokens", "CSS architecture", "component library", "style guide", "design bible". NOT for typography deep-dives (use typography-expert), color theory mathematics (use color-theory-palette-harmony-expert), brand identity strategy (use web-design-expert), or actual UI implementation (use web-design-expert or native-app-designer). |
| allowed-tools | Read,Write,Edit,Glob,mcp__magic__21st_magic_component_builder,mcp__magic__21st_magic_component_refiner,mcp__stability-ai__stability-ai-generate-image,mcp__firecrawl__firecrawl_search |
| category | Design & Creative |
| tags | ["design-system","tokens","components","css","style-guide"] |
| pairs-with | [{"skill":"typography-expert","reason":"Typography decisions for the system"},{"skill":"color-theory-palette-harmony-expert","reason":"Color token architecture"}] |
Design System Creator
Design systems architect specializing in comprehensive, scalable design system creation with three-tier token architecture.
Decision Points
Token Naming Conflicts Resolution
If brand token conflicts with semantic token:
├─ Brand name is descriptive (--color-sunset-orange)
│ └─ Keep brand name, map to semantic: --color-primary: var(--color-sunset-orange)
└─ Brand name is generic (--color-primary)
└─ Rename brand to specific: --color-acme-primary, keep semantic --color-primary
If component token conflicts with semantic:
├─ Component is reusable pattern (--button-bg)
│ └─ Keep component token, reference semantic: --button-bg: var(--color-primary)
└─ Component is one-off usage
└─ Use semantic directly: background: var(--color-primary)
If multiple teams contribute tokens:
├─ Core team tokens (spacing, typography)
│ └─ Use unprefixed names: --space-4, --font-size-lg
└─ Feature team tokens (component-specific)
└─ Use team prefix: --commerce-product-card-shadow
Component Documentation Depth
If component has < 3 variants:
└─ Document: Purpose, Anatomy, States, Code example
If component has 3-8 variants:
├─ Complex interactions (forms, navigation)
│ └─ Add: Responsive behavior, Accessibility guide, Usage guidelines
└─ Simple variants (buttons, badges)
└─ Add: Variant matrix table, Do/Don't examples
If component has > 8 variants:
└─ Split into sub-components or reconsider if variants are actually needed
CSS Architecture Choice
If existing codebase:
├─ < 50 components, no naming conflicts
│ └─ Use BEM methodology with component-scoped files
└─ > 50 components OR naming conflicts exist
└─ Use ITCSS structure with strict naming conventions
If greenfield project:
├─ Small team (< 3 developers)
│ └─ ITCSS with utility-first approach
└─ Large team (> 3 developers)
└─ ITCSS with component-scoped methodology
Failure Modes
Token Explosion
Detection: If you have > 12 spacing tokens or > 20 color tokens per theme
Symptom: Developers can't choose between similar options
Fix: Consolidate to max 8 spacing values, use semantic layer to reduce primitive exposure
Semantic Layer Bypass
Detection: Components directly reference primitive tokens (--color-blue-500)
Symptom: Theming breaks, can't swap brands without touching every component
Fix: Audit all CSS, replace primitives with semantic tokens, add linting rules
Documentation Drift
Detection: Design bible shows different values than actual CSS implementation
Symptom: Developers stop trusting documentation, inconsistencies multiply
: Generate documentation from CSS comments or implement single source of truth
