@multiplatform.one/theme 7.7.6 → 7.10.0

package/src/theme/chartPalette.ts

@@ -1,7 +1,8 @@
 import * as Colors from "@tamagui/colors";
+import { themes as stockThemes } from "@tamagui/themes";
 import { useMemo } from "react";
 import { useTheme as useTamaguiTheme, useThemeName } from "tamagui";
-import { normalizeToHex } from "./colorRules";
+import { contrastRatio, minContrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
 import { tintHueNames } from "./createThemes";
 
 /**
@@ -14,7 +15,7 @@ import { tintHueNames } from "./createThemes";
  * - `single` — every mark of a single-series chart takes the theme identity:
  *   the active accent, or the tint solid when a tint sub-theme is active
  *   (the palette re-anchors under tint exactly like the neutral ramp does).
- * - `categorical` — identity-led list of sanctioned Radix step-9 solids for
+ * - `categorical` — identity-led list of sanctioned Radix solids for
  *   multi-series data. Slot 0 is the theme identity; the fixed hue cycle
  *   fills the rest, dropping hues indistinguishable from the identity so
  *   adjacent series stay tellable-apart under every tint.
@@ -22,7 +23,7 @@ import { tintHueNames } from "./createThemes";
  *   semantic ramps ($red/$green/$yellow), tint-independent, scheme-aware.
  *
  * Values resolve from the same Radix scales the theme builder splats into the
- * base themes, so `categorical[1]` under `light` equals `$blue9`, and they
+ * base themes, so `categorical[1]` under `light` equals `$blue10`, and they
  * stay resolvable on native and under tint sub-themes (which only carry the
  * re-ramped neutral family).
  */
@@ -41,31 +42,65 @@ export interface ResolveChartPaletteInput {
   scheme: "light" | "dark";
   /**
    * Resolved theme-identity solid — `accentBackground` in base themes, the
-   * re-ramped `$color9` under a tint. Falls back to the violet ramp solid
-   * when missing or unparseable (SSR before hydration, exotic values).
+   * re-ramped `$color9` under a tint. Tries the ordered candidates, then
+   * falls back to violet when missing, unparseable or below the contrast floor.
    */
   identitySolid?: string;
+  /** Ordered alternatives when the identity cannot meet the mark contrast floor. */
+  identityCandidates?: readonly (string | undefined)[];
 }
 
 /**
- * Fixed categorical hue cycle: Radix step-9 solids ordered so neighbouring
+ * Fixed categorical hue cycle: Radix solids ordered so neighbouring
  * entries sit far apart on the hue wheel (min adjacent distance ~78°).
- * Step 9 is the Radix "solid" step, designed for filled marks on both
- * schemes; hues where Radix ships scheme-specific solids follow the scheme.
+ * Light blue, orange, green, amber and teal deepen within their hue to clear
+ * 3:1 on reference cards. Dark violet deepens for tinted card backgrounds.
  */
 const categoricalHueCycle = [
-  { family: "blue", light: Colors.blue.blue9, dark: Colors.blueDark.blue9 },
-  { family: "orange", light: Colors.orange.orange9, dark: Colors.orangeDark.orange9 },
-  { family: "green", light: Colors.green.green9, dark: Colors.greenDark.green9 },
-  { family: "amber", light: Colors.amber.amber9, dark: Colors.amberDark.amber9 },
+  { family: "blue", light: Colors.blue.blue10, dark: Colors.blueDark.blue9 },
+  { family: "orange", light: Colors.orange.orange11, dark: Colors.orangeDark.orange9 },
+  { family: "green", light: Colors.green.green10, dark: Colors.greenDark.green9 },
+  { family: "amber", light: Colors.amber.amber11, dark: Colors.amberDark.amber9 },
   { family: "pink", light: Colors.pink.pink9, dark: Colors.pinkDark.pink9 },
-  { family: "teal", light: Colors.teal.teal9, dark: Colors.tealDark.teal9 },
-  { family: "violet", light: Colors.violet.violet9, dark: Colors.violetDark.violet9 },
+  { family: "teal", light: Colors.teal.teal10, dark: Colors.tealDark.teal9 },
+  { family: "violet", light: Colors.violet.violet9, dark: Colors.violetDark.violet10 },
   { family: "red", light: Colors.red.red9, dark: Colors.redDark.red9 },
 ] as const;
 
+function configuredTintCardSurfaces(scheme: "light" | "dark"): string[] {
+  const themes = stockThemes as unknown as Record<string, { background?: string }>;
+  return [...tintHueNames].flatMap((hue) => {
+    const color = themes[`${scheme}_${hue}_Card`]?.background;
+    return color ? [color] : [];
+  });
+}
+
+// Use the shipped tinted Card backgrounds, which are deeper than their page
+// colors. Missing theme names are not invented surfaces. The rendered audit
+// still owns actual custom consumer backgrounds and elevation variants.
+const chartReferenceSurfaces = {
+  light: [
+    "#ffffff",
+    Colors.gray.gray2,
+    Colors.mauve.mauve2,
+    ...configuredTintCardSurfaces("light"),
+  ],
+  dark: [Colors.grayDark.gray2, Colors.mauveDark.mauve2, ...configuredTintCardSurfaces("dark")],
+} as const;
+
+function readableIdentity(color: string | undefined, scheme: "light" | "dark"): color is string {
+  const hex = color ? normalizeToHex(color) : null;
+  if (!hex) return false;
+  const luminance = relativeLuminance(hex);
+  return chartReferenceSurfaces[scheme].every((surface) => {
+    const backdrop = normalizeToHex(surface);
+    return !!backdrop && contrastRatio(luminance, relativeLuminance(backdrop)) >= minContrastRatio;
+  });
+}
+
 /**
- * Semantic series solids. Error/success use the step-9 solids. Warning uses
+ * Semantic series solids. Light success deepens to green10 for the mark floor.
+ * Error and dark success use step 9. Warning uses
  * the sanctioned $yellow ramp, but yellow9 measures ~1.3:1 against light
  * card surfaces (invisible marks), so light scheme takes the deep yellow11
  * step while dark keeps the bright yellow9 (13:1 on dark surfaces).
@@ -73,7 +108,7 @@ const categoricalHueCycle = [
 const semanticSeries = {
   light: {
     error: Colors.red.red9,
-    success: Colors.green.green9,
+    success: Colors.green.green10,
     warning: Colors.yellow.yellow11,
   },
   dark: {
@@ -118,6 +153,47 @@ function hueDistance(a: number, b: number): number {
   return d > 180 ? 360 - d : d;
 }
 
+/** Keep every solid after dedupe, moving only an invalid adjacent sequence. */
+function orderCategoricalCycle(identity: string, cycle: string[]): string[] {
+  const colors = [identity, ...cycle];
+  const hsl = colors.map((color) => colorToHsl(color) as Hsl);
+  const luminance = colors.map((color) => relativeLuminance(normalizeToHex(color) as string));
+  // LC-27: any one of hue, saturation or luminance can distinguish a pair.
+  const compatible = hsl.map((a, i) =>
+    hsl.map(
+      (b, j) =>
+        (a.s >= neutralSaturationFloor &&
+          b.s >= neutralSaturationFloor &&
+          hueDistance(a.h, b.h) >= hueDedupeThresholdDeg) ||
+        Math.abs(a.s - b.s) >= 0.5 ||
+        contrastRatio(luminance[i], luminance[j]) >= 1.5,
+    ),
+  );
+  const indices = cycle.map((_, i) => i + 1);
+  if (indices.every((i) => compatible[i - 1][i]) && compatible[colors.length - 1][0]) {
+    return cycle;
+  }
+
+  // The fixed cycle has at most eight entries. Original-order traversal
+  // preserves valid prefixes and the identity remains first, including wrap.
+  const arrange = (previous: number, remaining: number[]): number[] | undefined => {
+    if (!remaining.length) return compatible[previous][0] ? [] : undefined;
+    for (const next of remaining) {
+      if (!compatible[previous][next]) continue;
+      const tail = arrange(
+        next,
+        remaining.filter((index) => index !== next),
+      );
+      if (tail) return [next, ...tail];
+    }
+    return undefined;
+  };
+  const ordered = arrange(0, indices);
+  // Preserve the supplied series if no permutation can satisfy the rule.
+  // The actual chart audit must still report that unsatisfied distinction.
+  return ordered ? ordered.map((index) => colors[index]) : cycle;
+}
+
 /**
  * Pure palette resolution — see {@link ChartPalette} for the contract.
  * Exported separately from the hook so tests and non-React callers can
@@ -125,10 +201,12 @@ function hueDistance(a: number, b: number): number {
  */
 export function resolveChartPalette(input: ResolveChartPaletteInput): ChartPalette {
   const { scheme } = input;
-  const fallbackIdentity = scheme === "dark" ? Colors.violetDark.violet9 : Colors.violet.violet9;
-  const identityHslRaw = input.identitySolid ? colorToHsl(input.identitySolid) : null;
-  const single = identityHslRaw ? (input.identitySolid as string) : fallbackIdentity;
-  const identityHsl = identityHslRaw ?? (colorToHsl(fallbackIdentity) as Hsl);
+  const fallbackIdentity = scheme === "dark" ? Colors.violetDark.violet10 : Colors.violet.violet9;
+  const single =
+    [input.identitySolid, ...(input.identityCandidates ?? [])].find((candidate) =>
+      readableIdentity(candidate, scheme),
+    ) ?? fallbackIdentity;
+  const identityHsl = colorToHsl(single) as Hsl;
 
   const cycle = categoricalHueCycle.map((entry) => (scheme === "dark" ? entry.dark : entry.light));
   const deduped =
@@ -143,7 +221,7 @@ export function resolveChartPalette(input: ResolveChartPaletteInput): ChartPalet
   return {
     scheme,
     single,
-    categorical: [single, ...deduped],
+    categorical: [single, ...orderCategoricalCycle(single, deduped)],
     semantic: semanticSeries[scheme],
   };
 }
@@ -166,5 +244,10 @@ export function useChartPalette(): ChartPalette {
   const color9 = theme.color9?.val;
   const accent = theme.accentBackground?.val;
   const identitySolid = isTint ? (color9 ?? accent) : (accent ?? color9);
-  return useMemo(() => resolveChartPalette({ scheme, identitySolid }), [scheme, identitySolid]);
+  const color10 = theme.color10?.val;
+  const color11 = theme.color11?.val;
+  return useMemo(
+    () => resolveChartPalette({ scheme, identitySolid, identityCandidates: [color10, color11] }),
+    [scheme, identitySolid, color10, color11],
+  );
 }

package/src/theme/colorRules.spec.ts

@@ -239,12 +239,34 @@ describe("measureContrast", () => {
       background: "#161519",
       label: "MPO-48 dark accent toast action",
     });
-    expect(report.ratio).toBe(1.94);
+    expect(report.ratio).toBeCloseTo(1.94, 2);
     expect(report.floor).toBe(aaTextContrastRatio);
     expect(report.pass).toBe(false);
   });
 
