@multiplatform.one/theme 6.1.0 → 6.4.0

package/src/devWarn.ts

@@ -0,0 +1,235 @@
+/**
+ * Tree-shaken DEV guardrails (blueprint §5).
+ * No-ops when `NODE_ENV === "production"`.
+ *
+ * W12 owns `outline-none` + `positive-tabindex`. Other codes are catalogued
+ * here so consumers share one tree-shaken entry point.
+ */
+
+export type DevWarnCode =
+  | "placeholder-as-label"
+  | "two-primaries"
+  | "banned-error-word"
+  | "bare-disabled"
+  | "cancel-disabled"
+  | "dialog-too-many-actions"
+  | "select-too-few-options"
+  | "positive-tabindex"
+  | "tooltip-on-disabled"
+  | "outline-none"
+  // DG-A11Y-02 — a second level-1 heading mounted under one page scope.
+  // Emitted by PageHeadingScope in @multiplatform.one/components.
+  | "multiple-h1";
+
+export type DevWarnDetail = {
+  component?: string;
+  id?: string;
+  value?: unknown;
+  word?: string;
+  count?: number;
+  suggest?: string;
+  region?: string;
+  [key: string]: unknown;
+};
+
+const seen = new Set<string>();
+
+function isDev(): boolean {
+  return process.env.NODE_ENV !== "production";
+}
+
+/**
+ * Emit a once-per-key console warning in non-production builds.
+ */
+export function devWarn(code: DevWarnCode, detail: DevWarnDetail = {}): void {
+  if (!isDev()) return;
+  const key = [
+    code,
+    detail.component ?? "",
+    detail.id ?? "",
+    detail.region ?? "",
+    String(detail.value ?? ""),
+    detail.word ?? "",
+    detail.count ?? "",
+  ].join(":");
+  if (seen.has(key)) return;
+  seen.add(key);
+  const bits = [
+    detail.component ? `component=${detail.component}` : undefined,
+    detail.id ? `id=${detail.id}` : undefined,
+    detail.region ? `region=${detail.region}` : undefined,
+    detail.value !== undefined ? `value=${String(detail.value)}` : undefined,
+    detail.word ? `word=${detail.word}` : undefined,
+    detail.count !== undefined ? `count=${detail.count}` : undefined,
+    detail.suggest ? `suggest=${detail.suggest}` : undefined,
+  ].filter(Boolean);
+  const suffix = bits.length ? ` (${bits.join(", ")})` : "";
+  console.warn(`[theme] ${code}${suffix}`);
+}
+
+/** @internal test helper */
+export function __resetDevWarnSeen(): void {
+  seen.clear();
+}
+
+/** Alias kept for callers that imported the W12-era name. */
+export const themeDevWarn = devWarn;
+export const __resetThemeDevWarnSeen = __resetDevWarnSeen;
+
+/**
+ * DG-FORM-02 / DG-FORM-11: placeholder must not be the only label.
+ */
+export function warnPlaceholderAsLabel(args: {
+  placeholder?: string | null;
+  label?: unknown;
+  ariaLabel?: string | null;
+  id?: string;
+  component?: string;
+}): void {
+  if (!isDev()) return;
+  const placeholder = typeof args.placeholder === "string" ? args.placeholder.trim() : "";
+  if (!placeholder) return;
+  if (args.label != null && args.label !== false && args.label !== "") return;
+  const ariaLabel = typeof args.ariaLabel === "string" ? args.ariaLabel.trim() : "";
+  if (ariaLabel) return;
+  devWarn("placeholder-as-label", {
+    component: args.component ?? "FieldLayout",
+    id: args.id,
+  });
+}
+
+const BANNED_ERROR_WORDS = ["invalid", "error", "please", "sorry", "oops"] as const;
+
+/** DG-COPY-02 / DG-VAL-03 — banned words in error copy. */
+export function warnBannedErrorWords(
+  message: string | null | undefined,
+  detail: DevWarnDetail = {},
+): void {
+  if (!isDev() || !message) return;
+  const lower = message.toLowerCase();
+  for (const word of BANNED_ERROR_WORDS) {
+    if (new RegExp(`\\b${word}\\b`, "i").test(lower)) {
+      devWarn("banned-error-word", { ...detail, word });
+      return;
+    }
+  }
+}
+
+/** DG-ST-03 — bare `disabled` without reason / explain. */
+export function warnBareDisabled(args: {
+  disabled?: boolean;
+  disabledReason?: string | null;
+  skip?: boolean;
+  component?: string;
+  id?: string;
+}): void {
+  if (!isDev() || !args.disabled || args.skip) return;
+  if (typeof args.disabledReason === "string" && args.disabledReason.trim()) return;
+  devWarn("bare-disabled", { component: args.component, id: args.id });
+}
+
+/**
+ * DG-ACT-05 — the cancel/dismiss action never renders disabled (while confirm
+ * may be). Enforcing callers strip the prop and report the attempt here.
+ */
+export function warnCancelDisabled(args: {
+  disabled?: boolean;
+  component?: string;
+  id?: string;
+}): void {
+  if (!isDev() || !args.disabled) return;
+  devWarn("cancel-disabled", { component: args.component, id: args.id });
+}
+
+/** DG-OVL-04 — dialog action rows cap at this many actions by default. */
+export const DIALOG_MAX_ACTIONS = 2;
+
+/**
+ * DG-OVL-04 — max 2 actions in a dialog by default. Warn-only (never a hard
+ * block); `allowManyActions` is the explicit eject acknowledging the extra
+ * actions.
+ */
+export function warnDialogTooManyActions(args: {
+  count: number;
+  allowManyActions?: boolean;
+  component?: string;
+  id?: string;
+}): void {
+  if (!isDev() || args.allowManyActions || args.count <= DIALOG_MAX_ACTIONS) return;
+  devWarn("dialog-too-many-actions", {
+    component: args.component,
+    id: args.id,
+    count: args.count,
+  });
+}
+
+/**
+ * DG-CTRL — Select with too few options; suggest RadioGroup / ToggleGroup.
+ */
+export function warnSelectTooFewOptions(args: {
+  count: number;
+  multiple?: boolean;
+  component?: string;
+  id?: string;
+}): void {
+  if (!isDev() || args.multiple || args.count > 5) return;
+  const suggest = args.count <= 2 ? "ToggleGroup" : "RadioGroup";
+  devWarn("select-too-few-options", {
+    component: args.component,
+    id: args.id,
+    count: args.count,
+    suggest,
+  });
+}
+
+/** DG-A11Y-03 — never `tabIndex` > 0. */
+export function warnPositiveTabIndex(args: {
+  value?: number | string | null;
+  component?: string;
+  id?: string;
+}): void {
+  if (!isDev()) return;
+  const n = typeof args.value === "string" ? Number(args.value) : args.value;
+  if (typeof n !== "number" || Number.isNaN(n) || n <= 0) return;
+  devWarn("positive-tabindex", {
+    component: args.component,
+    id: args.id,
+    value: n,
+  });
+}
+
+/** DG-OVL-05 — no hover tooltip on disabled controls. */
+export function warnTooltipOnDisabled(args: {
+  childDisabled?: boolean;
+  component?: string;
+  id?: string;
+}): void {
+  if (!isDev() || !args.childDisabled) return;
+  devWarn("tooltip-on-disabled", {
+    component: args.component ?? "Tooltip",
+    id: args.id,
+  });
+}
+
+type OutlineLike =
+  | {
+      outline?: string | number;
+      outlineStyle?: string;
+      outlineWidth?: number;
+      outlineColor?: string;
+    }
+  | null
+  | undefined;
+
+/**
+ * DG-A11Y-01 / W12 — warn when a focus style strips the outline.
+ * Call on `focusVisibleStyle` / `focusStyle` only — not resting
+ * `outlineWidth: 0` + transparent (border-flicker rest).
+ */
+export function warnOutlineNone(style: OutlineLike, detail: DevWarnDetail = {}): void {
+  if (!isDev() || !style) return;
+  const stripped =
+    style.outline === "none" || style.outlineStyle === "none" || style.outlineWidth === 0;
+  if (!stripped) return;
+  devWarn("outline-none", detail);
+}

