react-native-terra-ui 0.7.2 → 0.8.1

package/src/utils/accent-generator.ts

@@ -0,0 +1,530 @@
+/**
+ * Pure, deterministic accent generation from a single seed color.
+ *
+ * Consumed by the resolver (`theme/resolve-config.ts`) for startup, runtime
+ * accent changes and `createTerraThemes`, and by the `normalizeAccent`
+ * compatibility wrapper. Must not import the registry, provider, Unistyles,
+ * or renderers — only `#theme/types` and the colour maths in `./color-utils`.
+ *
+ * ## Algorithm
+ *
+ * Every role is derived in OKLCH (Björn Ottosson's OKLab, in-house
+ * implementation in `./color-utils`): the seed's hue is kept for every role,
+ * chroma is capped per role and reduced further by sRGB gamut mapping, and
+ * perceptual lightness is *solved* per role against the scheme's actual
+ * ordinary surfaces so that WCAG 2.x targets are met (4.5:1 for text and
+ * solid/soft labels, 3:1 for the accent border). Contrast is evaluated with
+ * sRGB alpha compositing over each of the four surfaces and, for solid
+ * controls, additionally with the pressed opacity applied to the whole control.
+ *
+ * - `accent.solid.bg` keeps the seed exactly when black or white text reads on
+ *   it at both opacities; otherwise the fill is moved the smallest lightness
+ *   distance (ties prefer darker in light, lighter in dark) until a readable
+ *   label exists — so the fill MAY differ from the seed. Pin `accent.solid.bg`
+ *   through overrides for an exact fill.
+ * - `accent.solid.fg` is a tinted near-black or near-white (pure black/white
+ *   when the tint would not reach 4.5:1) picked by contrast, not brightness.
+ * - Hover/pressed fills darken in light and lighten in dark (mirroring the
+ *   built-in tokens); the direction flips only where following the scheme
+ *   would break the label contrast or leave the lightness range.
+ * - `accent.soft.bg` is a light tint in light / dark tint in dark, placed
+ *   relative to the surfaces; `accent.soft.fg` is solved on all three soft
+ *   states. `accent.text` (and `text.link`, the existing shorthand) is solved
+ *   on every surface; `accent.border` is solved to 3:1 on every surface.
+ * - Disabled fills are desaturated and low-contrast-but-visible, in the
+ *   spirit of the default `slate.200`/`slate.700`-like tokens.
+ *
+ * Unsatisfiable pairs (e.g. one very light and one very dark surface) are
+ * reported as `unsatisfied` diagnostics with the best deterministic colour
+ * kept; unparseable surfaces are excluded from solving and reported as
+ * `unsupported`. Nothing ever falls back to white silently.
+ *
+ */
+import type { CanonicalThemeColor, Scheme } from "#theme/types";
+import {
+  compositedContrast,
+  type OKLCH,
+  oklchToRgb,
+  parseColor,
+  type RGB,
+  type RGBA,
+  rgbToHex,
+  rgbToOklch,
+} from "./color-utils";
+
+/** Every canonical role a seed generates. `text.link` is kept for the existing shorthand behaviour. */
+export type GeneratedAccentRole =
+  | "accent.text"
+  | "accent.border"
+  | "accent.solid.bg"
+  | "accent.solid.bg.hover"
+  | "accent.solid.bg.pressed"
+  | "accent.solid.bg.disabled"
+  | "accent.solid.fg"
+  | "accent.soft.bg"
+  | "accent.soft.bg.hover"
+  | "accent.soft.bg.pressed"
+  | "accent.soft.bg.disabled"
+  | "accent.soft.fg"
+  | "text.link";
+
+export const GENERATED_ACCENT_ROLES: readonly GeneratedAccentRole[] = [
+  "accent.text",
+  "accent.border",
+  "accent.solid.bg",
+  "accent.solid.bg.hover",
+  "accent.solid.bg.pressed",
+  "accent.solid.bg.disabled",
+  "accent.solid.fg",
+  "accent.soft.bg",
+  "accent.soft.bg.hover",
+  "accent.soft.bg.pressed",
+  "accent.soft.bg.disabled",
+  "accent.soft.fg",
+  "text.link",
+];
+
+export type AccentSurfaceRole = "surface.canvas" | "surface.default" | "surface.raised" | "surface.sunken";
+
+/** The four ordinary surfaces every accent pair is evaluated over, in a fixed order. */
+export const ACCENT_SURFACE_ROLES: readonly AccentSurfaceRole[] = [
+  "surface.canvas",
+  "surface.default",
+  "surface.raised",
+  "surface.sunken",
+];
+
+/**
+ * The resolved scheme context a generator needs: the scheme's actual ordinary
+ * surfaces (after defaults, shared and scheme patches) and the opacity that
+ * components apply to a whole pressed control.
+ */
+export interface AccentGenerationContext {
+  scheme: Scheme;
+  surfaces: Record<AccentSurfaceRole, string>;
+  pressedOpacity: number;
+}
+
+/**
+ * `unsatisfied` — the pair was evaluated and fell below `required`.
+ * `unsupported` — a colour could not be evaluated (non-sRGB/opaque format);
+ * `ratio` is `null` and no accessibility claim is made.
+ */
+export type ContrastDiagnosticKind = "unsatisfied" | "unsupported";
+
+export interface ContrastDiagnostic {
+  kind: ContrastDiagnosticKind;
+  /** Foreground role checked, e.g. `accent.solid.fg` or `accent.text`. */
+  role: string;
+  /** Background role the foreground sits on, e.g. `accent.solid.bg` or `surface.canvas`. */
+  background: string;
+  /** Ordinary surface the pair was composited over. */
+  surface: AccentSurfaceRole;
+  /** Opacity applied to the whole control for this check (1 when none). */
+  opacity: number;
+  ratio: number | null;
+  required: number;
+  message: string;
+}
+
+export interface AccentGenerationResult {
+  colors: Record<GeneratedAccentRole, string>;
+  /** Pairs the generator could not satisfy or evaluate in the supported domain. */
+  diagnostics: ContrastDiagnostic[];
+}
+
+/** Whether `value` is an opaque six-digit sRGB hex seed (`#rrggbb`, case-insensitive). */
+export function isSupportedAccentSeed(value: unknown): value is string {
+  return typeof value === "string" && /^#[0-9a-f]{6}$/i.test(value.trim());
+}
+
+// ─── Targets and tuning ───────────────────────────────────────────────────────
+
+/** WCAG 2.x minimum for normal text and solid/soft labels. */
+export const ACCENT_TEXT_CONTRAST = 4.5;
+/** WCAG 2.x minimum for a meaningful accent boundary on an ordinary surface. */
+export const ACCENT_BORDER_CONTRAST = 3;
+
+/** Lightness resolution of the per-role solver (OKLCH L units). */
+const L_STEP = 0.005;
+
+type Direction = 1 | -1;
+
+interface SchemeTuning {
+  /** Scheme direction for hover/pressed and for role adjustments: darker in light, lighter in dark. */
+  dir: Direction;
+  /** Lightness step between the base fill and hover, and hover and pressed. */
+  solidStep: number;
+  /** Soft background lightness relative to the surfaces, with clamps. */
+  softBase: { offset: number; min: number; max: number };
+  /** Lightness step between soft base/hover/pressed (signed). */
+  softStep: number;
+  /** Chroma caps: soft tints stay pastel; disabled fills are near-neutral. */
+  softChroma: number;
+  solidDisabled: { l: number; c: number };
+  softDisabled: { l: number; c: number };
+  /** Tinted label lightness for the dark and light label polarity. */
+  darkLabelL: number;
+  lightLabelL: number;
+  /** Used to solve when no surface in the context can be evaluated. */
+  fallbackSurface: RGB;
+}
+
+const TUNING: Record<Scheme, SchemeTuning> = {
+  light: {
+    dir: -1,
+    solidStep: 0.06,
+    softBase: { offset: 0.01, min: 0.86, max: 0.965 },
+    softStep: -0.04,
+    softChroma: 0.08,
+    solidDisabled: { l: 0.93, c: 0.02 },
+    softDisabled: { l: 0.97, c: 0.01 },
+    darkLabelL: 0.15,
+    lightLabelL: 0.985,
+    fallbackSurface: { r: 255, g: 255, b: 255 },
+  },
+  dark: {
+    dir: 1,
+    solidStep: 0.06,
+    softBase: { offset: 0.03, min: 0.24, max: 0.5 },
+    softStep: 0.06,
+    softChroma: 0.06,
+    solidDisabled: { l: 0.4, c: 0.04 },
+    softDisabled: { l: 0.22, c: 0.01 },
+    darkLabelL: 0.15,
+    lightLabelL: 0.985,
+    fallbackSurface: { r: 0, g: 0, b: 0 },
+  },
+};
+
+const LABEL_CHROMA = 0.03;
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+const opaque = (rgb: RGB): RGBA => ({ ...rgb, a: 1 });
+
+/** OKLCH → sRGB rounded to the 0-255 grid, so scores match the emitted hex exactly. */
+const toRgb = (color: OKLCH): RGB => {
+  const rgb = oklchToRgb(color);
+  return { r: Math.round(rgb.r), g: Math.round(rgb.g), b: Math.round(rgb.b) };
+};
+
+/** A pressed opacity outside (0, 1] is not a usable multiplier; evaluate at 1 instead. */
+function normalizeOpacity(value: number): number {
+  return Number.isFinite(value) && value > 0 && value <= 1 ? value : 1;
+}
+
+/** Parses a surface as an opaque sRGB colour; translucent or unparseable surfaces are not evaluable. */
+function parseSurface(value: string): RGB | null {
+  const parsed = parseColor(value);
+  return parsed && parsed.a >= 1 ? parsed : null;
+}
+
+const clamp01 = (n: number): number => Math.max(0, Math.min(1, n));
+
+/** Rounds to the solver grid so equal inputs always visit identical candidates. */
+const snap = (l: number): number => Math.round(l / L_STEP) * L_STEP;
+
+/**
+ * Yields candidate lightness values starting at `start`: only in `dir` when
+ * `both` is false, otherwise alternating outward with `dir` visited first at
+ * each distance. Stops once every remaining candidate is outside [0, 1].
+ */
+function* lightnessCandidates(start: number, dir: Direction, both: boolean): Generator<number> {
+  const origin = clamp01(snap(start));
+  yield origin;
+  for (let k = 1; k <= Math.ceil(1 / L_STEP); k += 1) {
+    const forward = origin + dir * k * L_STEP;
+    const backward = origin - dir * k * L_STEP;
+    const forwardOk = forward >= -1e-9 && forward <= 1 + 1e-9;
+    const backwardOk = both && backward >= -1e-9 && backward <= 1 + 1e-9;
+    if (!forwardOk && !backwardOk) return;
+    if (forwardOk) yield clamp01(forward);
+    if (backwardOk) yield clamp01(backward);
+  }
+}
+
+interface Solved {
+  l: number;
+  rgb: RGB;
+  satisfied: boolean;
+}
+
+/**
+ * Finds the first candidate colour (hue/chroma fixed, lightness varied) whose
+ * `score` — min(ratio / required) over every pair it must satisfy — reaches 1.
+ * When nothing reaches 1, returns the best-scoring candidate (deterministic).
+ */
+function solveLightness(
+  base: Pick<OKLCH, "c" | "h">,
+  start: number,
+  dir: Direction,
+  both: boolean,
+  score: (rgb: RGB) => number
+): Solved {
+  let best: Solved | null = null;
+  let bestScore = Number.NEGATIVE_INFINITY;
+  for (const l of lightnessCandidates(start, dir, both)) {
+    const rgb = toRgb({ l, c: base.c, h: base.h });
+    const s = score(rgb);
+    if (s >= 1) return { l, rgb, satisfied: true };
+    if (s > bestScore) {
+      bestScore = s;
+      best = { l, rgb, satisfied: false };
+    }
+  }
+  return (
+    best ?? { l: clamp01(start), rgb: toRgb({ l: clamp01(start), c: base.c, h: base.h }), satisfied: false }
+  );
+}
+
+const min = (values: number[]): number =>
+  values.reduce((acc, v) => Math.min(acc, v), Number.POSITIVE_INFINITY);
+
+/** min over surfaces of contrast(fg on bg over surface) at each opacity, normalised by `required`. */
+function pairScore(fg: RGBA, bgs: RGBA[], surfaces: RGB[], opacities: number[], required: number): number {
+  const ratios: number[] = [];
+  for (const bg of bgs) {
+    for (const surface of surfaces) {
+      for (const opacity of opacities) ratios.push(compositedContrast(fg, bg, surface, opacity) / required);
+    }
+  }
+  return min(ratios);
+}
+
+/** Contrast of a standalone colour (text/border) against each surface, normalised by `required`. */
+function surfaceScore(color: RGB, surfaces: RGB[], required: number): number {
+  return min(
+    surfaces.map((surface) => compositedContrast(opaque(color), opaque(surface), surface, 1) / required)
+  );
+}
+
+// ─── Generation ───────────────────────────────────────────────────────────────
+
+/**
+ * Generates every {@link GeneratedAccentRole} for `seed` in the given scheme
+ * context. Pure and deterministic: same inputs → same output. Callers must
+ * validate the seed with {@link isSupportedAccentSeed} first.
+ */
+export function generateAccentColors(seed: string, context: AccentGenerationContext): AccentGenerationResult {
+  if (!isSupportedAccentSeed(seed)) {
+    throw new Error(
+      `generateAccentColors: unsupported seed ${JSON.stringify(seed)}; expected an opaque #rrggbb sRGB hex.`
+    );
+  }
+  const seedHex = seed.trim().toLowerCase();
+  const seedRgb = parseColor(seedHex) as RGBA;
+  const seedLch = rgbToOklch(seedRgb);
+  const tuning = TUNING[context.scheme];
+  const { dir } = tuning;
+  const pressedOpacity = normalizeOpacity(context.pressedOpacity);
+  const opacities = pressedOpacity < 1 ? [1, pressedOpacity] : [1];
+
+  const evaluable = ACCENT_SURFACE_ROLES.map((role) => parseSurface(context.surfaces[role])).filter(
+    (surface): surface is RGB => surface !== null
+  );
+  const surfaces = evaluable.length > 0 ? evaluable : [tuning.fallbackSurface];
+  const surfaceLs = surfaces.map((surface) => rgbToOklch(surface).l);
+
+  const hue = { c: seedLch.c, h: seedLch.h };
+  const black: RGBA = { r: 0, g: 0, b: 0, a: 1 };
+  const white: RGBA = { r: 255, g: 255, b: 255, a: 1 };
+
+  // ── Solid fill: keep the seed when black or white reads on it at every opacity.
+  const fillScore = (fill: RGB, fg: RGBA): number =>
+    pairScore(fg, [opaque(fill)], surfaces, opacities, ACCENT_TEXT_CONTRAST);
+  const readable = (fill: RGB): boolean => fillScore(fill, black) >= 1 || fillScore(fill, white) >= 1;
+
+  let fillRgb: RGB = seedRgb;
+  let fillL = seedLch.l;
+  if (!readable(seedRgb)) {
+    const solved = solveLightness(hue, seedLch.l, dir, true, (rgb) =>
+      Math.max(fillScore(rgb, black), fillScore(rgb, white))
+    );
+    fillRgb = solved.rgb;
+    fillL = solved.l;
+  }
+  const fillHex = fillRgb === seedRgb ? seedHex : rgbToHex(fillRgb);
+
+  // Label polarity by contrast, never by perceived brightness.
+  const polarity: "dark" | "light" =
+    fillScore(fillRgb, black) >= fillScore(fillRgb, white) ? "dark" : "light";
+  const pureLabel = polarity === "dark" ? black : white;
+
+  // ── Solid states: follow the scheme, flip when that would break the label or leave [0, 1].
+  const statesFor = (direction: Direction): RGB[] =>
+    [1, 2].map((k) => toRgb({ l: clamp01(fillL + direction * k * tuning.solidStep), c: hue.c, h: hue.h }));
+  const statesFit = (direction: Direction): boolean => {
+    const far = fillL + direction * 2 * tuning.solidStep;
+    return far >= 0.06 && far <= 0.94;
+  };
+  const statesReadable = (states: RGB[]): boolean =>
+    pairScore(pureLabel, states.map(opaque), surfaces, opacities, ACCENT_TEXT_CONTRAST) >= 1;
+
+  const statesOk = (direction: Direction): boolean =>
+    statesFit(direction) && statesReadable(statesFor(direction));
+  const flipped = -dir as Direction;
+  let stateDir: Direction = dir;
+  if (!statesOk(dir)) {
+    // Prefer a direction that keeps the label readable; otherwise at least stay in range.
+    if (statesOk(flipped) || (!statesFit(dir) && statesFit(flipped))) stateDir = flipped;
+  }
+  const [hoverRgb, pressedRgb] = statesFor(stateDir) as [RGB, RGB];
+  const solidBgs = [fillRgb, hoverRgb, pressedRgb].map(opaque);
+
+  // ── Solid label: tinted near-black/near-white when it still reads everywhere, else pure.
+  const tinted = opaque(
+    toRgb({
+      l: polarity === "dark" ? tuning.darkLabelL : tuning.lightLabelL,
+      c: Math.min(seedLch.c, LABEL_CHROMA),
+      h: seedLch.h,
+    })
+  );
+  const solidFg =
+    pairScore(tinted, solidBgs, surfaces, opacities, ACCENT_TEXT_CONTRAST) >= 1 ? tinted : pureLabel;
+
+  // ── Standalone text and border against every surface.
+  const text = solveLightness(hue, seedLch.l, dir, false, (rgb) =>
+    surfaceScore(rgb, surfaces, ACCENT_TEXT_CONTRAST)
+  );
+  const border = solveLightness(hue, seedLch.l, dir, false, (rgb) =>
+    surfaceScore(rgb, surfaces, ACCENT_BORDER_CONTRAST)
+  );
+
+  // ── Soft tint relative to the surfaces, with its own solved foreground.
+  const softAnchor = dir === -1 ? min(surfaceLs) : Math.max(...surfaceLs);
+  const softL = Math.max(
+    tuning.softBase.min,
+    Math.min(tuning.softBase.max, softAnchor + tuning.softBase.offset)
+  );
+  const softChroma = Math.min(seedLch.c, tuning.softChroma);
+  const softBgs = [0, 1, 2].map((k) =>
+    toRgb({ l: clamp01(softL + k * tuning.softStep), c: softChroma, h: seedLch.h })
+  );
+  const softFg = solveLightness(hue, text.l, dir, false, (rgb) =>
+    pairScore(opaque(rgb), softBgs.map(opaque), surfaces, [1], ACCENT_TEXT_CONTRAST)
+  );
+
+  // ── Disabled: desaturated, low-contrast-but-visible.
+  const solidDisabled = toRgb({
+    l: tuning.solidDisabled.l,
+    c: Math.min(seedLch.c, tuning.solidDisabled.c),
+    h: seedLch.h,
+  });
+  const softDisabled = toRgb({
+    l: tuning.softDisabled.l,
+    c: Math.min(seedLch.c, tuning.softDisabled.c),
+    h: seedLch.h,
+  });
+
+  const textHex = rgbToHex(text.rgb);
+  const colors: Record<GeneratedAccentRole, string> = {
+    "accent.text": textHex,
+    "accent.border": rgbToHex(border.rgb),
+    "accent.solid.bg": fillHex,
+    "accent.solid.bg.hover": rgbToHex(hoverRgb),
+    "accent.solid.bg.pressed": rgbToHex(pressedRgb),
+    "accent.solid.bg.disabled": rgbToHex(solidDisabled),
+    "accent.solid.fg": rgbToHex(solidFg),
+    "accent.soft.bg": rgbToHex(softBgs[0] as RGB),
+    "accent.soft.bg.hover": rgbToHex(softBgs[1] as RGB),
+    "accent.soft.bg.pressed": rgbToHex(softBgs[2] as RGB),
+    "accent.soft.bg.disabled": rgbToHex(softDisabled),
+    "accent.soft.fg": rgbToHex(softFg.rgb),
+    "text.link": textHex,
+  };
+
+  return { colors, diagnostics: checkAccentContrast(colors, context) };
+}
+
+// ─── Diagnostics ──────────────────────────────────────────────────────────────
+
+interface ContrastPair {
+  role: GeneratedAccentRole;
+  /** A generated role used as background, or the surface itself. */
+  background: GeneratedAccentRole | "surface";
+  opacity: number;
+  required: number;
+}
+
+function contrastPairs(pressedOpacity: number): ContrastPair[] {
+  const pairs: ContrastPair[] = [];
+  const opacities = pressedOpacity < 1 ? [1, pressedOpacity] : [1];
+  for (const background of ["accent.solid.bg", "accent.solid.bg.hover", "accent.solid.bg.pressed"] as const) {
+    for (const opacity of opacities) {
+      pairs.push({ role: "accent.solid.fg", background, opacity, required: ACCENT_TEXT_CONTRAST });
+    }
+  }
+  for (const background of ["accent.soft.bg", "accent.soft.bg.hover", "accent.soft.bg.pressed"] as const) {
+    pairs.push({ role: "accent.soft.fg", background, opacity: 1, required: ACCENT_TEXT_CONTRAST });
+  }
+  pairs.push({ role: "accent.text", background: "surface", opacity: 1, required: ACCENT_TEXT_CONTRAST });
+  pairs.push({ role: "text.link", background: "surface", opacity: 1, required: ACCENT_TEXT_CONTRAST });
+  pairs.push({ role: "accent.border", background: "surface", opacity: 1, required: ACCENT_BORDER_CONTRAST });
+  return pairs;
+}
+
+const show = (value: unknown): string => (typeof value === "string" ? JSON.stringify(value) : String(value));
+
+/**
+ * Evaluates the final accent roles (after explicit overrides) against their
+ * intended backgrounds in the supported domain and returns the failing or
+ * unevaluable pairs. Never repairs a colour.
+ */
+export function checkAccentContrast(
+  colors: Pick<CanonicalThemeColor, GeneratedAccentRole>,
+  context: AccentGenerationContext
+): ContrastDiagnostic[] {
+  const diagnostics: ContrastDiagnostic[] = [];
+  const pairs = contrastPairs(normalizeOpacity(context.pressedOpacity));
+  const values = colors as unknown as Record<string, unknown>;
+
+  for (const surfaceRole of ACCENT_SURFACE_ROLES) {
+    const surfaceValue = context.surfaces[surfaceRole];
+    const surface = parseSurface(surfaceValue);
+
+    for (const pair of pairs) {
+      const backgroundRole = pair.background === "surface" ? surfaceRole : pair.background;
+      const where = `${pair.role} on ${backgroundRole} over ${surfaceRole} at opacity ${pair.opacity}`;
+      const fgValue = values[pair.role];
+      const fg = parseColor(fgValue);
+      const bgValue = pair.background === "surface" ? surfaceValue : values[pair.background];
+      const bg = pair.background === "surface" ? (surface ? opaque(surface) : null) : parseColor(bgValue);
+
+      const unsupported: string[] = [];
+      if (!surface) unsupported.push(`${surfaceRole} ${show(surfaceValue)} is not an opaque sRGB colour`);
+      if (!fg) unsupported.push(`${pair.role} ${show(fgValue)} is not an sRGB colour`);
+      if (!bg && pair.background !== "surface") {
+        unsupported.push(`${pair.background} ${show(bgValue)} is not an sRGB colour`);
+      }
+      if (!surface || !fg || !bg) {
+        diagnostics.push({
+          kind: "unsupported",
+          role: pair.role,
+          background: backgroundRole,
+          surface: surfaceRole,
+          opacity: pair.opacity,
+          ratio: null,
+          required: pair.required,
+          message: `${where} cannot be evaluated: ${unsupported.join("; ")}.`,
+        });
+        continue;
+      }
+
+      const ratio = compositedContrast(fg, bg, surface, pair.opacity);
+      if (ratio < pair.required) {
+        diagnostics.push({
+          kind: "unsatisfied",
+          role: pair.role,
+          background: backgroundRole,
+          surface: surfaceRole,
+          opacity: pair.opacity,
+          ratio,
+          required: pair.required,
+          message: `${where} is ${ratio.toFixed(2)}:1, below the ${pair.required}:1 target.`,
+        });
+      }
+    }
+  }
+  return diagnostics;
+}