-  it("uses the reported 2-decimal ratio for the verdict", () => {
+  it.each([
+    { foreground: "#000000", background: "#595959", floor: 3 },
+    { foreground: "#77767c", background: "#ffffff", floor: 4.5 },
+  ])("does not round a below-$floor pair into a pass", (pair) => {
+    const report = measureContrast(pair);
+    expect(report.ratio).toBeGreaterThan(pair.floor - 0.005);
+    expect(report.ratio).toBeLessThan(pair.floor);
+    expect(report.pass).toBe(false);
+    expect(() => assertContrast(pair)).toThrow(/contrast floor missed/);
+  });
+
+  it("passes the exact measured floor and fails a higher floor", () => {
+    const pair = { foreground: "#77767c", background: "#ffffff" };
+    const floor = contrastRatio(
+      relativeLuminance(pair.foreground),
+      relativeLuminance(pair.background),
+    );
+    expect(measureContrast({ ...pair, floor }).pass).toBe(true);
+    expect(measureContrast({ ...pair, floor: floor - 0.00001 }).pass).toBe(true);
+    expect(measureContrast({ ...pair, floor: floor + 0.00001 }).pass).toBe(false);
+  });
+
+  it("uses the actual ratio for the verdict", () => {
     // #808080 on white is 3.9489…, reported 3.95 — pass at 3, miss at 4.5.
     const at3 = measureContrast({
       foreground: "#808080",
@@ -252,9 +274,9 @@ describe("measureContrast", () => {
       floor: minContrastRatio,
     });
     const atAa = measureContrast({ foreground: "#808080", background: "#ffffff" });
-    expect(at3.ratio).toBe(3.95);
+    expect(at3.ratio).toBeCloseTo(3.95, 2);
     expect(at3.pass).toBe(true);
-    expect(atAa.ratio).toBe(3.95);
+    expect(atAa.ratio).toBeCloseTo(3.95, 2);
     expect(atAa.pass).toBe(false);
   });
 
@@ -287,7 +309,7 @@ describe("assertContrast", () => {
         { foreground: "#808080", background: "#ffffff", label: "gray" },
       ]),
     ).toThrow(
-      /contrast floor missed \(2 of 3 pairs\):[\s\S]*toast pill: #46349d on #161519 = 1.94:1[\s\S]*gray: #808080 on #ffffff = 3.95:1/,
+      /contrast floor missed \(2 of 3 pairs\):[\s\S]*toast pill: #46349d on #161519 = 1\.937[0-9]+:1[\s\S]*gray: #808080 on #ffffff = 3\.949[0-9]+:1/,
     );
   });
 });