package/src/figma/figmaTokens.spec.ts

@@ -0,0 +1,244 @@
+import * as Colors from "@tamagui/colors";
+import { tokens } from "@tamagui/themes";
+import { describe, expect, it } from "vitest";
+import { normalizeToHex } from "../theme/colorRules";
+import { defaultAccentTheme } from "../theme/defaults/accent";
+import { defaultBaseTheme } from "../theme/defaults/base";
+import { interTrackingPx } from "../theme/defaults/fonts";
+import { FIGMA_THEME_MODES, buildFigmaTokens, figmaTokenName } from "./figmaTokens";
+
+const fontFamilies = {
+  "sans-serif": "Inter",
+  pixel: "'Silkscreen', 'Press Start 2P', monospace",
+};
+
+/**
+ * The Tamagui theme-builder normalizes palette colors (hex→hsla) and may
+ * round interior steps, so source↔built comparisons must be colorimetric.
+ * True when the two CSS colors are within `tolerance` per RGB channel.
+ */
+function sameColor(a: string, b: string, tolerance = 3): boolean {
+  const hexA = normalizeToHex(a);
+  const hexB = normalizeToHex(b);
+  if (!hexA || !hexB) return false;
+  for (let i = 1; i < 7; i += 2) {
+    const channelA = Number.parseInt(hexA.slice(i, i + 2), 16);
+    const channelB = Number.parseInt(hexB.slice(i, i + 2), 16);
+    if (Math.abs(channelA - channelB) > tolerance) return false;
+  }
+  return true;
+}
+
+describe("buildFigmaTokens", () => {
+  const result = buildFigmaTokens({ fontFamilies });
+
+  it("is deterministic (pure transform, golden-comparable)", () => {
+    expect(JSON.stringify(result)).toBe(JSON.stringify(buildFigmaTokens({ fontFamilies })));
+  });
+
+  describe("palette", () => {
+    it("exports the 9 spec theme modes with 12-step light+dark ramps", () => {
+      expect(Object.keys(result.palette.themes)).toEqual([...FIGMA_THEME_MODES]);
+      for (const theme of Object.values(result.palette.themes)) {
+        expect(theme.light).toHaveLength(12);
+        expect(theme.dark).toHaveLength(12);
+      }
+    });
+
+    it("derives base/accent ramps from the canonical default palettes", () => {
+      // The theme-builder rounds/normalizes palette values, so the export
+      // reflects the BUILT runtime themes — every step must still be
+      // colorimetrically the canonical source step.
+      for (const scheme of ["light", "dark"] as const) {
+        const built = result.palette.themes.base[scheme];
+        const source =
+          scheme === "light" ? defaultBaseTheme.lightPalette : defaultBaseTheme.darkPalette;
+        for (let i = 0; i < 12; i++) {
+          expect(sameColor(built[i], source[i])).toBe(true);
+        }
+      }
+      expect(defaultAccentTheme.lightPalette).toContain(result.palette.themes.accent.light[0]);
+      expect(defaultAccentTheme.darkPalette).toContain(result.palette.themes.accent.dark[0]);
+    });
+
+    it("derives intent ramps from @tamagui/colors (error=red, success=green, warning=yellow)", () => {
+      // Built themes carry hsla-normalized values; compare colorimetrically.
+      const includesColor = (ramp: string[], value: string) =>
+        ramp.some((step) => sameColor(step, value));
+      expect(includesColor(result.palette.themes.error.light, Colors.red.red9)).toBe(true);
+      expect(includesColor(result.palette.themes.error.dark, Colors.redDark.red9)).toBe(true);
+      expect(includesColor(result.palette.themes.success.light, Colors.green.green9)).toBe(true);
+      expect(includesColor(result.palette.themes.warning.light, Colors.yellow.yellow9)).toBe(true);
+    });
+
+    it("exports tint ramps with neutralized text tiers (runtime reality, not stock Radix)", () => {
+      // neutralizeTintText re-anchors color11/color12 of tint sub-themes to
+      // the neutral base scheme.
+      expect(result.palette.themes.orange.light[11]).toBe(result.palette.themes.base.light[11]);
+      expect(result.palette.themes.purple.dark[10]).toBe(result.palette.themes.base.dark[10]);
+      // Non-text steps keep the hue.
+      expect(result.palette.themes.orange.light[8]).not.toBe(result.palette.themes.base.light[8]);
+    });
+
+    it("exports 6 shadow steps per scheme from the base theme", () => {
+      expect(Object.keys(result.palette.shadows.light)).toHaveLength(6);
+      expect(result.palette.shadows.light.shadow1).toBe(defaultBaseTheme.lightShadows?.shadow1);
+      expect(result.palette.shadows.dark.shadow6).toBe(defaultBaseTheme.darkShadows?.shadow6);
+    });
+  });
+
+  describe("semantic", () => {
+    it("derives the current interaction-ramp aliases (post-knobs rebuild)", () => {
+      // These pin the drift the May 2026 spec missed: borderColor moved from
+      // color7 to color5, textMuted from color10 to color11.
+      expect(result.semantic.borderColor?.alias).toBe("color5");
+      expect(result.semantic.borderColorHover?.alias).toBe("color6");
+      expect(result.semantic.textMuted?.alias).toBe("color11");
+      expect(result.semantic.backgroundPress?.alias).toBe("color5");
+      expect(result.semantic.backgroundActive?.alias).toBe("color4");
+      expect(result.semantic.placeholderColor?.alias).toBe("color10");
+      expect(result.semantic.surfaceMuted?.alias).toBe("color10");
+      expect(result.semantic.borderStrong?.alias).toBe("color7");
+    });
+
+    it("exports the computed focus ring color (outlineColor) with per-scheme values", () => {
+      const outline = result.semantic.outlineColor;
+      expect(outline).toBeDefined();
+      expect(outline?.light).toBeTruthy();
+      expect(outline?.dark).toBeTruthy();
+    });
+
+    it("derives textAccent knob tiers as text-low/medium/high", () => {
+      expect(result.semantic["text-low"]?.alias).toBe("color11");
+      expect(result.semantic["text-medium"]?.alias).toBe("color11");
+      expect(result.semantic["text-high"]?.alias).toBe("color12");
+    });
+
+    it("excludes raw Radix hue steps (amber1, blueA12, ...) from semantic", () => {
+      const keys = Object.keys(result.semantic);
+      expect(keys.some((key) => /^(amber|blue|red|mauve)A?\d+$/.test(key))).toBe(false);
+      // Semantic surface is role tokens only — small, not the 600+ hue dump.
+      expect(keys.length).toBeGreaterThan(20);
+      expect(keys.length).toBeLessThan(100);
+    });
+
+    it("only aliases when light and dark agree; raw entries keep both values", () => {
+      for (const entry of Object.values(result.semantic)) {
+        if (entry.alias === null) {
+          expect(typeof entry.light).toBe("string");
+          expect(typeof entry.dark).toBe("string");
+        } else {
+          expect(entry.alias).toMatch(/^color([1-9]|1[0-2])$/);
+        }
+      }
+    });
+  });
+
+  describe("sizing", () => {
+    it("mirrors @tamagui/themes tokens with figma-safe names", () => {
+      const sizeTrue = (tokens.size as Record<string, { val: number }>).true.val;
+      expect(result.sizing["size-true"]).toBe(sizeTrue);
+      const radius4 = (tokens.radius as Record<string, { val: number }>)["4"].val;
+      expect(result.sizing["radius-4"]).toBe(radius4);
+      expect(result.sizing["space-1-5"]).toBe(
+        (tokens.space as Record<string, { val: number }>)["1.5"].val,
+      );
+    });
+
+    it("exports knob-shaped borderWidth values including the 0.5 hairline", () => {
+      expect(result.sizing["borderWidth-none"]).toBe(0);
+      expect(result.sizing["borderWidth-small"]).toBe(0.5);
+      expect(result.sizing["borderWidth-medium"]).toBe(1);
+      expect(result.sizing["borderWidth-large"]).toBe(2);
+    });
+  });
+
+  describe("knobs (resolved via resolveKnobs — no copied maps)", () => {
+    it("exports current borderRadius modes (medium=$4, not the May-era $3)", () => {
+      const { modes, default: def } = result.knobs.borderRadius;
+      expect(def).toBe("medium");
+      expect(modes.none.token).toBe("$0");
+      expect(modes.small.token).toBe("$2");
+      expect(modes.medium.token).toBe("$4");
+      expect(modes.large.token).toBe("$6");
+      expect(modes.full.token).toBe("$12");
+      expect(modes.medium.figmaName).toBe("radius-4");
+      expect(modes.medium.px).toBe(result.sizing["radius-4"]);
+      // Outer/nested radius fragment landed with the knobs rebuild.
+      expect(modes.full.outerToken).toBe("$5");
+    });
+
+    it("exports borderWidth knob modes", () => {
+      expect(result.knobs.borderWidth.modes).toEqual({
+        none: 0,
+        small: 0.5,
+        medium: 1,
+        large: 2,
+      });
+    });
+
+    it("exports platform-normalized elevation modes", () => {
+      const { modes } = result.knobs.elevation;
+      expect(modes.none).toEqual({ sizeToken: null, px: null });
+      expect(modes.small.sizeToken).toBe("$1");
+      expect(modes.small.px).toBe((tokens.size as Record<string, { val: number }>)["1"].val);
+      expect(modes.medium.sizeToken).toBe("$2");
+      expect(modes.large.sizeToken).toBe("$4");
+    });
+
+    it("exports fontWeight, space, size and cornerSmoothing modes", () => {
+      expect(result.knobs.fontWeight.modes).toEqual({ regular: "400", bold: "700" });
+      expect(result.knobs.space.modes.medium.paddingFigmaName).toBe("space-4");
+      expect(result.knobs.space.modes.medium.gapFigmaName).toBe("space-4");
+      expect(result.knobs.space.modes.medium.gapLgFigmaName).toBe("space-5");
+      expect(result.knobs.size.modes).toEqual({
+        small: { token: "$3", figmaName: "size-3" },
+        medium: { token: "$4", figmaName: "size-4" },
+        large: { token: "$5", figmaName: "size-5" },
+      });
+      expect(result.knobs.cornerSmoothing.modes).toEqual({ round: 0, smooth: 0.6 });
+    });
+
+    it("exports density compact stepping", () => {
+      expect(result.knobs.density.default).toBe("comfortable");
+      expect(result.knobs.density.compact.size).toEqual({
+        small: "small",
+        medium: "small",
+        large: "medium",
+      });
+      expect(result.knobs.density.compact.space).toEqual({
+        small: "small",
+        medium: "small",
+        large: "medium",
+      });
+    });
+  });
+
+  describe("typography (closes deferred task 10.0)", () => {
+    it("exports heading/body size + lineHeight tables from the built default fonts", () => {
+      // Heading scale is 1.4x Inter base: H1 $10 = round(46 * 1.4) = 64.
+      expect(result.typography.heading.size["10"]).toBe(64);
+      expect(result.typography.body.size.true).toBe(14);
+      // lineHeight = size + 10 (defaults/fonts.ts).
+      expect(result.typography.body.lineHeight.true).toBe(24);
+      expect(result.typography.heading.lineHeight["10"]).toBe(74);
+    });
+
+    it("exports Inter dynamic tracking per size", () => {
+      const body = result.typography.body;
+      expect(body.letterSpacing.true).toBe(interTrackingPx(14));
+      expect(Object.keys(body.letterSpacing).length).toBeGreaterThanOrEqual(16);
+    });
+
+    it("exports category stacks with a Figma-usable first family", () => {
+      expect(result.typography.categories.pixel.figmaFamily).toBe("Silkscreen");
+      expect(result.typography.categories["sans-serif"].figmaFamily).toBe("Inter");
+    });
+  });
+
+  it("figmaTokenName converts Tamagui token keys to Figma-safe names", () => {
+    expect(figmaTokenName("size", "1.5")).toBe("size-1-5");
+    expect(figmaTokenName("space", "true")).toBe("space-true");
+    expect(figmaTokenName("space", "-0.25")).toBe("space--0-25");
+  });
+});