@multiplatform.one/theme 6.1.0 → 6.4.0

package/src/theme/FontKnobStyles.native.tsx

@@ -0,0 +1,24 @@
+/**
+ * Native no-op. React Native has no CSS variables, so the web-only
+ * `.font_heading` / `.font_body` --f-family override cannot apply. On native,
+ * components consume the font knobs through `knobProps.heading` /
+ * `knobProps.body` from useResolvedKnobs (see e.g. public/components
+ * layouts/page.tsx).
+ */
+import type { FontCategory } from "./knobs";
+
+export function getConfiguredFontFamily(_category: FontCategory): string | undefined {
+  return undefined;
+}
+
+export function buildFontKnobCss(
+  _headingFont: FontCategory,
+  _bodyFont: FontCategory,
+  _resolveFamily?: (category: FontCategory) => string | undefined,
+): string {
+  return "";
+}
+
+export function FontKnobStyles() {
+  return null;
+}

package/src/theme/FontKnobStyles.tsx

@@ -0,0 +1,256 @@
+/**
+ * FontKnobStyles — makes the headingFont/bodyFont knobs retheme EVERY
+ * heading/body text on web without per-component wiring.
+ *
+ * How it works: on web Tamagui renders text with a font-scope class
+ * (`font_heading`, `font_body`, …) and resolves `font-family` through the
+ * scoped CSS variable `--f-family` (rule: `:root .font_heading { --f-family:
+ * Inter, … }`). Overriding that one variable per scope swaps the rendered
+ * family of every H1–H6 (`$heading`) and every default/body text (`$body`)
+ * at once, keeping the size scale intact.
+ *
+ * Density: the base lineHeight/letterSpacing tables are tuned for Inter
+ * (display leading ~1.16, negative tracking at large sizes). Most other
+ * families need looser leading — mono/serif/script glyphs fill more of the
+ * em box, so Inter's leading reads squished on them. Each category declares
+ * a minimum lineHeight:fontSize ratio in `fontCategoryMetrics`; sizes whose
+ * base leading falls below the floor get a scoped `--f-lineHeight-N`
+ * override (same var the text classes already consume), and "neutral"
+ * tracking categories zero out Inter's tracking-by-size letterSpacing.
+ *
+ * Components that explicitly set another font token (e.g. `fontFamily="$mono"`
+ * code blocks, or `knobProps.heading` consumers) carry a different font class
+ * and are untouched.
+ *
+ * Native has no CSS variables — there, components must consume
+ * `knobProps.heading` / `knobProps.body` (see FontKnobStyles.native.tsx no-op).
+ */
+import { getConfig } from "@tamagui/web";
+import { useEffect } from "react";
+import type { FontCategory } from "./knobs";
+import { defaultKnobs } from "./knobs";
+import { usePresetContext } from "./PresetContext";
+
+const STYLE_TAG_ID = "mp-font-knob-styles";
+
+/**
+ * Per-category legibility floors, applied on top of the base (Inter-tuned)
+ * lineHeight tables when the heading/body knob selects that category.
+ * `heading`/`body` are minimum lineHeight:fontSize ratios; `letterSpacing:
+ * "neutral"` zeroes Inter's tracking-by-size curve (wrong for fixed-pitch
+ * and connected-script families). "sans-serif" is the default scope (never
+ * overridden), listed for completeness.
+ */
+export const fontCategoryMetrics: Record<
+  FontCategory,
+  { heading: number; body: number; letterSpacing: "inherit" | "neutral" }
+> = {
+  "sans-serif": { heading: 1.15, body: 1.4, letterSpacing: "inherit" },
+  serif: { heading: 1.2, body: 1.4, letterSpacing: "inherit" },
+  mono: { heading: 1.25, body: 1.45, letterSpacing: "neutral" },
+  // Heading floors below are sized to each configured face's em box
+  // (ascent+descent) so display headings never clip (LC-11): Roboto Slab
+  // ≈1.32, Nunito ≈1.36, Silkscreen ≈1.3, Poppins/Futura ≈1.4.
+  slab: { heading: 1.35, body: 1.4, letterSpacing: "inherit" },
+  rounded: { heading: 1.4, body: 1.4, letterSpacing: "inherit" },
+  condensed: { heading: 1.15, body: 1.4, letterSpacing: "inherit" },
+  cursive: { heading: 1.3, body: 1.5, letterSpacing: "neutral" },
+  handwriting: { heading: 1.25, body: 1.45, letterSpacing: "neutral" },
+  pixel: { heading: 1.35, body: 1.4, letterSpacing: "neutral" },
+  blackletter: { heading: 1.3, body: 1.45, letterSpacing: "neutral" },
+  geometric: { heading: 1.45, body: 1.4, letterSpacing: "inherit" },
+};
+
+// Default leading for font-scoped text that carries no explicit lineHeight
+// (e.g. `Text fontFamily="$body" fontSize=…` renders `line-height: normal`
+// ≈1.2 — under every category's body floor). Emitted at ZERO specificity
+// (`:where()`) so any sized text keeps its per-size table value, while
+// unsized text meets the category floor (LC-11). The minimums keep the
+// default scope comfortable even where a category floor is lower.
+const DEFAULT_HEADING_LEADING_MIN = 1.25;
+const DEFAULT_BODY_LEADING_MIN = 1.5;
+
+/** Zero-specificity default line-height rule for one font scope. */
+function defaultLeadingRule(scope: "heading" | "body", category: FontCategory): string {
+  const metrics = fontCategoryMetrics[category] ?? fontCategoryMetrics["sans-serif"];
+  const ratio = Math.max(
+    metrics[scope],
+    scope === "heading" ? DEFAULT_HEADING_LEADING_MIN : DEFAULT_BODY_LEADING_MIN,
+  );
+  return `:where(:root .font_${scope}) { line-height: ${ratio}; }`;
+}
+
+/** Numeric font tables for a purpose font, keyed WITHOUT the `$` prefix. */
+export interface FontScopeTables {
+  size: Record<string, number>;
+  lineHeight: Record<string, number>;
+  letterSpacing?: Record<string, number>;
+}
+
+/**
+ * Resolve the concrete font-family stack registered in the Tamagui config for
+ * a font category. Returns undefined when the category font is not registered
+ * (the caller then leaves the default family in place).
+ */
+export function getConfiguredFontFamily(category: FontCategory): string | undefined {
+  let config: ReturnType<typeof getConfig> | undefined;
+  try {
+    config = getConfig();
+  } catch {
+    return undefined;
+  }
+  const fontsParsed = (config as { fontsParsed?: Record<string, unknown> }).fontsParsed;
+  const font = (fontsParsed?.[`$${category}`] ?? config.fonts?.[category]) as
+    | { family?: string | { val?: string } }
+    | undefined;
+  const family = font?.family;
+  if (typeof family === "string") return family;
+  if (family && typeof family.val === "string") return family.val;
+  return undefined;
+}
+
+/**
+ * Read the numeric size/lineHeight/letterSpacing tables of the `$heading` /
+ * `$body` purpose font from the Tamagui config, keys normalized without the
+ * `$` prefix (matching the emitted `--f-lineHeight-<key>` CSS var names).
+ * Returns undefined outside a configured Tamagui runtime (unit tests, SSR
+ * before setup) — callers then emit family-only overrides.
+ */
+export function getConfiguredFontTables(scope: "heading" | "body"): FontScopeTables | undefined {
+  let config: ReturnType<typeof getConfig> | undefined;
+  try {
+    config = getConfig();
+  } catch {
+    return undefined;
+  }
+  const fontsParsed = (config as { fontsParsed?: Record<string, unknown> }).fontsParsed;
+  const font = (fontsParsed?.[`$${scope}`] ?? config.fonts?.[scope]) as
+    | Record<string, Record<string, number | { val?: number }> | undefined>
+    | undefined;
+  if (!font) return undefined;
+  const unwrap = (
+    table: Record<string, number | { val?: number }> | undefined,
+  ): Record<string, number> | undefined => {
+    if (!table) return undefined;
+    const out: Record<string, number> = {};
+    for (const [key, value] of Object.entries(table)) {
+      const num =
+        typeof value === "number"
+          ? value
+          : value && typeof value.val === "number"
+            ? value.val
+            : undefined;
+      if (num !== undefined) out[key.replace(/^\$/, "")] = num;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  };
+  const size = unwrap(font.size);
+  const lineHeight = unwrap(font.lineHeight);
+  if (!size || !lineHeight) return undefined;
+  return { size, lineHeight, letterSpacing: unwrap(font.letterSpacing) };
+}
+
+/** Build the full override rule for one font scope (heading or body). */
+function buildScopeRule(
+  scope: "heading" | "body",
+  category: FontCategory,
+  family: string,
+  tables: FontScopeTables | undefined,
+): string {
+  const metrics = fontCategoryMetrics[category];
+  const decls = [`--f-family: ${family} !important`];
+  if (tables && metrics) {
+    const minRatio = metrics[scope];
+    for (const [key, size] of Object.entries(tables.size)) {
+      const baseLineHeight = tables.lineHeight[key];
+      if (typeof baseLineHeight !== "number") continue;
+      const floor = Math.round(size * minRatio);
+      if (baseLineHeight < floor) {
+        decls.push(`--f-lineHeight-${key}: ${floor}px !important`);
+      }
+    }
+    if (metrics.letterSpacing === "neutral" && tables.letterSpacing) {
+      // Inter's tracking-by-size curve (negative display tracking AND
+      // positive caption tracking) is Inter-specific: fixed-pitch faces must
+      // keep their pitch and connected scripts break when tracked apart, so
+      // "neutral" zeroes every non-zero entry (LC-11).
+      for (const [key, tracking] of Object.entries(tables.letterSpacing)) {
+        if (tracking !== 0) decls.push(`--f-letterSpacing-${key}: 0px !important`);
+      }
+    }
+  }
+  return `:root .font_${scope} { ${decls.join("; ")}; }`;
+}
+
+/**
+ * Build the CSS override for the current headingFont/bodyFont knob values.
+ * Always emits the zero-specificity default-leading rules (unsized scoped
+ * text must meet the active category's line-height floor — LC-11); family
+ * and per-size overrides are added for non-default categories. Exported for
+ * unit testing.
+ */
+export function buildFontKnobCss(
+  headingFont: FontCategory,
+  bodyFont: FontCategory,
+  resolveFamily: (category: FontCategory) => string | undefined = getConfiguredFontFamily,
+  resolveTables: (
+    scope: "heading" | "body",
+  ) => FontScopeTables | undefined = getConfiguredFontTables,
+): string {
+  const rules: string[] = [
+    defaultLeadingRule("heading", headingFont),
+    defaultLeadingRule("body", bodyFont),
+  ];
+  if (headingFont !== "sans-serif") {
+    const family = resolveFamily(headingFont);
+    if (family) {
+      rules.push(buildScopeRule("heading", headingFont, family, resolveTables("heading")));
+    }
+  }
+  if (bodyFont !== "sans-serif") {
+    const family = resolveFamily(bodyFont);
+    if (family) {
+      rules.push(buildScopeRule("body", bodyFont, family, resolveTables("body")));
+    }
+  }
+  return rules.join("\n");
+}
+
+/**
+ * Mount ONCE near the root (inside the Preset/PresetContext provider). Reads
+ * the active headingFont/bodyFont knobs and syncs a `<style>` override so all
+ * `$heading`/`$body` text follows the knobs. Renders nothing.
+ */
+export function FontKnobStyles() {
+  const presetCtx = usePresetContext();
+  const knobs = presetCtx ? { ...presetCtx.preset.knobs, ...presetCtx.overrides } : defaultKnobs;
+  const headingFont = knobs.headingFont ?? defaultKnobs.headingFont;
+  const bodyFont = knobs.bodyFont ?? defaultKnobs.bodyFont;
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const css = buildFontKnobCss(headingFont, bodyFont);
+    let tag = document.getElementById(STYLE_TAG_ID) as HTMLStyleElement | null;
+    if (!css) {
+      tag?.remove();
+      return;
+    }
+    if (!tag) {
+      tag = document.createElement("style");
+      tag.id = STYLE_TAG_ID;
+      document.head.appendChild(tag);
+    }
+    if (tag.textContent !== css) tag.textContent = css;
+  }, [headingFont, bodyFont]);
+
+  useEffect(
+    () => () => {
+      if (typeof document !== "undefined") {
+        document.getElementById(STYLE_TAG_ID)?.remove();
+      }
+    },
+    [],
+  );
+
+  return null;
+}

