/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`