@stephen-netu/design-system 0.1.0 → 0.2.0

package/dist/p0-primitives/theme.js

@@ -0,0 +1,150 @@
+/**
+ * Theme Utilities
+ *
+ * Factory functions for creating and composing themes.
+ *
+ * ADR: 2026-05-04-openui-generative-ui-integration
+ */
+/**
+ * Create a theme by merging overrides with a base theme
+ */
+export function createTheme(base, overrides) {
+    return {
+        ...base,
+        ...overrides,
+    };
+}
+/**
+ * Default dark theme — Neo-brutalist industrial
+ * Charcoal surfaces, brass accent, telemetry palette
+ */
+export const defaultDarkTheme = {
+    // Backgrounds (charcoal depth)
+    colorBgPrimary: '#0b0d0f',
+    colorBgSecondary: '#121518',
+    colorBgTertiary: '#181c20',
+    colorBgPanelElevated: '#20252a',
+    colorBgInset: '#0a0a0a',
+    // Foregrounds (warm silkscreen on dark)
+    colorFgPrimary: '#e8e0d0',
+    colorFgSecondary: '#a8a08c',
+    colorFgTertiary: '#6b6558',
+    colorFgMuted: '#3a3630',
+    // Accent (brass — energized signal, use sparingly)
+    colorAccent: '#b87333',
+    colorAccentHover: '#d4892f',
+    colorAccentActive: '#8a5526',
+    colorAccentSubtle: 'rgba(184, 115, 51, 0.08)',
+    colorAccentGlow: 'rgba(184, 115, 51, 0.28)',
+    colorAccentMuted: 'rgba(184, 115, 51, 0.16)',
+    colorAccentFaint: 'rgba(184, 115, 51, 0.04)',
+    // Telemetry
+    colorSuccess: '#4fa8a2',
+    colorWarning: '#d4a04c',
+    colorError: '#c14a4a',
+    colorInfo: '#5b8db8',
+    // Typography
+    fontSans: "'Outfit', system-ui, -apple-system, sans-serif",
+    fontMono: "'JetBrains Mono', 'Fira Code', ui-monospace, monospace",
+    // Animation
+    durationFast: '100ms',
+    durationNormal: '200ms',
+    durationSlow: '300ms',
+};
+/**
+ * Default light theme — warm desk surface
+ */
+export const defaultLightTheme = {
+    // Backgrounds (warm desk)
+    colorBgPrimary: '#d4d0c8',
+    colorBgSecondary: '#e8e4dc',
+    colorBgTertiary: '#c9c5bd',
+    colorBgPanelElevated: '#d9d5cd',
+    colorBgInset: '#bfbbb3',
+    // Foregrounds (dark on light)
+    colorFgPrimary: '#2a2a2a',
+    colorFgSecondary: '#5a5a5a',
+    colorFgTertiary: '#8a8a8a',
+    colorFgMuted: '#a0a0a0',
+    // Accent (brass — same in both modes)
+    colorAccent: '#b87333',
+    colorAccentHover: '#c9894f',
+    colorAccentActive: '#9a5f2a',
+    colorAccentSubtle: 'rgba(184, 115, 51, 0.12)',
+    colorAccentGlow: 'rgba(184, 115, 51, 0.2)',
+    colorAccentMuted: 'rgba(184, 115, 51, 0.15)',
+    colorAccentFaint: 'rgba(184, 115, 51, 0.06)',
+    // Feedback
+    colorSuccess: '#5a8a6e',
+    colorWarning: '#b8956b',
+    colorError: '#a65e5e',
+    colorInfo: '#6b8a9c',
+    // Typography
+    fontSans: "'Outfit', system-ui, -apple-system, sans-serif",
+    fontMono: "'JetBrains Mono', 'Fira Code', ui-monospace, monospace",
+    // Animation
+    durationFast: '100ms',
+    durationNormal: '200ms',
+    durationSlow: '300ms',
+};
+/**
+ * Control Room theme — terminal green / CRT aesthetic (opt-in alternate)
+ */
+export const controlRoomTheme = {
+    colorBgPrimary: '#0a0a0a',
+    colorBgSecondary: '#111111',
+    colorBgTertiary: '#141414',
+    colorBgPanelElevated: '#1a1a1a',
+    colorBgInset: '#080808',
+    colorFgPrimary: '#e8e8e8',
+    colorFgSecondary: '#888888',
+    colorFgTertiary: '#555555',
+    colorFgMuted: '#333333',
+    colorAccent: '#00ff41',
+    colorAccentHover: '#33ff66',
+    colorAccentActive: '#00cc33',
+    colorAccentSubtle: 'rgba(0, 255, 65, 0.1)',
+    colorAccentGlow: 'rgba(0, 255, 65, 0.3)',
+    colorAccentMuted: 'rgba(0, 255, 65, 0.2)',
+    colorAccentFaint: 'rgba(0, 255, 65, 0.05)',
+    colorSuccess: '#00ff41',
+    colorWarning: '#ff8c00',
+    colorError: '#ff3131',
+    colorInfo: '#00bfff',
+    fontSans: "'JetBrains Mono', 'IBM Plex Mono', 'Fira Code', ui-monospace, monospace",
+    fontMono: "'JetBrains Mono', 'IBM Plex Mono', 'Fira Code', ui-monospace, monospace",
+    durationFast: '50ms',
+    durationNormal: '100ms',
+    durationSlow: '150ms',
+};
+/**
+ * Brass accent theme variant — warm metallic (preserved for compatibility)
+ */
+export const brassAccentTheme = createTheme(defaultDarkTheme, {
+    colorAccent: '#b87333',
+    colorAccentHover: '#d4892f',
+    colorAccentActive: '#8a5526',
+    colorAccentSubtle: 'rgba(184, 115, 51, 0.08)',
+});
+/**
+ * Copper accent theme variant — reddish metallic (preserved for compatibility)
+ */
+export const copperAccentTheme = createTheme(defaultDarkTheme, {
+    colorAccent: '#b87333',
+    colorAccentHover: '#c98444',
+    colorAccentActive: '#a05f2a',
+    colorAccentSubtle: 'rgba(184, 115, 51, 0.08)',
+});
+/**
+ * High contrast accessibility theme
+ */
+export const highContrastTheme = createTheme(defaultDarkTheme, {
+    colorBgPrimary: '#000000',
+    colorBgSecondary: '#111111',
+    colorFgPrimary: '#ffffff',
+    colorFgSecondary: '#eeeeee',
+    colorFgMuted: '#aaaaaa',
+    colorAccent: '#ffcc00',
+    colorAccentHover: '#ffdd33',
+    colorAccentActive: '#e6b800',
+});

