@multiplatform.one/theme 7.69.2 → 7.71.0

package/src/theme/dedupeInherited.spec.ts

@@ -0,0 +1,160 @@
+/**
+ * LC-160: the theme matrix ships each value once per rule that needs it.
+ * `createTamagui` is mocked pass-through so `config.tamagui.themes` is the
+ * deduped record the CSS is built from.
+ */
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("tamagui", () => ({
+  createTamagui: vi.fn((config: Record<string, unknown>) => config),
+}));
+vi.mock("./animations/index", () => ({ animations: {} }));
+
+import { createDefaultThemeConfig } from "./createDefaultThemeConfig";
+import { createThemesBuilder } from "./createThemes";
+import {
+  dedupeInheritedThemeValues,
+  parentThemeNames,
+  resolveAllThemes,
+  resolveThemeThroughParents,
+} from "./dedupeInherited";
+import { defaultAccentTheme, defaultBaseTheme, defaultBuilderOptions } from "./defaults";
+
+type Themes = Record<string, Record<string, unknown>>;
+
+const deduped = createDefaultThemeConfig().tamagui.themes as unknown as Themes;
+const built = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as unknown as Themes;
+
+/** Names whose rules declare keys on an element rendered in `name`: its non-root chain and itself. */
+function declaringChain(name: string): string[] {
+  return [...parentThemeNames(name).slice(1), name];
+}
+
+describe("parentThemeNames", () => {
+  it("walks the chain the way proxyThemeToParents does, nearest last", () => {
+    expect(parentThemeNames("dark_blue_alt1_Button")).toEqual([
+      "dark",
+      "dark_blue",
+      "dark_blue_alt1",
+    ]);
+    expect(parentThemeNames("light")).toEqual([]);
+  });
+});
+
+describe("dedupeInheritedThemeValues", () => {
+  it("drops a key the nearest non-root ancestor keeps with the same value", () => {
+    const out = dedupeInheritedThemeValues({
+      light: { a: "1", b: "1" },
+      light_blue: { a: "2", b: "1" },
+      light_blue_Button: { a: "2", b: "1", c: "3" },
+    });
+    expect(out.light_blue_Button).toEqual({ c: "3" });
+    expect(out.light_blue).toEqual({ a: "2" });
+  });
+
+  it("keeps a root-valued key some other branch overrides (a Button inside a Card)", () => {
+    const out = dedupeInheritedThemeValues({
+      light: { borderColor: "#ccc" },
+      light_Card: { borderColor: "#eee" },
+      light_Button: { borderColor: "#ccc" },
+      dark: { borderColor: "#333" },
+    });
+    expect(out.light_Button).toEqual({ borderColor: "#ccc" });
+  });
+
+  it("keeps a root-valued key the other scheme's sibling rule declares (nested schemes)", () => {
+    const out = dedupeInheritedThemeValues({
+      light: { a: "1" },
+      light_Button: { a: "1" },
+      dark: { a: "9" },
+      dark_Button: { a: "8" },
+    });
+    expect(out.light_Button).toEqual({ a: "1" });
+  });
+
+  it("drops a key no non-root theme in either scheme moves off its root", () => {
+    const out = dedupeInheritedThemeValues({
+      light: { red5: "#f00" },
+      light_blue: { red5: "#f00" },
+      light_blue_Button: { red5: "#f00" },
+      dark: { red5: "#900" },
+      dark_blue: { red5: "#900" },
+    });
+    expect(out.light_blue).toEqual({});
+    expect(out.light_blue_Button).toEqual({});
+    expect(out.dark_blue).toEqual({});
+  });
+
+  it("does not depend on the record's order", () => {
+    const themes = {
+      light_blue_Button: { a: "2" },
+      light_blue: { a: "2" },
+      light: { a: "1" },
+    };
+    expect(dedupeInheritedThemeValues(themes)).toEqual(
+      dedupeInheritedThemeValues({
+        light: themes.light,
+        light_blue: themes.light_blue,
+        light_blue_Button: themes.light_blue_Button,
+      }),
+    );
+  });
+});
+
+describe("the default config ships deduped themes", () => {
+  it("resolves every theme to exactly what the builder's own themes resolve to", () => {
+    expect(Object.keys(deduped).sort()).toEqual(Object.keys(built).sort());
+    expect(resolveAllThemes(deduped)).toEqual(resolveAllThemes(built));
+  });
+
+  it("drops declarations, never whole themes", () => {
+    const count = (themes: Themes) =>
+      Object.values(themes).reduce((sum, theme) => sum + Object.keys(theme).length, 0);
+    expect(count(deduped)).toBeLessThan(count(built));
+    expect(deduped.light).toEqual(built.light);
+    expect(deduped.dark).toEqual(built.dark);
+  });
+
+  // The web hazard SHC's parent-chain rule has: a key no rule on the element
+  // declares is inherited from whatever ancestor element is nearest, so it
+  // must read the same in every theme of the scheme, and no rule of the other
+  // scheme may declare it on the element through a nested-scheme selector.
+  it("leaves every undeclared key reading the same from any ancestor theme", () => {
+    const names = Object.keys(deduped).filter((name) => name.includes("_"));
+    const valuesInScheme = new Map<string, Set<unknown>>();
+    for (const name of names) {
+      const scheme = name.split("_")[0];
+      for (const [key, value] of Object.entries(built[name] ?? {})) {
+        const slot = `${scheme}:${key}`;
+        if (!valuesInScheme.has(slot)) valuesInScheme.set(slot, new Set());
+        valuesInScheme.get(slot)?.add(value);
+      }
+    }
+    const hazards: string[] = [];
+    for (const name of names) {
+      const scheme = name.split("_")[0] as string;
+      const other = scheme === "light" ? "dark" : "light";
+      const resolved = resolveThemeThroughParents(deduped, name);
+      const declared = new Set(declaringChain(name).flatMap((n) => Object.keys(deduped[n] ?? {})));
+      // Keys the builder already left to inheritance are not this dedupe's.
+      const builtDeclared = new Set(
+        declaringChain(name).flatMap((n) => Object.keys(built[n] ?? {})),
+      );
+      const siblings = declaringChain(`${other}${name.slice(scheme.length)}`);
+      for (const key of Object.keys(resolved)) {
+        if (declared.has(key) || !builtDeclared.has(key)) continue;
+        const values = valuesInScheme.get(`${scheme}:${key}`) ?? new Set();
+        if ([...values].some((value) => value !== resolved[key])) hazards.push(`${name}.${key}`);
+        for (const sibling of siblings) {
+          if (deduped[sibling] && key in deduped[sibling])
+            hazards.push(`${sibling}.${key} over ${name}`);
+        }
+      }
+    }
+    expect(hazards).toEqual([]);
+  });
+});