@@ -359,7 +381,10 @@ describe("contrast floor on built themes (DG-A11Y-01 / DG-COL-01)", () => {
         resolveThemeContrast(themes, { theme, foreground: "color", background: "background" }),
       ),
     );
-    expect(reports.map((report) => report.ratio)).toEqual([7.31, 7.61]);
+    expect(reports.map((report) => report.ratio)).toEqual([
+      expect.closeTo(7.31, 2),
+      expect.closeTo(7.61, 2),
+    ]);
   });
 
   it("a colour pair below the floor FAILS", () => {
@@ -371,18 +396,27 @@ describe("contrast floor on built themes (DG-A11Y-01 / DG-COL-01)", () => {
         background: themes.dark.background,
         label: "MPO-48 dark accent toast action",
       }),
-    ).toThrow(/MPO-48 dark accent toast action: #46349d on #161519 = 1.94:1/);
+    ).toThrow(/MPO-48 dark accent toast action: #46349d on #161519 = 1\.937[0-9]+:1/);
 
-    // MPO-40: outlined warning $color11 on the warning page surface is 4.44:1.
-    expect(() =>
-      assertContrast(
-        resolveThemeContrast(themes, {
-          theme: "light_warning",
-          foreground: "color11",
-          background: "color1",
-        }),
-      ),
-    ).toThrow(/light_warning: color11 on color1: #9e6c00 on #fcfcf7 = 4.44:1/);
+    // MPO-40's warning-on-its-own-color1 arm used to sit here as the second
+    // negative control at 4.44:1. The `intentInkFloor` step closed it — the
+    // same pair now measures 4.71:1 — so it can no longer prove the trip-wire
+    // bites, and it moved to the passing assertion below rather than being
+    // deleted. MPO-48 above is still a live miss and still carries this test.
+  });
+
+  it("MPO-40's warning ink now clears the floor on its own color1 too", () => {
+    // The pair that used to be the negative control. The palette step was
+    // computed against the BASE color2 (#f9f9fa, the strictest ground), and
+    // this checks the intent's own surface came along with it. Was 4.44.
+    const [report] = assertContrast(
+      resolveThemeContrast(themes, {
+        theme: "light_warning",
+        foreground: "color11",
+        background: "color1",
+      }),
+    );
+    expect(report.ratio).toBeCloseTo(4.66, 2);
   });
 
   it("current light_accent color-on-background clears the 3:1 non-text floor", () => {
@@ -397,7 +431,7 @@ describe("contrast floor on built themes (DG-A11Y-01 / DG-COL-01)", () => {
         floor: minContrastRatio,
       }),
     );
-    expect(reports[0].ratio).toBe(3.96);
+    expect(reports[0].ratio).toBeCloseTo(3.96, 2);
     expect(reports[0].pass).toBe(true);
   });
 