package/src/theme/animations/reactNative.ts

@@ -1,6 +1,11 @@
 import { createAnimations } from "@tamagui/animations-react-native";
 
-const animationConfig = {
+/**
+ * Canonical spring vocabulary. Exported so native gesture code can drive
+ * RN `Animated.spring` (which provides completion callbacks) with the exact
+ * same physics as Tamagui's `transition` tokens — one closed vocabulary.
+ */
+export const animationConfig = {
   bouncy: {
     type: "spring",
     damping: 9,

package/src/theme/chartPalette.spec.ts

@@ -0,0 +1,159 @@
+import * as Colors from "@tamagui/colors";
+import { describe, expect, it } from "vitest";
+import { resolveChartPalette } from "./chartPalette";
+import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+
+// The default accent solid (accentBackground) from defaults/accent.ts.
+const lightAccent = "hsla(250, 50%, 54%, 1)";
+const darkAccent = "hsla(250, 50%, 60%, 1)";
+// Tint identity solids as the stock tint sub-themes resolve $color9.
+const redTintSolid = "hsl(358, 75.0%, 59.0%)";
+const purpleTintSolid = "hsl(272, 46.8%, 50.3%)";
+const tomatoTintSolid = "hsl(10, 78.0%, 54.0%)";
+const grayTintSolid = "hsla(270, 6%, 56%, 1)";
+
+function hexToHsl(color: string): { h: number; s: number; l: number } {
+  const hex = normalizeToHex(color);
+  if (!hex) throw new Error(`unparseable color: ${color}`);
+  const r = Number.parseInt(hex.slice(1, 3), 16) / 255;
+  const g = Number.parseInt(hex.slice(3, 5), 16) / 255;
+  const b = Number.parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) return { h: 0, s: 0, l };
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h: number;
+  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) * 60;
+  else if (max === g) h = ((b - r) / d + 2) * 60;
+  else h = ((r - g) / d + 4) * 60;
+  return { h, s, l };
+}
+
+function hueDistance(a: number, b: number): number {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+}
+
+/**
+ * Distinguishability bar for ADJACENT categorical marks. A pair is tellable
+ * apart when at least one perceptual channel separates it: hue (≥30° between
+ * saturated colors), saturation (neutral vs vivid, delta ≥0.5), or luminance
+ * (contrast ≥1.5:1).
+ */
+function adjacentDistinguishable(a: string, b: string): boolean {
+  const ha = hexToHsl(a);
+  const hb = hexToHsl(b);
+  if (ha.s >= 0.15 && hb.s >= 0.15 && hueDistance(ha.h, hb.h) >= 30) return true;
+  if (Math.abs(ha.s - hb.s) >= 0.5) return true;
+  const la = relativeLuminance(normalizeToHex(a) as string);
+  const lb = relativeLuminance(normalizeToHex(b) as string);
+  return contrastRatio(la, lb) >= 1.5;
+}
+
+describe("resolveChartPalette", () => {
+  it("single-series takes the theme identity solid", () => {
+    expect(resolveChartPalette({ scheme: "light", identitySolid: lightAccent }).single).toBe(
+      lightAccent,
+    );
+    expect(resolveChartPalette({ scheme: "dark", identitySolid: darkAccent }).single).toBe(
+      darkAccent,
+    );
+  });
+
+  it("categorical palette is identity-led", () => {
+    const palette = resolveChartPalette({ scheme: "light", identitySolid: lightAccent });
+    expect(palette.categorical[0]).toBe(lightAccent);
+  });
+
+  it("drops the cycle hue confusable with the accent identity (violet)", () => {
+    const palette = resolveChartPalette({ scheme: "light", identitySolid: lightAccent });
+    expect(palette.categorical).not.toContain(Colors.violet.violet9);
+    expect(palette.categorical).toContain(Colors.blue.blue9);
+    expect(palette.categorical).toHaveLength(8);
+  });
+
+  it("re-anchors under a red tint and drops the red cycle hue", () => {
+    const palette = resolveChartPalette({ scheme: "light", identitySolid: redTintSolid });
+    expect(palette.categorical[0]).toBe(redTintSolid);
+    expect(palette.categorical).not.toContain(Colors.red.red9);
+    expect(palette.categorical).toContain(Colors.violet.violet9);
+  });
+
+  it("re-anchors under a purple tint and drops the violet cycle hue", () => {
+    const palette = resolveChartPalette({ scheme: "light", identitySolid: purpleTintSolid });
+    expect(palette.categorical[0]).toBe(purpleTintSolid);
+    expect(palette.categorical).not.toContain(Colors.violet.violet9);
+    expect(palette.categorical).toContain(Colors.red.red9);
+  });
+
+  it("drops every cycle hue within the confusable band (tomato drops red and orange)", () => {
+    const palette = resolveChartPalette({ scheme: "light", identitySolid: tomatoTintSolid });
+    expect(palette.categorical).not.toContain(Colors.red.red9);
+    expect(palette.categorical).not.toContain(Colors.orange.orange9);
+    expect(palette.categorical).toHaveLength(7);
+  });
+
+  it("keeps the full cycle behind a neutral identity (gray tint)", () => {
+    const palette = resolveChartPalette({ scheme: "light", identitySolid: grayTintSolid });
+    expect(palette.categorical[0]).toBe(grayTintSolid);
+    expect(palette.categorical).toHaveLength(9);
+  });
+
+  it("falls back to the violet ramp solid when identity is missing or unparseable", () => {
+    const missing = resolveChartPalette({ scheme: "light" });
+    expect(missing.single).toBe(Colors.violet.violet9);
+    const unparseable = resolveChartPalette({
+      scheme: "light",
+      identitySolid: "var(--accentBackground)",
+    });
+    expect(unparseable.single).toBe(Colors.violet.violet9);
+    // Fallback identity still dedupes its own hue family from the cycle.
+    expect(unparseable.categorical.filter((c) => c === Colors.violet.violet9)).toHaveLength(1);
+  });
+
+  it("semantic series come from the sanctioned semantic ramps, scheme-aware", () => {
+    const light = resolveChartPalette({ scheme: "light", identitySolid: lightAccent });
+    const dark = resolveChartPalette({ scheme: "dark", identitySolid: darkAccent });
+    expect(light.semantic.error).toBe(Colors.red.red9);
+    expect(light.semantic.success).toBe(Colors.green.green9);
+    expect(light.semantic.warning).toBe(Colors.yellow.yellow11);
+    expect(dark.semantic.error).toBe(Colors.redDark.red9);
+    expect(dark.semantic.success).toBe(Colors.greenDark.green9);
+    expect(dark.semantic.warning).toBe(Colors.yellowDark.yellow9);
+    // Warning adapts per scheme (yellow9 is ~1.3:1 against light surfaces).
+    expect(light.semantic.warning).not.toBe(dark.semantic.warning);
+  });
+
+  it("keeps adjacent categorical marks distinguishable in light and dark for every identity", () => {
+    const identities = [
+      lightAccent,
+      darkAccent,
+      redTintSolid,
+      purpleTintSolid,
+      tomatoTintSolid,
+      grayTintSolid,
+      undefined,
+    ];
+    for (const scheme of ["light", "dark"] as const) {
+      for (const identitySolid of identities) {
+        const palette = resolveChartPalette({ scheme, identitySolid });
+        for (let i = 0; i < palette.categorical.length - 1; i++) {
+          const a = palette.categorical[i];
+          const b = palette.categorical[i + 1];
+          expect(
+            adjacentDistinguishable(a, b),
+            `${scheme} identity=${identitySolid ?? "(none)"} pair ${i}: ${a} vs ${b}`,
+          ).toBe(true);
+        }
+      }
+    }
+  });
+
+  it("is pure and stable for identical input", () => {
+    const a = resolveChartPalette({ scheme: "dark", identitySolid: redTintSolid });
+    const b = resolveChartPalette({ scheme: "dark", identitySolid: redTintSolid });
+    expect(a).toEqual(b);
+  });
+});

package/src/theme/chartPalette.ts

@@ -0,0 +1,170 @@
+import * as Colors from "@tamagui/colors";
+import { useMemo } from "react";
+import { useTheme as useTamaguiTheme, useThemeName } from "tamagui";
+import { normalizeToHex } from "./colorRules";
+import { tintHueNames } from "./createThemes";
+
+/**
+ * Chart palette contract (SB-D-07 / SB-D-25 GAP closure).
+ *
+ * Charts are chrome that renders data, so their DEFAULT colors must come from
+ * the one theme channel (Axiom 5 ONE SOURCE) while explicit user/data colors
+ * pass through untouched (Axiom 11 VALUE IS DATA):
+ *
+ * - `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
+ *   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.
+ * - `semantic` — error/success/warning series solids from the sanctioned
+ *   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
+ * stay resolvable on native and under tint sub-themes (which only carry the
+ * re-ramped neutral family).
+ */
+export interface ChartPalette {
+  /** Scheme the palette resolved for. */
+  scheme: "light" | "dark";
+  /** Theme-identity solid: paints every mark of a single-series chart. */
+  single: string;
+  /** Identity-led distinguishable solids for categorical multi-series data. */
+  categorical: string[];
+  /** Semantic series solids (trend/status series), tint-independent. */
+  semantic: { error: string; success: string; warning: string };
+}
+
+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).
+   */
+  identitySolid?: string;
+}
+
+/**
+ * Fixed categorical hue cycle: Radix step-9 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.
+ */
+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: "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: "red", light: Colors.red.red9, dark: Colors.redDark.red9 },
+] as const;
+
+/**
+ * Semantic series solids. Error/success use the step-9 solids. 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).
+ */
+const semanticSeries = {
+  light: {
+    error: Colors.red.red9,
+    success: Colors.green.green9,
+    warning: Colors.yellow.yellow11,
+  },
+  dark: {
+    error: Colors.redDark.red9,
+    success: Colors.greenDark.green9,
+    warning: Colors.yellowDark.yellow9,
+  },
+} as const;
+
+/** Below this HSL saturation the identity is neutral-ish; hue is meaningless. */
+const neutralSaturationFloor = 0.15;
+/** Cycle hues closer than this to the identity hue are dropped as confusable. */
+const hueDedupeThresholdDeg = 30;
+
+interface Hsl {
+  h: number;
+  s: number;
+  l: number;
+}
+
+function colorToHsl(color: string): Hsl | null {
+  const hex = normalizeToHex(color);
+  if (!hex) return null;
+  const r = Number.parseInt(hex.slice(1, 3), 16) / 255;
+  const g = Number.parseInt(hex.slice(3, 5), 16) / 255;
+  const b = Number.parseInt(hex.slice(5, 7), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) return { h: 0, s: 0, l };
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h: number;
+  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) * 60;
+  else if (max === g) h = ((b - r) / d + 2) * 60;
+  else h = ((r - g) / d + 4) * 60;
+  return { h, s, l };
+}
+
+function hueDistance(a: number, b: number): number {
+  const d = Math.abs(a - b) % 360;
+  return d > 180 ? 360 - d : d;
+}
+
+/**
+ * Pure palette resolution — see {@link ChartPalette} for the contract.
+ * Exported separately from the hook so tests and non-React callers can
+ * resolve palettes for any scheme/identity combination.
+ */
+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 cycle = categoricalHueCycle.map((entry) => (scheme === "dark" ? entry.dark : entry.light));
+  const deduped =
+    identityHsl.s < neutralSaturationFloor
+      ? cycle
+      : cycle.filter((value) => {
+          const hsl = colorToHsl(value);
+          if (!hsl) return true;
+          return hueDistance(hsl.h, identityHsl.h) >= hueDedupeThresholdDeg;
+        });
+
+  return {
+    scheme,
+    single,
+    categorical: [single, ...deduped],
+    semantic: semanticSeries[scheme],
+  };
+}
+
+/**
+ * Canonical chart palette for the active Tamagui theme.
+ *
+ * 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
+ * series colors from this hook; explicit `color`/`colors` props on chart
+ * data are user values and pass through untouched.
+ */
+export function useChartPalette(): ChartPalette {
+  const themeName = useThemeName() as string | undefined;
+  const theme = useTamaguiTheme() as unknown as Record<string, { val?: string } | undefined>;
+  const scheme: "light" | "dark" = themeName?.startsWith("dark") ? "dark" : "light";
+  const nameParts = (themeName ?? "").split("_");
+  const isTint = nameParts.length > 1 && tintHueNames.has(nameParts[1]);
+  const color9 = theme.color9?.val;
+  const accent = theme.accentBackground?.val;
+  const identitySolid = isTint ? (color9 ?? accent) : (accent ?? color9);
+  return useMemo(() => resolveChartPalette({ scheme, identitySolid }), [scheme, identitySolid]);
+}

