curiositech/design-system-creator

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 Fix: Generate documentation from CSS comments or implement single source of truth

Utility Class Abuse

Detection: HTML classes exceed 5-6 utility classes per element Symptom: HTML becomes unreadable, design intent is lost in implementation Fix: Create component classes for common patterns, limit utilities to tweaks

Scale Breaking

Detection: Custom values appear outside the design token system (padding: 13px) Symptom: Visual inconsistency, system erosion over time Fix: If scale doesn't work, fix the scale—don't work around it

Worked Example: Multi-Brand Token Refactor

Scenario: E-commerce platform needs to support 3 brands with shared components but different visual identity.

Initial Assessment:

• 47 existing components using hardcoded colors
• 2 brands already live, 3rd brand launch in 6 weeks
• Development team of 5, design team of 2

Decision Process:

1. Token Architecture Decision: Need three-tier system

   • Primitive: Raw brand colors (--acme-red-500, --beta-blue-600, --gamma-green-400)
   • Semantic: Intent-based (--color-primary, --color-secondary, --color-danger)
   • Component: Usage-specific (--button-primary-bg, --card-border-color)

2. Migration Strategy Decision:

   • Audit shows 200+ color references, 40+ spacing values
   • Trade-off: Token explosion vs migration complexity
   • Choice: Start with semantic layer, gradually add component tokens for complex components

3. Implementation:

   /* Brand A Theme */
   :root[data-brand="acme"] {
     --color-primary: var(--acme-red-500);
     --color-secondary: var(--acme-gray-600);
   }
   
   /* Brand B Theme */
   :root[data-brand="beta"] {
     --color-primary: var(--beta-blue-600);
     --color-secondary: var(--beta-slate-600);
   }
   
   /* Components use semantic tokens */
   .button--primary {
     background: var(--color-primary);
     color: var(--color-on-primary);
   }
   

4. Validation: Built 3 key pages in all brands, caught 12 contrast issues early

Expert Insight: Novice would try to solve with CSS-in-JS theming. Expert recognizes CSS custom properties provide better performance and simpler mental model.

Result: 6-week delivery met, 95% code reuse across brands, 0 critical bugs in production.

Quality Gates

• [ ] All design tokens defined in three-tier architecture (primitive → semantic → component)
• [ ] Token architecture validated with 2+ themes/brands successfully applied
• [ ] 5+ core components documented with Purpose, Anatomy, Variants, States
• [ ] All components tested for WCAG AA compliance (color contrast, keyboard navigation)
• [ ] CSS organization follows ITCSS methodology with clear file structure
• [ ] Component examples exist in Storybook or equivalent living style guide
• [ ] Design bible includes visual examples, not just code snippets
• [ ] Naming conventions documented and followed consistently across all files
• [ ] Responsive behavior specified for components that change across breakpoints
• [ ] Token usage linting rules implemented to prevent primitive token abuse

Not-For Boundaries

Do NOT use this skill for:

• Typography pairing and selection → Use typography-expert for font choices, reading hierarchy
• Color theory and palette mathematics → Use color-theory-palette-harmony-expert for color relationships
• Brand identity and visual direction → Use web-design-expert for logo, brand colors, visual personality
• Component implementation code → Use web-design-expert for React/Vue or native-app-designer for mobile
• Icon design and creation → Use web-design-expert for custom iconography
• Motion design and animations → Use native-app-designer for interaction design
• Content strategy and UX writing → Delegate to content specialists
• User research and usability testing → Delegate to UX researchers

Delegation triggers:

• "What colors should represent our brand?" → color-theory-palette-harmony-expert
• "How should this component animate?" → native-app-designer
• "What fonts work well together?" → typography-expert
• "Build this in React" → web-design-expert