@@ -422,7 +456,7 @@ describe("contrast floor on built themes (DG-A11Y-01 / DG-COL-01)", () => {
           floor: minContrastRatio,
         }),
       ),
-    ).toThrow(/light_accent: color on background: #f9f8fc on #eeecf9 = 1.1:1/);
+    ).toThrow(/light_accent: color on background: #f9f8fc on #eeecf9 = 1\.103[0-9]+:1/);
   });
 });
 
@@ -455,37 +489,51 @@ describe("intent color11 on the base page surfaces (MPO-40)", () => {
    * MPO-40 measured the outlined intent label on the gallery harness ground
    * and recorded warning 4.34:1 and success 4.48:1. That ground is the BASE
    * theme's `color2` (#f9f9fa) — NOT `background`/`color1`, which are both
-   * #ffffff and where the same two pairs clear the floor at 4.57 and 4.72.
-   * The miss is therefore surface-specific: an outlined warning or success
-   * Button only goes unreadable once it sits on a color2 surface (a card, a
-   * striped row, the gallery ground). Measuring against the plain page is
-   * exactly how a check reports a pass on a control that is failing.
+   * #ffffff and where the same two pairs cleared the floor even unfixed. The
+   * miss was therefore surface-specific: an outlined warning or success Button
+   * only went unreadable once it sat on a color2 surface (a card, a striped
+   * row, the gallery ground). Measuring against the plain page is exactly how
+   * a check reports a pass on a control that is failing.
    *
-   * The two misses are PINNED to their measured ratios rather than skipped.
-   * Raise the $color11 step and the recorded ratio stops matching, which
-   * fails here and forces the entry out of this table — an exemption that
-   * retires itself instead of one that rots.
+   * Both are CLOSED by the `intentInkFloor` step in `createThemes.ts`, which
+   * darkens light `yellow11` and `green11` to the nearest hue-holding value
+   * that clears the floor on `color2`. The exemption table that used to stand
+   * here retired itself exactly as designed: the step moved, its pinned ratios
+   * stopped matching, and the entries had to come out. There is now no
+   * exemption to rot.
    */
-  const pinnedMisses: Record<string, number> = {
-    "light_warning: color11 on light.color2": 4.34,
-    "light_success: color11 on light.color2": 4.48,
-  };
-
   it("sweeps every intent x base surface x scheme — 18 pairs, none dropped", () => {
     expect(intentInkPairs).toHaveLength(18);
   });
 
-  it("clears AA everywhere except the two pinned MPO-40 misses", () => {
+  it("clears AA on every intent x base surface x scheme pair, with no exemptions", () => {
     const misses = intentInkPairs
       .map(measureContrast)
       .filter((report) => !report.pass)
       .map((report) => [report.label, report.ratio] as const);
-    expect(Object.fromEntries(misses)).toEqual(pinnedMisses);
+    expect(Object.fromEntries(misses)).toEqual({});
+  });
+
+  it("pins the two MPO-40 stops on color2, the ground they used to fail", () => {
+    // The regression guard proper: color2 is the STRICTEST base surface, so a
+    // future palette move that quietly re-lightens either stop lands here
+    // first. Was 4.34 / 4.48 against a 4.5 floor.
+    const reports = assertContrast(
+      (["warning", "success"] as const).map((intent) => ({
+        foreground: themes[`light_${intent}`].color11,
+        background: themes.light.color2,
+        label: `light_${intent}: color11 on light.color2`,
+      })),
+    );
+    expect(reports.map((report) => report.ratio)).toEqual([
+      expect.closeTo(4.56, 2),
+      expect.closeTo(4.55, 2),
+    ]);
   });
 
-  it("the same warning/success ink clears the floor on background and color1", () => {
-    // Locks the surface-specificity so a future fix cannot be signed off by
-    // re-measuring against the white page.
+  it("the same warning/success ink still clears the floor on background and color1", () => {
+    // Locks the surface-specificity so a future change cannot be signed off by
+    // re-measuring against the white page. Was 4.57 / 4.72.
     const reports = assertContrast(
       (["warning", "success"] as const).flatMap((intent) =>
         (["background", "color1"] as const).map((surface) => ({
@@ -495,6 +543,11 @@ describe("intent color11 on the base page surfaces (MPO-40)", () => {
         })),
       ),
     );
-    expect(reports.map((report) => report.ratio)).toEqual([4.57, 4.57, 4.72, 4.72]);
+    expect(reports.map((report) => report.ratio)).toEqual([
+      expect.closeTo(4.8, 2),
+      expect.closeTo(4.8, 2),
+      expect.closeTo(4.79, 2),
+      expect.closeTo(4.79, 2),
+    ]);
   });
 });

package/src/theme/colorRules.ts

@@ -104,7 +104,7 @@ export interface ContrastReport {
   /** The colors actually measured, as normalized 6-digit hex. */
   foreground: string;
   background: string;
-  /** WCAG 2.x ratio rounded to 2 decimals — the number a report reads. */
+  /** Unrounded WCAG 2.x ratio. Round only when formatting a display value. */
   ratio: number;
   floor: number;
   pass: boolean;
@@ -114,8 +114,8 @@ export interface ContrastReport {
  * Measure one pair against its floor. Throws when a color cannot be reduced
  * to an opaque hex: an alpha color has no contrast of its own and the house
  * ramps are fully opaque, so an unmeasurable pair is a genuine failure,
- * never a skip. The verdict compares the REPORTED (2-decimal) ratio, so
- * pass/fail always matches the printed number.
+ * never a skip. Compare the actual ratio: rounding before classification
+ * can turn a below-floor pair into a passing one.
  */
 export function measureContrast(pair: ContrastPair): ContrastReport {
   const floor = pair.floor ?? aaTextContrastRatio;
@@ -128,9 +128,7 @@ export function measureContrast(pair: ContrastPair): ContrastReport {
   if (!background) {
     throw new Error(`${label}: background is not an opaque color: ${pair.background}`);
   }
-  const ratio =
-    Math.round(contrastRatio(relativeLuminance(foreground), relativeLuminance(background)) * 100) /
-    100;
+  const ratio = contrastRatio(relativeLuminance(foreground), relativeLuminance(background));
   return { label, foreground, background, ratio, floor, pass: ratio >= floor };
 }
 

package/src/theme/createDefaultThemeConfig.ts

@@ -87,7 +87,7 @@ function composeGetTheme(
   >;
   if (!custom) return base;
   return (props: GetThemeProps) => {
-    const merged: Record<string, string | number> = { ...base(props) };
+    const merged: Record<string, string | number | null | undefined> = { ...base(props) };
     const consumer = custom(props);
     // MPO-23 / 10 B.3 item 3. Dropping nullish is not enough: a misspelled
     // colour is not nullish, survives the merge, and resolves to nothing at

package/src/theme/createThemes.ts

@@ -5,6 +5,61 @@ import {
 } from "@tamagui/theme-builder";
 import { themes as tamaguiThemes } from "@tamagui/themes";
 
+/**
+ * MPO-40. Radix aims a scale's step 11 at the AA text floor against ITS OWN
+ * step 1-2, never against a foreign neutral. mpo paints intent ink on the BASE
+ * theme's surfaces, and on `$color2` — `#f9f9fa`, the ground 35 catalog
+ * surfaces and every gallery board actually paint — light `yellow11`
+ * (`#9e6c00`) measures 4.34:1 and light `green11` (`#218358`) 4.48:1, both
+ * under `colorRules`' `aaTextContrastRatio` of 4.5. So the stock stop is right
+ * upstream and wrong here.
+ *
+ * Only these two stops move. Light `red11` clears at 4.95:1 and every dark
+ * intent stop clears by 8.49:1 or more, measured, so red and both dark ramps
+ * stay untouched stock Radix — as does every other step of yellow and green.
+ *
+ * The replacements are the smallest darkening that clears the floor on the
+ * strictest base surface while holding the hue — dE76 1.94 for warning and
+ * 0.70 for success, both far under the ~2.3 just-noticeable difference, so
+ * neither intent hue visibly shifts.
+ *
+ * THESE ARE QUANTIZED VALUES, and that is not a detail. `createThemes` stores
+ * every palette entry through color2k as `hsla()` with INTEGER degrees and
+ * percentages, so the reachable palette is coarser than hex and a hex chosen
+ * on paper is not what renders. The first pass here picked `#996800` /
+ * `#208156` by minimising CIEDE2000 in hex space; `#208156` quantized to the
+ * SAME `hsla(154, 60%, 32%)` as the stock stop and changed nothing at all,
+ * while `#996800` landed two hundredths off its predicted ratio. Both values
+ * below were searched in the quantized space and confirmed against the built
+ * theme, not against the arithmetic.
+ *
+ * `$color11` is ALSO the solid intent Button's resting fill (`step(10)` in
+ * `defaults/builderOptions.ts`), so this shifts that fill by the same
+ * imperceptible amount. It improves it: the solid warning Button's
+ * luminance-picked on-fill label was itself at 4.48:1 — a second, unpinned AA
+ * miss. The `pickReadableForeground` anchor does not flip for either intent,
+ * so no label changes colour.
+ */
+const intentInkFloor = {
+  /** stored `hsla(41, 100%, 30%)`; 4.34:1 -> 4.56:1 on the base `$color2` */
+  warning: "#996900",
+  /** stored `hsla(155, 64%, 31%)`; 4.48:1 -> 4.56:1 on the base `$color2` */
+  success: "#1c8257",
+} as const;
+
+/**
+ * Replace a Radix ramp's step-11 ink stop, leaving all eleven other steps
+ * stock. Radix ramps are 12 entries with step N at index N-1; anything else is
+ * not a ramp this rule understands, so it passes through untouched rather than
+ * writing to a position that means something different.
+ */
+function withIntentInkFloor(palette: string[], ink: string): string[] {
+  if (palette.length !== 12) return palette;
+  const stepped = [...palette];
+  stepped[10] = ink;
+  return stepped;
+}
+
 const grayTheme = {
   dark_gray: tamaguiThemes.dark,
   dark_gray_active: tamaguiThemes.dark_active,
@@ -55,7 +110,7 @@ export interface GetThemeProps {
 
 export interface CreateThemesBuilderOptions {
   grandChildrenThemes?: CreateThemesProps["grandChildrenThemes"];
-  getTheme?: (props: GetThemeProps) => Record<string, string | number>;
+  getTheme?: (props: GetThemeProps) => Record<string, string | number | null | undefined>;
 }
 
 /**
@@ -311,7 +366,7 @@ export function createThemesBuilder(
     warning: {
       palette: {
         dark: Object.values(Colors.yellowDark),
-        light: Object.values(Colors.yellow),
+        light: withIntentInkFloor(Object.values(Colors.yellow), intentInkFloor.warning),
       },
     },
     error: {
@@ -323,7 +378,7 @@ export function createThemesBuilder(
     success: {
       palette: {
         dark: Object.values(Colors.greenDark),
-        light: Object.values(Colors.green),
+        light: withIntentInkFloor(Object.values(Colors.green), intentInkFloor.success),
       },
     },
   };

package/src/theme/devtools/ColorLineVisualizer.stories.tsx

@@ -0,0 +1,36 @@
+import { defaultKnobs } from "../knobs";
+import { ColorLineVisualizer } from "./ColorLineVisualizer";
+
+const SAMPLE = Array.from({ length: 12 }, (_, i) => `hsl(${i * 28}, 62%, ${72 - i * 3.5}%)`);
+
+export default {
+  title: "Theme/ColorLineVisualizer",
+  component: ColorLineVisualizer,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Twelve-step theme ramp with semantic group brackets. Tamagui has no equivalent; this is the mpo knob-devtools colour line.",
+      },
+    },
+  },
+};
+
+export const main = {
+  name: "Main",
+  render: () => (
+    <div data-testid="color-line-visualizer">
+      <ColorLineVisualizer knobs={defaultKnobs} isDark={false} themeColors={SAMPLE} />
+    </div>
+  ),
+};
+
+export const dark = {
+  name: "Dark",
+  render: () => (
+    <div data-testid="color-line-visualizer-dark">
+      <ColorLineVisualizer knobs={defaultKnobs} isDark themeColors={SAMPLE} />
+    </div>
+  ),
+};

package/src/theme/devtools/ThemeDevtoolsPanel.stories.tsx

@@ -0,0 +1,16 @@
+import { ThemeDevtoolsPanel } from "./ThemeDevtoolsPanel";
+
+export default {
+  title: "Theme/ThemeDevtoolsPanel",
+  component: ThemeDevtoolsPanel,
+  parameters: { status: { type: "beta" } },
+};
+
+export const main = {
+  name: "Main",
+  render: () => (
+    <div data-testid="theme-devtools-panel" style={{ maxHeight: 640, overflow: "auto" }}>
+      <ThemeDevtoolsPanel devtoolsTheme="light" />
+    </div>
+  ),
+};

package/src/theme/glyphPaint.spec.ts

@@ -2,6 +2,20 @@ import { describe, expect, it } from "vitest";
 import { resolveGlyphPaint } from "./glyphPaint";
 
 describe("resolveGlyphPaint (LC-84)", () => {
+  it("falls back to concrete ink when a requested theme token is absent", () => {
+    expect(resolveGlyphPaint({ color: { val: "#111" } }, "$accentColor")).toBe("#111");
+    expect(resolveGlyphPaint({ color12: { val: "#eee" } }, "$missing")).toBe("#eee");
+    expect(resolveGlyphPaint({ color11: { val: "#ddd" } }, "$missing")).toBe("#ddd");
+    expect(resolveGlyphPaint({}, "$missing")).toBe("currentColor");
+  });
+
+  it("preserves supplied theme tokens and supported literal paint", () => {
+    expect(resolveGlyphPaint({ accentColor: { val: "#123456" } }, "$accentColor")).toBe("#123456");
+    for (const paint of ["currentColor", "red", "#123456", "rgb(1, 2, 3)", "hsl(0, 0%, 50%)"]) {
+      expect(resolveGlyphPaint({ color: { val: "#111" } }, paint)).toBe(paint);
+    }
+  });
+
   it("never returns undefined", () => {
     expect(resolveGlyphPaint({})).toBe("currentColor");
     expect(resolveGlyphPaint({}, undefined)).toBe("currentColor");

package/src/theme/glyphPaint.ts

@@ -26,7 +26,8 @@ export function resolveGlyphPaint(
     push(theme[key]?.val);
     if (color.startsWith("#") || color.startsWith("rgb") || color.startsWith("hsl")) {
       push(color);
-    } else if (!theme[key]) {
+    } else if (!theme[key] && !color.startsWith("$")) {
+      // Literal CSS colors may pass through; an unresolved theme token cannot paint.
       push(color);
     }
   }

package/src/theme/intent.spec.tsx

@@ -5,6 +5,7 @@ import { describe, expect, it, vi } from "vitest";
 
 // Mock Tamagui's <Theme> so we can inspect the chosen theme name
 vi.mock("tamagui", () => ({
+  useThemeName: () => "light",
   Theme: ({ name, children }: { name: string; children: ReactNode }) =>
     createElement("div", { "data-tamagui-theme": name }, children),
   createStyledContext: (defaults: { size: string; density: string }) => ({

package/src/theme/layoutTokensHooks.spec.tsx

@@ -25,6 +25,7 @@ vi.mock(import("tamagui"), async (importOriginal) => ({
   ...(await importOriginal()),
   // Pin the web path — these specs drive size class via matchMedia listeners.
   isWeb: true,
+  useThemeName: () => "light",
   useWindowDimensions: () => nativeWindowDimensions,
 }));