@principal-ade/industry-theme 0.1.20 → 0.1.22

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>
+  );
+};

package/src/README.md

@@ -98,9 +98,8 @@ const borderRadius = getRadius(theme, 1); // theme.radii[1]
 
 The theme system supports automatic light/dark mode switching:
 
-- Automatically detects system preference on first load
-- Saves user preference to localStorage
-- Provides `toggleColorMode()` function
+- Mode is held in React state for the lifetime of the provider (not persisted)
+- Seed the initial mode via the `initialMode` prop
 - Dark mode colors are defined in `theme.colors.modes.dark`
 
 ## Migration from old theme

package/src/ThemeProvider.tsx

@@ -1,4 +1,4 @@
-import React, { createContext, useContext, ReactNode, useState, useEffect } from 'react';
+import React, { createContext, useContext, ReactNode, useState } from 'react';
 
 import { getMode } from './themeHelpers';
 
@@ -76,25 +76,6 @@ export const ThemeProvider: React.FC<ThemeProviderProps> = ({
     };
   }, [customTheme, mode]);
 
-  // Load saved mode from localStorage on mount
-  useEffect(() => {
-    if (!initialMode) {
-      const savedMode = localStorage.getItem('principlemd-theme-mode');
-      if (savedMode) {
-        setMode(savedMode);
-      }
-    }
-  }, [initialMode]);
-
-  // Save mode to localStorage when it changes
-  useEffect(() => {
-    if (mode) {
-      localStorage.setItem('principlemd-theme-mode', mode);
-    } else {
-      localStorage.removeItem('principlemd-theme-mode');
-    }
-  }, [mode]);
-
   const value: ThemeContextValue = {
     theme: activeTheme,
     mode,

package/src/contrast.ts

@@ -0,0 +1,172 @@
+/**
+ * WCAG 2.x contrast evaluation for themes.
+ *
+ * Implements the relative-luminance / contrast-ratio formulas from
+ * https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio and provides a
+ * declarative audit of the meaningful foreground/background pairings in a
+ * {@link Theme}. This is the deterministic, exhaustive counterpart to the
+ * axe-core checks surfaced by `@storybook/addon-a11y`: axe only inspects text
+ * that is actually rendered, whereas this audits every declared color role.
+ */
+
+import { Theme } from './index';
+
+/** WCAG 2.x contrast thresholds. */
+export const WCAG_THRESHOLDS = {
+  /** Normal-size text (< 18pt, or < 14pt bold). */
+  text: { AA: 4.5, AAA: 7 },
+  /** Large text (>= 18pt, or >= 14pt bold). */
+  large: { AA: 3, AAA: 4.5 },
+  /** Non-text UI components & graphical objects (borders, icons, focus rings). */
+  ui: { AA: 3, AAA: 3 },
+} as const;
+
+export type ContrastUse = keyof typeof WCAG_THRESHOLDS;
+export type ContrastLevel = 'AAA' | 'AA' | 'fail';
+
+/** Parse a CSS color string into an [r, g, b] triple in the 0–255 range. */
+export function parseColor(input: string): [number, number, number] | null {
+  if (!input) return null;
+  const color = input.trim().toLowerCase();
+
+  // #rgb / #rgba / #rrggbb / #rrggbbaa
+  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;
+  }
+
+  // rgb(...) / rgba(...)
+  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;
+}
+
+/** Relative luminance per WCAG, from an [r, g, b] triple (0–255). */
+export function relativeLuminance([r, g, b]: [number, number, number]): number {
+  const toLinear = (c: number) => {
+    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);
+}
+
+/**
+ * WCAG contrast ratio between two colors (1–21). Returns `null` if either
+ * color cannot be parsed.
+ */
+export function contrastRatio(fg: string, bg: string): number | null {
+  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);
+}
+
+/** Classify a ratio against the thresholds for a given use. */
+export function gradeContrast(ratio: number, use: ContrastUse): ContrastLevel {
+  const t = WCAG_THRESHOLDS[use];
+  if (ratio >= t.AAA) return 'AAA';
+  if (ratio >= t.AA) return 'AA';
+  return 'fail';
+}
+
+type ColorKey = keyof Theme['colors'];
+
+/** A foreground/background pairing to audit. */
+export interface ContrastPair {
+  label: string;
+  fg: ColorKey;
+  bg: ColorKey;
+  use: ContrastUse;
+}
+
+/**
+ * The meaningful color pairings every theme should satisfy. Text-on-surface
+ * pairs require AA 4.5:1; borders/graphical roles require AA 3:1.
+ */
+export const CONTRAST_PAIRS: ContrastPair[] = [
+  // Body & secondary text on the main surfaces
+  { 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' },
+
+  // Text drawn on top of brand colors (e.g. button labels)
+  { 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' },
+
+  // Brand color used as text/links/headings on the main background
+  { label: 'primary on background', fg: 'primary', bg: 'background', use: 'large' },
+
+  // Non-text UI: status colors and borders must clear 3:1
+  { 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' },
+];
+
+export interface ContrastResult {
+  pair: ContrastPair;
+  fgColor: string;
+  bgColor: string;
+  ratio: number | null;
+  /** Threshold required for AA at this pair's use. */
+  required: number;
+  level: ContrastLevel;
+}
+
+export interface ThemeContrastReport {
+  results: ContrastResult[];
+  /** Pairs that fail AA. */
+  failures: ContrastResult[];
+  /** True when every parseable pair clears AA. */
+  passesAA: boolean;
+}
+
+/** Run the full contrast audit for a single theme. */
+export function evaluateThemeContrast(theme: Theme): ThemeContrastReport {
+  const results: ContrastResult[] = CONTRAST_PAIRS.map((pair) => {
+    const fgColor = (theme.colors[pair.fg] as string) ?? '';
+    const bgColor = (theme.colors[pair.bg] as string) ?? '';
+    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 };
+}

package/src/index.ts

@@ -234,4 +234,26 @@ export { overrideColors, makeTheme, addMode, getMode } from './themeHelpers';
 export { ThemeShowcase } from './ThemeShowcase';
 export type { ThemeShowcaseProps } from './ThemeShowcase';
 
+// Export contrast evaluation utilities
+export {
+  WCAG_THRESHOLDS,
+  CONTRAST_PAIRS,
+  parseColor,
+  relativeLuminance,
+  contrastRatio,
+  gradeContrast,
+  evaluateThemeContrast,
+} from './contrast';
+export type {
+  ContrastUse,
+  ContrastLevel,
+  ContrastPair,
+  ContrastResult,
+  ThemeContrastReport,
+} from './contrast';
+
+// Export ContrastReport component
+export { ContrastReport } from './ContrastReport';
+export type { ContrastReportProps } from './ContrastReport';
+
 export default theme;

package/src/themes.ts

@@ -1348,7 +1348,7 @@ export const slateNeonTheme: Theme = {
     // Base colors - Slate greys with tangerine primary
     text: '#d0d6e0', // Near-white grey for most text
     background: '#1a1c1e', // Very dark charcoal
-    primary: '#ff6b35', // Bright tangerine
+    primary: '#F36F41', // Bright tangerine
     secondary: '#ff8257', // Lighter tangerine for hover
     accent: '#00ff00', // Neon green accent
     highlight: '#2a1f18', // Tangerine-tinted highlight
@@ -1373,10 +1373,10 @@ export const slateNeonTheme: Theme = {
 
     // Search highlight colors
     highlightBg: '#2a1f18', // Tangerine highlight
-    highlightBorder: '#ff6b35', // Tangerine border
+    highlightBorder: '#F36F41', // Tangerine border
 
     // Text on primary background
-    textOnPrimary: '#ffffff', // White text on tangerine primary
+    textOnPrimary: '#1a1c1e', // Dark text on tangerine primary (AA contrast)
     // Text on secondary background
     textOnSecondary: '#ffffff', // White text on lighter tangerine secondary
     // Text on accent background
@@ -1651,7 +1651,7 @@ export const iceTangerineDarkTheme: Theme = {
   colors: {
     // Base colors
     text: '#d0e5ea', // Light ice blue for primary text
-    background: '#0d274d', // Deep navy/midnight blue
+    background: '#0a1829', // Deep midnight navy (promoted from backgroundDark)
     primary: '#ff6b35', // Bright tangerine - primary action color
     secondary: '#ff8257', // Lighter tangerine for hover
     accent: '#0893d2', // Bright teal accent
@@ -1665,34 +1665,34 @@ export const iceTangerineDarkTheme: Theme = {
     info: '#0893d2', // Bright teal (matches accent)
 
     // Additional semantic colors
-    border: '#1e3a5f', // Navy border
+    border: '#5a82aa', // Navy border (brightened for 3:1 WCAG contrast)
     backgroundSecondary: '#0f2e58', // Slightly lighter navy for cards/sections
     backgroundTertiary: '#123461', // Even lighter navy
     backgroundLight: '#0b1f3f', // Darker navy
-    backgroundDark: '#0a1829', // Extra dark navy
+    backgroundDark: '#040b15', // Deepest navy backdrop
     backgroundHover: '#2a1f18', // Dark tangerine tint hover
     primaryBlade: '#0e2b53', // Primary blade/panel color
     surface: '#0f2e58', // Navy surface
     textSecondary: '#9fc4d4', // Muted ice blue for secondary text
     textTertiary: '#7ba8bc', // Darker ice blue
-    textMuted: '#5a8a9e', // Even darker ice blue
+    textMuted: '#73a0b3', // Even darker ice blue (lightened for 4.5:1 WCAG contrast)
 
     // Search highlight colors
     highlightBg: '#2a1f18', // Dark tangerine highlight
     highlightBorder: '#ff6b35', // Tangerine border
 
     // Text on primary background
-    textOnPrimary: '#ffffff', // White text on tangerine primary
+    textOnPrimary: '#0d274d', // Deep navy text on tangerine primary (4.5:1+ WCAG)
     // Text on secondary background
-    textOnSecondary: '#ffffff', // White text on lighter tangerine
+    textOnSecondary: '#0d274d', // Deep navy text on lighter tangerine (4.5:1+ WCAG)
     // Text on accent background
-    textOnAccent: '#ffffff', // White text on teal accent
+    textOnAccent: '#0a1829', // Dark navy text on teal accent (4.5:1+ WCAG)
   },
 
   // Component variants
   buttons: {
     primary: {
-      color: '#ffffff', // White text on tangerine
+      color: '#0d274d', // Deep navy text on tangerine (4.5:1+ WCAG)
       bg: 'primary',
       borderWidth: 0,
       '&:hover': {