package/src/theme/dedupeInherited.ts

@@ -0,0 +1,117 @@
+/**
+ * Drop theme values that another rule already puts on the element (LC-160).
+ *
+ * Ported from SHC (`shc/packages/themes/dedupeInherited.ts`), which measured
+ * every theme rule restating keys its parent chain carries. MPO's builder
+ * restates fewer of them, and SHC's rule is not safe on web as written, so
+ * this keeps the subset that cannot change a resolved value.
+ *
+ * JS and native are never at risk: `createTamagui` runs
+ * `proxyThemesToParents`, which `Object.assign`s every ancestor onto each
+ * theme before anything reads it. CSS is the consumer that needs care. A
+ * themed element carries its theme's whole hierarchy as classes
+ * (`light_blue_Button` puts `t_blue t_blue_Button` on the Button), so a key
+ * dropped from `light_blue_Button` and kept by `light_blue` is still declared
+ * on that same element. A key every non-root rule drops is different: it
+ * reaches the element by inheritance from the nearest ANCESTOR element that
+ * declares it, and that ancestor need not be in the theme's name chain. A
+ * Button inside a Card resolves `light_Button`, but its nearest ancestor is
+ * the Card's `light_Card`; nested schemes add `dark_*` rules that match the
+ * element through `.t_dark .t_X` selectors. SHC's parent-chain rule drops
+ * those keys anyway, which repaints a Button's root-valued key with its
+ * Card's.
+ *
+ * So a key is dropped from a non-root theme only when:
+ *
+ * - the nearest non-root theme in its own chain keeps the key with the same
+ *   value (declared on the same element), or
+ * - no non-root theme in either scheme gives the key a value other than its
+ *   scheme root's, so whatever ancestor the element inherits from, it reads
+ *   the root value, and no other rule declares it.
+ *
+ * Resolution reads the input and the already-pruned shallower themes, so the
+ * result does not depend on the record's iteration order.
+ */
+
+type ThemeValues = Record<string, unknown>;
+
+/**
+ * Ancestor names of `dark_blue_alt1_Button`, nearest last:
+ * `["dark", "dark_blue", "dark_blue_alt1"]`. The same walk as Tamagui's
+ * `proxyThemeToParents`; the two must agree or a dropped key would not come
+ * back on the JS side.
+ */
+export function parentThemeNames(name: string): string[] {
+  const parts = name.split("_");
+  const parents: string[] = [];
+  for (let i = 1; i < parts.length; i++) parents.push(parts.slice(0, i).join("_"));
+  return parents;
+}
+
+/** Keys some non-root theme sets to a value other than its scheme root's. */
+function keysThatLeaveTheRoot(themes: Record<string, ThemeValues>): Set<string> {
+  const leaving = new Set<string>();
+  for (const [name, theme] of Object.entries(themes)) {
+    const root = themes[name.split("_")[0] ?? ""];
+    if (!root || root === theme) continue;
+    for (const [key, value] of Object.entries(theme)) {
+      if (root[key] !== value) leaving.add(key);
+    }
+  }
+  return leaving;
+}
+
+/** Each non-root theme without the values another rule already puts on its element. */
+export function dedupeInheritedThemeValues<T extends ThemeValues>(
+  themes: Record<string, T>,
+): Record<string, T> {
+  const leaving = keysThatLeaveTheRoot(themes);
+  const byDepth = Object.keys(themes).sort((a, b) => a.split("_").length - b.split("_").length);
+  const pruned: Record<string, ThemeValues> = {};
+  for (const name of byDepth) {
+    const theme = themes[name] as ThemeValues;
+    const parents = parentThemeNames(name);
+    if (parents.length === 0) {
+      pruned[name] = theme;
+      continue;
+    }
+    const root = themes[parents[0] as string];
+    const nonRoot = parents.slice(1).reverse();
+    const kept: ThemeValues = {};
+    for (const [key, value] of Object.entries(theme)) {
+      const holder = nonRoot.find((parent) => pruned[parent] && key in pruned[parent]);
+      if (holder) {
+        if (pruned[holder]?.[key] !== value) kept[key] = value;
+        continue;
+      }
+      if (root?.[key] === value && !leaving.has(key)) continue;
+      kept[key] = value;
+    }
+    pruned[name] = kept;
+  }
+  return Object.fromEntries(Object.keys(themes).map((name) => [name, pruned[name] as T]));
+}
+
+/**
+ * One theme as Tamagui resolves it: every ancestor, then the theme itself.
+ * Use it to read a key off a deduped record; `getConfig().themes` and
+ * `themeConfig.tamagui.themes` come out of `createTamagui` already resolved.
+ */
+export function resolveThemeThroughParents<T extends ThemeValues>(
+  themes: Record<string, T>,
+  name: string,
+): T {
+  const out: ThemeValues = {};
+  for (const parent of parentThemeNames(name)) Object.assign(out, themes[parent]);
+  Object.assign(out, themes[name]);
+  return out as T;
+}
+
+/** Every theme of a deduped record resolved through its parents. */
+export function resolveAllThemes<T extends ThemeValues>(
+  themes: Record<string, T>,
+): Record<string, T> {
+  return Object.fromEntries(
+    Object.keys(themes).map((name) => [name, resolveThemeThroughParents(themes, name)]),
+  );
+}

