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. 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 = {
a11y: {
options: {
runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'] },
},
config: {
rules: [
{ id: 'target-size', enabled: true }, // WCAG 2.5.8; off by default in axe
],
},
// 'todo' (the default) reports violations as warnings; 'error' fails the test
test: 'error',
},
};
// Per-story override
export const MyStory = {
parameters: {
a11y: {
config: {
rules: [{ id: 'color-contrast', enabled: false }], // Document WHY
}
}
}
};
axe-core has no focus-visible rule; check focus indicators manually or with Playwright.
Running Storybook a11y Checks in CI
# Storybook 9 and later recommend the Vitest addon (npx storybook add @storybook/addon-vitest),
# which runs the a11y checks with each story test. The test runner still works:
npm install --save-dev @storybook/test-runner
# package.json scripts
{
"scripts": {
"storybook:test": "test-storybook",
"storybook:test:a11y": "test-storybook --ci"
}
}
# Run in CI
npx storybook dev --port 6006 &
npx wait-on tcp:6006
npx test-storybook --ci
WCAG 2.4.13 Focus Appearance Requirements (AAA, exceeds AA baseline)
WCAG 2.4.13 Focus Appearance (Level AAA in WCAG 2.2) - exceeds the 2.4.7 Focus Visible (AA) baseline, but recommended as best practice:
- Area: The focus indicator is at least as large as the area of a 2 CSS pixel thick perimeter of the unfocused component
- Contrast change: The focus indicator area has a contrast ratio of at least 3:1 between the same pixels in the focused and unfocused states
- Exceptions: The indicator is determined by the user agent and cannot be adjusted by the author, or the author has not modified the indicator or its background
Obscuring by author content is a separate requirement: 2.4.11 Focus Not Obscured (Minimum, AA) and 2.4.12 (Enhanced, AAA).
Minimum Compliant Focus Ring Implementation
/* Focus ring that meets 1.4.11 at AA and helps meet 2.4.13 (AAA) */
:focus-visible {
outline: 2px solid #0054B3; /* >= 2px width */
outline-offset: 2px; /* Separates from component edge */
/* #0054B3 on #FFF = 7.19:1 -> passes 3:1 for UI components */
}
/* Dark mode variant */
@media (prefers-color-scheme: dark) {
:focus-visible {
outline-color: #7CAFFF; /* lighter blue on dark background */
/* #7CAFFF on #1E1E1E = 7.49:1 */
}
}
/* VIOLATION patterns to detect */
:focus { outline: none; } /* Hard fail */
:focus { outline: 0; } /* Hard fail */
:focus-visible { box-shadow: none; outline: none; } /* Hard fail */
button:focus { outline: none; } /* Hard fail */
*:focus { outline-color: transparent; } /* Hard fail */
Focus Ring Token Validation Checklist
Each check, with its requirement and tool.
| Check | Requirement | Tool |
|---|---|---|
outline-width >= 2px |
WCAG 2.4.13 (AAA) area requirement | CSS audit |
| Focus color contrast >= 3:1 | Against adjacent background (1.4.11) | Contrast calculator |
| Focus state differs from unfocused | Visible change required | Visual inspection |
No outline: none without replacement |
N/A | grep / CSS audit |
| Present in both light and dark modes | Consistent | Visual inspection |
Design Token File Discovery Commands
# Find all token files in a project
find . -type f \( \
-name "tokens.json" \
-o -name "design-tokens.json" \
-o -name "colors.json" \
-o -name "variables.css" \
-o -name "tokens.css" \
-o -name "_variables.scss" \
-o -name "theme.ts" \
-o -name "theme.js" \
-o -name "tailwind.config.*" \
\) \
-not -path "*/node_modules/*" \
-not -path "*/.next/*" \
-not -path "*/dist/*"
# PowerShell equivalent
Get-ChildItem -Recurse -File -Include tokens.json,design-tokens.json,colors.json,`
variables.css,tokens.css,_variables.scss,theme.ts,theme.js,tailwind.config.js,tailwind.config.ts `
| Where-Object FullName -notmatch 'node_modules|\.next|dist'
Severity Classification
Each finding, with its severity (the a11y-core values).
| Finding | Severity |
|---|---|
| Text token below 3:1 | critical |
| Text token 3:1-4.49:1 (normal text) | serious |
| Text token 4.5:1-6.99:1, AAA target | minor |
| UI component token below 3:1 | serious |
| Focus ring missing completely | critical |
| Focus ring below 2px (2.4.13, AAA) | minor |
| Focus ring contrast below 3:1 | serious |
| Touch target token below 24 x 24px (WCAG 2.5.8) | serious |
| Touch target token below 44 x 44px (WCAG 2.5.5) | minor |
No prefers-reduced-motion reset |
minor |
| Placeholder color below 4.5:1 | serious |
| Disabled token below 3:1 | none - note only (documented exemption) |