everyone-needs-a-copilot/design-patterns

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