package/dist/p0-primitives/tokens/contrast-audit.d.ts

@@ -0,0 +1,42 @@
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+}
+/** Parse hex color (#rgb, #rrggbb) to RGB */
+export declare function parseHex(hex: string): RGB | null;
+/** Parse rgb(r,g,b) or rgba(r,g,b,a) to RGB */
+export declare function parseRgb(func: string): RGB | null;
+/** Parse HSLA colors */
+export declare function parseHsl(func: string): RGB | null;
+/** Parse any CSS color to RGB */
+export declare function parseColor(value: string): RGB | null;
+export declare function sRGBtoLinear(c: number): number;
+export declare function relativeLuminance(rgb: RGB): number;
+export declare function contrastRatio(a: RGB, b: RGB): number;
+interface AuditResult {
+    name: string;
+    fg: string;
+    bg: string;
+    fgResolved: string;
+    bgResolved: string;
+    ratio: number;
+    required: number;
+    pass: boolean;
+    type: string;
+    decorative: boolean;
+    status: 'pass' | 'fail' | 'warn';
+}
+export declare function extractCSSVariables(cssContent: string): Map<string, string>;
+/**
+ * Resolve CSS variable references with full chain traversal.
+ * Handles nested var(--a, var(--b, default)) patterns.
+ */
+export declare function resolveVarValue(value: string, variables: Map<string, string>, depth?: number): string;
+/** Run contrast checks on all defined token pairs */
+export declare function auditContrast(cssContent: string): AuditResult[];
+/** Format audit results for terminal output */
+export declare function formatAuditReport(results: AuditResult[]): string;
+export {};
+//# sourceMappingURL=contrast-audit.d.ts.map

