Create Design System

Create Design System

Estimated time: 6-12 weeks

A design system is the single source of truth for your organization's visual language and UI components. It reduces duplication, enforces consistency, improves accessibility, and accelerates development by providing pre-built, tested, documented components. This workflow takes you from a UI audit through design token definition, component development, documentation, and the hardest part: organizational adoption.

The workflow is structured to deliver value incrementally. You will start by auditing what exists, define the foundational tokens, build a small set of core components, document them thoroughly, and then expand based on adoption feedback. A design system that nobody uses is worse than no design system at all -- so adoption strategy is woven throughout.

When to Use

• User wants to create design system
• User needs a structured, step-by-step process for create design system
• User wants to create a design system
• I need to build a component library
• How do I establish design tokens
• Do NOT use when: the request is outside the scope of create design system or requires professional advice beyond educational guidance
• Do NOT use for single-step tasks that one atomic skill can handle independently

Prerequisites

Before starting this workflow, ensure:

• An existing product (or products) with UI inconsistencies to resolve
• Design team or design lead who can define visual standards
• Frontend engineering capacity for component development
• Stakeholder support for the investment (design systems take time to pay off)
• Chosen framework (React, Vue, or framework-agnostic Web Components)

Steps

Step 1: Audit Existing UI (uses: accessibility-auditor)

evaluate the current state of your UI. Conduct a visual audit: screenshot every unique button, form element, color, typography style, spacing value, and icon across all products. Catalog the inconsistencies. Run an accessibility audit (WCAG 2.2 Level AA) to identify violations that the design system must address. This audit becomes your "before" baseline and prioritization input.

• Input: Existing product(s) with their UI, Any existing style guides or brand guidelines, Known accessibility issues
• Output: Visual inventory: catalog of every unique UI pattern in use, Inconsistency report (e.g., "17 different button styles found"), Accessibility audit report with WCAG violations
• Key focus: Use the Accessibility Auditor skill to evaluate the current state of your UI

Step 2: Define Design Tokens (uses: css-master)

define your design token architecture: the atomic values (colors, spacing, typography, shadows, borders, breakpoints) that every component will reference. Use the Tailwind Designer skill if you are using Tailwind to map tokens to a custom theme configuration. Design tokens in three tiers: global (raw values), semantic (purpose-based aliases), and component (component-specific supersedes). Ensure tokens support dark mode and high-contrast themes from the start.

• Input: Brand guidelines (colors, typography, spacing), Audit results from Step 1, Multi-theme requirements (dark mode, high contrast)
• Output: Design token specification (JSON/YAML format), Color palette with semantic aliases (primary, secondary, success, error, etc.), Typography scale (font families, sizes, weights, line heights)
• Key focus: Use the CSS Master skill to define your design token architecture: the atomic values (colors, spacing, typography, shadows, borders, breakpoints) that every component will reference

Step 3: Build Core Components (uses: component-library)

design component APIs that are composable, accessible, and flexible. Use the React Architect skill (or equivalent for your framework) to implement the components with proper TypeScript types, ref forwarding, and polymorphic props (as/component pattern). Start with the 8-12 foundational components: Button, Input, Select, Checkbox, Radio, TextArea, Card, Modal, Toast, Badge, Avatar, and Spinner. Each component must be fully accessible by default (keyboard navigation, ARIA attributes, focus management).

• Input: Design tokens from Step 2, Prioritized component list from Step 1, Framework choice (React, Vue, etc.)
• Output: 8-12 core components with full TypeScript types, Component API documentation (props, variants, sizes), Accessibility implementation (ARIA, keyboard nav, focus management)
• Key focus: Use the Component Library skill to design component APIs that are composable, accessible, and flexible

Step 4: Test Components Thoroughly (uses: unit-test-writer)

write unit tests for component behavior (interactions, state changes, prop variations). Use the Visual Regression skill to set up visual regression testing that catches unintended visual changes. Re-run the Accessibility Auditor skill to verify every component meets WCAG 2.2 Level AA. Test across supported browsers and devices. The test suite must be fast enough to run in CI on every PR.

• Input: Components from Step 3, Visual design specifications, Browser/device support requirements
• Output: Unit test suite (behavior and interaction tests), Visual regression test baseline screenshots, Accessibility test suite (automated axe-core + manual checklist)
• Key focus: Use the Unit Test Writer skill to write unit tests for component behavior (interactions, state changes, prop variations)

Step 5: Build Documentation Site (uses: docs-site-builder)

create a documentation site that serves as the design system's home. Include: live component playground (interactive props), copy-pasteable code examples, design token reference, accessibility guidelines, getting started guide, contribution guide, and migration guide from old patterns. The docs site is the design system's marketing material -- it must be excellent.

• Input: Components from Step 3, Design tokens from Step 2, Target audience (designers, developers, product managers)
• Output: Documentation site with live component playground, Getting started guide (install, configure, use first component), Component API reference with interactive examples
• Key focus: Use the Docs Site Builder skill to create a documentation site that serves as the design system's home

Step 6: Establish Versioning and Release Process (uses: changelog-writer)

establish a versioning and release process. Follow semantic versioning strictly: patch for bug fixes, minor for new features and new components, major for breaking API changes. Automate changelog generation from conventional commits. Set up a release pipeline that publishes to your package registry (npm, internal registry). Create a deprecation policy: components and props get deprecated warnings for at least one major version before removal.

• Input: Component library package, Consumer applications, Breaking change expectations
• Output: Semantic versioning policy, Automated changelog generation, Release pipeline (npm publish on tag)
• Key focus: Use the Changelog Writer skill to establish a versioning and release process

Step 7: Drive Adoption (uses: component-library)

develop an adoption strategy. Start with one willing team as a pilot. Help them migrate their most-used components and measure the reduction in CSS and custom component code. Create codemods or migration scripts for common patterns. Track adoption metrics: percentage of UI using design system components, number of custom components replaced, and developer satisfaction scores. Address resistance by showing time savings and quality improvements.

• Input: Published design system package, Product teams as consumers, Existing component usage in products
• Output: Adoption metrics dashboard, Migration scripts/codemods for common patterns, Pilot team case study with measured improvements
• Key focus: Use the Component Library skill to develop an adoption strategy