Build Scalable Design Systems

This skill provides expertise in creating comprehensive, scalable design systems that bridge design and development, covering design tokens, component architecture, atomic design principles, accessibility standards, and building maintainable systems across multiple platforms and products. Core design token structure organizes tokens hierarchically from primitive to semantic - a JSON structure defining primitive color scales (e.g. blue.50 through blue.900), semantic aliases referencing primitives (primary.default/hover/pressed, text.primary/secondary/inverse), spacing scale tokens (xs through xl), and typography tokens (font families, font sizes, line heights).

Component API design defines consistent component interfaces with clear props and variants, demonstrated through a TypeScript ButtonProps interface specifying variant, size, children, disabled, loading, icon, iconPosition, and fullWidth props with usage examples. Atomic design implementation structures components into atoms (typography, form elements, icons, buttons, badges), molecules (search field, form field, card header - functional groupings of atoms), and organisms (navigation bar, data table, modal, form sections - complex composed components).

CSS architecture with design tokens is demonstrated through CSS custom properties generated from tokens (--color-primary-default, --spacing-md, --border-radius-md) consumed by component styles like a button's default, primary, and secondary variant classes. Documentation standards specify a six-part structure per component - overview (purpose and when to use), variants (visual examples of all states), props/API (complete parameter documentation), usage guidelines (dos and don'ts), accessibility (ARIA requirements, keyboard navigation), and code examples (implementation across platforms) - plus a design token documentation table format listing token name, value, and usage.

Accessibility and inclusive design cover WCAG AA color contrast standards (minimum 4.5:1 ratio, high-contrast AAA variants, never relying on color alone), demonstrated through component accessibility patterns - a Button component setting aria-busy and aria-disabled attributes, and a FormField component associating labels, required indicators, and error messages with role="alert". Cross-platform implementation covers design token distribution using Style Dictionary, configuring separate build targets that transform the same token source into CSS custom properties for web and Swift classes for iOS.

Governance and maintenance cover version management (semantic versioning for design system releases, a changelog with migration guides, gradual component deprecation with clear timelines), contribution guidelines (an RFC process for major changes, required design and development reviews, accessibility audits in the approval process, maintained test coverage), and quality assurance (visual regression testing with tools like Chromatic, automated accessibility testing with axe-core, performance benchmarks for component rendering, cross-browser compatibility validation).

Use this skill when building a design system from scratch or extending one - defining design tokens, component APIs, atomic component hierarchy, cross-platform token distribution, or governance processes. It is well suited to products spanning multiple platforms or teams that need a shared, versioned source of design truth. It is not meant for a single small project with no need for shared, reusable design tokens or cross-platform component consistency.

Input: the product's existing design language, target platforms, and component needs.

Output: a hierarchical design token structure, component API definitions, atomic component organization, and cross-platform token distribution configuration. Example semantic token referencing a primitive:

{
  "color": {
    "semantic": {
      "primary": {
        "default": "{color.primitive.blue.500}",
        "hover": "{color.primitive.blue.600}"
      }
    }
  }
}

Works with Style Dictionary for cross-platform token generation (CSS, Swift), Chromatic for visual regression testing, and axe-core for automated accessibility testing.

Design system engineers and design/development teams building or scaling a shared component library, and organizations that need consistent, accessible, cross-platform design tokens and components rather than platform-specific one-off styling.