Design Token System

Single source of truth for visual design decisions with accessibility compliance.

When to Use This Skill

• Building a consistent design system

• Need WCAG AA compliant color contrast

• Want type-safe token access

• Supporting multiple frameworks (Tailwind, CSS-in-JS)

Core Concepts

Design tokens provide:

• Typography - Font families, sizes, weights, presets

• Colors - Semantic palettes with contrast ratios

• Type safety - TypeScript types for autocomplete

• Framework agnostic - Export to CSS vars, Tailwind, etc.

Implementation

TypeScript

// tokens/typography.ts export const fontFamily = { sans: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif', mono: '"SF Mono", Monaco, "Cascadia Code", Consolas, monospace', } as const;

export const fontSize = { xs: '12px', sm: '14px', base: '16px', lg: '18px', xl: '20px', '2xl': '24px', '3xl': '30px', '4xl': '36px', } as const;

export const fontWeight = { normal: 400, medium: 500, semibold: 600, bold: 700, } as const;

export const lineHeight = { tight: 1.2, snug: 1.3, normal: 1.5, relaxed: 1.625, } as const;

// Typography presets for consistent usage export const typographyPresets = { h1: { fontSize: fontSize['3xl'], fontWeight: fontWeight.bold, lineHeight: lineHeight.tight, }, h2: { fontSize: fontSize['2xl'], fontWeight: fontWeight.semibold, lineHeight: lineHeight.snug, }, h3: { fontSize: fontSize.xl, fontWeight: fontWeight.semibold, lineHeight: lineHeight.snug, }, body: { fontSize: fontSize.base, fontWeight: fontWeight.normal, lineHeight: lineHeight.normal, }, caption: { fontSize: fontSize.xs, fontWeight: fontWeight.normal, lineHeight: lineHeight.snug, }, } as const;

Color Tokens

// tokens/colors.ts export const primary = { 50: '#E6F4F5', 100: '#CCE9EB', 200: '#99D3D7', 300: '#66BDC3', 400: '#33A7AF', 500: '#21808D', // Main primary 600: '#1A6671', 700: '#144D55', 800: '#0D3338', 900: '#071A1C', } as const;

export const neutral = { 50: '#F8F9FA', 100: '#F1F3F5', 200: '#E9ECEF', 300: '#DEE2E6', 400: '#CED4DA', 500: '#ADB5BD', 600: '#868E96', 700: '#495057', 800: '#343A40', 900: '#1F2121', } as const;

export const semantic = { success: { light: '#86efac', main: '#218081', dark: '#16a34a' }, warning: { light: '#fde047', main: '#A84F2F', dark: '#92400E' }, error: { light: '#fca5a5', main: '#C0152F', dark: '#9f1239' }, info: { light: '#99D3D7', main: '#62756E', dark: '#475569' }, } as const;

// Semantic background colors export const background = { default: '#1F2121', surface: '#262828', elevated: '#334155', overlay: 'rgba(31, 33, 33, 0.8)', } as const;

// Text colors with WCAG contrast ratios export const text = { primary: '#FCFCF9', // 15.8:1 - AAA secondary: '#B8BABA', // 8.2:1 - AAA tertiary: '#9A9E9E', // 5.8:1 - AA muted: '#7D8282', // 4.5:1 - AA minimum link: '#32B8C6', // 6.2:1 - AA } as const;

export const border = { default: 'rgba(167, 169, 169, 0.20)', subtle: 'rgba(119, 124, 124, 0.30)', strong: '#777C7C', focus: '#21808D', } as const;

TypeScript Types

// types/tokens.ts export type FontFamily = keyof typeof fontFamily; export type FontSize = keyof typeof fontSize; export type FontWeight = keyof typeof fontWeight; export type TypographyPreset = keyof typeof typographyPresets;

export type PrimaryColor = keyof typeof primary; export type NeutralColor = keyof typeof neutral; export type SemanticColor = keyof typeof semantic; export type BackgroundColor = keyof typeof background; export type TextColor = keyof typeof text;

CSS Variables Export

// tokens/export.ts export function generateCSSVariables(): string { return ` :root { /* Typography */ --font-sans: ${fontFamily.sans}; --font-mono: ${fontFamily.mono}; --text-sm: ${fontSize.sm}; --text-base: ${fontSize.base}; --text-lg: ${fontSize.lg};

/* Colors */ --color-primary: ${primary[500]}; --color-primary-light: ${primary[300]}; --color-primary-dark: ${primary[700]};

/* Backgrounds */ --bg-default: ${background.default}; --bg-surface: ${background.surface}; --bg-elevated: ${background.elevated};

/* Text */ --text-primary: ${text.primary}; --text-secondary: ${text.secondary}; --text-muted: ${text.muted};

/* Borders */ --border-default: ${border.default}; --border-focus: ${border.focus}; }`; }

Tailwind Integration

// tailwind.config.ts import { primary, neutral, background, text } from './tokens/colors';

export default { theme: { extend: { colors: { primary: { 50: primary[50], 500: primary[500], 900: primary[900], DEFAULT: primary[500], }, neutral, }, backgroundColor: { default: background.default, surface: background.surface, elevated: background.elevated, }, textColor: { primary: text.primary, secondary: text.secondary, muted: text.muted, }, }, }, };

Usage Examples

CSS-in-JS

import styled from '@emotion/styled'; import { text, background, typographyPresets, border } from '@/tokens';

export const Button = styled.button` font-size: ${typographyPresets.body.fontSize}; font-weight: ${typographyPresets.body.fontWeight}; background-color: ${primary[500]}; color: ${text.primary};

&:hover { background-color: ${primary[400]}; }

&:focus { outline: 2px solid ${border.focus}; outline-offset: 2px; } `;

React Component

import { typographyPresets, text } from '@/tokens';

export function Heading({ children }: { children: React.ReactNode }) { return ( <h1 style={{ ...typographyPresets.h1, color: text.primary, }}> {children} </h1> ); }

WCAG Compliance

Token Color Contrast Level

text.primary #FCFCF9 15.8:1 AAA

text.secondary #B8BABA 8.2:1 AAA

text.tertiary #9A9E9E 5.8:1 AA

text.muted #7D8282 4.5:1 AA min

Best Practices

• Use semantic tokens (text.primary not #FCFCF9)

• Leverage typography presets for consistency

• Test all text colors meet WCAG AA (4.5:1)

• Export TypeScript types for autocomplete

• Document contrast ratios for each text color

Common Mistakes

• Using raw hex values instead of tokens

• Not testing contrast ratios

• Missing focus states for accessibility

• Inconsistent typography across components

• No dark/light mode support

Related Patterns

• pwa-setup - Mobile app styling

• mobile-components - Responsive design