design-patterns

name	design-patterns
description	Visual design patterns covering design tokens (color, spacing, typography), component state specifications, WCAG 2.1 AA compliance rules, and anti-patterns for hard-coded values or missing states. Use proactively when defining a design token system, specifying component states across all interactive conditions, verifying WCAG 2.1 AA compliance for contrast and touch targets, building a consistent accessible design system, or reviewing components for missing states or hard-coded values.
version	1.0.0
tags	["design","tokens","visual","components","accessibility","pattern","anti-pattern"]
when_to_use	["Defining a design token system for colors, spacing, or typography","Specifying component states across all interactive conditions","Verifying WCAG 2.1 AA compliance for contrast and touch targets","Building a consistent, accessible design system","Reviewing components for missing states or hard-coded values"]

Design Patterns

Visual design patterns for creating consistent, accessible interfaces with proper design tokens and component specifications.

Purpose

Provides patterns for:

• Design token systems (colors, typography, spacing)
• Component visual specifications
• WCAG 2.1 AA accessibility compliance
• Responsive design across breakpoints

---

Core Patterns

Pattern 1: Semantic Color Tokens

When to use: Defining color systems that work across themes.

Implementation:

/* Base palette (reference only) */
--blue-500: #3b82f6;
--blue-700: #1d4ed8;

/* Semantic tokens (use these) */
--color-primary: var(--blue-500);
--color-primary-hover: var(--blue-700);
--color-text: #111827;
--color-text-muted: #6b7280;
--color-background: #ffffff;
--color-error: #ef4444;
--color-success: #10b981;

Benefits:

• Theme switching via semantic tokens
• Consistent color usage across components
• Easier maintenance and updates

Pattern 2: 8px Spacing Scale

When to use: All spacing decisions (padding, margins, gaps).

Implementation:

--space-1: 0.25rem;  /* 4px - tight */
--space-2: 0.5rem;   /* 8px - compact */
--space-3: 0.75rem;  /* 12px */
--space-4: 1rem;     /* 16px - default */
--space-6: 1.5rem;   /* 24px - medium */
--space-8: 2rem;     /* 32px - large */
--space-12: 3rem;    /* 48px - section */

Benefits:

• Visual rhythm and consistency
• Predictable spacing relationships
• Easier to maintain

Pattern 3: Component State Matrix

When to use: Defining all interactive component states.

Implementation:

State	Background	Border	Text	Cursor
Default	--color-bg	--color-border	--color-text	default
Hover	--color-bg-hover	--color-border	--color-text	pointer
Focus	--color-bg	--color-focus-ring	--color-text	—
Active	--color-bg-active	--color-border	--color-text	pointer
Disabled	--color-bg	--color-border	--color-text-muted	not-allowed
Loading	--color-bg	--color-border	--color-text-muted	wait
Error	--color-bg	--color-error	--color-error	—

---

Anti-Patterns

Anti-Pattern 1: Hard-Coded Values

Aspect	Description
WHY	Breaks design system consistency, makes theme switching impossible
DETECTION	Raw hex colors, pixel values without tokens in CSS
FIX	Always use design tokens for colors, spacing, typography

Bad Example:

.button {
  background: #3b82f6;
  padding: 12px 16px;
  color: white;
}

Good Example:

.button {
  background: var(--color-primary);
  padding: var(--space-3) var(--space-4);
  color: var(--color-on-primary);
}

Anti-Pattern 2: Missing States

Aspect	Description
WHY	Creates incomplete interactions, accessibility failures
DETECTION	Components only define default + hover, missing focus/disabled/error
FIX	Define ALL states: default, hover, focus, active, disabled, loading, error

Anti-Pattern 3: Insufficient Contrast

Aspect	Description
WHY	WCAG 2.1 AA violation, excludes users with visual impairments
DETECTION	Text contrast < 4.5:1, UI component contrast < 3:1
FIX	Use contrast checker, ensure text 4.5:1, UI elements 3:1 minimum

---

WCAG 2.1 AA Requirements

Requirement	Threshold	Applies To
Text contrast	4.5:1	All text
Large text contrast	3:1	18px+ or 14px bold
UI component contrast	3:1	Borders, icons, focus rings
Touch target	44x44px	Mobile interactive elements
Focus visible	2px outline	All focusable elements

---

Validation Checklist

Color System

• All colors use semantic tokens, not raw values
• Text meets 4.5:1 contrast ratio
• UI components meet 3:1 contrast ratio
• Color is not sole indicator (add icons/text)

Components

• All states defined (default, hover, focus, active, disabled, loading, error)
• Touch targets minimum 44x44px
• Focus ring visible with 2px minimum
• Tokens used for all values

Responsive

• Works on mobile, tablet, desktop
• Typography scales appropriately
• Spacing adjusts for viewport
• No horizontal scroll on mobile

---

Output Templates

Design Tokens Spec

## Design Tokens: [System Name]

### Colors
| Token | Value | Usage |
|-------|-------|-------|
| --color-primary | #3b82f6 | Primary actions |
| --color-text | #111827 | Body text (4.54:1) |

### Typography
| Token | Value | Usage |
|-------|-------|-------|
| --text-base | 1rem | Body text |
| --font-sans | 'Inter', sans-serif | Primary font |

### Spacing
| Token | Value | Usage |
|-------|-------|-------|
| --space-4 | 1rem | Default padding |

Component Spec

## Component: [Name]

### Variants
| Variant | Use Case | Treatment |
|---------|----------|-----------|
| Primary | Main actions | Filled, brand |
| Secondary | Alternative | Outlined |

### States
| State | Background | Border | Text |
|-------|------------|--------|------|
| Default | --color-bg | --color-border | --color-text |

### Accessibility
- Contrast: X.X:1 (meets AA)
- Touch target: 44x44px
- Focus: 2px outline