package/src/theme/defaults/builderOptions.ts

@@ -123,7 +123,7 @@ function getBaseTheme(theme: Record<string, string>) {
     // The v5 makeSurface templates own the interaction ramp and borders.
     // No ramp step is pinned here; only semantic aliases are added.
     textMuted: pickSecondaryInk(theme),
-    textSubtle: theme.color6,
+    textSubtle: theme.color10,
     borderStrong: theme.color7,
     borderStrongHover: theme.color8,
     borderStrongPress: theme.color6,

package/src/theme/fillContrast.spec.ts

@@ -0,0 +1,204 @@
+/**
+ * LC-172 FILL-CONTRAST, as a ratchet. Every preset MPO ships (the catalog's
+ * and the app presets in packages/themes) is audited: its filled accent
+ * control, active toggle and first chart series carry a hue, the label on
+ * the filled control clears APCA Lc 60, the off toggle track is HIG's
+ * light system fill and stays clearly apart from the on track, and a fill on a track (Slider, Progress) clears 3:1 on its
+ * rail. There is no baseline: every preset passes outright, so
+ * no preset can ship an achromatic accent.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("tamagui", () => ({
+  createTamagui: vi.fn((config: Record<string, unknown>) => config),
+}));
+vi.mock("./animations/index", () => ({ animations: {} }));
+
+import {
+  aaTextContrastRatio,
+  contrastRatio,
+  fillLabelLc,
+  inSwitchOffBand,
+  normalizeToHex,
+  relativeLuminance,
+} from "./colorRules";
+import { createDefaultThemeConfig } from "./createDefaultThemeConfig";
+import { resolveAllThemes } from "./dedupeInherited";
+import {
+  apcaContrast,
+  auditPresetFills,
+  oklabDistance,
+  srgbChroma,
+  toggleStateFloor,
+} from "./fillContrast";
+import {
+  boldPreset,
+  consolePreset,
+  defaultPreset,
+  densePreset,
+  heroPreset,
+  roomyPreset,
+  storefrontPreset,
+} from "./presets";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "../../../..");
+
+/** The app presets' colour themes, read from source: public/theme cannot import @package/themes. */
+function appPresetThemes(): Record<string, string> {
+  const source = readFileSync(join(repoRoot, "packages/themes/presets.ts"), "utf8");
+  const out: Record<string, string> = {};
+  for (const block of source.split(/export const /).slice(1)) {
+    const name = block.match(/^(\w+)Preset\b/)?.[1];
+    if (!name) continue;
+    out[name] = block.match(/\btheme:\s*"([^"]*)"/)?.[1] ?? "";
+  }
+  return out;
+}
+
+const presetThemes: Record<string, string> = {
+  default: defaultPreset.theme,
+  hero: heroPreset.theme,
+  bold: boldPreset.theme,
+  dense: densePreset.theme,
+  roomy: roomyPreset.theme,
+  console: consolePreset.theme,
+  storefront: storefrontPreset.theme,
+  ...appPresetThemes(),
+};
+
+const resolved = resolveAllThemes(
+  createDefaultThemeConfig().tamagui.themes as unknown as Record<string, Record<string, unknown>>,
+);
+
+describe("LC-172 APCA and chroma measures", () => {
+  it("reads grey and black as chroma 0 and a Radix solid as a hue", () => {
+    expect(srgbChroma("#202020")).toBe(0);
+    expect(srgbChroma("hsla(0, 0%, 45%, 1)")).toBe(0);
+    expect(srgbChroma("#8e4ec6")).toBeGreaterThan(0.1);
+  });
+
+  it("holds the off toggle to HIG's system-fill band", () => {
+    // UISwitch's off track, rgba(120,120,128,0.16) over white and 0.32 over black.
+    expect(inSwitchOffBand("#e9e9eb", "#ffffff")).toBe(true);
+    expect(inSwitchOffBand("#262629", "#000000")).toBe(true);
+    // The round-2 console track and the old gray10 read as on beside a hue fill.
+    expect(inSwitchOffBand("#202020", "#ffffff")).toBe(false);
+    expect(inSwitchOffBand("#838383", "#f7f7f7")).toBe(false);
+    expect(inSwitchOffBand("#000000", "#000000")).toBe(false);
+  });
+
+  it("tells the on track from the off track by colour, not only by the thumb", () => {
+    // UIKit's own pairs over systemFill clear the floor; systemYellow on white is the closest.
+    expect(oklabDistance("#34c759", "#e9e9eb")).toBeGreaterThan(toggleStateFloor);
+    expect(oklabDistance("#ffcc00", "#e9e9eb")).toBeGreaterThan(toggleStateFloor);
+    expect(oklabDistance("#0a84ff", "#262629")).toBeGreaterThan(toggleStateFloor);
+    // FZ-8117 on main: default dark painted an rgb 115 grey on track beside an rgb 121 off track.
+    expect(oklabDistance("#737373", "#797979")).toBeLessThan(toggleStateFloor);
+  });
+
+  it("matches APCA's published reference pairs", () => {
+    expect(apcaContrast("#888888", "#ffffff")).toBeCloseTo(63.06, 1);
+    expect(apcaContrast("#ffffff", "#888888")).toBeCloseTo(-68.54, 1);
+    expect(apcaContrast("#000000", "#aaaaaa")).toBeCloseTo(58.15, 1);
+    expect(apcaContrast("#aaaaaa", "#000000")).toBeCloseTo(-56.24, 1);
+  });
+});
+
+describe("LC-172 FILL-CONTRAST every preset's fills carry a hue and a readable label", () => {
+  it("covers the catalog and the app presets", () => {
+    expect(Object.keys(presetThemes)).toEqual(
+      expect.arrayContaining(["default", "console", "storefront", "studio", "ocean", "slate"]),
+    );
+  });
+
+  for (const [preset, theme] of Object.entries(presetThemes)) {
+    it(`${preset} (${theme || "house accent"}) paints hued fills and a light off toggle`, () => {
+      expect(auditPresetFills(preset, theme, resolved)).toEqual([]);
+    });
+  }
+});
+
+describe("LC-172 the engine keeps every off toggle in the HIG band, a preset's or a user's pick", () => {
+  // The page grounds a Switch sits on: the inverse _accent and the _active press
+  // surfaces are control fills, not grounds.
+  const scopes = Object.keys(resolved).filter(
+    (name) => /^(light|dark)(_[a-z]+)?$/.test(name) && !/_(accent|active)$/.test(name),
+  );
+
+  it("covers both schemes and every hue", () => {
+    expect(scopes.length).toBeGreaterThanOrEqual(18);
+  });
+
+  for (const name of scopes) {
+    it(`${name}: the off track sits in the system-fill band over the page`, () => {
+      const off = String(resolved[name].switchTrackOff);
+      const ground = String(resolved[name].background);
+      expect(inSwitchOffBand(off, ground), `${off} on ${ground}`).toBe(true);
+    });
+  }
+});
+
+describe("LC-172 the engine keeps every on track clearly apart from its off track", () => {
+  const scopes = Object.keys(resolved).filter(
+    (name) => /^(light|dark)(_[a-z]+)?$/.test(name) && !/_(accent|active)$/.test(name),
+  );
+
+  for (const name of scopes) {
+    it(`${name}: on and off tracks differ by colour, not only by the thumb`, () => {
+      const on = String(resolved[name].accentBackground);
+      const off = String(resolved[name].switchTrackOff);
+      expect(oklabDistance(on, off), `${on} / ${off}`).toBeGreaterThanOrEqual(toggleStateFloor);
+    });
+  }
+});
+
+describe("LC-172 the engine holds every hue's accent solid, a preset's or a user's pick", () => {
+  const solids = Object.keys(resolved).filter((name) => /^(light|dark)_[a-z]+_accent$/.test(name));
+
+  it("builds a solid per hue and scheme", () => {
+    expect(solids.length).toBeGreaterThanOrEqual(16);
+  });
+
+  for (const name of solids) {
+    it(`${name}: the label clears WCAG AA 4.5 and APCA Lc 60 on the fill`, () => {
+      const fill = normalizeToHex(String(resolved[name].background));
+      const label = normalizeToHex(String(resolved[name].color));
+      expect(fill && label, name).toBeTruthy();
+      const ratio = contrastRatio(
+        relativeLuminance(fill as string),
+        relativeLuminance(label as string),
+      );
+      expect(ratio).toBeGreaterThanOrEqual(aaTextContrastRatio);
+      expect(Math.abs(apcaContrast(label as string, fill as string))).toBeGreaterThanOrEqual(
+        fillLabelLc,
+      );
+    });
+  }
+});
+
+describe("LC-172 non-text fills on a track clear WCAG 1.4.11 3:1, every preset and scheme", () => {
+  // Slider and Progress paint formSelectedColors.trackFill ($accentColor) on
+  // formControlColors.background ($color5), or on the page when outlined.
+  const nonTextFloor = 3;
+  const ratio = (a: unknown, b: unknown) => {
+    const x = normalizeToHex(String(a));
+    const y = normalizeToHex(String(b));
+    expect(x && y, `${String(a)} / ${String(b)}`).toBeTruthy();
+    return contrastRatio(relativeLuminance(x as string), relativeLuminance(y as string));
+  };
+
+  for (const [preset, theme] of Object.entries(presetThemes)) {
+    for (const scheme of ["light", "dark"] as const) {
+      const name = theme ? `${scheme}_${theme}` : scheme;
+      it(`${preset} ${scheme}: the track fill holds 3:1 on its rail and on the page`, () => {
+        const scope = resolved[name];
+        expect(scope, name).toBeDefined();
+        expect(ratio(scope.accentColor, scope.color5)).toBeGreaterThanOrEqual(nonTextFloor);
+        expect(ratio(scope.accentColor, scope.background)).toBeGreaterThanOrEqual(nonTextFloor);
+      });
+    }
+  }
+});