package/dist/p0-primitives/tokens/contrast-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrast-audit.d.ts","sourceRoot":"","sources":["../../../src/p0-primitives/tokens/contrast-audit.ts"],"names":[],"mappings":"AAoBA,UAAU,GAAG;IACX,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6CAA6C;AAC7C,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAchD;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAejD;AAED,wBAAwB;AACxB,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAgCjD;AAED,iCAAiC;AACjC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAMpD;AAMD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAMlD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAMpD;AAwDD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAY3E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,SAAI,GAAG,MAAM,CAsBhG;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE,CAqD/D;AAED,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAmDhE"}

package/dist/p0-primitives/tokens/contrast-audit.js

@@ -0,0 +1,331 @@
+// @ts-nocheck — Node-only script (runs via tsx); uses fs/path/url/process
+// Contrast Audit — WCAG color contrast validation for design system tokens
+// Runs in Node via tsx; can also be used as a vitest test module
+//
+// Checks all foreground/background token pairs against WCAG 2.2 AA:
+//   - Normal text: contrast ratio >= 4.5:1
+//   - Large text (>=18px or >=14px bold): contrast ratio >= 3:1
+//   - UI components & borders: contrast ratio >= 3:1
+//
+// Related: LEAP-PRINCIPIA-v4 S-03 (semantic conservation),
+//          leap-frontend-hardening-2026-05-12.md item E
+import { readFileSync, existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+/** Parse hex color (#rgb, #rrggbb) to RGB */
+export function parseHex(hex) {
+    hex = hex.trim().replace(/^#/, '');
+    if (hex.length === 3) {
+        hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+    }
+    if (hex.length !== 6)
+        return null;
+    const n = parseInt(hex, 16);
+    if (isNaN(n))
+        return null;
+    return {
+        r: (n >> 16) & 0xff,
+        g: (n >> 8) & 0xff,
+        b: n & 0xff,
+        alpha: 1,
+    };
+}
+/** Parse rgb(r,g,b) or rgba(r,g,b,a) to RGB */
+export function parseRgb(func) {
+    const match = func.match(/^rgba?\(\s*(\d+(?:\.\d+)?%?)\s*,\s*(\d+(?:\.\d+)?%?)\s*,\s*(\d+(?:\.\d+)?%?)(?:\s*,\s*([0-9.]+))?\s*\)$/i);
+    if (!match)
+        return null;
+    const toByte = (v) => {
+        const num = parseFloat(v);
+        return v.endsWith('%') ? Math.round((num / 100) * 255) : Math.min(255, Math.max(0, Math.round(num)));
+    };
+    return {
+        r: toByte(match[1]),
+        g: toByte(match[2]),
+        b: toByte(match[3]),
+        alpha: match[4] !== undefined ? parseFloat(match[4]) : 1,
+    };
+}
+/** Parse HSLA colors */
+export function parseHsl(func) {
+    const match = func.match(/^hsla?\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?%?)\s*,\s*(\d+(?:\.\d+)?%?)(?:\s*,\s*([0-9.]+))?\s*\)$/i);
+    if (!match)
+        return null;
+    const h = parseFloat(match[1]) / 360;
+    const s = parseFloat(match[2]) / (match[2].endsWith('%') ? 100 : 1);
+    const l = parseFloat(match[3]) / (match[3].endsWith('%') ? 100 : 1);
+    const hue2rgb = (p, q, t) => {
+        if (t < 0)
+            t += 1;
+        if (t > 1)
+            t -= 1;
+        if (t < 1 / 6)
+            return p + (q - p) * 6 * t;
+        if (t < 1 / 2)
+            return q;
+        if (t < 2 / 3)
+            return p + (q - p) * (2 / 3 - t) * 6;
+        return p;
+    };
+    let r, g, b;
+    if (s === 0) {
+        r = g = b = l;
+    }
+    else {
+        const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+        const p = 2 * l - q;
+        r = hue2rgb(p, q, h + 1 / 3);
+        g = hue2rgb(p, q, h);
+        b = hue2rgb(p, q, h - 1 / 3);
+    }
+    return {
+        r: Math.round(r * 255),
+        g: Math.round(g * 255),
+        b: Math.round(b * 255),
+        alpha: match[4] !== undefined ? parseFloat(match[4]) : 1,
+    };
+}
+/** Parse any CSS color to RGB */
+export function parseColor(value) {
+    value = value.trim();
+    if (value.startsWith('#'))
+        return parseHex(value);
+    if (value.startsWith('rgb'))
+        return parseRgb(value);
+    if (value.startsWith('hsl'))
+        return parseHsl(value);
+    return null;
+}
+// ---------------------------------------------------------------------------
+// 2. Relative luminance and contrast ratio (WCAG 2.2)
+// ---------------------------------------------------------------------------
+export function sRGBtoLinear(c) {
+    c = c / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+export function relativeLuminance(rgb) {
+    const adjustAlpha = (c) => c * rgb.alpha + 0 * (1 - rgb.alpha);
+    const r = sRGBtoLinear(adjustAlpha(rgb.r));
+    const g = sRGBtoLinear(adjustAlpha(rgb.g));
+    const b = sRGBtoLinear(adjustAlpha(rgb.b));
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export function contrastRatio(a, b) {
+    const lumA = relativeLuminance(a);
+    const lumB = relativeLuminance(b);
+    const lighter = Math.max(lumA, lumB);
+    const darker = Math.min(lumA, lumB);
+    return lighter === darker ? 1 : (lighter + 0.05) / (darker + 0.05);
+}
+const TOKEN_PAIRS = [
+    // Normal text — 4.5:1 required
+    { name: 'text-primary on bg-primary', fg: '--color-text-primary', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'text-secondary on bg-primary', fg: '--color-text-secondary', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'text-primary on bg-secondary', fg: '--color-text-primary', bg: '--color-bg-secondary', minRatio: 4.5, type: 'normal' },
+    { name: 'text-secondary on bg-secondary', fg: '--color-text-secondary', bg: '--color-bg-secondary', minRatio: 4.5, type: 'normal' },
+    { name: 'text-primary on bg-panel', fg: '--color-text-primary', bg: '--color-bg-panel', minRatio: 4.5, type: 'normal' },
+    { name: 'text-secondary on bg-panel', fg: '--color-text-secondary', bg: '--color-bg-panel', minRatio: 4.5, type: 'normal' },
+    { name: 'accent on bg-primary', fg: '--color-accent', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'success on bg-primary', fg: '--color-success', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'warning on bg-primary', fg: '--color-warning', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'error on bg-primary', fg: '--color-error', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'info on bg-primary', fg: '--color-info', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'text-primary on bg-canvas', fg: '--color-text-primary', bg: '--color-bg-canvas', minRatio: 4.5, type: 'normal' },
+    { name: 'text-primary on card-bg', fg: '--color-text-primary', bg: '--color-card-bg', minRatio: 4.5, type: 'normal' },
+    { name: 'text-primary on bg-elevated', fg: '--color-text-primary', bg: '--color-bg-elevated', minRatio: 4.5, type: 'normal' },
+    { name: 'text-primary on bg-app', fg: '--color-text-primary', bg: '--color-bg-app', minRatio: 4.5, type: 'normal' },
+    { name: 'validity-high on bg-primary', fg: '--validity-high', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'validity-critical on bg-primary', fg: '--validity-critical', bg: '--color-bg-primary', minRatio: 4.5, type: 'normal' },
+    { name: 'text-inverse on accent', fg: '--color-text-inverse', bg: '--color-accent', minRatio: 4.5, type: 'normal' },
+    // Large text / secondary — 3:1 required
+    { name: 'text-muted on bg-primary', fg: '--color-text-muted', bg: '--color-bg-primary', minRatio: 3, type: 'large' },
+    { name: 'text-muted on bg-secondary', fg: '--color-text-muted', bg: '--color-bg-secondary', minRatio: 3, type: 'large' },
+    { name: 'text-muted on bg-panel', fg: '--color-text-muted', bg: '--color-bg-panel', minRatio: 3, type: 'large' },
+    { name: 'text-muted on bg-canvas', fg: '--color-text-muted', bg: '--color-bg-canvas', minRatio: 3, type: 'large' },
+    { name: 'text-primary on card-bg', fg: '--color-text-primary', bg: '--color-card-bg', minRatio: 4.5, type: 'large' },
+    { name: 'text-secondary on card-bg', fg: '--color-text-secondary', bg: '--color-card-bg', minRatio: 4.5, type: 'large' },
+    // UI components — 3:1 required
+    { name: 'border-focus on bg-primary', fg: '--border-focus', bg: '--color-bg-primary', minRatio: 3, type: 'ui' },
+    { name: 'border-default on bg-primary', fg: '--border-default', bg: '--color-bg-primary', minRatio: 3, type: 'ui' },
+    { name: 'text-inverse on accent-bg', fg: '--color-text-inverse', bg: '--color-accent-active', minRatio: 3, type: 'ui' },
+    { name: 'text-muted on bg-elevated', fg: '--color-text-muted', bg: '--color-bg-panel-elevated', minRatio: 3, type: 'ui' },
+    // Decorative/ambient — 1.5:1 (informational only, not accessibility-critical)
+    { name: 'border-subtle on bg-primary', fg: '--border-subtle', bg: '--color-bg-primary', minRatio: 1.5, type: 'ui', decorative: true },
+    { name: 'accent-subtle on bg-primary', fg: '--color-accent-subtle', bg: '--color-bg-primary', minRatio: 1.5, type: 'ui', decorative: true },
+];
+export function extractCSSVariables(cssContent) {
+    // Strip CSS comments before parsing
+    const clean = cssContent.replace(/\/\*[\s\S]*?\*\//g, '');
+    const vars = new Map();
+    const regex = /--([a-zA-Z0-9-]+)\s*:\s*([^;]+?)(?=\s*(?:;|$))/g;
+    let match;
+    while ((match = regex.exec(clean)) !== null) {
+        const name = '--' + match[1];
+        const value = match[2].trim();
+        vars.set(name, value);
+    }
+    return vars;
+}
+/**
+ * Resolve CSS variable references with full chain traversal.
+ * Handles nested var(--a, var(--b, default)) patterns.
+ */
+export function resolveVarValue(value, variables, depth = 0) {
+    if (depth > 20)
+        return value;
+    return value.replace(/var\(([^)]+)\)/g, (_, inner) => {
+        const parts = inner.split(',').map((p) => p.trim());
+        const varName = parts[0].trim();
+        const fallback = parts.length > 1 ? parts.slice(1).join(',') : undefined;
+        // Normalize: some vars in tokens.css lack the -- prefix in var() references
+        const lookupName = varName.startsWith('--') ? varName : '--' + varName;
+        const resolved = variables.get(lookupName);
+        if (resolved !== undefined) {
+            return resolveVarValue(resolved, variables, depth + 1);
+        }
+        if (fallback !== undefined) {
+            return resolveVarValue(fallback, variables, depth + 1);
+        }
+        // If we can't resolve at all, try without -- prefix
+        if (lookupName !== varName) {
+            const alt = variables.get(varName);
+            if (alt !== undefined)
+                return resolveVarValue(alt, variables, depth + 1);
+        }
+        return value;
+    });
+}
+/** Run contrast checks on all defined token pairs */
+export function auditContrast(cssContent) {
+    const variables = extractCSSVariables(cssContent);
+    // Also extract from control-room theme if present
+    // (both themes share the same variable names in their respective :root scopes)
+    return TOKEN_PAIRS.map((pair) => {
+        const rawFg = variables.get(pair.fg) ?? '';
+        const rawBg = variables.get(pair.bg) ?? '';
+        const resolvedFg = resolveVarValue(rawFg, variables);
+        const resolvedBg = resolveVarValue(rawBg, variables);
+        const fgColor = parseColor(resolvedFg);
+        const bgColor = parseColor(resolvedBg);
+        let ratio = 0;
+        let pass = false;
+        let status = 'pass';
+        if (fgColor && bgColor) {
+            ratio = contrastRatio(fgColor, bgColor);
+            pass = ratio >= pair.minRatio;
+            if (pass && pair.type === 'normal' && ratio < pair.minRatio * 1.15) {
+                status = 'warn';
+            }
+            else if (pass) {
+                status = 'pass';
+            }
+            else if (pair.decorative) {
+                status = 'warn';
+            }
+            else {
+                status = 'fail';
+            }
+        }
+        else {
+            // Can't resolve colors — mark as fail with 0 ratio
+            ratio = 0;
+            pass = false;
+            status = 'fail';
+        }
+        return {
+            name: pair.name,
+            fg: pair.fg,
+            bg: pair.bg,
+            fgResolved: resolvedFg,
+            bgResolved: resolvedBg,
+            ratio: Math.round(ratio * 100) / 100,
+            required: pair.minRatio,
+            pass,
+            type: pair.type,
+            decorative: !!pair.decorative,
+            status,
+        };
+    });
+}
+/** Format audit results for terminal output */
+export function formatAuditReport(results) {
+    const failures = results.filter((r) => r.status === 'fail');
+    const warnings = results.filter((r) => r.status === 'warn');
+    const passes = results.filter((r) => r.status === 'pass');
+    let output = '\n';
+    output += '═══════════════════════════════════════════════════════════════════\n';
+    output += '  COLOR CONTRAST AUDIT — Design System Token Palette\n';
+    output += '  WCAG 2.2 AA Compliance Check\n';
+    output += '═══════════════════════════════════════════════════════════════════\n\n';
+    if (failures.length === 0) {
+        output += '  ✅ ALL CONTRAST CHECKS PASSED\n\n';
+    }
+    else {
+        output += `  ❌ ${failures.length} FAILURES FOUND\n\n`;
+    }
+    // Summary table
+    output += '  Token Pair                               │ Ratio │ Req  │ Status\n';
+    output += '  ─────────────────────────────────────────│──────│──────│──────\n';
+    for (const r of results) {
+        let status;
+        if (r.status === 'pass')
+            status = '✅ PASS';
+        else if (r.status === 'fail')
+            status = '❌ FAIL';
+        else
+            status = '⚠️  WARN';
+        output += `  ${r.name.padEnd(39)}│ ${r.ratio.toFixed(2).padStart(6)} │ ${r.required.toFixed(1).padStart(5)} │ ${status}\n`;
+    }
+    if (failures.length > 0) {
+        output += `\n  ❌ FAILURES:\n`;
+        for (const f of failures) {
+            output += `     - ${f.name}: ${f.ratio.toFixed(2)}:1 (need ${f.required}:1)\n`;
+            output += `       Fg: ${f.fgResolved} | Bg: ${f.bgResolved}\n`;
+        }
+    }
+    if (warnings.length > 0) {
+        output += `\n  ⚠️  WARNINGS (${warnings.length} marginal or decorative):\n`;
+        for (const w of warnings) {
+            output += `     - ${w.name} (${w.ratio.toFixed(2)}:1 vs ${w.required}:1 required)`;
+            if (w.decorative)
+                output += ' [decorative]';
+            output += '\n';
+        }
+    }
+    output += '\n  ───────────────────────────────────────────────────────────────\n';
+    output += `  Total: ${results.length} | Passed: ${passes.length} | Warned: ${warnings.length} | Failed: ${failures.length}\n`;
+    output += '═══════════════════════════════════════════════════════════════════\n';
+    return output;
+}
+// ---------------------------------------------------------------------------
+// 5. CLI entry point
+// ---------------------------------------------------------------------------
+async function main() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const cssFiles = [
+        path.resolve(__dirname, './tokens.css'),
+        path.resolve(__dirname, './validity-tokens.css'),
+    ];
+    let combinedCss = '';
+    for (const cssPath of cssFiles) {
+        if (!existsSync(cssPath)) {
+            console.error(`Token file not found: ${cssPath}`);
+            return 1;
+        }
+        combinedCss += readFileSync(cssPath, 'utf-8') + '\n';
+    }
+    const results = auditContrast(combinedCss);
+    console.log(formatAuditReport(results));
+    const failures = results.filter((r) => r.status === 'fail');
+    if (failures.length > 0) {
+        return 1;
+    }
+    return 0;
+}
+if (process.argv[1] && process.argv[1].includes('contrast-audit')) {
+    main().then((code) => process.exit(code)).catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/p0-primitives/tokens/contrast-audit.test.js

@@ -0,0 +1,84 @@
+// Tests for the WCAG color contrast audit
+import { describe, it, expect } from 'vitest';
+import { parseHex, parseRgb, parseHsl, parseColor, sRGBtoLinear, relativeLuminance, contrastRatio, auditContrast, formatAuditReport, extractCSSVariables, resolveVarValue, } from './index';
+describe('Color parsing', () => {
+    it('parses hex colors', () => {
+        expect(parseHex('#0b0d0f')).toEqual({ r: 11, g: 13, b: 15, alpha: 1 });
+        expect(parseHex('#fff')).toEqual({ r: 255, g: 255, b: 255, alpha: 1 });
+        expect(parseHex('invalid')).toBeNull();
+    });
+    it('parses rgb() colors', () => {
+        expect(parseRgb('rgb(255, 255, 255)')).toEqual({ r: 255, g: 255, b: 255, alpha: 1 });
+        expect(parseRgb('rgba(88, 166, 255, 0.12)')).toEqual({ r: 88, g: 166, b: 255, alpha: 0.12 });
+    });
+    it('parses hsl() colors', () => {
+        const result = parseHsl('hsl(210, 50%, 50%)');
+        expect(result).not.toBeNull();
+        expect(result.r).toBeCloseTo(64, 0);
+        expect(result.g).toBeCloseTo(127, 0);
+        expect(result.b).toBeCloseTo(191, 0);
+    });
+    it('returns null for unparseable colors', () => {
+        expect(parseColor('not-a-color')).toBeNull();
+        expect(parseColor('')).toBeNull();
+    });
+});
+describe('Relative luminance', () => {
+    it('computes sRGB linearization correctly', () => {
+        expect(sRGBtoLinear(0)).toBe(0);
+        expect(sRGBtoLinear(255)).toBeCloseTo(1.0, 4);
+    });
+    it('computes relative luminance for white', () => {
+        expect(relativeLuminance({ r: 255, g: 255, b: 255, alpha: 1 })).toBeCloseTo(1.0, 4);
+    });
+    it('computes relative luminance for black', () => {
+        expect(relativeLuminance({ r: 0, g: 0, b: 0, alpha: 1 })).toBe(0);
+    });
+});
+describe('Contrast ratio', () => {
+    it('computes ratio for white on black', () => {
+        const white = { r: 255, g: 255, b: 255, alpha: 1 };
+        const black = { r: 0, g: 0, b: 0, alpha: 1 };
+        expect(contrastRatio(white, black)).toBeCloseTo(21, 0);
+    });
+    it('same color has ratio of 1', () => {
+        const c = { r: 128, g: 128, b: 128, alpha: 1 };
+        expect(contrastRatio(c, c)).toBe(1);
+    });
+});
+describe('Audit integration', () => {
+    const testCss = `
+:root {
+  --color-bg-primary: #0b0d0f;
+  --color-text-primary: #e8e0d0;
+  --color-text-secondary: #a8a08c;
+  --color-accent: #b87333;
+  --color-success: #4fa8a2;
+  --color-bg-panel: #181c20;
+}
+`;
+    it('extracts CSS variables from a stylesheet string', () => {
+        const vars = extractCSSVariables(testCss);
+        expect(vars.get('--color-bg-primary')).toBe('#0b0d0f');
+        expect(vars.get('--color-text-primary')).toBe('#e8e0d0');
+    });
+    it('resolves var() references', () => {
+        const vars = new Map([['--color-accent', '#b87333']]);
+        expect(resolveVarValue('var(--color-accent)', vars)).toBe('#b87333');
+        expect(resolveVarValue('var(--missing, #fff)', vars)).toBe('#fff');
+    });
+    it('audits token pairs and returns results', () => {
+        const results = auditContrast(testCss);
+        expect(results.length).toBeGreaterThan(0);
+        const bodyText = results.find((r) => r.name.includes('text-primary on bg-primary'));
+        expect(bodyText).toBeDefined();
+        expect(bodyText.pass).toBe(true);
+        expect(bodyText.ratio).toBeGreaterThanOrEqual(4.5);
+    });
+    it('formats a readable report', () => {
+        const results = auditContrast(testCss);
+        const report = formatAuditReport(results);
+        expect(report).toContain('COLOR CONTRAST AUDIT');
+        expect(report).toContain('PASS');
+    });
+});