design-system-alignment

name	design-system-alignment
description	Use when working with or building design systems — tokens, components, naming conventions, theming, or pattern libraries — ensures consistency, accessibility compliance, and systematic thinking

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]

Step 4: Naming Conventions

Consistent naming makes a system learnable:

• Components: PascalCase for components, kebab-case for tokens
• Descriptive names: AlertDialog not Modal2 or PopupThing
• State modifiers: consistent pattern (e.g., --disabled, --error, --active)
• Size modifiers: use a scale (sm, md, lg) or semantic names (compact, comfortable, spacious)

Step 5: Accessibility Audit

For every component in the system, verify:

Check	Requirement
Colour contrast	All text/background pairings meet WCAG AA minimum
Keyboard access	Every interactive component is reachable and operable via keyboard
Screen reader	Every component announces its role, name, state, and value correctly
Focus indicator	Every focusable element has a visible focus ring
Touch targets	All interactive elements meet 44x44px minimum
Motion	All animations respect prefers-reduced-motion
Resize	Components function at 200% zoom

Step 6: Document and Communicate

A design system only works if people use it. Ensure:

• Every component has usage documentation with examples
• Accessibility requirements are documented per component, not in a separate "accessibility section"
• Migration guides exist for any changes to existing components
• The system is versioned so consumers know when changes occur

Integration

• Called by: ui-composition (when components need to align with a system)
• Pairs with: ui-composition (visual decisions), accessible-content (content patterns within components)
• Reviewed by: designpowers-critique