Design System Starter

Design System Starter

Overview

This skill provides comprehensive guidance for building robust, scalable design systems that ensure visual consistency, improve development velocity, and create exceptional user experiences.

When to use this skill:

• Creating a new design system from scratch
• Evolving or refactoring existing design systems
• Establishing design token standards
• Defining component architecture
• Creating design documentation
• Ensuring accessibility compliance (WCAG 2.1)
• Implementing theming and dark mode

Bundled Resources:

• references/design-tokens.md - Complete token definitions
• references/component-patterns.md - Architecture patterns
• references/component-examples.md - Full component implementations
• references/theming.md - Theme and dark mode patterns
• templates/design-tokens-template.json - W3C design token format
• templates/component-template.tsx - React component template

// Example: Design token structure
const tokens = {
  colors: {
    primary: { base: "#0066cc", hover: "#0052a3" },
    semantic: { success: "#28a745", error: "#dc3545" }
  },
  spacing: { xs: "4px", sm: "8px", md: "16px", lg: "24px" }
};

• checklists/design-system-checklist.md - Design system audit checklist

Design System Philosophy

A design system is more than a component library. It includes:

Core Principles

1. Consistency Over Creativity - Predictable patterns reduce cognitive load
2. Accessible by Default - WCAG 2.1 Level AA compliance minimum
3. Scalable and Maintainable - Design tokens enable global changes
4. Developer-Friendly - Clear API contracts and documentation

References

Design Tokens

See: references/design-tokens.md

Key topics covered:

• Color scales (primitive 50-950, semantic tokens)
• Typography system (font families, sizes, weights, line heights)
• Spacing scale (4px base system)
• Border radius and shadow tokens
• W3C design token format
• Tailwind @theme integration

Quick Reference - Token Categories:

Component Patterns

See: references/component-patterns.md

Key topics covered:

• Atomic Design methodology (Atoms -> Pages)
• Props best practices (predictable names, sensible defaults)
• Composition over configuration
• Compound component pattern
• Polymorphic components
• CVA variant pattern

See: references/component-examples.md for full implementations.

Quick Reference - Atomic Design:

Theming

See: references/theming.md

Key topics covered:

• Theme structure and TypeScript interfaces
• Dark mode implementation approaches
• Tailwind @theme directive (recommended)
• Tailwind dark mode variant
• Styled Components ThemeProvider
• Theme toggle component
• System preference detection

Quick Reference - Dark Mode Approaches:

Accessibility Guidelines

WCAG 2.1 Level AA Requirements

Essential Patterns

• Keyboard Navigation: All interactive elements must be keyboard accessible
• Focus Management: Use focus traps in modals, maintain logical focus order
• Semantic HTML: Use <button>, <nav>, <main> instead of generic divs
• ARIA Attributes: aria-label, aria-expanded, aria-controls, aria-live
• Screen Readers: Provide meaningful labels, announce dynamic content

Quick Start Checklist

When creating a new design system:

• Define design principles and values
• Establish design token structure (colors, typography, spacing)
• Create primitive color palette (50-950 scale)
• Define semantic color tokens (brand, text, background, feedback)
• Set typography scale and font families
• Establish spacing scale (4px or 8px base)
• Use Tailwind @theme directive to define tokens
• Components use Tailwind utilities (bg-primary, text-text-primary)
• Design atomic components (Button, Input, Label, etc.)
• Implement theming system (light/dark mode)
• Ensure WCAG 2.1 Level AA compliance
• Set up documentation (Storybook or similar)
• Create usage examples for each component
• Establish versioning and release strategy

Current Implementation (January 2026):

• All colors defined in frontend/src/styles/tokens.css using @theme directive
• Components use Tailwind utilities: bg-primary, text-text-primary, border-border
• DO NOT use CSS variables in className: bg-[var(--color-primary)]

Design System Workflow

1. Design Phase

• Audit existing patterns and identify inconsistencies
• Define design tokens (colors, typography, spacing)
• Create component inventory
• Design in Figma (create component library)

2. Development Phase

• Set up tooling (Storybook, TypeScript, testing)
• Implement tokens (CSS variables or theme config)
• Build atoms first, then compose upward
• Document as you go

3. Adoption Phase

• Create migration guide for teams
• Provide codemods to automate migrations
• Run workshops to train teams
• Gather feedback and iterate

4. Maintenance Phase

• Version semantically (major/minor/patch)
• Define deprecation strategy
• Maintain changelog
• Monitor adoption across products

Integration with Agents

Skill Version: 1.0.0 Last Updated: 2025-10-31 Maintained by: AI Agent Hub Team

Related Skills

• a11y-testing - Automated accessibility testing to validate WCAG compliance of design system components
• focus-management - Keyboard focus patterns for accessible interactive widgets in design systems
• type-safety-validation - End-to-end type safety with Zod for design token schemas and component props
• react-server-components-framework - React 19 patterns for server-rendered design system components

Key Decisions

Capability Details

design-tokens

Keywords: design tokens, css variables, theme, colors, spacing Solves:

• Create design token system
• Color palette
• Typography scale

component-architecture

Keywords: component library, atomic design, atoms, molecules Solves:

• Structure component library
• Compound components
• Variants

accessibility

Keywords: a11y, wcag, aria, keyboard navigation, focus Solves:

• WCAG 2.1 AA compliance
• ARIA attributes
• Keyboard support

theming

Keywords: theme, dark mode, light mode, color scheme Solves:

• Implement dark/light mode
• Theme switching
• CSS custom properties