package/src/utils/accent-utils.ts

@@ -1,49 +1,76 @@
-import type { Accent, AccentShorthand, NormalizedAccent, TerraTheme } from "#theme/types";
-import { readableOn, shade, withAlpha } from "./color-utils";
+import { normalizeTokenOverride } from "#theme/legacy-tokens";
+import { normalizeAccentScheme } from "#theme/resolve-config";
+import { defaultDarkTheme, defaultLightTheme } from "#theme/theme";
+import type {
+  Accent,
+  AccentSchemeInput,
+  NormalizedAccent,
+  Scheme,
+  TerraTheme,
+  ThemeColor,
+} from "#theme/types";
+import {
+  ACCENT_SURFACE_ROLES,
+  type AccentGenerationContext,
+  type AccentSurfaceRole,
+  generateAccentColors,
+} from "./accent-generator";
 import type { DeepPartial } from "./deep-merge";
 
-const isShorthand = (accent: Accent): accent is AccentShorthand =>
-  typeof (accent as AccentShorthand).light === "string" ||
-  typeof (accent as AccentShorthand).dark === "string";
+/**
+ * The generation context of a built-in default theme: its four ordinary
+ * surfaces and pressed opacity. Used by the {@link normalizeAccent}
+ * compatibility wrapper, which has no access to shared/scheme patches.
+ */
+export function defaultAccentContext(scheme: Scheme): AccentGenerationContext {
+  const theme = scheme === "light" ? defaultLightTheme : defaultDarkTheme;
+  const surfaces = {} as Record<AccentSurfaceRole, string>;
+  for (const role of ACCENT_SURFACE_ROLES) surfaces[role] = theme.color[role];
+  return { scheme, surfaces, pressedOpacity: theme.opacity.pressed };
+}
 
 /**
- * Expands a single hue into a fuller per-scheme patch so primary AND subtle
- * actions (plus accent text) all recolor consistently:
- * - primary: solid hue with derived hover/active and a legible foreground,
- * - subtle: soft translucent tint of the hue with the hue as foreground,
- * - text.accent / text.link / text.on-accent.
- *
- * On `light` the hover/active darken; on `dark` they lighten.
+ * Generated accent colours for `seed` with `overrides` applied last. Within
+ * the override patch canonical names beat their legacy aliases, while an
+ * alias-only key still beats the generated canonical value.
  */
