@principal-ade/industry-theme 0.1.21 → 0.1.22

package/dist/esm/index.js

@@ -1872,7 +1872,7 @@ var iceTangerineDarkTheme = {
   zIndices: [0, 1, 10, 20, 30, 40, 50],
   colors: {
     text: "#d0e5ea",
-    background: "#0d274d",
+    background: "#0a1829",
     primary: "#ff6b35",
     secondary: "#ff8257",
     accent: "#0893d2",
@@ -1882,26 +1882,26 @@ var iceTangerineDarkTheme = {
     warning: "#f59e0b",
     error: "#ef4444",
     info: "#0893d2",
-    border: "#1e3a5f",
+    border: "#5a82aa",
     backgroundSecondary: "#0f2e58",
     backgroundTertiary: "#123461",
     backgroundLight: "#0b1f3f",
-    backgroundDark: "#0a1829",
+    backgroundDark: "#040b15",
     backgroundHover: "#2a1f18",
     primaryBlade: "#0e2b53",
     surface: "#0f2e58",
     textSecondary: "#9fc4d4",
     textTertiary: "#7ba8bc",
-    textMuted: "#5a8a9e",
+    textMuted: "#73a0b3",
     highlightBg: "#2a1f18",
     highlightBorder: "#ff6b35",
-    textOnPrimary: "#ffffff",
-    textOnSecondary: "#ffffff",
-    textOnAccent: "#ffffff"
+    textOnPrimary: "#0d274d",
+    textOnSecondary: "#0d274d",
+    textOnAccent: "#0a1829"
   },
   buttons: {
     primary: {
-      color: "#ffffff",
+      color: "#0d274d",
       bg: "primary",
       borderWidth: 0,
       "&:hover": {
@@ -2805,6 +2805,272 @@ var ThemeShowcase = ({
     }
   }, modeName)))));
 };
