@runtypelabs/persona 3.21.3 → 3.23.0

package/src/theme-editor/webmcp/coerce.ts

@@ -0,0 +1,286 @@
+/**
+ * Input coercion for the WebMCP theme tools.
+ *
+ * Agent inputs are flexible by design (arcade.dev "parameter coercion"): colors
+ * accept hex with/without `#`, 3-digit hex, rgb(), and common CSS color names;
+ * enums accept friendly synonyms. Each coercer throws an Error whose message
+ * lists the valid options (arcade.dev "error-guided recovery").
+ */
+
+import {
+  normalizeColorValue,
+  isValidHex,
+  parseCssValue,
+  formatCssValue,
+} from '../color-utils';
+import { ROLE_FAMILIES } from '../role-mappings';
+import { STYLE_SECTIONS } from '../sections';
+
+// ─── CSS named colors (common subset) ───────────────────────────
+
+export const CSS_NAMED_COLORS: Record<string, string> = {
+  black: '#000000',
+  white: '#ffffff',
+  red: '#ff0000',
+  green: '#008000',
+  lime: '#00ff00',
+  blue: '#0000ff',
+  yellow: '#ffff00',
+  cyan: '#00ffff',
+  aqua: '#00ffff',
+  magenta: '#ff00ff',
+  fuchsia: '#ff00ff',
+  silver: '#c0c0c0',
+  gray: '#808080',
+  grey: '#808080',
+  maroon: '#800000',
+  olive: '#808000',
+  purple: '#800080',
+  teal: '#008080',
+  navy: '#000080',
+  orange: '#ffa500',
+  pink: '#ffc0cb',
+  hotpink: '#ff69b4',
+  gold: '#ffd700',
+  indigo: '#4b0082',
+  violet: '#ee82ee',
+  brown: '#a52a2a',
+  beige: '#f5f5dc',
+  ivory: '#fffff0',
+  khaki: '#f0e68c',
+  coral: '#ff7f50',
+  salmon: '#fa8072',
+  tomato: '#ff6347',
+  crimson: '#dc143c',
+  turquoise: '#40e0d0',
+  lavender: '#e6e6fa',
+  plum: '#dda0dd',
+  orchid: '#da70d6',
+  tan: '#d2b48c',
+  chocolate: '#d2691e',
+  sienna: '#a0522d',
+  slategray: '#708090',
+  slategrey: '#708090',
+  steelblue: '#4682b4',
+  royalblue: '#4169e1',
+  dodgerblue: '#1e90ff',
+  skyblue: '#87ceeb',
+  lightblue: '#add8e6',
+  midnightblue: '#191970',
+  forestgreen: '#228b22',
+  seagreen: '#2e8b57',
+  limegreen: '#32cd32',
+  olivedrab: '#6b8e23',
+  darkgreen: '#006400',
+  emerald: '#50c878',
+  mint: '#3eb489',
+  goldenrod: '#daa520',
+  firebrick: '#b22222',
+  darkred: '#8b0000',
+  indianred: '#cd5c5c',
+  deeppink: '#ff1493',
+  mediumpurple: '#9370db',
+  rebeccapurple: '#663399',
+  darkviolet: '#9400d3',
+  slateblue: '#6a5acd',
+  cornflowerblue: '#6495ed',
+  teal2: '#008080',
+  charcoal: '#36454f',
+  graphite: '#3b3b3b',
+  transparent: 'transparent',
+};
+
+// ─── Colors ─────────────────────────────────────────────────────
+
+/** Structural validation for rgb()/rgba() so malformed "rgb…" input is rejected. */
+const RGB_RE =
+  /^rgba?\(\s*\d{1,3}%?\s*,\s*\d{1,3}%?\s*,\s*\d{1,3}%?\s*(,\s*(0|1|0?\.\d+|\d{1,3}%)\s*)?\)$/;
+
+function isValidRgb(value: string): boolean {
+  return RGB_RE.test(value);
+}
+
+/**
+ * Coerce a flexible color input into a canonical CSS color string.
+ * Accepts: `#1d4ed8`, `1d4ed8`, `#18f`, `rgb(...)`, `transparent`, and common
+ * CSS color names. Throws with guidance when the value can't be understood.
+ */
+export function coerceColor(input: unknown): string {
+  if (typeof input !== 'string' || input.trim() === '') {
+    throw new Error('Color must be a non-empty string (e.g. "#2563eb" or "blue").');
+  }
+  const trimmed = input.trim().toLowerCase();
+
+  const named = CSS_NAMED_COLORS[trimmed];
+  if (named) return named;
+
+  const normalized = normalizeColorValue(trimmed);
+  if (isValidHex(normalized) || normalized === 'transparent' || isValidRgb(normalized)) {
+    return normalized;
+  }
+
+  throw new Error(
+    `"${input}" is not a recognized color. Pass a hex value like "#ef4444" or a CSS color name (e.g. ${Object.keys(
+      CSS_NAMED_COLORS
+    )
+      .slice(0, 6)
+      .join(', ')}).`
+  );
+}
+
+// ─── Enums ──────────────────────────────────────────────────────
+
+export type BrandFamily = 'primary' | 'secondary' | 'accent';
+export type RoleFamilyInput = BrandFamily | 'neutral';
+
+/**
+ * Tool-facing family names, derived from the role layer's `ROLE_FAMILIES`. The
+ * role layer's canonical neutral family is `gray`; tools surface it as
+ * `neutral`. Deriving here keeps the tool vocabulary in sync if a family is
+ * added to `ROLE_FAMILIES`.
+ */
+export const ROLE_FAMILY_NAMES: RoleFamilyInput[] = ROLE_FAMILIES.map((f) =>
+  f === 'gray' ? 'neutral' : (f as RoleFamilyInput)
+);
+
+const FAMILY_SYNONYMS: Record<string, RoleFamilyInput> = {
+  ...Object.fromEntries(ROLE_FAMILY_NAMES.map((f) => [f, f])),
+  gray: 'neutral',
+  grey: 'neutral',
+};
+
+/** Coerce a palette family. Set `allowNeutral` for role assignments. */
+export function coerceFamily(input: unknown, allowNeutral = true): RoleFamilyInput {
+  const key = String(input ?? '').trim().toLowerCase();
+  const family = FAMILY_SYNONYMS[key];
+  if (!family || (!allowNeutral && family === 'neutral')) {
+    const valid = allowNeutral
+      ? 'primary, secondary, accent, neutral'
+      : 'primary, secondary, accent';
+    throw new Error(`Unknown color family "${input}". Valid families: ${valid}.`);
+  }
+  return family;
+}
+
+export function coerceIntensity(input: unknown): 'solid' | 'soft' {
+  const key = String(input ?? 'solid').trim().toLowerCase();
+  if (key === 'solid' || key === 'soft') return key;
+  throw new Error(`Unknown intensity "${input}". Valid intensities: solid, soft.`);
+}
+
+export function coerceScheme(input: unknown): 'light' | 'dark' | 'auto' {
+  const key = String(input ?? '').trim().toLowerCase();
+  if (key === 'light' || key === 'dark' || key === 'auto') return key;
+  if (key === 'system') return 'auto';
+  throw new Error(`Unknown color scheme "${input}". Valid: light, dark, auto.`);
+}
+
+export type RoundnessStyle = 'sharp' | 'default' | 'rounded' | 'pill';
+
+const ROUNDNESS_SYNONYMS: Record<string, RoundnessStyle> = {
+  sharp: 'sharp',
+  square: 'sharp',
+  none: 'sharp',
+  default: 'default',
+  normal: 'default',
+  rounded: 'rounded',
+  round: 'rounded',
+  soft: 'rounded',
+  pill: 'pill',
+  circle: 'pill',
+  full: 'pill',
+};
+
+export function coerceRoundnessStyle(input: unknown): RoundnessStyle {
+  const key = String(input ?? '').trim().toLowerCase();
+  const style = ROUNDNESS_SYNONYMS[key];
+  if (!style) {
+    throw new Error(`Unknown roundness "${input}". Valid: sharp, default, rounded, pill.`);
+  }
+  return style;
+}
+
+// ─── Sizes ──────────────────────────────────────────────────────
+
+/** Coerce a radius value: numbers become `${n}px`; CSS strings are normalized. */
+export function coerceRadius(input: unknown): string {
+  if (typeof input === 'number' && Number.isFinite(input)) {
+    return `${input}px`;
+  }
+  if (typeof input === 'string' && input.trim() !== '') {
+    const trimmed = input.trim();
+    if (trimmed === '9999px' || /^(100%|9999px)$/.test(trimmed)) return '9999px';
+    const parsed = parseCssValue(trimmed);
+    return formatCssValue(parsed.value, parsed.unit);
+  }
+  throw new Error('Radius must be a number (px) or a CSS length string like "0.5rem".');
+}
+
+// ─── Typography keyword → token-ref maps ────────────────────────
+// Base maps are derived from the editor's typography <select> options in
+// sections.ts (keyed by each option value's last path segment), so the
+// high-level tool's accepted values track the editor. Only the friendly
+// synonyms (monospace, small/medium/large, numeric weights/line-heights) are
+// hand-maintained on top.
+
+function refsFromTypographyField(fieldId: string): Record<string, string> {
+  for (const section of STYLE_SECTIONS) {
+    const field = section.fields.find((f) => f.id === fieldId);
+    if (field?.options) {
+      const map: Record<string, string> = {};
+      for (const opt of field.options) {
+        const key = opt.value.split('.').pop();
+        if (key) map[key] = opt.value;
+      }
+      return map;
+    }
+  }
+  return {};
+}
+
+const FAMILY_BASE = refsFromTypographyField('typo-font-family');
+const SIZE_BASE = refsFromTypographyField('typo-font-size');
+const WEIGHT_BASE = refsFromTypographyField('typo-font-weight');
+const LINE_BASE = refsFromTypographyField('typo-line-height');
+
+export const FONT_FAMILY_REFS: Record<string, string> = {
+  ...FAMILY_BASE,
+  monospace: FAMILY_BASE.mono,
+};
+
+export const FONT_SIZE_REFS: Record<string, string> = {
+  ...SIZE_BASE,
+  small: SIZE_BASE.sm,
+  md: SIZE_BASE.base,
+  medium: SIZE_BASE.base,
+  large: SIZE_BASE.lg,
+};
+
+export const FONT_WEIGHT_REFS: Record<string, string> = {
+  ...WEIGHT_BASE,
+  '400': WEIGHT_BASE.normal,
+  '500': WEIGHT_BASE.medium,
+  '600': WEIGHT_BASE.semibold,
+  '700': WEIGHT_BASE.bold,
+};
+
+export const LINE_HEIGHT_REFS: Record<string, string> = {
+  ...LINE_BASE,
+  '1.25': LINE_BASE.tight,
+  '1.5': LINE_BASE.normal,
+  '1.625': LINE_BASE.relaxed,
+};
+
+export function coerceTypographyRef(
+  input: unknown,
+  refs: Record<string, string>,
+  label: string
+): string {
+  const key = String(input ?? '').trim().toLowerCase();
+  const ref = refs[key];
+  if (!ref) {
+    const valid = [...new Set(Object.values(refs).map((r) => r.split('.').pop()))].join(', ');
+    throw new Error(`Unknown ${label} "${input}". Valid: ${valid}.`);
+  }
+  return ref;
+}