package/src/theme/colorRules.ts

@@ -34,8 +34,13 @@ export function normalizeToHex(raw: string): string | null {
     if (s.length === 4) return `#${s[1]}${s[1]}${s[2]}${s[2]}${s[3]}${s[3]}`;
     return s;
   }
-  const hslMatch = s.match(/hsl\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)/);
+  const hslMatch = s.match(
+    /hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*(?:,\s*([\d.]+)\s*)?\)/,
+  );
   if (hslMatch) {
+    // Treat only fully-opaque hsla as a plain color; alpha blends depend on
+    // the backdrop and cannot be reduced to a single hex.
+    if (hslMatch[4] !== undefined && Number(hslMatch[4]) < 0.999) return null;
     const h = Number(hslMatch[1]);
     const sat = Number(hslMatch[2]) / 100;
     const l = Number(hslMatch[3]) / 100;
@@ -69,6 +74,33 @@ export function contrastRatio(l1: number, l2: number): number {
 
 export const minContrastRatio = 3;
 
+/** WCAG AA contrast floor for normal-size body/label text. */
+export const aaTextContrastRatio = 4.5;
+
+/**
+ * Axiom 15 OPTICS — pick whichever candidate foreground carries more WCAG
+ * contrast on a given `fill`. The canonical "readable foreground on a fill"
+ * primitive: intent Buttons (defaults/builderOptions), the Switch thumb and
+ * on-accent labels (useReadableTextOn) all reduce to this. Inputs/outputs are
+ * raw color strings so callers keep their own tokens/hsla; returns
+ * `candidateA` unchanged when any color fails to parse (safe default).
+ */
+export function pickReadableForeground(
+  fill: string,
+  candidateA: string,
+  candidateB: string,
+): string {
+  const fillHex = normalizeToHex(fill);
+  const aHex = normalizeToHex(candidateA);
+  const bHex = normalizeToHex(candidateB);
+  if (!fillHex || !aHex || !bHex) return candidateA;
+  const fillLum = relativeLuminance(fillHex);
+  return contrastRatio(relativeLuminance(aHex), fillLum) >=
+    contrastRatio(relativeLuminance(bHex), fillLum)
+    ? candidateA
+    : candidateB;
+}
+
 /**
  * Given a 12-color scale (hex strings), a background step, and a starting
  * text step, scan towards `preferredDir` for the first step whose contrast