prism-design 2.13.0

package/scripts/shared/css-helpers.ts

@@ -0,0 +1,263 @@
+/**
+ * shared/css-helpers.ts — Prism Phase 5 Sprint 80/20
+ * Primitives pures unifiées (parseRgb×3 → 1, luminance×3 → 1, NOISE_VALUES, etc.)
+ */
+
+// ─── Color parsing & normalization ────────────────────────────────────────────
+
+/** Parse rgb/rgba string → [r,g,b]. Returns null if invalid. */
+export function parseRgb(color: string): [number, number, number] | null {
+  if (!color) return null;
+  const m = color.match(/rgba?\(\s*(\d+),\s*(\d+),\s*(\d+)/);
+  if (!m) return null;
+  return [parseInt(m[1]), parseInt(m[2]), parseInt(m[3])];
+}
+
+/** Normalize rgb/rgba string: uniform spacing, preserve alpha when <1. */
+export function normalizeRgb(color: string): string {
+  const m = color.match(/rgba?\(\s*(\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\s*\)/);
+  if (!m) return color;
+  const a = m[4];
+  if (a !== undefined && parseFloat(a) < 1) {
+    return `rgba(${m[1]}, ${m[2]}, ${m[3]}, ${a})`;
+  }
+  return `rgb(${m[1]}, ${m[2]}, ${m[3]})`;
+}
+
+// ─── Luminance (WCAG perceptual) — accepts (r,g,b) OR ([r,g,b]) ──────────────
+
+/**
+ * WCAG relative luminance (perceptual, gamma-corrected).
+ * Used by: retheme.ts, bank-register.ts (isDark detection + fuzzy matching).
+ * Accepts both signatures for backward compat.
+ */
+export function luminance(r: number | [number, number, number], g?: number, b?: number): number {
+  let rr: number, gg: number, bb: number;
+  if (Array.isArray(r)) {
+    [rr, gg, bb] = r;
+  } else {
+    rr = r;
+    gg = g as number;
+    bb = b as number;
+  }
+  const s = [rr, gg, bb].map(v => {
+    const n = v / 255;
+    return n <= 0.03928 ? n / 12.92 : Math.pow((n + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * s[0] + 0.7152 * s[1] + 0.0722 * s[2];
+}
+
+/**
+ * Simple luminance (ITU-R BT.601, not gamma-corrected).
+ * Used by: tokenize.ts classifyColors (keeping legacy behavior for compat).
+ * DO NOT change formula — changes isDark detection on 411 existing snapshots.
+ */
+export function luminanceSimple(rgb: [number, number, number]): number {
+  return (0.299 * rgb[0] + 0.587 * rgb[1] + 0.114 * rgb[2]) / 255;
+}
+
+// ─── Memoized luminance (Sprint 80/20 J3 perf) ───────────────────────────────
+
+const _lumCache = new Map<string, number>();
+
+export function luminanceMemo(r: number, g: number, b: number): number {
+  const key = `${r},${g},${b}`;
+  const cached = _lumCache.get(key);
+  if (cached !== undefined) return cached;
+  // LRU cap 10K entries
+  if (_lumCache.size >= 10000) {
+    const firstKey = _lumCache.keys().next().value;
+    if (firstKey !== undefined) _lumCache.delete(firstKey);
+  }
+  const result = luminance(r, g, b);
+  _lumCache.set(key, result);
+  return result;
+}
+
+// ─── Perceptual color distance (weighted euclidean) ───────────────────────────
+
+export function colorDistance(a: [number, number, number], b: [number, number, number]): number {
+  const rMean = (a[0] + b[0]) / 2;
+  const dr = a[0] - b[0];
+  const dg = a[1] - b[1];
+  const db = a[2] - b[2];
+  return Math.sqrt(
+    (2 + rMean / 256) * dr * dr +
+    4 * dg * dg +
+    (2 + (255 - rMean) / 256) * db * db
+  );
+}
+
+// ─── Pixel parsing (from tokenize.ts — most permissive) ───────────────────────
+
+export function parsePixels(val: string): number {
+  const m = (val || '').match(/(-?\d+(?:\.\d+)?)\s*px/);
+  return m ? parseFloat(m[1]) : 0;
+}
+
+/**
+ * Normalize a CSS border-radius value for display.
+ * Chrome MAX_INT border-radius (3.35544e+07px) → '9999px'.
+ * Preserves valid values under 9999.
+ */
+export function normalizeRadius(val: string): string {
+  if (!val || val === 'none' || val === '0px') return val;
+  // Handle multi-value radius (e.g. "4px 4px 0px 0px") — normalize each part
+  const parts = val.trim().split(/\s+/);
+  const normalized = parts.map(part => {
+    const n = parseFloat(part);
+    if (!isNaN(n) && n > 9999) return '9999px';
+    return part;
+  });
+  return normalized.join(' ');
+}
+
+// ─── HEX conversion ───────────────────────────────────────────────────────────
+
+export function rgbToHex(rgb: [number, number, number]): string {
+  const [r, g, b] = rgb;
+  const toHex = (n: number) => n.toString(16).padStart(2, '0');
+  return '#' + toHex(r) + toHex(g) + toHex(b);
+}
+
+// ─── Clean color value (from tokenize.ts) ─────────────────────────────────────
+
+export function cleanColorValue(v: string): string {
+  return (v || '').trim().replace(/\s+/g, ' ');
+}
+
+// ─── Dark site detection (unified) ────────────────────────────────────────────
+
+export function isDarkBackground(color: string, threshold = 0.3): boolean {
+  if (!color || color.includes('rgba(0, 0, 0, 0)') || color === 'transparent') return false;
+  const rgb = parseRgb(color);
+  if (!rgb) return false;
+  return luminance(rgb) < threshold;
+}
+
+// ─── CSS NOISE filter (formerly in bank-inject.ts + renderers.ts duplicated) ──
+
+export const NOISE_VALUES: Record<string, Set<string>> = {
+  backgroundColor: new Set(['rgba(0, 0, 0, 0)', 'transparent', 'initial', 'inherit']),
+  border: new Set(['0px none rgb(0, 0, 0)', '0px none', 'none', '0px', 'medium none']),
+  borderColor: new Set([]),
+  boxShadow: new Set(['none']),
+  opacity: new Set(['1']),
+  overflow: new Set(['visible']),
+  position: new Set(['static']),
+  flexDirection: new Set(['row']),
+  alignItems: new Set(['normal', 'stretch']),
+  justifyContent: new Set(['normal', 'flex-start']),
+  transition: new Set(['all', 'all 0s ease 0s', 'none 0s ease 0s', 'none']),
+  textTransform: new Set(['none']),
+  textDecoration: new Set(['none']),
+  letterSpacing: new Set(['normal', '0px']),
+  fontFeatureSettings: new Set(['normal']),
+  fontVariationSettings: new Set(['normal']),
+  gap: new Set(['normal', '0px']),
+  gridTemplateColumns: new Set(['none']),
+  gridTemplateRows: new Set(['none']),
+  maxWidth: new Set(['none']),
+  minHeight: new Set(['auto', '0px']),
+};
+
+export const ALWAYS_DROP_PROPS = new Set([
+  'borderColor',
+  'marginTop', 'marginRight', 'marginBottom', 'marginLeft',
+  'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft',
+]);
+
+export const INHERITED_PROPS = new Set([
+  'color', 'fontFamily', 'fontSize', 'fontWeight', 'lineHeight',
+  'letterSpacing', 'textTransform',
+]);
+
+export function isNoise(prop: string, value: string): boolean {
+  if (ALWAYS_DROP_PROPS.has(prop)) return true;
+  const noiseSet = NOISE_VALUES[prop];
+  if (!noiseSet) return false;
+  if (noiseSet.size === 0) return true; // empty = always drop
+  return noiseSet.has(value);
+}
+
+export function isTransparent(color: string): boolean {
+  return !color || color.includes('rgba(0, 0, 0, 0)') || color === 'transparent';
+}
+
+// ─── Filter styles: apply NOISE + inheritance ─────────────────────────────────
+
+export function filterStyles(
+  styles: Record<string, string>,
+  parentStyles: Record<string, string>,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [prop, val] of Object.entries(styles)) {
+    if (typeof val !== 'string') continue;
+    if (isNoise(prop, val)) continue;
+    if (INHERITED_PROPS.has(prop) && parentStyles[prop] === val) continue;
+    result[prop] = val;
+  }
+  return result;
+}
+
+export function buildChildParentStyles(
+  ownStyles: Record<string, string>,
+  parentStyles: Record<string, string>,
+): Record<string, string> {
+  const next = { ...parentStyles };
+  for (const [prop, val] of Object.entries(ownStyles)) {
+    if (INHERITED_PROPS.has(prop)) next[prop] = val;
+  }
+  return next;
+}
+
+// ─── HTML utilities ───────────────────────────────────────────────────────────
+
+export function escapeHtml(str: string): string {
+  if (!str) return '';
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+export function sanitizeUrl(url: string): string {
+  if (!url) return '';
+  const lower = url.trim().toLowerCase();
+  if (lower.startsWith('javascript:') || lower.startsWith('data:')) return '#';
+  if (url.startsWith('//')) return 'https:' + url;
+  return url;
+}
+
+export function cssKebab(prop: string): string {
+  return prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+
+// ─── Color hue family (for tagging) ───────────────────────────────────────────
+
+export function colorHueTag(color: string): string | null {
+  const rgb = parseRgb(color);
+  if (!rgb) return null;
+  const [r, g, b] = rgb;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  if (delta < 30) return null;
+
+  let hue = 0;
+  if (max === r) hue = ((g - b) / delta) % 6;
+  else if (max === g) hue = (b - r) / delta + 2;
+  else hue = (r - g) / delta + 4;
+  hue = Math.round(hue * 60);
+  if (hue < 0) hue += 360;
+
+  if (hue < 30)   return 'accent-red';
+  if (hue < 60)   return 'accent-orange';
+  if (hue < 150)  return 'accent-green';
+  if (hue < 210)  return 'accent-teal';
+  if (hue < 270)  return 'accent-blue';
+  if (hue < 330)  return 'accent-purple';
+  return 'accent-pink';
+}

package/scripts/shared/logger.ts

@@ -0,0 +1,57 @@
+/**
+ * shared/logger.ts — Prism
+ * Logger léger avec niveaux + contexte + JSON mode pour CI
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LEVEL_WEIGHT: Record<LogLevel, number> = {
+  debug: 0, info: 1, warn: 2, error: 3,
+};
+
+const CURRENT_LEVEL: LogLevel = (process.env.CLONE_LOG_LEVEL as LogLevel) || 'info';
+const JSON_MODE = process.env.CLONE_LOG_JSON === '1';
+
+function shouldLog(level: LogLevel): boolean {
+  return LEVEL_WEIGHT[level] >= LEVEL_WEIGHT[CURRENT_LEVEL];
+}
+
+function format(level: LogLevel, module: string, msg: string, meta?: any): string {
+  if (JSON_MODE) {
+    return JSON.stringify({ level, module, msg, meta, ts: new Date().toISOString() });
+  }
+  const prefix = level === 'error' ? '❌' : level === 'warn' ? '⚠️ ' : level === 'debug' ? '🔍' : 'ℹ️ ';
+  const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
+  return `${prefix} [${module}] ${msg}${metaStr}`;
+}
+
+export class Logger {
+  constructor(private module: string) {}
+
+  debug(msg: string, meta?: any): void {
+    if (shouldLog('debug')) console.log(format('debug', this.module, msg, meta));
+  }
+  info(msg: string, meta?: any): void {
+    if (shouldLog('info')) console.log(format('info', this.module, msg, meta));
+  }
+  warn(msg: string, meta?: any): void {
+    if (shouldLog('warn')) console.warn(format('warn', this.module, msg, meta));
+  }
+  error(msg: string, meta?: any): void {
+    if (shouldLog('error')) console.error(format('error', this.module, msg, meta));
+  }
+
+  /** Wrap a promise with try/catch + warn on failure. */
+  async tryOrWarn<T>(label: string, fn: () => Promise<T>, fallback: T): Promise<T> {
+    try {
+      return await fn();
+    } catch (err) {
+      this.warn(`${label} failed`, { error: (err as Error).message });
+      return fallback;
+    }
+  }
+}
+
+export function getLogger(module: string): Logger {
+  return new Logger(module);
+}

package/scripts/shared/named-colors.ts

@@ -0,0 +1,355 @@
+/**
+ * shared/named-colors.ts — Prism
+ * Palette de couleurs nommées pour nameColor/nameColorUnique.
+ * Extrait de generate-design-md.ts (RFC D).
+ */
+
+import { parseRgb, colorDistance } from './css-helpers.js';
+
+export interface NamedColor {
+  name: string;
+  hex: string;
+  rgb: [number, number, number];
+}
+
+export const NAMED_COLORS: NamedColor[] = [
+  { name: 'Pure White', hex: '#ffffff', rgb: [255, 255, 255] },
+  { name: 'Snow', hex: '#fffafa', rgb: [255, 250, 250] },
+  { name: 'Off-White', hex: '#fafafa', rgb: [250, 250, 250] },
+  { name: 'Ghost White', hex: '#f8f8ff', rgb: [248, 248, 255] },
+  { name: 'Warm Cream', hex: '#f7f4ed', rgb: [247, 244, 237] },
+  { name: 'Light Gray', hex: '#f0f0f0', rgb: [240, 240, 240] },
+  { name: 'Silver', hex: '#c0c0c0', rgb: [192, 192, 192] },
+  { name: 'Medium Gray', hex: '#808080', rgb: [128, 128, 128] },
+  { name: 'Dim Gray', hex: '#696969', rgb: [105, 105, 105] },
+  { name: 'Dark Gray', hex: '#404040', rgb: [64, 64, 64] },
+  { name: 'Charcoal', hex: '#333333', rgb: [51, 51, 51] },
+  { name: 'Near Black', hex: '#1c1c1c', rgb: [28, 28, 28] },
+  { name: 'Jet Black', hex: '#111111', rgb: [17, 17, 17] },
+  { name: 'Pure Black', hex: '#000000', rgb: [0, 0, 0] },
+  { name: 'Deep Navy', hex: '#0a1628', rgb: [10, 22, 40] },
+  { name: 'Navy Blue', hex: '#001f3f', rgb: [0, 31, 63] },
+  { name: 'Royal Blue', hex: '#4169e1', rgb: [65, 105, 225] },
+  { name: 'Cobalt Blue', hex: '#0047ab', rgb: [0, 71, 171] },
+  { name: 'Sky Blue', hex: '#87ceeb', rgb: [135, 206, 235] },
+  { name: 'Steel Blue', hex: '#4682b4', rgb: [70, 130, 180] },
+  { name: 'Cornflower Blue', hex: '#6495ed', rgb: [100, 149, 237] },
+  { name: 'Slate Blue', hex: '#6a5acd', rgb: [106, 90, 205] },
+  { name: 'Light Blue', hex: '#add8e6', rgb: [173, 216, 230] },
+  { name: 'Baby Blue', hex: '#89cff0', rgb: [137, 207, 240] },
+  { name: 'Indigo', hex: '#5e6ad2', rgb: [94, 106, 210] },
+  { name: 'Violet', hex: '#7c3aed', rgb: [124, 58, 237] },
+  { name: 'Deep Purple', hex: '#533afd', rgb: [83, 58, 253] },
+  { name: 'Lavender', hex: '#b9b9f9', rgb: [185, 185, 249] },
+  { name: 'Amethyst', hex: '#9966cc', rgb: [153, 102, 204] },
+  { name: 'Plum', hex: '#dda0dd', rgb: [221, 160, 221] },
+  { name: 'Red', hex: '#ff0000', rgb: [255, 0, 0] },
+  { name: 'Crimson', hex: '#dc143c', rgb: [220, 20, 60] },
+  { name: 'Ruby', hex: '#ea2261', rgb: [234, 34, 97] },
+  { name: 'Vermillion', hex: '#e34234', rgb: [227, 66, 52] },
+  { name: 'Cherry', hex: '#de3163', rgb: [222, 49, 99] },
+  { name: 'Coral', hex: '#ff7f50', rgb: [255, 127, 80] },
+  { name: 'Rose', hex: '#ff007f', rgb: [255, 0, 127] },
+  { name: 'Warm Rose', hex: '#ff385c', rgb: [255, 56, 92] },
+  { name: 'Bright Orange', hex: '#f54e00', rgb: [245, 78, 0] },
+  { name: 'Tangerine', hex: '#ff9966', rgb: [255, 153, 102] },
+  { name: 'Amber', hex: '#ffbf00', rgb: [255, 191, 0] },
+  { name: 'Gold', hex: '#ffd700', rgb: [255, 215, 0] },
+  { name: 'Honey', hex: '#c08532', rgb: [192, 133, 50] },
+  { name: 'Emerald', hex: '#10b981', rgb: [16, 185, 129] },
+  { name: 'Forest Green', hex: '#228b22', rgb: [34, 139, 34] },
+  { name: 'Sage', hex: '#9fbbe0', rgb: [159, 187, 224] },
+  { name: 'Mint', hex: '#98fb98', rgb: [152, 251, 152] },
+  { name: 'Teal', hex: '#1f8a65', rgb: [31, 138, 101] },
+  { name: 'Success Green', hex: '#27a644', rgb: [39, 166, 68] },
+  { name: 'Magenta', hex: '#f96bee', rgb: [249, 107, 238] },
+  { name: 'Hot Pink', hex: '#ff69b4', rgb: [255, 105, 180] },
+  { name: 'Pink', hex: '#ffc0cb', rgb: [255, 192, 203] },
+  { name: 'Soft Pink', hex: '#ffd7ef', rgb: [255, 215, 239] },
+  { name: 'Warm Brown', hex: '#26251e', rgb: [38, 37, 30] },
+  { name: 'Chocolate', hex: '#7b3f00', rgb: [123, 63, 0] },
+  { name: 'Beige', hex: '#f5f5dc', rgb: [245, 245, 220] },
+  { name: 'Parchment', hex: '#f7f4ed', rgb: [247, 244, 237] },
+  // Brand-specific extensions (2026-05-25, sprint v3)
+  { name: 'Cream', hex: '#fcfbf8', rgb: [252, 251, 248] },        // Lovable / Anthropic warm canvas
+  { name: 'Off-Cream', hex: '#fafaf7', rgb: [250, 250, 247] },
+  { name: 'Slate', hex: '#475569', rgb: [71, 85, 105] },          // Tailwind slate-600
+  { name: 'Slate Gray', hex: '#64748b', rgb: [100, 116, 139] },
+  { name: 'Cool Gray', hex: '#9ca3af', rgb: [156, 163, 175] },
+  { name: 'Stone', hex: '#78716c', rgb: [120, 113, 108] },        // Tailwind stone-500
+  { name: 'Terracotta', hex: '#c96442', rgb: [201, 100, 66] },    // Anthropic Claude brand
+  { name: 'Warm Terracotta', hex: '#d97757', rgb: [217, 119, 87] }, // Claude alt
+  { name: 'Ring Blue', hex: '#3b82f6', rgb: [59, 130, 246] },     // Tailwind focus ring (Lovable, many SaaS)
+  { name: 'Sky Bright', hex: '#0ea5e9', rgb: [14, 165, 233] },
+  { name: 'Brand Indigo', hex: '#6366f1', rgb: [99, 102, 241] },  // Tailwind indigo-500
+  { name: 'M Tricolor Red', hex: '#e22718', rgb: [226, 39, 24] }, // BMW M
+  { name: 'M Tricolor Blue', hex: '#1c69d4', rgb: [28, 105, 212] },
+  { name: 'Vibrant Yellow', hex: '#fff8c2', rgb: [255, 248, 194] }, // Mistral cards
+];
+
+/**
+ * Color distance threshold above which we fallback to hex (no name).
+ * RGB Euclidean distance — calibrated so that bright distinctive colors
+ * far from any named entry get a fair `#hex` label instead of a misleading match.
+ * Default: 60 (allows ~30% per-channel variation from nearest).
+ */
+const COLOR_NAME_DISTANCE_THRESHOLD = 60;
+
+function rgbToHex(r: number, g: number, b: number): string {
+  return '#' + [r, g, b].map(v => v.toString(16).padStart(2, '0')).join('');
+}
+
+export interface NamedColorResult {
+  /** Semantic color name (e.g. "Indigo", "Transparent", "Translucent White (2%)"). */
+  name: string;
+  /** Solid hex equivalent ("#000000" for transparent fallback, real hex otherwise). Use for palette indexing. */
+  hex: string;
+  /** The value to render in user-facing output. 'transparent' if alpha=0, 'rgba(...)' if 0<alpha<1, '#hex' if alpha=1. */
+  displayValue: string;
+  /** Alpha channel 0..1. Undefined if input had no alpha (treated as 1). */
+  alpha?: number;
+}
+
+/** Parse hex color string (#RGB, #RRGGBB, #RRGGBBAA) → [r,g,b,a]. Returns null if invalid. */
+function parseHex(color: string): { rgb: [number, number, number]; alpha: number } | null {
+  const trimmed = color.trim();
+  // Match #RGB, #RGBA, #RRGGBB, #RRGGBBAA
+  const m = trimmed.match(/^#([0-9a-fA-F]{3,8})$/);
+  if (!m) return null;
+  const hex = m[1];
+  let r: number, g: number, b: number, a: number;
+  if (hex.length === 3) {
+    r = parseInt(hex[0] + hex[0], 16); g = parseInt(hex[1] + hex[1], 16); b = parseInt(hex[2] + hex[2], 16); a = 1;
+  } else if (hex.length === 4) {
+    r = parseInt(hex[0] + hex[0], 16); g = parseInt(hex[1] + hex[1], 16); b = parseInt(hex[2] + hex[2], 16);
+    a = parseInt(hex[3] + hex[3], 16) / 255;
+  } else if (hex.length === 6) {
+    r = parseInt(hex.slice(0, 2), 16); g = parseInt(hex.slice(2, 4), 16); b = parseInt(hex.slice(4, 6), 16); a = 1;
+  } else if (hex.length === 8) {
+    r = parseInt(hex.slice(0, 2), 16); g = parseInt(hex.slice(2, 4), 16); b = parseInt(hex.slice(4, 6), 16);
+    a = parseInt(hex.slice(6, 8), 16) / 255;
+  } else {
+    return null;
+  }
+  return { rgb: [r, g, b], alpha: a };
+}
+
+/**
+ * Resolve a color's semantic name from CSS custom properties matching the same value.
+ * If a CSS var (e.g. `--brand-primary: #533afd`) matches the input RGB, returns a human
+ * name derived from the var key ("Brand Primary"). Returns null if no semantic match.
+ *
+ * Priority order (highest → lowest):
+ * 1. Simple single-word brand var (--palette-rausch, --color-luxe, --brand-primary as single)
+ * 2. Single semantic role (--error, --success, --primary)
+ * 3. Vendor-prefixed canonical role (--hds-color-accent-border-solid → "Accent")
+ * 4. Two-segment brand+role (--brand-primary, --primary-default)
+ * 5. Composed palette tokens (--palette-bg-primary-core → "Primary")
+ *
+ * Decorative/derivative names (containing gradient/stop/subtle/quiet/hover/disabled)
+ * are de-prioritized — we prefer canonical names over variants.
+ */
+export function resolveSemanticBrandName(
+  rgb: [number, number, number],
+  cssVars: Record<string, string> | undefined
+): string | null {
+  if (!cssVars || Object.keys(cssVars).length === 0) return null;
+
+  const targetHex = rgbToHex(rgb[0], rgb[1], rgb[2]).toLowerCase();
+
+  // Tokens that suggest a derivative/variant rather than canonical brand name
+  const DERIVATIVE_TOKENS = /(?:^|-)(gradient|stop|color-stop|subtle|subdued|quiet|hover|active|focus|disabled|pressed|selected|onSubdued|alternate|alt|inverse|tint|shade|opacity|alpha|translucent|core-rtl|rtl)(?:-|$)/i;
+
+  const SEMANTIC_PATTERNS: Array<{
+    regex: RegExp;
+    transform: (m: RegExpMatchArray) => string;
+    priority: number;
+  }> = [
+    // --palette-WORD or --color-WORD (single brand word: Rausch, Luxe, Hof, Babu)
+    { regex: /^--(?:palette|color)-([a-zA-Z]{3,})$/, transform: m => titleCase(m[1]), priority: 100 },
+    // Single semantic role: --error, --warning, --success, --info, --danger, --primary
+    { regex: /^--(error|warning|success|info|danger|alert|primary|secondary|tertiary|brand|accent)$/i,
+      transform: m => titleCase(m[1]), priority: 95 },
+    // --brand-WORD (single descriptor: --brand-primary, --brand-blue)
+    { regex: /^--brand-([a-zA-Z]{3,})$/, transform: m => `${titleCase('Brand')} ${titleCase(m[1])}`, priority: 90 },
+    // Vendor-prefixed canonical role: --hds-color-accent[-X], --tw-color-primary, etc.
+    // Returns just the role name (e.g. "Accent") — clean and reusable.
+    { regex: /^--(?:hds|tw|ds|ui|next|app|nx|nui|ant|aria|mui)-color-(accent|brand|primary|surface|text|border|action|link|secondary|tertiary)(?:-[a-zA-Z0-9-]+)*$/i,
+      transform: m => titleCase(m[1]), priority: 80 },
+    // --(brand|primary|accent|secondary)-WORD (single-segment descriptor only, no hyphens in group 2)
+    { regex: /^--(brand|primary|accent|secondary|tertiary|action|link)-([a-zA-Z]{2,})$/i,
+      transform: m => `${titleCase(m[1])} ${titleCase(m[2])}`, priority: 70 },
+    // --color-(role)-WORD (single-segment descriptor)
+    { regex: /^--color-(text|bg|background|surface|border|fill|stroke|accent|brand|action|link)-([a-zA-Z]{2,})$/i,
+      transform: m => `${titleCase(m[1])} ${titleCase(m[2])}`, priority: 60 },
+    // --palette-(role)-WORD-core
+    { regex: /^--palette-(?:bg|surface|text|border|action|fg|fill)-([a-zA-Z]+)-?(?:core|main|primary|default)?$/i,
+      transform: m => titleCase(m[1]), priority: 50 },
+    // --palette-WORD-core
+    { regex: /^--palette-([a-zA-Z]+)-(?:core|main|primary|default)$/i,
+      transform: m => titleCase(m[1]), priority: 45 },
+  ];
+
+  let bestMatch: { name: string; priority: number; keyLength: number; isDerivative: boolean } | null = null;
+
+  for (const [key, value] of Object.entries(cssVars)) {
+    if (!value || typeof value !== 'string') continue;
+
+    // Try to parse the value as a color (hex or rgb/rgba)
+    let varRgb: [number, number, number] | null = null;
+    const hexParsed = parseHex(value.trim());
+    if (hexParsed && hexParsed.alpha === 1) {
+      varRgb = hexParsed.rgb;
+    } else {
+      varRgb = parseRgb(value);
+    }
+    if (!varRgb) continue;
+
+    // Exact hex match required (no fuzzy matching on semantic names)
+    const varHex = rgbToHex(varRgb[0], varRgb[1], varRgb[2]).toLowerCase();
+    if (varHex !== targetHex) continue;
+
+    const isDerivative = DERIVATIVE_TOKENS.test(key);
+
+    // Try patterns in priority order, first match wins per key
+    for (const pattern of SEMANTIC_PATTERNS) {
+      const match = key.match(pattern.regex);
+      if (match) {
+        const name = pattern.transform(match);
+        // Selection logic (in order of precedence):
+        // 1. Non-derivative beats derivative (always prefer canonical "Accent" over "Accent Hover")
+        // 2. Higher priority beats lower
+        // 3. On tie: shorter key (more canonical)
+        const beatsCurrentBest = !bestMatch
+          || (!isDerivative && bestMatch.isDerivative)
+          || (isDerivative === bestMatch.isDerivative && pattern.priority > bestMatch.priority)
+          || (isDerivative === bestMatch.isDerivative && pattern.priority === bestMatch.priority && key.length < bestMatch.keyLength);
+
+        if (beatsCurrentBest) {
+          bestMatch = { name, priority: pattern.priority, keyLength: key.length, isDerivative };
+        }
+        break; // first pattern wins per key
+      }
+    }
+  }
+
+  return bestMatch?.name || null;
+}
+
+function titleCase(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1).toLowerCase();
+}
+
+function titleCaseHyphenated(s: string): string {
+  return s.split(/[-_]/).filter(Boolean).map(titleCase).join(' ');
+}
+
+/**
+ * Name a color using brand-aware semantic lookup, falling back to nearest-neighbor.
+ *
+ * @param color - CSS color string (hex, rgb, rgba, "transparent")
+ * @param cssVars - Optional CSS custom properties from the same site. If provided,
+ *   any var whose resolved color equals `color` will produce a semantic name
+ *   (e.g. "Rausch" for --palette-rausch) instead of nearest-neighbor ("Warm Rose").
+ */
+export function nameColor(color: string, cssVars?: Record<string, string>): NamedColorResult {
+  if (!color) return { name: 'Unknown', hex: '#000000', displayValue: '#000000' };
+
+  const trimmed = color.trim().toLowerCase();
+  if (trimmed === 'transparent' || trimmed === 'rgba(0,0,0,0)' || trimmed === 'rgba(0, 0, 0, 0)') {
+    return { name: 'Transparent', hex: 'transparent', displayValue: 'transparent', alpha: 0 };
+  }
+
+  // Detect hex input first (parseRgb only handles rgb/rgba strings)
+  let rgb: [number, number, number] | null = null;
+  let alpha = 1;
+  const hexParsed = parseHex(color);
+  if (hexParsed) {
+    rgb = hexParsed.rgb;
+    alpha = hexParsed.alpha;
+  } else {
+    const rgbaMatch = color.match(/rgba?\(\s*(\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\s*\)/);
+    alpha = rgbaMatch && rgbaMatch[4] !== undefined ? parseFloat(rgbaMatch[4]) : 1;
+    rgb = parseRgb(color);
+  }
+
+  if (alpha === 0) {
+    return { name: 'Transparent', hex: 'transparent', displayValue: 'transparent', alpha: 0 };
+  }
+
+  if (!rgb) return { name: 'Unknown', hex: '#000000', displayValue: '#000000' };
+
+  const hex = rgbToHex(rgb[0], rgb[1], rgb[2]);
+
+  // Brand-aware semantic naming: if cssVars provided, try to match a brand/semantic CSS var
+  // before falling back to nearest-neighbor. Only applies to fully opaque colors.
+  if (cssVars && alpha === 1) {
+    const semanticName = resolveSemanticBrandName(rgb, cssVars);
+    if (semanticName) {
+      return { name: semanticName, hex, displayValue: hex };
+    }
+  }
+
+  let bestName = 'Unknown';
+  let bestDist = Infinity;
+
+  for (const nc of NAMED_COLORS) {
+    const dist = colorDistance(rgb, nc.rgb);
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestName = nc.name;
+    }
+  }
+
+  // If nearest named color is too far, fall back to the hex value as name.
+  // Prevents misleading labels like "Indigo" for a totally different bright color.
+  if (bestDist > COLOR_NAME_DISTANCE_THRESHOLD) {
+    bestName = hex;
+  }
+
+  if (alpha < 1) {
+    const opacityPct = Math.round(alpha * 100);
+    // For translucent colors, attempt semantic match on the opaque equivalent
+    if (cssVars) {
+      const opaqueSemanticName = resolveSemanticBrandName(rgb, cssVars);
+      if (opaqueSemanticName) {
+        return {
+          name: `Translucent ${opaqueSemanticName} (${opacityPct}%)`,
+          hex,
+          displayValue: `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${alpha})`,
+          alpha,
+        };
+      }
+    }
+    return {
+      name: `Translucent ${bestName} (${opacityPct}%)`,
+      hex,
+      displayValue: `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${alpha})`,
+      alpha,
+    };
+  }
+
+  return { name: bestName, hex, displayValue: hex };
+}
+
+/**
+ * Factory pour un nameColorUnique stateful (chaque générateur utilise sa propre map).
+ *
+ * @param cssVars - Optional default CSS custom properties for brand-aware semantic naming.
+ *   Each call to nameColorUnique can also pass its own cssVars to override.
+ */
+export function createColorNamer(defaultCssVars?: Record<string, string>) {
+  const usedColorNames = new Map<string, number>();
+  return {
+    nameColorUnique(color: string, cssVars?: Record<string, string>): NamedColorResult {
+      const result = nameColor(color, cssVars ?? defaultCssVars);
+      const count = usedColorNames.get(result.name) || 0;
+      usedColorNames.set(result.name, count + 1);
+      if (count > 0) {
+        result.name = `${result.name} (${result.hex})`;
+      }
+      return result;
+    },
+    reset() { usedColorNames.clear(); },
+  };
+}