package/src/theme-editor/webmcp/index.ts

@@ -0,0 +1,45 @@
+/**
+ * WebMCP tools for the Persona theme editor.
+ *
+ * Transport-agnostic: `createThemeEditorTools(state)` returns plain tool
+ * definitions. Host code (e.g. an example app or a self-styling widget) is
+ * responsible for obtaining a `document.modelContext` and calling
+ * `registerTool` for each — this module has no polyfill dependency.
+ */
+
+export { createThemeEditorTools } from './tools';
+export { toolResult } from './types';
+export type {
+  WebMcpTool,
+  ToolResult,
+  ToolAnnotations,
+  ToolTextContent,
+  ToolExecute,
+  ThemeEditorLike,
+  EditTarget,
+  CreateThemeEditorToolsOptions,
+} from './types';
+export {
+  buildSummary,
+  runContrastChecks,
+  quickContrastWarnings,
+  CONTRAST_PAIRS,
+  RADIUS_PRESETS,
+} from './summary';
+export type {
+  ThemeSummary,
+  RoleState,
+  ContrastReport,
+  ContrastCheck,
+  ContrastWarning,
+  ContrastLevel,
+} from './summary';
+export {
+  coerceColor,
+  coerceFamily,
+  coerceIntensity,
+  coerceScheme,
+  coerceRoundnessStyle,
+  coerceRadius,
+  CSS_NAMED_COLORS,
+} from './coerce';

