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
• assets/design-tokens-template.json - W3C design token format
• assets/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:

Layer	Description	Examples
Design Tokens	Foundational design decisions	Colors, spacing, typography
Components	Reusable UI building blocks	Button, Input, Card, Modal
Patterns	Common UX solutions	Forms, Navigation, Layouts
Guidelines	Rules and best practices	Accessibility, naming, APIs
Documentation	How to use everything	Storybook, usage examples

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:

Category	Examples	Scale
Colors	blue.500, text.primary, feedback.error	50-950
Typography	fontSize.base, fontWeight.semibold	xs-5xl
Spacing	spacing.4, spacing.8	0-24 (4px base)
Border Radius	borderRadius.md, borderRadius.full	none-full
Shadows	shadow.sm, shadow.lg	xs-xl

---

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:

Level	Description	Examples
Atoms	Indivisible primitives	Button, Input, Label, Icon
Molecules	Simple compositions	FormField, SearchBar, Card
Organisms	Complex compositions	Navigation, Modal, DataTable
Templates	Page layouts	DashboardLayout, AuthLayout
Pages	Specific instances	HomePage, SettingsPage

---

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:

Approach	Best For	Complexity
Tailwind @theme	New projects	Low
Tailwind dark: variant	Quick implementation	Low
CSS Variables	Framework-agnostic	Medium
ThemeProvider	CSS-in-JS apps	Medium

---

Accessibility Guidelines

WCAG 2.1 Level AA Requirements

Requirement	Threshold	Tools
Normal text contrast	4.5:1 minimum	WebAIM Contrast Checker
Large text contrast	3:1 minimum
UI components	3:1 minimum

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

Agent	Usage
Rapid UI Designer	Uses tokens for consistent interfaces, references components
Frontend UI Developer	Implements components following patterns
Code Quality Reviewer	Validates design system adherence

---

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

Decision	Choice	Rationale
Token Format	W3C Design Tokens	Industry standard, tool-agnostic, supports theming
Component Architecture	Atomic Design	Scalable hierarchy from atoms to pages
Styling Approach	Tailwind @theme directive	Native CSS variable integration, zero runtime
Variant Management	CVA (Class Variance Authority)	Type-safe variants, composable styles
Documentation	Storybook	Interactive component playground, visual testing

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