/kb-design-system

name: kb-design-system
description: Reference data, not a reviewer. Validate design system tokens for WCAG AA/AAA contrast. Compute color token contrast, focus ring validation (WCAG 2.4.13), motion tokens, and spacing for touch targets across frameworks.
license: MIT
disable-model-invocation: true
user-invocable: false
metadata:
  tier: reference
  domain: cross-cutting
  output: none
  effort: low
  title: Design System

Design System Accessibility Skill

This skill provides reference data for design token contrast validation, focus ring compliance, and spacing audits. Used by the `design-system-auditor` skill.

---

WCAG Contrast Ratio - Computation Reference

Step 1: Linearize sRGB Channel

For each channel `C` in `[0, 255]`:

c = C / 255
c_lin = c / 12.92              if c <= 0.04045
c_lin = ((c + 0.055) / 1.055)^2.4   otherwise

Step 2: Relative Luminance

L = 0.2126 * R_lin + 0.7152 * G_lin + 0.0722 * B_lin

Step 3: Contrast Ratio

ratio = (L_lighter + 0.05) / (L_darker + 0.05)

Quick JavaScript Implementation

function relativeLuminance(hex) {
  const c = hex.replace('#', '').match(/.{2}/g)
    .map(h => parseInt(h, 16) / 255)
    .map(c => c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
}

function contrastRatio(hex1, hex2) {
  const L1 = relativeLuminance(hex1);
  const L2 = relativeLuminance(hex2);
  const lighter = Math.max(L1, L2);
  const darker = Math.min(L1, L2);
  return (lighter + 0.05) / (darker + 0.05);
}

// Example
contrastRatio('#6B7280', '#FFFFFF'); // 4.83:1 - PASSES AA, fails AAA
contrastRatio('#9CA3AF', '#FFFFFF'); // 2.54:1 - FAILS AA

HSL to Hex Conversion (for CSS variable tokens)

Some design systems store colors as HSL triplets (e.g., shadcn/ui themes for Tailwind v3). Current shadcn/ui and Tailwind v4 themes use `oklch()`; convert those to sRGB before computing contrast.

function hslToHex(h, s, l) {
  s /= 100; l /= 100;
  const a = s * Math.min(l, 1 - l);
  const f = n => {
    const k = (n + h / 30) % 12;
    return l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
  };
  return '#' + [f(0), f(8), f(4)]
    .map(x => Math.round(x * 255).toString(16).padStart(2, '0'))
    .join('');
}

// shadcn/ui: --muted-foreground: 215.4 16.3% 46.9%
hslToHex(215.4, 16.3, 46.9); // -> #64748B (4.76:1 on white)

---

WCAG Contrast Thresholds

Each WCAG contrast threshold, with use case, AA, AAA and notes.

| Use Case | AA | AAA | Notes | |----------|-----|-----|-------| | Normal text (< 18pt / < 14pt bold) | 4.5:1 | 7:1 | Most body text | | Large text (>= 18pt / >= 14pt bold) | 3:1 | 4.5:1 | Headings, display text | | UI components (borders, icons) | 3:1 | - | Input borders, icon buttons | | Focus indicators | 3:1 against adjacent colors (1.4.11) | 3:1 focused vs unfocused, 2px perimeter area (2.4.13) | 2.4.13 Focus Appearance is AAA | | Placeholder text | 4.5:1 | - | Counts as normal text | | Disabled state | Exempt | Exempt | Documented exemption | | Logo / brand | Exempt | Exempt | No requirement | | Decorative content | Exempt | Exempt | Must be marked decorative |

---

Framework Token Paths

Token paths and default palette values for Tailwind CSS, shadcn/ui and Radix, Material UI, Chakra UI and Style Dictionary are in [references/framework-token-paths.md](references/framework-token-paths.md). Read it when the project uses one of them.

---

High-Risk Token Pairs - Known Failures

Each token pair, with its common value, ratio on white, status and notes.

| Token pair | Common value | Ratio on white | Status | Notes | |-----------|-------------|----------------|--------|-------| | MUI `warning.main` | `#ed6c02` | 3.11:1 | FAIL | Orange on white - fails for normal text | | MUI `warning.light` | `#ff9800` | 2.16:1 | FAIL | Light orange - critical failure | | MUI `info.main` | `#0288d1` | 3.86:1 | FAIL | Fails for normal text | | Tailwind v3 `amber-400` | `#FBBF24` | 1.67:1 | FAIL | Never use amber-400 as text | | Tailwind v3 `yellow-400` | `#FACC15` | 1.53:1 | FAIL | Yellow always fails on white | | Tailwind v3 `gray-400` | `#9CA3AF` | 2.54:1 | FAIL | Common placeholder color | | Tailwind v3 `gray-500` | `#6B7280` | 4.83:1 | Pass AA, fails AAA | Often assumed to fail; it passes AA | | Chakra v2 `chakra-placeholder-color` | `gray.500` = `#718096` | 4.02:1 | FAIL | Chakra v2 default placeholder | | MUI `text.disabled` | `rgba(0,0,0,0.38)` | ~2.68:1 | Exempt | Disabled = exempt per WCAG | | MUI `action.active` | `rgba(0,0,0,0.54)` | ~4.61:1 | Pass | Icon color on white | | shadcn v3 theme `--muted-foreground` | `hsl(215.4 16.3% 46.9%)` | ~4.76:1 | Pass AA, fails AAA | Tailwind v3 shadcn theme | | shadcn v3 theme `--destructive` | `hsl(0 84.2% 60.2%)` | ~3.76:1 | FAIL | Red text on white; passes 3:1 for large text and UI |

Compliant Replacements

Each failing token, with its replacement, new ratio and notes.

| Failing token | Replacement | New ratio | Notes | |--------------|-------------|-----------|-------| | `#9CA3AF` (gray-400) | `#6B7280` (gray-500) | 4.83:1 | Passes AA; use `#595959` (7.00:1) for AAA | | `#6B7280` (gray-500), AAA target only | `#4B5563` (gray-600) | 7.56:1 | Meets AAA | | `#ed6c02` (MUI warning) | `#b45309` (amber-700) | 5.02:1 | | | `#ff9800` (MUI warning.light) | `#b45309` (amber-700) | 5.02:1 | | | `#FBBF24` (amber-400) | `#92400e` (amber-800) | 7.09:1 | Keep amber-400 for backgrounds, not text | | `#FACC15` (yellow-400) | `#713f12` (yellow-900) | 8.67:1 | Keep yellow-400 for backgrounds, not text | | `hsl(0 84.2% 60.2%)` (shadcn destructive) | `#b91c1c` (red-700) | 6.47:1 | |

---

Storybook addon-a11y Configuration

npm install --save-dev @storybook/addon-a11y

// .storybook/main.js (ESM; Storybook 10 is ESM-only)
export default {
  addons: ['@storybook/addon-a11y'],
};

// .storybook/preview.js - global configuration
export const parameters = {
  a1