Accessible Design Tokens — Accessible Color, Typography, and Spacing

In this tutorial, you will learn about Accessible Design Tokens. We cover key concepts, practical examples, and best practices to help you master this topic.

Accessible design tokens define color palettes with WCAG-compliant contrast, typography scales with readable sizes and line heights, and spacing units that ensure touch targets meet minimum size requirements.

What You'll Learn

You will learn how to create design tokens that bake in Accessibility, how to validate tokens against WCAG criteria, and how to organize tokens for consistent accessible usage.

Why It Matters

Design tokens are the foundation of a design system. If the tokens are inaccessible, every component built from them will be inaccessible. Getting tokens right prevents accessibility issues from propagating.

Real-World Use

DodaKit's design tokens include a color palette validated for 4.5:1 contrast, a typography scale starting at 16px with 1.5 line height, and spacing tokens that enforce minimum 44px touch targets.

flowchart TD
  A[Design Tokens] --> B[Color Tokens]
  A --> C[Typography Tokens]
  A --> D[Spacing Tokens]
  A --> E[Focus Tokens]
  A --> F[Motion Tokens]
  B --> B1[Foreground, background]
  B --> B2[Semantic colors]
  C --> C1[Size, line height]
  C --> C2[Font family]
  D --> D1[Touch targets]
  D --> D2[Layout spacing]
  E --> E1[Focus ring]
  F --> F1[Duration, easing]

Color Tokens

Define color tokens with accessibility baked in. Each foreground-background pair must meet WCAG contrast ratios: 4.5:1 for small text, 3:1 for large text and UI components.

// Accessible color token validator
function validateColorTokens(tokens) {
  const results = [];

  tokens.forEach(token => {
    const foreground = token.foreground;
    const background = token.background;

    // Relative luminance calculation (simplified)
    const getLuminance = (hex) => {
      const rgb = hex.match(/[A-Fa-f0-9]{2}/g).map(c => {
        const v = parseInt(c, 16) / 255;
        return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
      });
      return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2];
    };

    const l1 = getLuminance(foreground);
    const l2 = getLuminance(background);
    const lighter = Math.max(l1, l2);
    const darker = Math.min(l1, l2);
    const contrast = (lighter + 0.05) / (darker + 0.05);

    results.push({
      name: token.name,
      foreground: foreground,
      background: background,
      contrastRatio: Math.round(contrast * 100) / 100,
      passesAA: contrast >= 4.5,
      passesLarge: contrast >= 3.0,
      status: contrast >= 4.5 ? 'Pass' : contrast >= 3.0 ? 'Large only' : 'Fail'
    });
  });

  return results;
}

const tokens = [
  { name: 'text-primary', foreground: '#1a1a1a', background: '#ffffff' },
  { name: 'text-secondary', foreground: '#666666', background: '#ffffff' },
  { name: 'text-disabled', foreground: '#999999', background: '#ffffff' }
];

console.table(validateColorTokens(tokens));

Expected output:

┌─────────┬────────────────┬─────────────┬──────────────┬──────────────┬──────────────┬──────────────┬──────────┐
│ (index) │ name           │ foreground  │ background   │ contrastRatio│ passesAA     │ passesLarge  │ status   │
├─────────┼────────────────┼─────────────┼──────────────┼──────────────┼──────────────┼──────────────┼──────────┤
│ 0       │ text-primary   │ '#1a1a1a'  │ '#ffffff'    │ 15.35        │ true         │ true         │ 'Pass'   │
│ 1       │ text-secondary │ '#666666'  │ '#ffffff'    │ 5.74         │ true         │ true         │ 'Pass'   │
│ 2       │ text-disabled  │ '#999999'  │ '#ffffff'    │ 2.82         │ false        │ false        │ 'Fail'   │
└─────────┴────────────────┴─────────────┴──────────────┴──────────────┴──────────────┴──────────────┴──────────┘

Typography Tokens

Define a typography scale with accessible sizes. Minimum 16px for body text. Line height between 1.5 and 2.0. Font families that include sans-serif fallbacks.

Spacing Tokens

Define spacing tokens that ensure interactive elements have minimum 44x44px touch targets. Use 4px or 8px grid units for consistency.

/* Accessible design token definitions */
:root {
  /* Color tokens — all validated for 4.5:1 contrast */
  --ds-color-primary: #005fcc;
  --ds-color-on-primary: #ffffff;
  --ds-color-text-primary: #1a1a1a;
  --ds-color-text-secondary: #505050;
  --ds-color-background: #ffffff;
  --ds-color-surface: #f5f5f5;
  --ds-color-border: #cccccc;
  --ds-color-error: #cc3300;

  /* Typography tokens */
  --ds-font-body: 'Inter', 'Segoe UI', Arial, sans-serif;
  --ds-font-heading: 'Inter', 'Segoe UI', Arial, sans-serif;
  --ds-font-size-sm: 0.875rem;  /* 14px */
  --ds-font-size-md: 1rem;      /* 16px */
  --ds-font-size-lg: 1.25rem;   /* 20px */
  --ds-font-size-xl: 1.5rem;    /* 24px */
  --ds-font-size-2xl: 2rem;     /* 32px */
  --ds-line-height-sm: 1.3;
  --ds-line-height-md: 1.5;
  --ds-line-height-lg: 1.8;

  /* Spacing tokens */
  --ds-space-xs: 0.25rem;  /* 4px */
  --ds-space-sm: 0.5rem;   /* 8px */
  --ds-space-md: 1rem;     /* 16px */
  --ds-space-lg: 1.5rem;   /* 24px */
  --ds-space-xl: 2rem;     /* 32px */

  /* Focus tokens */
  --ds-focus-ring: 3px solid #005fcc;
}

Common Mistakes

1. Defining Colors Without Contrast Validation

Creating color tokens without checking contrast leads to inaccessible components. Validate every foreground-background pair.

2. Typography Under 16px

Body text below 16px fails readability requirements. Start the body scale at 16px.

3. Spacing Tokens That Do Not Support 44px Touch Targets

Interactive components need minimum 44x44px touch targets. Ensure spacing tokens can produce this.

4. No Focus Ring Token

A focus ring should be a design token so it is consistent. Define it at the token level.

5. Hardcoding Colors in Components

When colors are hardcoded in components, they bypass the token system and may be inaccessible. Use tokens everywhere.

6. Not Defining Token Aliases

Tokens should have semantic aliases (--ds-color-text-primary) not just raw values (--ds-blue-600). Aliases make usage clear.

7. No Token for Error States

Error colors must also meet contrast requirements. Define error tokens and validate them.

Practice Questions

1. What are the four main categories of accessibility-related design tokens?

Color, typography, spacing, and focus tokens.

2. What WCAG contrast ratio must small text tokens meet?

4.5:1 for normal text, 3:1 for large text and UI components.

3. What is the minimum body text size in an accessible typography scale?

16px (1rem).

4. Why should focus indicators be defined as design tokens?

Consistency. A focus ring defined as a token looks the same on every component.

5. Challenge: Create an accessible color token set for a design system. Include 5 foreground-background pairs and validate each against WCAG AA.

FAQ

Mini Project

Create an accessible design token specification with at least 20 tokens across color, typography, spacing, and focus categories. Validate all color pairs against WCAG AA.

What's Next

Learn about Accessible Color Systems for building inclusive color palettes. Then explore Typography System accessibility.