-function hueToPartial(hue: string | undefined, scheme: "light" | "dark"): DeepPartial<TerraTheme> {
-  if (!hue) return {};
-  const dir = scheme === "light" ? -1 : 1;
-  const isLight = scheme === "light";
-  const fg = readableOn(hue);
-  // Flat color keys to patch — deepMerge replaces string leaves directly.
-  const color = {
-    "action.bg.primary": hue,
-    "action.fg.primary": fg,
-    "action.bg.primary.hover": shade(hue, dir * 0.12),
-    "action.bg.primary.active": shade(hue, dir * 0.24),
-    "action.bg.primary.subtle": withAlpha(hue, isLight ? 0.12 : 0.2),
-    "action.fg.primary.subtle": hue,
-    "action.bg.primary.subtle.hover": withAlpha(hue, isLight ? 0.18 : 0.28),
-    "action.bg.primary.subtle.active": withAlpha(hue, isLight ? 0.24 : 0.36),
-    "text.accent": hue,
-    "text.link": hue,
-    "text.on-accent": fg,
-  };
+function seedToColorPatch(
+  seed: string,
+  overrides: Partial<ThemeColor> | undefined,
+  scheme: Scheme
+): DeepPartial<TerraTheme> {
+  const generated = generateAccentColors(seed, defaultAccentContext(scheme)).colors;
+  const color: Record<string, string> = { ...generated };
+  const normalized = normalizeTokenOverride({ color: overrides })?.color;
+  if (normalized) {
+    for (const [key, value] of Object.entries(normalized)) {
+      if (value !== undefined) color[key] = value as string;
+    }
+  }
   return { color } as unknown as DeepPartial<TerraTheme>;
 }
 
-/** Normalizes any accent input into per-scheme partial-theme overrides. */
-export function normalizeAccent(accent: Accent): NormalizedAccent {
-  if (isShorthand(accent)) {
-    return {
-      light: hueToPartial(accent.light, "light"),
-      dark: hueToPartial(accent.dark, "dark"),
-    };
+function normalizeSchemeInput(input: AccentSchemeInput | undefined, scheme: Scheme): DeepPartial<TerraTheme> {
+  const normalized = normalizeAccentScheme(input, `accents.<accent>.${scheme}`);
+  if (normalized.kind === "none") return {};
+  if (normalized.kind === "seed") {
+    return seedToColorPatch(normalized.seed, normalized.overrides, scheme);
   }
-  return { light: accent.light ?? {}, dark: accent.dark ?? {} };
+  // Preserve the compatibility helper's identity contract for full patches;
+  // the resolver itself uses the sanitized copy in `normalized.patch`.
+  return input as DeepPartial<TerraTheme>;
+}
+
+/**
+ * Compatibility wrapper: normalizes any accent input into per-scheme
+ * partial-theme overrides. Strings and `{ seed, overrides }` are generated
+ * against the DEFAULT themes' surfaces and pressed opacity (the resolver
+ * pipeline uses the actual resolved surfaces instead); full theme patches
+ * pass through unchanged. Pure and independent of the registry.
+ */
+export function normalizeAccent(accent: Accent): NormalizedAccent {
+  return {
+    light: normalizeSchemeInput(accent.light, "light"),
+    dark: normalizeSchemeInput(accent.dark, "dark"),
+  };
 }