+// src/contrast.ts
+var WCAG_THRESHOLDS = {
+  text: { AA: 4.5, AAA: 7 },
+  large: { AA: 3, AAA: 4.5 },
+  ui: { AA: 3, AAA: 3 }
+};
+function parseColor(input) {
+  if (!input)
+    return null;
+  const color = input.trim().toLowerCase();
+  if (color.startsWith("#")) {
+    let hex = color.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      hex = hex.split("").map((c) => c + c).join("");
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      const r = parseInt(hex.slice(0, 2), 16);
+      const g = parseInt(hex.slice(2, 4), 16);
+      const b = parseInt(hex.slice(4, 6), 16);
+      if ([r, g, b].some((n) => Number.isNaN(n)))
+        return null;
+      return [r, g, b];
+    }
+    return null;
+  }
+  const rgbMatch = color.match(/^rgba?\(([^)]+)\)$/);
+  if (rgbMatch) {
+    const parts = rgbMatch[1].split(/[,/\s]+/).filter(Boolean).slice(0, 3);
+    if (parts.length < 3)
+      return null;
+    const channels = parts.map((p) => p.endsWith("%") ? Math.round(parseFloat(p) / 100 * 255) : parseFloat(p));
+    if (channels.some((n) => Number.isNaN(n)))
+      return null;
+    return [channels[0], channels[1], channels[2]];
+  }
+  return null;
+}
+function relativeLuminance([r, g, b]) {
+  const toLinear = (c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+function contrastRatio(fg, bg) {
+  const a = parseColor(fg);
+  const b = parseColor(bg);
+  if (!a || !b)
+    return null;
+  const l1 = relativeLuminance(a);
+  const l2 = relativeLuminance(b);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function gradeContrast(ratio, use) {
+  const t = WCAG_THRESHOLDS[use];
+  if (ratio >= t.AAA)
+    return "AAA";
+  if (ratio >= t.AA)
+    return "AA";
+  return "fail";
+}
+var CONTRAST_PAIRS = [
+  { label: "text on background", fg: "text", bg: "background", use: "text" },
+  { label: "text on surface", fg: "text", bg: "surface", use: "text" },
+  { label: "text on backgroundSecondary", fg: "text", bg: "backgroundSecondary", use: "text" },
+  { label: "textSecondary on background", fg: "textSecondary", bg: "background", use: "text" },
+  { label: "textTertiary on background", fg: "textTertiary", bg: "background", use: "text" },
+  { label: "textMuted on background", fg: "textMuted", bg: "background", use: "text" },
+  { label: "textOnPrimary on primary", fg: "textOnPrimary", bg: "primary", use: "text" },
+  { label: "textOnSecondary on secondary", fg: "textOnSecondary", bg: "secondary", use: "text" },
+  { label: "textOnAccent on accent", fg: "textOnAccent", bg: "accent", use: "text" },
+  { label: "primary on background", fg: "primary", bg: "background", use: "large" },
+  { label: "success on background", fg: "success", bg: "background", use: "ui" },
+  { label: "warning on background", fg: "warning", bg: "background", use: "ui" },
+  { label: "error on background", fg: "error", bg: "background", use: "ui" },
+  { label: "info on background", fg: "info", bg: "background", use: "ui" },
+  { label: "border on background", fg: "border", bg: "background", use: "ui" },
+  { label: "border on surface", fg: "border", bg: "surface", use: "ui" }
+];
+function evaluateThemeContrast(theme2) {
+  const results = CONTRAST_PAIRS.map((pair) => {
+    const fgColor = theme2.colors[pair.fg] ?? "";
+    const bgColor = theme2.colors[pair.bg] ?? "";
+    const ratio = contrastRatio(fgColor, bgColor);
+    const required = WCAG_THRESHOLDS[pair.use].AA;
+    const level = ratio === null ? "fail" : gradeContrast(ratio, pair.use);
+    return { pair, fgColor, bgColor, ratio, required, level };
+  });
+  const failures = results.filter((r) => r.level === "fail");
+  return { results, failures, passesAA: failures.length === 0 };
+}
+// src/ContrastReport.tsx
+import React3 from "react";
+var LEVEL_STYLE = {
+  AAA: { bg: "#0f7b3f", fg: "#ffffff", label: "AAA" },
+  AA: { bg: "#1f6feb", fg: "#ffffff", label: "AA" },
+  fail: { bg: "#cf222e", fg: "#ffffff", label: "FAIL" }
+};
+var ui = {
+  fontFamily: "ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+  text: "#1c2128",
+  subtle: "#57606a",
+  border: "#d0d7de",
+  surface: "#ffffff",
+  panel: "#f6f8fa"
+};
+var Badge = ({ level }) => {
+  const s = LEVEL_STYLE[level];
+  return /* @__PURE__ */ React3.createElement("span", {
+    style: {
+      display: "inline-block",
+      minWidth: 44,
+      textAlign: "center",
+      padding: "2px 8px",
+      borderRadius: 999,
+      fontSize: 11,
+      fontWeight: 700,
+      letterSpacing: 0.4,
+      backgroundColor: s.bg,
+      color: s.fg
+    }
+  }, s.label);
+};
+var Swatch = ({ fg, bg }) => /* @__PURE__ */ React3.createElement("span", {
+  title: `${fg} on ${bg}`,
+  style: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    width: 40,
+    height: 24,
+    borderRadius: 4,
+    border: `1px solid ${ui.border}`,
+    backgroundColor: bg,
+    color: fg,
+    fontSize: 13,
+    fontWeight: 700
+  }
+}, "Aa");
+var Row = ({ r }) => {
+  const failed = r.level === "fail";
+  return /* @__PURE__ */ React3.createElement("tr", {
+    style: { backgroundColor: failed ? "#fff5f5" : "transparent" }
+  }, /* @__PURE__ */ React3.createElement("td", {
+    style: cell
+  }, /* @__PURE__ */ React3.createElement(Swatch, {
+    fg: r.fgColor,
+    bg: r.bgColor
+  })), /* @__PURE__ */ React3.createElement("td", {
+    style: { ...cell, fontWeight: 500 }
+  }, r.pair.label, /* @__PURE__ */ React3.createElement("div", {
+    style: { fontSize: 11, color: ui.subtle, fontFamily: "monospace" }
+  }, r.fgColor, " / ", r.bgColor)), /* @__PURE__ */ React3.createElement("td", {
+    style: { ...cell, textAlign: "right", fontVariantNumeric: "tabular-nums" }
+  }, /* @__PURE__ */ React3.createElement("span", {
+    style: { fontWeight: 700, color: failed ? "#cf222e" : ui.text }
+  }, r.ratio === null ? "—" : `${r.ratio.toFixed(2)}:1`)), /* @__PURE__ */ React3.createElement("td", {
+    style: {
+      ...cell,
+      textAlign: "right",
+      color: ui.subtle,
+      fontVariantNumeric: "tabular-nums"
+    }
+  }, r.required, ":1"), /* @__PURE__ */ React3.createElement("td", {
+    style: { ...cell, textAlign: "center", textTransform: "capitalize", color: ui.subtle }
+  }, r.pair.use), /* @__PURE__ */ React3.createElement("td", {
+    style: { ...cell, textAlign: "center" }
+  }, /* @__PURE__ */ React3.createElement(Badge, {
+    level: r.level
+  })));
+};
+var cell = {
+  padding: "8px 12px",
+  borderBottom: `1px solid ${ui.border}`,
+  fontSize: 13,
+  verticalAlign: "middle"
+};
+var headCell = {
+  padding: "8px 12px",
+  textAlign: "left",
+  fontSize: 11,
+  fontWeight: 700,
+  textTransform: "uppercase",
+  letterSpacing: 0.5,
+  color: ui.subtle,
+  borderBottom: `2px solid ${ui.border}`
+};
+var ThemeTable = ({ name, theme: theme2 }) => {
+  const report = evaluateThemeContrast(theme2);
+  const fails = report.failures.length;
+  return /* @__PURE__ */ React3.createElement("section", {
+    style: {
+      marginBottom: 28,
+      border: `1px solid ${ui.border}`,
+      borderRadius: 8,
+      overflow: "hidden",
+      backgroundColor: ui.surface
+    }
+  }, /* @__PURE__ */ React3.createElement("header", {
+    style: {
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "space-between",
+      gap: 12,
+      padding: "12px 16px",
+      backgroundColor: ui.panel,
+      borderBottom: `1px solid ${ui.border}`
+    }
+  }, /* @__PURE__ */ React3.createElement("h3", {
+    style: { margin: 0, fontSize: 16, color: ui.text }
+  }, name), /* @__PURE__ */ React3.createElement("span", {
+    style: {
+      fontSize: 12,
+      fontWeight: 700,
+      padding: "4px 10px",
+      borderRadius: 999,
+      backgroundColor: report.passesAA ? "#dafbe1" : "#ffebe9",
+      color: report.passesAA ? "#0f7b3f" : "#cf222e"
+    }
+  }, report.passesAA ? "✓ Passes AA" : `${fails} AA failure${fails === 1 ? "" : "s"}`)), /* @__PURE__ */ React3.createElement("table", {
+    style: { width: "100%", borderCollapse: "collapse" }
+  }, /* @__PURE__ */ React3.createElement("thead", null, /* @__PURE__ */ React3.createElement("tr", null, /* @__PURE__ */ React3.createElement("th", {
+    style: headCell
+  }, "Sample"), /* @__PURE__ */ React3.createElement("th", {
+    style: headCell
+  }, "Pair"), /* @__PURE__ */ React3.createElement("th", {
+    style: { ...headCell, textAlign: "right" }
+  }, "Ratio"), /* @__PURE__ */ React3.createElement("th", {
+    style: { ...headCell, textAlign: "right" }
+  }, "Req. (AA)"), /* @__PURE__ */ React3.createElement("th", {
+    style: { ...headCell, textAlign: "center" }
+  }, "Use"), /* @__PURE__ */ React3.createElement("th", {
+    style: { ...headCell, textAlign: "center" }
+  }, "Grade"))), /* @__PURE__ */ React3.createElement("tbody", null, report.results.map((r, i) => /* @__PURE__ */ React3.createElement(Row, {
+    key: i,
+    r
+  })))));
+};
+var ContrastReport = ({
+  theme: theme2,
+  themes,
+  title = "WCAG Contrast Report"
+}) => {
+  const list = themes ?? (theme2 ? [{ name: title, theme: theme2 }] : []);
+  return /* @__PURE__ */ React3.createElement("div", {
+    style: {
+      fontFamily: ui.fontFamily,
+      color: ui.text,
+      backgroundColor: ui.panel,
+      padding: 24,
+      minHeight: "100vh"
+    }
+  }, /* @__PURE__ */ React3.createElement("header", {
+    style: { marginBottom: 20 }
+  }, /* @__PURE__ */ React3.createElement("h1", {
+    style: { margin: "0 0 6px", fontSize: 22 }
+  }, title), /* @__PURE__ */ React3.createElement("p", {
+    style: { margin: 0, fontSize: 13, color: ui.subtle, maxWidth: 720 }
+  }, "WCAG 2.x contrast ratios for each theme's declared color roles. Text pairs require AA", " ", WCAG_THRESHOLDS.text.AA, ":1 (AAA ", WCAG_THRESHOLDS.text.AAA, ":1); large text requires", " ", WCAG_THRESHOLDS.large.AA, ":1; borders and other non-text UI require", " ", WCAG_THRESHOLDS.ui.AA, ":1.")), list.map((t) => /* @__PURE__ */ React3.createElement(ThemeTable, {
+    key: t.name,
+    name: t.name,
+    theme: t.theme
+  })));
+};
 
 // src/index.ts
 var theme = terminalTheme;
@@ -2843,7 +3109,9 @@ export {
   scaleThemeFonts,
   responsive,
   resetFontScale,
+  relativeLuminance,
   regalTheme,
+  parseColor,
   overrideColors,
   neuralPulseTheme,
   mergeThemes,
@@ -2856,6 +3124,7 @@ export {
   iceTangerineTheme,
   iceTangerineDarkTheme,
   humanCentricTheme,
+  gradeContrast,
   getZIndex,
   getSpace,
   getShadow,
@@ -2863,6 +3132,7 @@ export {
   getMode,
   getFontSize,
   getColor,
+  evaluateThemeContrast,
   enterpriseTheme,
   defaultTerminalTheme,
   defaultMarkdownTheme,
@@ -2870,7 +3140,11 @@ export {
   src_default as default,
   decreaseFontScale,
   createStyle,
+  contrastRatio,
   addMode,
+  WCAG_THRESHOLDS,
   ThemeShowcase,
-  ThemeProvider
+  ThemeProvider,
+  ContrastReport,
+  CONTRAST_PAIRS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ade/industry-theme",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "type": "module",
   "description": "Theme components and styles for industry-themed markdown",
   "main": "./dist/cjs/index.js",
@@ -41,10 +41,11 @@
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.3",
     "@eslint/js": "^9.32.0",
-    "@storybook/addon-docs": "^10.1.2",
-    "@storybook/addon-links": "^10.1.2",
-    "@storybook/addon-onboarding": "^10.1.2",
-    "@storybook/react-vite": "^10.1.2",
+    "@storybook/addon-a11y": "^10.4.2",
+    "@storybook/addon-docs": "^10.4.2",
+    "@storybook/addon-links": "^10.4.2",
+    "@storybook/addon-onboarding": "^10.4.2",
+    "@storybook/react-vite": "^10.4.2",
     "@types/bun": "latest",
     "@types/react": "^19.1.12",
     "@types/react-dom": "^19.0.0",
@@ -53,11 +54,11 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-storybook": "^10.1.2",
+    "eslint-plugin-storybook": "^10.4.2",
     "prettier": "^3.6.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "storybook": "^10.1.2",
+    "storybook": "^10.4.2",
     "typescript": "^5.0.4",
     "typescript-eslint": "^8.38.0",
     "vite": "^6.0.7"

package/src/ContrastReport.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ContrastReport } from './ContrastReport';
+import {
+  terminalTheme,
+  regalTheme,
+  matrixTheme,
+  matrixMinimalTheme,
+  slateTheme,
+  slateNeonTheme,
+  slateGoldTheme,
+  iceTangerineTheme,
+  iceTangerineDarkTheme,
+  enterpriseTheme,
+  neuralPulseTheme,
+  humanCentricTheme,
+  landingPageTheme,
+  landingPageLightTheme,
+} from './themes';
+
+const allThemes = [
+  { name: 'Terminal', theme: terminalTheme },
+  { name: 'Regal', theme: regalTheme },
+  { name: 'Matrix', theme: matrixTheme },
+  { name: 'Matrix Minimal', theme: matrixMinimalTheme },
+  { name: 'Slate', theme: slateTheme },
+  { name: 'Slate Neon', theme: slateNeonTheme },
+  { name: 'Slate Gold', theme: slateGoldTheme },
+  { name: 'Ice Tangerine', theme: iceTangerineTheme },
+  { name: 'Ice Tangerine Dark', theme: iceTangerineDarkTheme },
+  { name: 'Enterprise', theme: enterpriseTheme },
+  { name: 'Neural Pulse', theme: neuralPulseTheme },
+  { name: 'Human-Centric', theme: humanCentricTheme },
+  { name: 'Landing Page (Dark)', theme: landingPageTheme },
+  { name: 'Landing Page (Light)', theme: landingPageLightTheme },
+];
+
+const meta: Meta<typeof ContrastReport> = {
+  title: 'Themes/Contrast Report',
+  component: ContrastReport,
+  parameters: {
+    layout: 'fullscreen',
+    // This story renders raw color swatches by design; axe would double-report
+    // the same contrast findings the table already surfaces.
+    a11y: { disable: true },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ContrastReport>;
+
+/** WCAG audit across every theme in the library. */
+export const AllThemes: Story = {
+  args: {
+    title: 'WCAG Contrast Report — All Themes',
+    themes: allThemes,
+  },
+};
+
+/** Tangerine family + Slate Neon side by side. */
+export const TangerineAndSlateNeon: Story = {
+  args: {
+    title: 'Ice Tangerine, Ice Tangerine Dark & Slate Neon',
+    themes: [
+      { name: 'Ice Tangerine', theme: iceTangerineTheme },
+      { name: 'Ice Tangerine Dark', theme: iceTangerineDarkTheme },
+      { name: 'Slate Neon', theme: slateNeonTheme },
+    ],
+  },
+};
+
+export const Terminal: Story = {
+  args: { title: 'Terminal Theme', theme: terminalTheme },
+};
+
+export const LandingPageDark: Story = {
+  args: { title: 'Landing Page (Dark)', theme: landingPageTheme },
+};

package/src/ContrastReport.tsx

@@ -0,0 +1,226 @@
+import React from 'react';
+
+import { ContrastLevel, ContrastResult, evaluateThemeContrast, WCAG_THRESHOLDS } from './contrast';
+
+import { Theme } from './index';
+
+export interface ContrastReportProps {
+  /** A single theme to audit. */
+  theme?: Theme;
+  /** Multiple named themes to audit side by side. */
+  themes?: { name: string; theme: Theme }[];
+  title?: string;
+}
+
+const LEVEL_STYLE: Record<ContrastLevel, { bg: string; fg: string; label: string }> = {
+  AAA: { bg: '#0f7b3f', fg: '#ffffff', label: 'AAA' },
+  AA: { bg: '#1f6feb', fg: '#ffffff', label: 'AA' },
+  fail: { bg: '#cf222e', fg: '#ffffff', label: 'FAIL' },
+};
+
+const ui = {
+  fontFamily: "ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+  text: '#1c2128',
+  subtle: '#57606a',
+  border: '#d0d7de',
+  surface: '#ffffff',
+  panel: '#f6f8fa',
+};
+
+const Badge: React.FC<{ level: ContrastLevel }> = ({ level }) => {
+  const s = LEVEL_STYLE[level];
+  return (
+    <span
+      style={{
+        display: 'inline-block',
+        minWidth: 44,
+        textAlign: 'center',
+        padding: '2px 8px',
+        borderRadius: 999,
+        fontSize: 11,
+        fontWeight: 700,
+        letterSpacing: 0.4,
+        backgroundColor: s.bg,
+        color: s.fg,
+      }}
+    >
+      {s.label}
+    </span>
+  );
+};
+
+const Swatch: React.FC<{ fg: string; bg: string }> = ({ fg, bg }) => (
+  <span
+    title={`${fg} on ${bg}`}
+    style={{
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      width: 40,
+      height: 24,
+      borderRadius: 4,
+      border: `1px solid ${ui.border}`,
+      backgroundColor: bg,
+      color: fg,
+      fontSize: 13,
+      fontWeight: 700,
+    }}
+  >
+    Aa
+  </span>
+);
+
+const Row: React.FC<{ r: ContrastResult }> = ({ r }) => {
+  const failed = r.level === 'fail';
+  return (
+    <tr style={{ backgroundColor: failed ? '#fff5f5' : 'transparent' }}>
+      <td style={cell}>
+        <Swatch fg={r.fgColor} bg={r.bgColor} />
+      </td>
+      <td style={{ ...cell, fontWeight: 500 }}>
+        {r.pair.label}
+        <div style={{ fontSize: 11, color: ui.subtle, fontFamily: 'monospace' }}>
+          {r.fgColor} / {r.bgColor}
+        </div>
+      </td>
+      <td style={{ ...cell, textAlign: 'right', fontVariantNumeric: 'tabular-nums' }}>
+        <span style={{ fontWeight: 700, color: failed ? '#cf222e' : ui.text }}>
+          {r.ratio === null ? '—' : `${r.ratio.toFixed(2)}:1`}
+        </span>
+      </td>
+      <td
+        style={{
+          ...cell,
+          textAlign: 'right',
+          color: ui.subtle,
+          fontVariantNumeric: 'tabular-nums',
+        }}
+      >
+        {r.required}:1
+      </td>
+      <td style={{ ...cell, textAlign: 'center', textTransform: 'capitalize', color: ui.subtle }}>
+        {r.pair.use}
+      </td>
+      <td style={{ ...cell, textAlign: 'center' }}>
+        <Badge level={r.level} />
+      </td>
+    </tr>
+  );
+};
+
+const cell: React.CSSProperties = {
+  padding: '8px 12px',
+  borderBottom: `1px solid ${ui.border}`,
+  fontSize: 13,
+  verticalAlign: 'middle',
+};
+
+const headCell: React.CSSProperties = {
+  padding: '8px 12px',
+  textAlign: 'left',
+  fontSize: 11,
+  fontWeight: 700,
+  textTransform: 'uppercase',
+  letterSpacing: 0.5,
+  color: ui.subtle,
+  borderBottom: `2px solid ${ui.border}`,
+};
+
+const ThemeTable: React.FC<{ name: string; theme: Theme }> = ({ name, theme }) => {
+  const report = evaluateThemeContrast(theme);
+  const fails = report.failures.length;
+
+  return (
+    <section
+      style={{
+        marginBottom: 28,
+        border: `1px solid ${ui.border}`,
+        borderRadius: 8,
+        overflow: 'hidden',
+        backgroundColor: ui.surface,
+      }}
+    >
+      <header
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          gap: 12,
+          padding: '12px 16px',
+          backgroundColor: ui.panel,
+          borderBottom: `1px solid ${ui.border}`,
+        }}
+      >
+        <h3 style={{ margin: 0, fontSize: 16, color: ui.text }}>{name}</h3>
+        <span
+          style={{
+            fontSize: 12,
+            fontWeight: 700,
+            padding: '4px 10px',
+            borderRadius: 999,
+            backgroundColor: report.passesAA ? '#dafbe1' : '#ffebe9',
+            color: report.passesAA ? '#0f7b3f' : '#cf222e',
+          }}
+        >
+          {report.passesAA ? '✓ Passes AA' : `${fails} AA failure${fails === 1 ? '' : 's'}`}
+        </span>
+      </header>
+      <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+        <thead>
+          <tr>
+            <th style={headCell}>Sample</th>
+            <th style={headCell}>Pair</th>
+            <th style={{ ...headCell, textAlign: 'right' }}>Ratio</th>
+            <th style={{ ...headCell, textAlign: 'right' }}>Req. (AA)</th>
+            <th style={{ ...headCell, textAlign: 'center' }}>Use</th>
+            <th style={{ ...headCell, textAlign: 'center' }}>Grade</th>
+          </tr>
+        </thead>
+        <tbody>
+          {report.results.map((r, i) => (
+            <Row key={i} r={r} />
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+};
+
+/**
+ * Renders a WCAG contrast audit for one or more themes — a deterministic,
+ * exhaustive view of every declared foreground/background pairing with its
+ * ratio and AA/AAA grade. Complements `@storybook/addon-a11y`, which only
+ * checks contrast on actually-rendered text.
+ */
+export const ContrastReport: React.FC<ContrastReportProps> = ({
+  theme,
+  themes,
+  title = 'WCAG Contrast Report',
+}) => {
+  const list = themes ?? (theme ? [{ name: title, theme }] : []);
+
+  return (
+    <div
+      style={{
+        fontFamily: ui.fontFamily,
+        color: ui.text,
+        backgroundColor: ui.panel,
+        padding: 24,
+        minHeight: '100vh',
+      }}
+    >
+      <header style={{ marginBottom: 20 }}>
+        <h1 style={{ margin: '0 0 6px', fontSize: 22 }}>{title}</h1>
+        <p style={{ margin: 0, fontSize: 13, color: ui.subtle, maxWidth: 720 }}>
+          WCAG 2.x contrast ratios for each theme&apos;s declared color roles. Text pairs require AA{' '}
+          {WCAG_THRESHOLDS.text.AA}:1 (AAA {WCAG_THRESHOLDS.text.AAA}:1); large text requires{' '}
+          {WCAG_THRESHOLDS.large.AA}:1; borders and other non-text UI require{' '}
+          {WCAG_THRESHOLDS.ui.AA}:1.
+        </p>
+      </header>
+      {list.map((t) => (
+        <ThemeTable key={t.name} name={t.name} theme={t.theme} />
+      ))}
+    </div>
+  );
+};