package/src/theme/fillContrast.ts

@@ -0,0 +1,163 @@
+import { accentIdentityCandidates, resolveChartPalette } from "./chartPalette";
+import { apcaContrast, fillLabelLc, inSwitchOffBand, normalizeToHex } from "./colorRules";
+import { tintHueNames } from "./createThemes";
+
+export { apcaContrast };
+
+/**
+ * LC-172 FILL-CONTRAST. A preset's fills carry a hue: the filled accent
+ * control, the active toggle track and the first chart series are never grey
+ * or black on the grey and white grounds, and the label on the filled
+ * control passes APCA Lc 60. The off toggle track is HIG's light system fill,
+ * never a grey darker than systemFill on a light ground (`inSwitchOffBand`),
+ * and the on and off tracks sit at least `toggleStateFloor` apart in OKLab.
+ */
+
+/** sRGB chroma (max channel minus min channel, 0..1) under which a fill reads as grey or black. */
+export const fillChromaFloor = 0.1;
+
+/** APCA |Lc| the label on a filled control must reach. */
+export const fillLabelLcFloor = fillLabelLc;
+
+function channels(hex: string): [number, number, number] {
+  return [1, 3, 5].map((offset) => Number.parseInt(hex.slice(offset, offset + 2), 16) / 255) as [
+    number,
+    number,
+    number,
+  ];
+}
+
+/**
+ * OKLab distance the on and off toggle tracks must keep, so a Switch's state
+ * reads from its track and not only from the thumb's side. UIKit's least
+ * distinct pair, systemYellow on the light off fill, measures 0.19; the
+ * FZ-8117 default dark pair (an rgb 115 grey on an rgb 121 grey) measured 0.02.
+ */
+export const toggleStateFloor = 0.15;
+
+const linear = (channel: number) =>
+  channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+
+/** Björn Ottosson's OKLab of an opaque colour, or null when it does not parse. */
+export function oklab(color: string): [number, number, number] | null {
+  const hex = normalizeToHex(color);
+  if (!hex) return null;
+  const [r, g, b] = channels(hex).map(linear) as [number, number, number];
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787405 * b);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+
+/** Euclidean OKLab distance between two colours, 0 when either does not parse. */
+export function oklabDistance(a: string, b: string): number {
+  const x = oklab(a);
+  const y = oklab(b);
+  if (!x || !y) return 0;
+  return Math.hypot(x[0] - y[0], x[1] - y[1], x[2] - y[2]);
+}
+
+/** sRGB chroma of an opaque colour, 0 for any grey. */
+export function srgbChroma(color: string): number {
+  const hex = normalizeToHex(color);
+  if (!hex) return 0;
+  const rgb = channels(hex);
+  return Math.max(...rgb) - Math.min(...rgb);
+}
+
+export interface FillContrastFinding {
+  preset: string;
+  scheme: "light" | "dark";
+  part: "accent fill" | "toggle" | "toggle off" | "toggle state" | "chart series" | "fill label";
+  detail: string;
+}
+
+type ResolvedThemes = Record<string, Record<string, unknown> | undefined>;
+
+const text = (value: unknown) => (typeof value === "string" ? value : undefined);
+
+/**
+ * Every LC-172 breach of one preset colour theme in `resolved` (themes run
+ * through `resolveAllThemes`). `theme` is the preset's colour theme, `""`
+ * for the house accent.
+ */
+export function auditPresetFills(
+  preset: string,
+  theme: string,
+  resolved: ResolvedThemes,
+): FillContrastFinding[] {
+  const findings: FillContrastFinding[] = [];
+  for (const scheme of ["light", "dark"] as const) {
+    const scopeName = theme ? `${scheme}_${theme}` : scheme;
+    const scope = resolved[scopeName] ?? {};
+    const solid = resolved[`${scopeName}_accent`] ?? {};
+    const isTint = tintHueNames.has(theme);
+    const accent = text(scope.accentBackground);
+    const color9 = text(scope.color9);
+    const identity = isTint ? (color9 ?? accent) : (accent ?? color9);
+    const accentSolids = Array.from({ length: 10 }, (_, index) =>
+      text(scope[`accent${index + 1}`]),
+    );
+    const chart = resolveChartPalette({
+      scheme,
+      identitySolid: identity,
+      identityCandidates: [
+        ...(isTint ? [] : accentIdentityCandidates(identity, accentSolids)),
+        text(scope.color10),
+        text(scope.color11),
+      ],
+      surfaces: [text(scope.color2), text(scheme === "light" ? scope.color1 : scope.color3)],
+    });
+    const fills: [FillContrastFinding["part"], string | undefined][] = [
+      ["accent fill", text(solid.background)],
+      ["toggle", accent],
+      ["chart series", chart.single],
+    ];
+    for (const [part, fill] of fills) {
+      const chroma = fill ? srgbChroma(fill) : 0;
+      if (chroma < fillChromaFloor) {
+        findings.push({
+          preset,
+          scheme,
+          part,
+          detail: `${fill ?? "missing"} is grey (chroma ${chroma.toFixed(2)} < ${fillChromaFloor})`,
+        });
+      }
+    }
+    const off = text(scope.switchTrackOff);
+    const ground = text(scope.background);
+    if (!off || !ground || !inSwitchOffBand(off, ground)) {
+      findings.push({
+        preset,
+        scheme,
+        part: "toggle off",
+        detail: `${off ?? "missing"} on ${ground ?? "missing"} is outside the HIG system-fill band`,
+      });
+    }
+    const apart = accent && off ? oklabDistance(accent, off) : 0;
+    if (apart < toggleStateFloor) {
+      findings.push({
+        preset,
+        scheme,
+        part: "toggle state",
+        detail: `on ${accent ?? "missing"} and off ${off ?? "missing"} are OKLab ${apart.toFixed(2)} apart < ${toggleStateFloor}`,
+      });
+    }
+    const label = text(solid.color);
+    const background = text(solid.background);
+    const lc = label && background ? Math.abs(apcaContrast(label, background)) : 0;
+    if (lc < fillLabelLcFloor) {
+      findings.push({
+        preset,
+        scheme,
+        part: "fill label",
+        detail: `${label ?? "missing"} on ${background ?? "missing"} is APCA Lc ${lc.toFixed(1)} < ${fillLabelLcFloor}`,
+      });
+    }
+  }
+  return findings;
+}

package/src/theme/index.ts

@@ -6,6 +6,7 @@ export * from "./cookies";
 export * from "./cornerSmoothing";
 export * from "./createDefaultThemeConfig";
 export * from "./createThemes";
+export * from "./dedupeInherited";
 export * from "./defaults/index";
 export * from "./devtools/ThemeDevtoolsPanel";
 export * from "./dynamicType";
@@ -50,6 +51,7 @@ export * from "./transitionProps";
 
 export * from "./theme";
 export * from "./Tint";
+export * from "./v3TokenRoles";
 export * from "./useResolvedKnobs";
 export * from "./useTheme";
 export * from "./usePresetSwitch";