@multiplatform.one/theme 7.34.3 → 7.35.0

package/src/theme/chartPalette.spec.ts

@@ -1,9 +1,17 @@
 import * as Colors from "@tamagui/colors";
-import { themes as stockThemes } from "@tamagui/themes";
 import { describe, expect, it } from "vitest";
 import { accentIdentityCandidates, resolveChartPalette } from "./chartPalette";
 import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
-import { tintHueNames } from "./createThemes";
+import { createThemesBuilder, tintHueNames } from "./createThemes";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+import { defaultBuilderOptions } from "./defaults/builderOptions";
+
+const builtThemes = createThemesBuilder(
+  defaultBaseTheme,
+  defaultAccentTheme,
+  defaultBuilderOptions,
+).themes() as unknown as Record<string, Record<string, string>>;
 
 // The default accent solid (accentBackground) from defaults/accent.ts.
 const lightAccent = "hsla(250, 50%, 54%, 1)";
@@ -57,30 +65,26 @@ function adjacentDistinguishable(a: string, b: string): boolean {
 describe("resolveChartPalette", () => {
   it("floors every categorical mark across the registered tint identities", () => {
     for (const scheme of ["light", "dark"] as const) {
-      const cardSurfaces = Object.entries(stockThemes)
-        .filter(
-          ([name]) =>
-            name.startsWith(`${scheme}_`) &&
-            name.endsWith("_Card") &&
-            tintHueNames.has(name.split("_")[1]) &&
-            name.split("_").length === 3,
-        )
-        .map(([, theme]) => theme.background);
-      expect(cardSurfaces.length).toBeGreaterThan(0);
-      const surfaces = [
-        ...cardSurfaces,
-        ...(scheme === "light"
+      const builtSurfaces = [scheme, ...[...tintHueNames].map((hue) => `${scheme}_${hue}`)]
+        .filter((name) => builtThemes[name])
+        .flatMap((name) => [builtThemes[name].background, builtThemes[`${name}_Card`].background]);
+      expect(builtSurfaces.length).toBeGreaterThan(2);
+      const references =
+        scheme === "light"
           ? ["#ffffff", Colors.gray.gray2, Colors.mauve.mauve2]
-          : [Colors.grayDark.gray2, Colors.mauveDark.mauve2]),
-      ];
+          : [Colors.grayDark.gray2, Colors.mauveDark.mauve2];
+      const surfaces = [...builtSurfaces, ...references];
       for (const hue of tintHueNames) {
         const ramp = (Colors as unknown as Record<string, Record<string, string>>)[
           scheme === "dark" ? `${hue}Dark` : hue
         ];
+        const tint = builtThemes[`${scheme}_${hue}`];
+        const tintSurfaces = tint ? [tint.color2, tint.color3] : [];
         const palette = resolveChartPalette({
           scheme,
           identitySolid: ramp[`${hue}9`],
           identityCandidates: [ramp[`${hue}10`], ramp[`${hue}11`]],
+          surfaces: tintSurfaces,
         });
         for (let i = 0; i < palette.categorical.length; i++) {
           expect(
@@ -91,14 +95,19 @@ describe("resolveChartPalette", () => {
             `${scheme}/${hue}: adjacent series ${i}`,
           ).toBe(true);
         }
-        for (const paint of [...palette.categorical, ...Object.values(palette.semantic)]) {
-          for (const surface of surfaces) {
-            const ratio = contrastRatio(
-              relativeLuminance(normalizeToHex(paint)!),
-              relativeLuminance(normalizeToHex(surface)!),
-            );
-            expect(ratio, `${scheme}/${hue}: ${paint} on ${surface}`).toBeGreaterThanOrEqual(3);
-          }
+        const [identity, ...cycle] = palette.categorical;
+        const marks = [
+          ...[...references, ...tintSurfaces].map((surface) => [identity, surface]),
+          ...[...cycle, ...Object.values(palette.semantic)].flatMap((paint) =>
+            surfaces.map((surface) => [paint, surface]),
+          ),
+        ];
+        for (const [paint, surface] of marks) {
+          const ratio = contrastRatio(
+            relativeLuminance(normalizeToHex(paint)!),
+            relativeLuminance(normalizeToHex(surface)!),
+          );
+          expect(ratio, `${scheme}/${hue}: ${paint} on ${surface}`).toBeGreaterThanOrEqual(3);
         }
       }
     }
@@ -128,7 +137,7 @@ describe("resolveChartPalette", () => {
       Colors.green.green10,
       Colors.amber.amber11,
       Colors.pink.pink9,
-      Colors.teal.teal10,
+      Colors.teal.teal11,
       Colors.red.red9,
     ]);
     const grass = resolveChartPalette({
@@ -144,7 +153,7 @@ describe("resolveChartPalette", () => {
         Colors.orange.orange11,
         Colors.amber.amber11,
         Colors.pink.pink9,
-        Colors.teal.teal10,
+        Colors.teal.teal11,
         Colors.violet.violet9,
         Colors.red.red9,
       ].sort(),
@@ -175,6 +184,25 @@ describe("resolveChartPalette", () => {
     ).toBe(Colors.violet.violet9);
   });
 
+  it("steps the identity down when it misses the tint's Card fill", () => {
+    const tint = builtThemes.light_gray;
+    const card = builtThemes.light_gray_Card.background;
+    expect(card).toBe(tint.color3);
+    const onCard = resolveChartPalette({
+      scheme: "light",
+      identitySolid: tint.color9,
+      identityCandidates: [tint.color10, tint.color11],
+      surfaces: [tint.color2, tint.color3],
+    });
+    expect(onCard.single).toBe(tint.color10);
+    expect(
+      contrastRatio(
+        relativeLuminance(normalizeToHex(onCard.single)!),
+        relativeLuminance(normalizeToHex(card)!),
+      ),
+    ).toBeGreaterThanOrEqual(3);
+  });
+
   it("single-series takes the theme identity solid", () => {
     expect(resolveChartPalette({ scheme: "light", identitySolid: lightAccent }).single).toBe(
       lightAccent,
@@ -295,6 +323,7 @@ describe("chart identity under the held dark accent (MPO-448)", () => {
         ...accentIdentityCandidates(identitySolid, darkAccentSolids),
         "hsla(270, 6%, 54%, 1)",
       ],
+      surfaces: [builtThemes.dark_purple.color2, builtThemes.dark_purple.color3],
     });
     expect(palette.single).toBe(darkAccentSolids[9]);
   });

package/src/theme/chartPalette.ts

@@ -1,5 +1,4 @@
 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 { contrastRatio, minContrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
@@ -41,20 +40,29 @@ export interface ChartPalette {
 export interface ResolveChartPaletteInput {
   scheme: "light" | "dark";
   /**
-   * Resolved theme-identity solid — `accentBackground` in base themes, the
+   * Resolved theme-identity solid — the accent solid in base themes, the
    * 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)[];
+  /**
+   * The active colour theme's page and Card fills (`$color2` and `$color3`
+   * under v5's templates, the same in every sub-theme of that colour). A
+   * tint's surfaces are deeper than the reference whites, so the identity
+   * must clear them too, and one palette serves a chart on the page or in a
+   * Card.
+   */
+  surfaces?: readonly (string | undefined)[];
 }
 
 /**
  * Fixed categorical hue cycle: Radix solids ordered so neighbouring
  * entries sit far apart on the hue wheel (min adjacent distance ~78°).
  * 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.
+ * 3:1 on every built page and Card surface. Dark violet deepens for tinted
+ * card backgrounds.
  */
 const categoricalHueCycle = [
   { family: "blue", light: Colors.blue.blue10, dark: Colors.blueDark.blue9 },
@@ -62,37 +70,31 @@ const categoricalHueCycle = [
   { 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.teal10, dark: Colors.tealDark.teal9 },
+  { family: "teal", light: Colors.teal.teal11, 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.
+// The rendered audit still owns 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")],
+  light: ["#ffffff", Colors.gray.gray2, Colors.mauve.mauve2],
+  dark: [Colors.grayDark.gray2, Colors.mauveDark.mauve2],
 } as const;
 
-function readableIdentity(color: string | undefined, scheme: "light" | "dark"): color is string {
+function readableIdentity(
+  color: string | undefined,
+  scheme: "light" | "dark",
+  themeSurfaces: readonly (string | undefined)[],
+): color is string {
   const hex = color ? normalizeToHex(color) : null;
   if (!hex) return false;
   const luminance = relativeLuminance(hex);
-  return chartReferenceSurfaces[scheme].every((surface) => {
+  const surfaces = [
+    ...chartReferenceSurfaces[scheme],
+    ...themeSurfaces.filter((surface): surface is string => !!surface),
+  ];
+  return surfaces.every((surface) => {
     const backdrop = normalizeToHex(surface);
     return !!backdrop && contrastRatio(luminance, relativeLuminance(backdrop)) >= minContrastRatio;
   });
@@ -204,7 +206,7 @@ export function resolveChartPalette(input: ResolveChartPaletteInput): ChartPalet
   const fallbackIdentity = scheme === "dark" ? Colors.violetDark.violet10 : Colors.violet.violet9;
   const single =
     [input.identitySolid, ...(input.identityCandidates ?? [])].find((candidate) =>
-      readableIdentity(candidate, scheme),
+      readableIdentity(candidate, scheme, input.surfaces ?? []),
     ) ?? fallbackIdentity;
   const identityHsl = colorToHsl(single) as Hsl;
 
@@ -229,7 +231,7 @@ export function resolveChartPalette(input: ResolveChartPaletteInput): ChartPalet
 /**
  * The accent solids ordered nearest-first in luminance to `identity`, so a
  * chart identity that misses the 3:1 mark floor on the reference cards falls
- * to the next accent step before a neutral one. `$accentBackground` is held
+ * to the next accent step before a neutral one. The accent solid is held
  * to the text floor (MPO-448), which in dark lands it one step deeper than
  * the marks need; the chart keeps the accent channel on the step beside it.
  */
@@ -256,7 +258,7 @@ export function accentIdentityCandidates(
  *
  * Reads scheme and tint from the resolved theme name and the identity solid
  * from the active theme (`$color9` under a tint — the re-ramped neutral
- * solid — otherwise `$accentBackground`). Chart chrome MUST take its default
+ * solid — otherwise the accent solid). Chart chrome MUST take its default
  * series colors from this hook; explicit `color`/`colors` props on chart
  * data are user values and pass through untouched.
  */
@@ -268,6 +270,8 @@ export function useChartPalette(): ChartPalette {
   const isTint = nameParts.length > 1 && tintHueNames.has(nameParts[1]);
   const color9 = theme.color9?.val;
   const accent = theme.accentBackground?.val;
+  const page = theme.color2?.val;
+  const card = theme.color3?.val;
   const identitySolid = isTint ? (color9 ?? accent) : (accent ?? color9);
   const color10 = theme.color10?.val;
   const color11 = theme.color11?.val;
@@ -283,8 +287,9 @@ export function useChartPalette(): ChartPalette {
           color10,
           color11,
         ],
+        surfaces: [page, card],
       }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [scheme, identitySolid, isTint, accentKey, color10, color11],
+    [scheme, identitySolid, isTint, accentKey, color10, color11, page, card],
   );
 }

package/src/theme/colorRules.spec.ts

@@ -382,34 +382,21 @@ 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([
-      expect.closeTo(7.31, 2),
-      expect.closeTo(7.61, 2),
-    ]);
+    expect(reports).toHaveLength(2);
+    expect(reports.every((report) => report.ratio >= aaTextContrastRatio)).toBe(true);
   });
 
-  it("a colour pair below the floor FAILS", () => {
-    // MPO-48 measured the dark accent toast action pill on the page ground.
-    // Built: dark_accent.backgroundHover is #46349d; dark.background is #161519.
+  it("a colour pair below the floor fails", () => {
     expect(() =>
       assertContrast({
-        foreground: themes.dark_accent.backgroundHover,
-        background: themes.dark.background,
-        label: "MPO-48 dark accent toast action",
+        foreground: themes.light.color3,
+        background: themes.light.background,
+        label: "low-contrast ink",
       }),
-    ).toThrow(/MPO-48 dark accent toast action: #46349d on #161519 = 1\.937[0-9]+: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.
+    ).toThrow(/low-contrast ink/);
   });
 
-  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.
+  it("warning ink clears the floor on its own color1 too", () => {
     const [report] = assertContrast(
       resolveThemeContrast(themes, {
         theme: "light_warning",
@@ -417,47 +404,42 @@ describe("contrast floor on built themes (DG-A11Y-01 / DG-COL-01)", () => {
         background: "color1",
       }),
     );
-    expect(report.ratio).toBeCloseTo(4.66, 2);
+    expect(report.ratio).toBeGreaterThanOrEqual(aaTextContrastRatio);
   });
 
-  it("current light_accent color-on-background clears the 3:1 non-text floor", () => {
-    // Parent accent is 3.96:1 — under AA, over the large-text/UI floor. The
-    // Button pair (asserted above) is the AA text contract; this pair is the
-    // trip-wire's control so the old pale-lavender step is the thing that fails.
-    const reports = assertContrast(
-      resolveThemeContrast(themes, {
-        theme: "light_accent",
-        foreground: "color",
-        background: "background",
-        floor: minContrastRatio,
-      }),
-    );
-    expect(reports[0].ratio).toBeCloseTo(3.96, 2);
-    expect(reports[0].pass).toBe(true);
+  it("the inverted-base accent text clears AA on its background", () => {
+    for (const scheme of ["light", "dark"]) {
+      const [report] = assertContrast(
+        resolveThemeContrast(themes, {
+          theme: `${scheme}_accent`,
+          foreground: "color",
+          background: "background",
+        }),
+      );
+      expect(report.ratio).toBeGreaterThanOrEqual(aaTextContrastRatio);
+    }
   });
 
-  it("re-introducing the old accent lightPalette[0] fails the test", () => {
-    // The pale-lavender step that shipped a ~1.17:1 CTA. Swapping only [0]
-    // leaves Button (palette[3]) alone and drops light_accent.background.
+  it("a pale accent page fails the contrast guard", () => {
+    const palette = [...defaultAccentTheme.lightPalette];
+    palette[1] = defaultAccentTheme.lightPalette[11];
     const broken = createThemesBuilder(
       defaultBaseTheme,
       {
         ...defaultAccentTheme,
-        lightPalette: ["hsla(250, 50%, 95%, 1)", ...defaultAccentTheme.lightPalette.slice(1)],
+        lightPalette: palette,
       },
       defaultBuilderOptions,
-    ).themes() as Record<string, Record<string, string>>;
-
+    ).themes();
     expect(() =>
       assertContrast(
         resolveThemeContrast(broken, {
           theme: "light_accent",
           foreground: "color",
           background: "background",
-          floor: minContrastRatio,
         }),
       ),
-    ).toThrow(/light_accent: color on background: #f9f8fc on #eeecf9 = 1\.103[0-9]+:1/);
+    ).toThrow(/light_accent: color on background/);
   });
 });
 
@@ -486,23 +468,6 @@ 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 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.
-   *
-   * 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.
-   */
   it("sweeps every intent x base surface x scheme — 18 pairs, none dropped", () => {
     expect(intentInkPairs).toHaveLength(18);
   });
@@ -516,9 +481,6 @@ describe("intent color11 on the base page surfaces (MPO-40)", () => {
   });
 
   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,
@@ -527,14 +489,12 @@ describe("intent color11 on the base page surfaces (MPO-40)", () => {
       })),
     );
     expect(reports.map((report) => report.ratio)).toEqual([
-      expect.closeTo(4.56, 2),
-      expect.closeTo(4.55, 2),
+      expect.closeTo(4.54, 2),
+      expect.closeTo(4.53, 2),
     ]);
   });
 
   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) => ({
@@ -545,10 +505,10 @@ describe("intent color11 on the base page surfaces (MPO-40)", () => {
       ),
     );
     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),
+      expect.closeTo(4.54, 2),
+      expect.closeTo(4.87, 2),
+      expect.closeTo(4.53, 2),
+      expect.closeTo(4.85, 2),
     ]);
   });
 });

package/src/theme/cookies.spec.ts

@@ -1,8 +1,10 @@
 import { describe, expect, it, beforeEach } from "vitest";
 import { defaultKnobs, type Knobs } from "./knobs";
 import {
+  sanitizeOverrides,
   splitCookieValue,
   joinSplitCookieValues,
+  isKnobKey,
   readOverridesCookie,
   readPresetCookie,
   writePresetCookie,
@@ -78,7 +80,7 @@ describe("readOverridesCookie", () => {
   });
 
   it("reads and joins multiple chunks", () => {
-    const overrides: Partial<Knobs> = { fillStyle: "outlined", size: "large" };
+    const overrides: Partial<Knobs> = { fillStyle: "outlined", elevation: "large" };
     const json = JSON.stringify(overrides);
     const mid = Math.floor(json.length / 2);
     const cookies: Record<string, string> = {
@@ -110,12 +112,12 @@ describe("readOverridesCookie", () => {
 // JSON.parse threw, and overrides silently resolved to {} app-wide.
 describe("readOverridesCookie with universal-cookie auto-parsed values", () => {
   it("accepts an already-parsed object cookie value (universal-cookie shape)", () => {
-    const overrides: Partial<Knobs> = { borderRadius: "none", space: "small" };
+    const overrides: Partial<Knobs> = { borderRadius: "none", textAccent: "low" };
     expect(readOverridesCookie({ "mp.ov.0": overrides })).toEqual(overrides);
   });
 
   it("accepts a raw JSON string cookie value (document.cookie / SSR shape)", () => {
-    const overrides: Partial<Knobs> = { borderRadius: "none", space: "small" };
+    const overrides: Partial<Knobs> = { borderRadius: "none", textAccent: "low" };
     expect(readOverridesCookie({ "mp.ov.0": JSON.stringify(overrides) })).toEqual(overrides);
   });
 
@@ -125,7 +127,7 @@ describe("readOverridesCookie with universal-cookie auto-parsed values", () => {
   });
 
   it("round-trips writeOverridesCookie output through an auto-parsing jar", () => {
-    const overrides: Partial<Knobs> = { density: "compact", fillStyle: "outlined" };
+    const overrides: Partial<Knobs> = { elevation: "none", fillStyle: "outlined" };
     const { toSet } = writeOverridesCookie(overrides);
     // Simulate universal-cookie readCookie: JSON.parse succeeds on the
     // single-chunk value, so the jar hands back an object.
@@ -135,7 +137,7 @@ describe("readOverridesCookie with universal-cookie auto-parsed values", () => {
 
   it("round-trips oversized multi-chunk payloads through an auto-parsing jar", () => {
     const bigValue = "x".repeat(8000);
-    const overrides = { animation: bigValue } as unknown as Partial<Knobs>;
+    const overrides = { headingFont: bigValue } as unknown as Partial<Knobs>;
     const { toSet } = writeOverridesCookie(overrides);
     expect(toSet.length).toBeGreaterThan(1);
     // universal-cookie leaves each chunk a string: a JSON fragment throws in
@@ -239,9 +241,9 @@ describe("computeOverrides", () => {
   });
 
   it("returns only changed keys", () => {
-    const current: Knobs = { ...defaultKnobs, fillStyle: "outlined", size: "large" };
+    const current: Knobs = { ...defaultKnobs, fillStyle: "outlined", elevation: "large" };
     const overrides = computeOverrides(defaultKnobs, current);
-    expect(overrides).toEqual({ fillStyle: "outlined", size: "large" });
+    expect(overrides).toEqual({ fillStyle: "outlined", elevation: "large" });
   });
 
   it("does not include unchanged keys", () => {
@@ -250,17 +252,22 @@ describe("computeOverrides", () => {
     expect(Object.keys(overrides)).toEqual(["fillStyle"]);
   });
 
-  it("persists density override via mp.ov.* pattern", () => {
-    const current: Knobs = { ...defaultKnobs, density: "compact" };
-    const overrides = computeOverrides(defaultKnobs, current);
-    expect(overrides).toEqual({ density: "compact" });
-
-    const { toSet } = writeOverridesCookie(overrides);
-    expect(toSet[0].key).toBe("mp.ov.0");
-    expect(JSON.parse(toSet[0].value)).toEqual({ density: "compact" });
-
-    const roundtrip = readOverridesCookie({ "mp.ov.0": toSet[0].value });
-    expect(roundtrip).toEqual({ density: "compact" });
+  it("drops a stale size / space / density override a cookie still carries", () => {
+    const stale = JSON.stringify({
+      size: "large",
+      space: "small",
+      density: "compact",
+      fillStyle: "outlined",
+      hover: { space: "large", elevation: "medium" },
+    });
+    expect(readOverridesCookie({ "mp.ov.0": stale })).toEqual({
+      fillStyle: "outlined",
+      hover: { elevation: "medium" },
+    });
+    expect(isKnobKey("density")).toBe(false);
+    expect(isKnobKey("space")).toBe(false);
+    expect(isKnobKey("size")).toBe(false);
+    expect(isKnobKey("borderRadius")).toBe(true);
   });
 
   it("persists house-decision overrides via mp.ov.* pattern", () => {
@@ -299,3 +306,27 @@ describe("getCookieWatchList", () => {
     expect(getCookieWatchList()).toHaveLength(11);
   });
 });
+
+describe("persisted animation knobs", () => {
+  it.each([
+    ["tooltip", "slow"],
+    ["snappy", "quickest"],
+    ["gentle", "slow"],
+    ["quick", "quick"],
+    ["none", "none"],
+    ["superLazy", "superLazy"],
+  ])("normalizes %s to %s", (stored, expected) => {
+    expect(sanitizeOverrides({ animation: stored })).toEqual({ animation: expected });
+    expect(readOverridesCookie({ "mp.ov.0": JSON.stringify({ animation: stored }) })).toEqual({
+      animation: expected,
+    });
+  });
+  it.each(["100ms", "ease", "unknown", 100, null, { hover: "quick" }])(
+    "drops unknown animation %s",
+    (animation) => {
+      expect(sanitizeOverrides({ animation, borderRadius: "small" })).toEqual({
+        borderRadius: "small",
+      });
+    },
+  );
+});

package/src/theme/cookies.ts

@@ -11,7 +11,7 @@
  */
 
 import { getCookie, setCookie, deleteCookie } from "@multiplatform.one/platform";
-import type { Knobs } from "./knobs";
+import { type Knobs, type StateKnobs, defaultKnobs, normalizeAnimationKnob } from "./knobs";
 
 // ---------------------------------------------------------------------------
 // Cookie key constants
@@ -69,25 +69,54 @@ function chunkKey(index: number): string {
 // Cookie read helpers (work with raw cookie objects from react-cookie)
 // ---------------------------------------------------------------------------
 
+/**
+ * The knob names an overrides payload may carry; anything else is dropped,
+ * including the retired `size` / `space` / `density` a stale cookie holds.
+ */
+const knobKeys = new Set<string>(Object.keys(defaultKnobs));
+
+/** True when `key` names a live knob (stale and foreign names are not). */
+export function isKnobKey(key: string): key is keyof Knobs {
+  return knobKeys.has(key);
+}
+
+const stateKnobKeys = new Set<string>([
+  "fillStyle",
+  "borderRadius",
+  "borderWidth",
+  "elevation",
+  "textAccent",
+  "headingFont",
+  "bodyFont",
+  "fontWeight",
+] satisfies (keyof StateKnobs)[]);
+
 /**
  * Shape-validate a parsed overrides payload before it reaches knob
  * resolution: keep knob-shaped entries — string values plus one-level
- * StateKnobs-style objects of string values (`hover`, `press`, …) — and drop
- * everything else, so a corrupt or foreign cookie can never spread garbage
- * (arrays, numbers, deep objects) into `{ ...preset.knobs, ...overrides }`.
+ * StateKnobs-style objects of string values (`hover`, `press`, …) — under a
+ * known knob name, and drop everything else, so a corrupt, foreign or stale
+ * cookie can never spread garbage (unknown keys, arrays, numbers, deep
+ * objects) into `{ ...preset.knobs, ...overrides }`.
  */
-function sanitizeOverrides(parsed: unknown): Partial<Knobs> {
+export function sanitizeOverrides(parsed: unknown): Partial<Knobs> {
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     return {};
   }
   const overrides: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(parsed)) {
-    if (typeof value === "string") {
+    if (!knobKeys.has(key)) continue;
+    if (key === "animation") {
+      const animation = normalizeAnimationKnob(value);
+      if (animation !== undefined) overrides.animation = animation;
+    } else if (typeof value === "string") {
       overrides[key] = value;
     } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
       const nested: Record<string, string> = {};
       for (const [stateKey, stateValue] of Object.entries(value)) {
-        if (typeof stateValue === "string") nested[stateKey] = stateValue;
+        if (stateKnobKeys.has(stateKey) && typeof stateValue === "string") {
+          nested[stateKey] = stateValue;
+        }
       }
       overrides[key] = nested;
     }