package/src/theme-editor/webmcp/summary.ts

@@ -0,0 +1,324 @@
+/**
+ * Theme state summarization + contrast feedback for the WebMCP tools.
+ *
+ * Every mutation tool returns a compact `ThemeSummary` plus any contrast
+ * warnings, so an agent gets actionable feedback without a follow-up read
+ * (arcade.dev "proactive state-returning").
+ */
+
+import { wcagContrastRatio, SHADE_KEYS } from '../color-utils';
+import { ALL_ROLES, detectRoleAssignment } from '../role-mappings';
+import { STYLE_SECTIONS } from '../sections';
+import type { RoleAssignmentOptions } from '../types';
+import type { ThemeEditorLike } from './types';
+import type { RoundnessStyle } from './coerce';
+
+// ─── Radius presets (derived from the editor's shape section) ───
+// The editor's shape section in sections.ts owns the canonical radius preset
+// values (default/sharp/rounded); we derive them here so the tool and the GUI
+// can't drift, and add the "pill" preset the editor doesn't expose.
+
+const RADIUS_PATH_PREFIX = 'theme.palette.radius.';
+
+function buildRadiusPresets(): Record<string, Record<string, string>> {
+  const presets: Record<string, Record<string, string>> = {
+    pill: { sm: '9999px', md: '9999px', lg: '9999px', xl: '9999px', full: '9999px' },
+  };
+  for (const section of STYLE_SECTIONS) {
+    for (const preset of section.presets ?? []) {
+      const match = preset.id.match(/^radius-(\w+)$/);
+      if (!match) continue;
+      const radius: Record<string, string> = {};
+      for (const [path, value] of Object.entries(preset.values)) {
+        if (path.startsWith(RADIUS_PATH_PREFIX) && typeof value === 'string') {
+          radius[path.slice(RADIUS_PATH_PREFIX.length)] = value;
+        }
+      }
+      presets[match[1]] = radius;
+    }
+  }
+  return presets;
+}
+
+export const RADIUS_PRESETS: Record<string, Record<string, string>> = buildRadiusPresets();
+
+const RADIUS_KEYS = ['sm', 'md', 'lg', 'xl', 'full'] as const;
+
+// ─── Variant-aware color resolution ─────────────────────────────
+
+/**
+ * Resolve a theme token path to a concrete color, following `palette.*`,
+ * `semantic.*`, and `components.*` references. When resolving the `darkTheme`
+ * variant, tokens the dark theme doesn't define fall back to the light theme —
+ * mirroring the widget's runtime merge behavior.
+ */
+export function resolveColor(
+  state: ThemeEditorLike,
+  path: string,
+  prefix: 'theme' | 'darkTheme' = 'theme',
+  depth = 0
+): string | null {
+  if (depth > 6) return null;
+  const raw = state.get(`${prefix}.${path}`);
+  if (typeof raw !== 'string' || raw === '') {
+    return prefix === 'darkTheme' ? resolveColor(state, path, 'theme', depth) : null;
+  }
+  if (raw.startsWith('#') || raw.startsWith('rgb') || raw === 'transparent') return raw;
+  if (
+    raw.startsWith('palette.') ||
+    raw.startsWith('semantic.') ||
+    raw.startsWith('components.')
+  ) {
+    return resolveColor(state, raw, prefix, depth + 1);
+  }
+  return null;
+}
+
+// ─── Summary ────────────────────────────────────────────────────
+
+export interface RoleState {
+  family: string;
+  intensity: string;
+}
+
+export interface ThemeSummary {
+  brand: { primary: string | null; secondary: string | null; accent: string | null };
+  roles: Record<string, RoleState | null>;
+  typography: {
+    fontFamily: string;
+    fontSize: string;
+    fontWeight: string;
+    lineHeight: string;
+  };
+  roundness: { style: RoundnessStyle | 'custom'; radius: Record<string, string> };
+  colorScheme: string;
+  history: { index: number; canUndo: boolean; canRedo: boolean };
+}
+
+function refSuffix(state: ThemeEditorLike, path: string): string {
+  const raw = state.get(path);
+  if (typeof raw !== 'string') return 'unknown';
+  const parts = raw.split('.');
+  return parts[parts.length - 1] || String(raw);
+}
+
+/** Friendly role key, e.g. `role-user-messages` → `user-messages`. */
+export function roleKey(roleId: string): string {
+  return roleId.replace(/^role-/, '');
+}
+
+function detectRoundness(radius: Record<string, string>): RoundnessStyle | 'custom' {
+  for (const [style, preset] of Object.entries(RADIUS_PRESETS) as [
+    RoundnessStyle,
+    Record<string, string>,
+  ][]) {
+    if (RADIUS_KEYS.every((k) => radius[k] === preset[k])) return style;
+  }
+  return 'custom';
+}
+
+export function buildSummary(state: ThemeEditorLike): ThemeSummary {
+  const radius: Record<string, string> = {};
+  for (const k of RADIUS_KEYS) {
+    radius[k] = String(state.get(`theme.palette.radius.${k}`) ?? '');
+  }
+
+  const roles: Record<string, RoleState | null> = {};
+  for (const role of ALL_ROLES) {
+    roles[roleKey(role.roleId)] = detectRoleAssignment(
+      (p) => state.get(`theme.${p}`),
+      role
+    );
+  }
+
+  return {
+    brand: {
+      primary: asColor(state.get('theme.palette.colors.primary.500')),
+      secondary: asColor(state.get('theme.palette.colors.secondary.500')),
+      accent: asColor(state.get('theme.palette.colors.accent.500')),
+    },
+    roles,
+    typography: {
+      fontFamily: refSuffix(state, 'theme.semantic.typography.fontFamily'),
+      fontSize: refSuffix(state, 'theme.semantic.typography.fontSize'),
+      fontWeight: refSuffix(state, 'theme.semantic.typography.fontWeight'),
+      lineHeight: refSuffix(state, 'theme.semantic.typography.lineHeight'),
+    },
+    roundness: { style: detectRoundness(radius), radius },
+    colorScheme: String(state.get('colorScheme') ?? 'light'),
+    history: {
+      index: state.getHistoryIndex(),
+      canUndo: state.canUndo(),
+      canRedo: state.canRedo(),
+    },
+  };
+}
+
+function asColor(value: unknown): string | null {
+  return typeof value === 'string' && value !== '' ? value : null;
+}
+
+// ─── Contrast ───────────────────────────────────────────────────
+
+export interface ContrastPair {
+  key: string;
+  label: string;
+  fg: string;
+  bg: string;
+}
+
+export const CONTRAST_PAIRS: ContrastPair[] = [
+  { key: 'user-message', label: 'User message text', fg: 'components.message.user.text', bg: 'components.message.user.background' },
+  { key: 'assistant-message', label: 'Assistant message text', fg: 'components.message.assistant.text', bg: 'components.message.assistant.background' },
+  { key: 'header', label: 'Header title', fg: 'components.header.titleForeground', bg: 'components.header.background' },
+  { key: 'primary-button', label: 'Primary button label', fg: 'components.button.primary.foreground', bg: 'components.button.primary.background' },
+  { key: 'input', label: 'Input placeholder', fg: 'components.input.placeholder', bg: 'components.input.background' },
+  { key: 'link', label: 'Link text', fg: 'components.markdown.link.foreground', bg: 'semantic.colors.background' },
+  { key: 'scroll', label: 'Scroll-to-bottom icon', fg: 'components.scrollToBottom.foreground', bg: 'components.scrollToBottom.background' },
+  { key: 'body', label: 'Body text on background', fg: 'semantic.colors.text', bg: 'semantic.colors.background' },
+  { key: 'surface', label: 'Body text on surface', fg: 'semantic.colors.text', bg: 'semantic.colors.surface' },
+];
+
+/**
+ * The contrast-pair keys relevant to a role, derived by intersecting the role's
+ * target token paths with the contrast pairs. This replaces a hand-maintained
+ * map so a new role or contrast pair is covered automatically. Roles with no
+ * text pair (e.g. borders) correctly yield `[]`.
+ */
+export function roleContrastPairKeys(role: RoleAssignmentOptions): string[] {
+  const targets = new Set(role.targets.map((t) => t.path));
+  return CONTRAST_PAIRS.filter((p) => targets.has(p.fg) || targets.has(p.bg)).map((p) => p.key);
+}
+
+export interface ContrastWarning {
+  code: 'contrast';
+  pair: string;
+  variant: 'light' | 'dark';
+  ratio: number;
+  threshold: number;
+  message: string;
+}
+
+export const CONTRAST_THRESHOLDS = { AA: 4.5, AAA: 7 } as const;
+export type ContrastLevel = keyof typeof CONTRAST_THRESHOLDS;
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+/**
+ * Suggest a same-family shade for `fgPath` that meets `threshold` against
+ * `bgHex`, preferring the passing shade closest to the current one. Returns a
+ * token-ref string (e.g. `palette.colors.primary.700`) or null.
+ */
+function suggestShade(
+  state: ThemeEditorLike,
+  fgPath: string,
+  bgHex: string,
+  threshold: number,
+  prefix: 'theme' | 'darkTheme'
+): string | null {
+  const raw = state.get(`${prefix}.${fgPath}`);
+  if (typeof raw !== 'string') return null;
+  const m = raw.match(/^palette\.colors\.(\w+)\.(\d+)$/);
+  if (!m) return null;
+  const family = m[1];
+  const currentIdx = SHADE_KEYS.indexOf(m[2] as (typeof SHADE_KEYS)[number]);
+
+  let best: string | null = null;
+  let bestDistance = Infinity;
+  SHADE_KEYS.forEach((shade, idx) => {
+    const hex = state.get(`${prefix}.palette.colors.${family}.${shade}`);
+    if (typeof hex !== 'string' || !(hex.startsWith('#') || hex.startsWith('rgb'))) return;
+    if (wcagContrastRatio(hex, bgHex) >= threshold) {
+      const distance = currentIdx >= 0 ? Math.abs(idx - currentIdx) : idx;
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        best = `palette.colors.${family}.${shade}`;
+      }
+    }
+  });
+  return best;
+}
+
+export interface ContrastCheck {
+  pair: string;
+  label: string;
+  variant: 'light' | 'dark';
+  fg: string;
+  bg: string;
+  ratio: number;
+  threshold: number;
+  passes: boolean;
+  suggestion?: string;
+}
+
+export interface ContrastReport {
+  level: ContrastLevel;
+  checks: ContrastCheck[];
+  failures: ContrastCheck[];
+}
+
+/** Run contrast over the named pairs (default: all) for the given variant(s). */
+export function runContrastChecks(
+  state: ThemeEditorLike,
+  level: ContrastLevel = 'AA',
+  variant: 'light' | 'dark' | 'both' = 'both',
+  pairKeys?: string[]
+): ContrastReport {
+  const threshold = CONTRAST_THRESHOLDS[level];
+  const variants: ('light' | 'dark')[] = variant === 'both' ? ['light', 'dark'] : [variant];
+  const pairs = pairKeys
+    ? CONTRAST_PAIRS.filter((p) => pairKeys.includes(p.key))
+    : CONTRAST_PAIRS;
+
+  const checks: ContrastCheck[] = [];
+  for (const v of variants) {
+    const prefix = v === 'light' ? 'theme' : 'darkTheme';
+    for (const pair of pairs) {
+      const fg = resolveColor(state, pair.fg, prefix);
+      const bg = resolveColor(state, pair.bg, prefix);
+      if (!fg || !bg) continue;
+      const ratio = round2(wcagContrastRatio(fg, bg));
+      const passes = ratio >= threshold;
+      const check: ContrastCheck = {
+        pair: pair.key,
+        label: pair.label,
+        variant: v,
+        fg,
+        bg,
+        ratio,
+        threshold,
+        passes,
+      };
+      if (!passes) {
+        const suggestion = suggestShade(state, pair.fg, bg, threshold, prefix);
+        if (suggestion) check.suggestion = suggestion;
+      }
+      checks.push(check);
+    }
+  }
+
+  return { level, checks, failures: checks.filter((c) => !c.passes) };
+}
+
+/** Compact contrast warnings for the regions a mutation touched. */
+export function quickContrastWarnings(
+  state: ThemeEditorLike,
+  pairKeys: string[],
+  variant: 'light' | 'dark' | 'both' = 'light',
+  level: ContrastLevel = 'AA'
+): ContrastWarning[] {
+  if (pairKeys.length === 0) return [];
+  const report = runContrastChecks(state, level, variant, pairKeys);
+  return report.failures.map((f) => ({
+    code: 'contrast' as const,
+    pair: f.pair,
+    variant: f.variant,
+    ratio: f.ratio,
+    threshold: f.threshold,
+    message: `${f.label} (${f.variant}) has a contrast ratio of ${f.ratio}:1, below the ${level} threshold of ${f.threshold}:1${
+      f.suggestion ? `. Try ${f.suggestion} for the foreground.` : '.'
+    }`,
+  }));
+}