design-system-alignment

Design System Alignment

A design system is a shared language. When components are consistent, accessible, and well-documented, every new screen starts from a strong foundation. This skill ensures design work aligns with existing systems or builds new ones with the right properties.

When to Use

• A design system already exists and new work must align with it
• Building new components for an existing system
• Creating a new design system from scratch
• Auditing an existing system for consistency or accessibility
• Defining or modifying design tokens

Process

Step 1: Inventory the Existing System

If a design system exists, catalogue:

• Tokens: colours, spacing, typography, shadows, borders, motion
• Components: what exists, what states are covered, accessibility status
• Patterns: common layouts, form patterns, navigation patterns
• Documentation: what is documented, what is tribal knowledge
• Gaps: what is missing, inconsistent, or broken

If no system exists, document what patterns are already in use (even informally).

Step 2: Token Architecture

Design tokens are the atoms of the system. Structure them in layers:

Global tokens — raw values

color-blue-500: #3B82F6
spacing-4: 16px
font-size-base: 1rem

Semantic tokens — purpose-driven aliases

color-primary: {color-blue-500}
color-error: {color-red-600}
spacing-element: {spacing-4}
font-size-body: {font-size-base}

Component tokens — component-specific overrides

button-background: {color-primary}
button-padding: {spacing-3} {spacing-4}
input-border-color: {color-neutral-300}

Every token must meet accessibility requirements at the semantic level — if color-primary is used for text, it must have sufficient contrast against its background token.

Step 3: Component Specification

For each component, document:

## [Component Name]

**Purpose:** [What this component is for]

**Variants:** [e.g., primary, secondary, ghost, destructive]

**States:** [default, hover, focus, active, disabled, error, loading]

**Accessibility:**
- Role: [ARIA role if not implicit]
- Label: [How it is labelled — visible text, aria-label, aria-labelledby]
- Keyboard: [How to interact via keyboard]
- Screen reader: [What is announced in each state]
- Focus: [Focus indicator style, focus order]

**Tokens used:** [Which design tokens this component references]

**Do:** [Correct usage examples]
**Do not:** [Incorrect usage examples]