@multiplatform.one/theme 6.1.0 → 6.3.0

package/src/theme/useResolvedKnobsBehavior.spec.tsx

@@ -0,0 +1,166 @@
+/**
+ * useResolvedKnobs behavior specs — the resolution rules consumers feel but
+ * that aren't covered by the pure resolveKnobs specs: Tamagui size-token →
+ * knob-size mapping, OS reduced-motion forcing animation off, the legacy
+ * addListener matchMedia branch, and the semantic-intent Button label color
+ * rule (filled binds $color, outlined pins $color11).
+ */
+
+import { renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { createElement } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ThemeName } from "@tamagui/web";
+import { defaultKnobs } from "./knobs";
+import type { Preset as PresetType } from "./preset.types";
+import { PresetContext, type PresetContextValue } from "./PresetContext";
+import { useResolvedKnobs } from "./useResolvedKnobs";
+
+let originalMatchMedia: typeof window.matchMedia;
+
+function stubMatchMedia(
+  impl: (query: string) => Partial<MediaQueryList> & Record<string, unknown>,
+) {
+  window.matchMedia = vi.fn(
+    (query: string) => impl(query) as MediaQueryList,
+  ) as typeof window.matchMedia;
+}
+
+function modernMq(matches: boolean) {
+  return {
+    matches,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  };
+}
+
+beforeEach(() => {
+  originalMatchMedia = window.matchMedia;
+  stubMatchMedia(() => modernMq(false));
+});
+
+afterEach(() => {
+  window.matchMedia = originalMatchMedia;
+});
+
+function presetWrapper(preset: PresetType) {
+  const ctx: PresetContextValue = { preset };
+  return ({ children }: { children: ReactNode }) =>
+    createElement(PresetContext.Provider, { value: ctx }, children);
+}
+
+function makePreset(overrides: Partial<PresetType> = {}): PresetType {
+  return {
+    theme: "light" as ThemeName,
+    knobs: { ...defaultKnobs },
+    intents: {},
+    tints: [],
+    ...overrides,
+  };
+}
+
+describe("size token mapping", () => {
+  it.each([
+    ["$1", "small"],
+    ["$3", "small"],
+    ["$4", "medium"],
+    ["$5", "large"],
+    ["$6", "large"],
+    ["$true", "medium"],
+  ] as const)("maps Tamagui size %s to knob size %s", (token, expected) => {
+    const { result } = renderHook(() => useResolvedKnobs({ size: token as never }));
+    expect(result.current.knobProps.size).toBe(expected);
+  });
+
+  it("keeps the knob size for unmapped tokens", () => {
+    const { result } = renderHook(() => useResolvedKnobs({ size: "$11" as never }));
+    expect(result.current.knobProps.size).toBe(defaultKnobs.size);
+  });
+});
+
+describe("reduced motion", () => {
+  it("keeps the animation knob's transition when the OS does not prefer reduced motion", () => {
+    const { result } = renderHook(() => useResolvedKnobs());
+    expect(result.current.knobProps.transition).toBe(defaultKnobs.animation);
+  });
+
+  it("forces the transition off when prefers-reduced-motion matches", () => {
+    stubMatchMedia((query) => modernMq(query === "(prefers-reduced-motion: reduce)"));
+    const { result } = renderHook(() => useResolvedKnobs());
+    expect(result.current.knobProps.transition).toBeUndefined();
+  });
+
+  it("supports legacy MediaQueryList hosts exposing only addListener", () => {
+    const addListener = vi.fn();
+    const removeListener = vi.fn();
+    stubMatchMedia(() => ({ matches: true, addListener, removeListener }));
+    const { result, unmount } = renderHook(() => useResolvedKnobs());
+    expect(result.current.knobProps.transition).toBeUndefined();
+    expect(addListener).toHaveBeenCalledWith(expect.any(Function));
+    unmount();
+    expect(removeListener).toHaveBeenCalledWith(expect.any(Function));
+  });
+});
+
+describe("semantic-intent Button label color (LC-05)", () => {
+  it("binds filled error Buttons to $color (the on-fill foreground)", () => {
+    // defaultIntents.error sets Button.fillStyle = "filled".
+    const { result } = renderHook(() => useResolvedKnobs({ intent: "error", component: "Button" }));
+    expect(result.current.knobProps.body.color).toBe("$color");
+  });
+
+  it("pins outlined error Buttons to $color11 (readable on page surfaces)", () => {
+    const preset = makePreset({
+      intents: { error: { Button: { fillStyle: "outlined" } } },
+    });
+    const { result } = renderHook(
+      () => useResolvedKnobs({ intent: "error", component: "Button" }),
+      { wrapper: presetWrapper(preset) },
+    );
+    expect(result.current.knobProps.body.color).toBe("$color11");
+  });
+
+  it("leaves non-semantic intents without the label override", () => {
+    const { result } = renderHook(() =>
+      useResolvedKnobs({ intent: "accent", component: "Button" }),
+    );
+    const plain = renderHook(() => useResolvedKnobs());
+    expect(result.current.knobProps.body.color).toBe(plain.result.current.knobProps.body.color);
+  });
+});
+
+describe("intent + component knob merging", () => {
+  it("applies intent-level string overrides and component-level objects", () => {
+    const preset = makePreset({
+      intents: {
+        error: {
+          borderRadius: "small",
+          Card: { elevation: "large" },
+        },
+      },
+    });
+    const withComponent = renderHook(
+      () => useResolvedKnobs({ intent: "error", component: "Card" }),
+      { wrapper: presetWrapper(preset) },
+    );
+    const withoutComponent = renderHook(() => useResolvedKnobs({ intent: "error" }), {
+      wrapper: presetWrapper(preset),
+    });
+    // Component-scoped override only applies when the component matches.
+    expect(withComponent.result.current.knobProps.elevation).not.toBe(
+      withoutComponent.result.current.knobProps.elevation,
+    );
+    // Intent-level knob override applies to both.
+    expect(withComponent.result.current.knobProps.borderRadius).toEqual(
+      withoutComponent.result.current.knobProps.borderRadius,
+    );
+  });
+
+  it("compact option steps sizing down regardless of the density knob", () => {
+    const comfortable = renderHook(() => useResolvedKnobs());
+    const compact = renderHook(() => useResolvedKnobs({ compact: true }));
+    // default medium comfort → small under compact stepping
+    expect(comfortable.result.current.knobProps.size).toBe("medium");
+    expect(compact.result.current.knobProps.size).toBe("small");
+  });
+});

package/types/audit/constraintAudit.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Constraint Audit System
+ *
+ * Audits the rendered DOM to verify all structural CSS values land on valid
+ * Tamagui token steps defined by the knob system. Off-scale values indicate
+ * styles that bypassed the constraint system.
+ *
+ * Token values are from @tamagui/themes v5 + resolveKnobs.ts mappings.
+ * Run this in-browser via Playwright's page.evaluate(runConstraintAudit).
+ */
+export interface PropertyAudit {
+    value: number;
+    unit: string;
+    knob: string;
+    offScale: boolean;
+}
+export interface TextPropertyAudit {
+    value: string;
+    knob: string;
+    offScale: boolean;
+}
+export interface ElementAudit {
+    /** Human-readable element descriptor */
+    label: string;
+    /** Tag name */
+    tag: string;
+    /** id attribute if present */
+    id: string;
+    /** Non-hash class names (for readability) */
+    classes: string[];
+    /** Audited properties (only populated when value is non-default/non-zero) */
+    borderRadius?: PropertyAudit;
+    borderWidth?: PropertyAudit;
+    gap?: PropertyAudit;
+    rowGap?: PropertyAudit;
+    columnGap?: PropertyAudit;
+    paddingTop?: PropertyAudit;
+    paddingRight?: PropertyAudit;
+    paddingBottom?: PropertyAudit;
+    paddingLeft?: PropertyAudit;
+    fontWeight?: PropertyAudit;
+    fontFamily?: TextPropertyAudit;
+    /** Inline color bypasses (hardcoded color/backgroundColor not from theme) */
+    inlineColor?: TextPropertyAudit;
+    /** Violations found on this element */
+    violations: string[];
+}
+export interface AuditSummary {
+    totalElements: number;
+    auditedElements: number;
+    totalViolations: number;
+    byProperty: {
+        borderRadius: number;
+        borderWidth: number;
+        gap: number;
+        padding: number;
+        fontWeight: number;
+        fontFamily: number;
+        inlineColor: number;
+    };
+}
+export interface AuditReport {
+    url: string;
+    timestamp: string;
+    preset: string;
+    scheme: string;
+    summary: AuditSummary;
+    violations: ElementAudit[];
+    /** All audited elements (including compliant ones) */
+    elements: ElementAudit[];
+}
+/**
+ * Runs the constraint audit in the browser.
+ *
+ * This function is completely self-contained — no imports or external refs.
+ * Pass it directly to Playwright's page.evaluate():
+ *
+ *   const report = await page.evaluate(runConstraintAudit);
+ *
+ * Returns an AuditReport object describing all structural CSS violations.
+ */
+export declare function runConstraintAudit(): AuditReport;
+//# sourceMappingURL=constraintAudit.d.ts.map

package/types/audit/constraintAudit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraintAudit.d.ts","sourceRoot":"","sources":["../../src/audit/constraintAudit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,eAAe;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,uCAAuC;IACvC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAkPD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CAgiBhD"}

package/types/audit/diffReport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Audit Diff Reporter
+ *
+ * Compares two AuditReport snapshots (pre/post change) and produces
+ * a human-readable delta in constraint terms.
+ */
+import type { AuditReport, PropertyAudit, TextPropertyAudit } from "./constraintAudit";
+export interface PropertyDiff {
+    property: string;
+    before: PropertyAudit | TextPropertyAudit | undefined;
+    after: PropertyAudit | TextPropertyAudit | undefined;
+    changed: boolean;
+    becameViolation: boolean;
+    fixedViolation: boolean;
+}
+export interface ElementDiff {
+    label: string;
+    tag: string;
+    status: "added" | "removed" | "changed" | "unchanged";
+    propertyDiffs: PropertyDiff[];
+    newViolations: string[];
+    fixedViolations: string[];
+}
+export interface AuditDiff {
+    baselineUrl: string;
+    currentUrl: string;
+    baselineTimestamp: string;
+    currentTimestamp: string;
+    baselinePreset: string;
+    currentPreset: string;
+    summary: {
+        elementsAdded: number;
+        elementsRemoved: number;
+        elementsChanged: number;
+        newViolations: number;
+        fixedViolations: number;
+        netViolationChange: number;
+    };
+    elementDiffs: ElementDiff[];
+    /** Human-readable report text */
+    report: string;
+}
+export declare function diffAuditReports(baseline: AuditReport, current: AuditReport): AuditDiff;
+export declare function formatAuditReport(report: AuditReport): string;
+//# sourceMappingURL=diffReport.d.ts.map

package/types/audit/diffReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffReport.d.ts","sourceRoot":"","sources":["../../src/audit/diffReport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EAEX,aAAa,EACb,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACtD,KAAK,EAAE,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACtD,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAoCD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,SAAS,CAmMvF;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAwD7D"}

package/types/audit/index.d.ts

@@ -0,0 +1,5 @@
+export type { AuditReport, AuditSummary, ElementAudit, PropertyAudit, TextPropertyAudit, } from "./constraintAudit";
+export { runConstraintAudit } from "./constraintAudit";
+export type { AuditDiff, ElementDiff, PropertyDiff } from "./diffReport";
+export { diffAuditReports, formatAuditReport } from "./diffReport";
+//# sourceMappingURL=index.d.ts.map

package/types/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/types/dates.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Canonical timestamp/date registers (LC-12 TIMESTAMP-REGISTER, Axiom 9).
+ *
+ * One formatter owns every absolute date the catalog renders — Timeline
+ * timestamps, table date cells (FieldDisplay), DatePicker display values —
+ * so the same data class never speaks in multiple voices ("2026-07-01" vs
+ * "Aug 9, 3:30 PM" vs "11/01/2026").
+ *
+ * Content class picks the register (paired with the `timestampStyle` knob):
+ *   - feeds/social       → relative ("2h ago") via `formatRelativeTimestamp`
+ *   - tables/system      → compact absolute ("Jul 1" / "Aug 9, 3:30 PM"),
+ *                          current year elided (`year: "auto"`)
+ *   - editing surfaces   → compact absolute with the year always shown
+ *                          ("Jul 1, 2026") — pickers are precision contexts
+ * No default may emit verbose locale output with seconds.
+ */
+export type DateInput = Date | string | number | null | undefined;
+export interface AbsoluteDateFormatOptions {
+    /**
+     * `"auto"` (default) elides the current year — the display register for
+     * tables, feeds, and system events. `"always"` keeps it — the editing
+     * register for picker display values.
+     */
+    year?: "auto" | "always";
+    /** Include the time component ("Aug 9, 3:30 PM"). Default false. */
+    withTime?: boolean;
+    /** BCP-47 locale forwarded to Intl. Default: system locale. */
+    locale?: string;
+    /** Reference date for current-year elision (injectable for tests). */
+    now?: Date;
+}
+/** ISO date-only shape ("YYYY-MM-DD"). */
+export declare const ISO_DATE_ONLY: RegExp;
+/**
+ * Compact absolute date — the house register for every absolute date.
+ * "Jul 1" / "Jul 1, 2025" (year auto-elided when current), or with
+ * `withTime` "Aug 9, 3:30 PM". Empty input renders "" and an unparseable
+ * string passes through unchanged (honest passthrough — never invents).
+ */
+export declare function formatAbsoluteDate(value: DateInput, options?: AbsoluteDateFormatOptions): string;
+/**
+ * Compact absolute date-time ("Aug 9, 3:30 PM"; year added when not
+ * current). The system-event register (LC-12) and the tooltip form for
+ * relative timestamps.
+ */
+export declare function formatAbsoluteDateTime(value: DateInput, options?: Omit<AbsoluteDateFormatOptions, "withTime">): string;
+/**
+ * Relative timestamp ("just now", "5m ago", "2h ago", "10 days ago") — the
+ * feed/social register (LC-12), selected by `timestampStyle: "relative"`.
+ */
+export declare function formatRelativeTimestamp(value: DateInput, now?: number): string;
+//# sourceMappingURL=dates.d.ts.map

package/types/dates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,0CAA0C;AAC1C,eAAO,MAAM,aAAa,QAAwB,CAAC;AAyBnD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,yBAA8B,GACtC,MAAM,CA0BR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,UAAU,CAAM,GACxD,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAgB1F"}

package/types/devWarn.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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" | "multiple-h1";
+export type DevWarnDetail = {
+    component?: string;
+    id?: string;
+    value?: unknown;
+    word?: string;
+    count?: number;
+    suggest?: string;
+    region?: string;
+    [key: string]: unknown;
+};
+/**
+ * Emit a once-per-key console warning in non-production builds.
+ */
+export declare function devWarn(code: DevWarnCode, detail?: DevWarnDetail): void;
+/** @internal test helper */
+export declare function __resetDevWarnSeen(): void;
+/** Alias kept for callers that imported the W12-era name. */
+export declare const themeDevWarn: typeof devWarn;
+export declare const __resetThemeDevWarnSeen: typeof __resetDevWarnSeen;
+/**
+ * DG-FORM-02 / DG-FORM-11: placeholder must not be the only label.
+ */
+export declare function warnPlaceholderAsLabel(args: {
+    placeholder?: string | null;
+    label?: unknown;
+    ariaLabel?: string | null;
+    id?: string;
+    component?: string;
+}): void;
+/** DG-COPY-02 / DG-VAL-03 — banned words in error copy. */
+export declare function warnBannedErrorWords(message: string | null | undefined, detail?: DevWarnDetail): void;
+/** DG-ST-03 — bare `disabled` without reason / explain. */
+export declare function warnBareDisabled(args: {
+    disabled?: boolean;
+    disabledReason?: string | null;
+    skip?: boolean;
+    component?: string;
+    id?: string;
+}): void;
+/**
+ * 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 declare function warnCancelDisabled(args: {
+    disabled?: boolean;
+    component?: string;
+    id?: string;
+}): void;
+/** DG-OVL-04 — dialog action rows cap at this many actions by default. */
+export declare 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 declare function warnDialogTooManyActions(args: {
+    count: number;
+    allowManyActions?: boolean;
+    component?: string;
+    id?: string;
+}): void;
+/**
+ * DG-CTRL — Select with too few options; suggest RadioGroup / ToggleGroup.
+ */
+export declare function warnSelectTooFewOptions(args: {
+    count: number;
+    multiple?: boolean;
+    component?: string;
+    id?: string;
+}): void;
+/** DG-A11Y-03 — never `tabIndex` > 0. */
+export declare function warnPositiveTabIndex(args: {
+    value?: number | string | null;
+    component?: string;
+    id?: string;
+}): void;
+/** DG-OVL-05 — no hover tooltip on disabled controls. */
+export declare function warnTooltipOnDisabled(args: {
+    childDisabled?: boolean;
+    component?: string;
+    id?: string;
+}): void;
+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 declare function warnOutlineNone(style: OutlineLike, detail?: DevWarnDetail): void;
+export {};
+//# sourceMappingURL=devWarn.d.ts.map

package/types/devWarn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devWarn.d.ts","sourceRoot":"","sources":["../src/devWarn.ts"],"names":[],"mappings":"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"}

package/types/figma/figmaTokens.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Figma token export transform — the code→Figma projection for
+ * `agent-os/specs/2026-05-08-figma-v2-token-migration`.
+ *
+ * Everything here is DERIVED from the canonical theme sources at call time
+ * (no hand-copied values):
+ *
+ * - Palette ramps + shadows: `createThemesBuilder(defaultBaseTheme,
+ *   defaultAccentTheme, defaultBuilderOptions).themes()` — the exact themes
+ *   apps run, including tint text neutralization and computed tokens like
+ *   `outlineColor`.
+ * - Semantic aliases: reverse-matched per scheme against the ramp steps of
+ *   the built base themes (a key only becomes a `colorN` alias when light
+ *   AND dark agree on the step index; otherwise raw per-scheme values are
+ *   exported).
+ * - Sizing: `tokens` from `@tamagui/themes` (the tokens
+ *   `createDefaultThemeConfig` installs).
+ * - Knob outputs: `resolveKnobs()` is executed per knob mode — the export
+ *   shows exactly what the runtime resolver produces.
+ * - Typography: the built `defaultHeadingFont` / `defaultBodyFont` tables
+ *   (size / lineHeight / letterSpacing / weight).
+ *
+ * The transform is pure and deterministic (no Date, no I/O) so it can be
+ * golden-tested; the runner script (`scripts/export-figma-tokens.mts`)
+ * stamps `generatedAt` when writing to disk.
+ */
+import { type Knobs } from "../theme/knobs";
+/**
+ * Theme modes of the `Palette/Theme` Figma collection (spec.md §Variable
+ * Collection Structure): semantic intents take the red/yellow/green slots;
+ * the remaining stock tints are manual designer picks. 9 modes — inside
+ * Figma Pro's 10-modes-per-collection cap with 1 slot of headroom.
+ */
+export declare const FIGMA_THEME_MODES: readonly ["base", "accent", "error", "success", "warning", "orange", "blue", "purple", "pink"];
+export type FigmaThemeMode = (typeof FIGMA_THEME_MODES)[number];
+/**
+ * Figma's per-node corner-smoothing dial value per `cornerSmoothing` knob.
+ * `smooth` = 0.6 ≈ `corner-shape: squircle` ≡ superellipse(2) ≈ Apple's
+ * continuous corners (see cornerSmoothing.ts). This is a Figma rendering
+ * constant, not a Variable — Figma cannot bind cornerSmoothing to Variables.
+ */
+export declare const FIGMA_CORNER_SMOOTHING: Record<string, number>;
+/** Tamagui token key (`1.5`, `true`) → Figma-safe variable name segment. */
+export declare function figmaTokenName(prefix: string, key: string): string;
+export interface FigmaPaletteTheme {
+    light: string[];
+    dark: string[];
+}
+export interface FigmaShadows {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+export type FigmaSemanticEntry = {
+    alias: string;
+    light: string;
+    dark: string;
+} | {
+    alias: null;
+    light: string;
+    dark: string;
+};
+export interface FigmaRadiusMode {
+    /** Tamagui radius token resolveKnobs emits for this knob mode (e.g. `$4`). */
+    token: string;
+    /** `Sizing` collection variable to alias (e.g. `radius-4`). */
+    figmaName: string;
+    px: number;
+    /** Outer/nested radius fragment (`knobProps.borderRadiusOuter`). */
+    outerToken: string;
+    outerFigmaName: string;
+    outerPx: number;
+}
+export interface FigmaElevationMode {
+    /** Tamagui size token backing the elevation shadow scale (null = none). */
+    sizeToken: string | null;
+    px: number | null;
+}
+export interface FigmaSpaceMode {
+    paddingToken: string;
+    paddingFigmaName: string;
+    gapToken: string;
+    gapFigmaName: string;
+    gapLgToken: string;
+    gapLgFigmaName: string;
+}
+export interface FigmaKnobsExport {
+    borderRadius: {
+        default: Knobs["borderRadius"];
+        modes: Record<string, FigmaRadiusMode>;
+    };
+    borderWidth: {
+        default: Knobs["borderWidth"];
+        modes: Record<string, number>;
+    };
+    elevation: {
+        default: Knobs["elevation"];
+        modes: Record<string, FigmaElevationMode>;
+    };
+    fontWeight: {
+        default: Knobs["fontWeight"];
+        modes: Record<string, string>;
+    };
+    space: {
+        default: Knobs["space"];
+        modes: Record<string, FigmaSpaceMode>;
+    };
+    size: {
+        default: Knobs["size"];
+        modes: Record<string, {
+            token: string;
+            figmaName: string;
+        }>;
+    };
+    cornerSmoothing: {
+        default: string;
+        modes: Record<string, number>;
+    };
+    density: {
+        default: Knobs["density"];
+        /** compact steps size/space down one level (applyDensity). */
+        compact: {
+            size: Record<string, string>;
+            space: Record<string, string>;
+        };
+    };
+}
+export interface FigmaFontExport {
+    family: string;
+    size: Record<string, number>;
+    lineHeight: Record<string, number>;
+    letterSpacing: Record<string, number>;
+    weight: Record<string, string>;
+}
+export interface FigmaTypographyExport {
+    heading: FigmaFontExport;
+    body: FigmaFontExport;
+    /**
+     * Category font stacks (the `headingFont`/`bodyFont` knob targets), as
+     * supplied by the app config (`packages/config/fonts.ts` in this repo).
+     * `figmaFamily` is the first family of the stack — Figma cannot resolve
+     * CSS fallback chains.
+     */
+    categories: Record<string, {
+        stack: string;
+        figmaFamily: string;
+    }>;
+}
+export interface FigmaTokensExport {
+    $meta: {
+        generator: string;
+        spec: string;
+        note: string;
+    };
+    palette: {
+        themes: Record<string, FigmaPaletteTheme>;
+        shadows: FigmaShadows;
+    };
+    semantic: Record<string, FigmaSemanticEntry>;
+    sizing: Record<string, number>;
+    knobs: FigmaKnobsExport;
+    typography: FigmaTypographyExport;
+}
+export interface BuildFigmaTokensOptions {
+    /** Category font stacks to export (e.g. `fontFamilies` from app config). */
+    fontFamilies?: Record<string, string>;
+}
+export declare function buildFigmaTokens(options?: BuildFigmaTokensOptions): FigmaTokensExport;
+//# sourceMappingURL=figmaTokens.d.ts.map

package/types/figma/figmaTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaTokens.d.ts","sourceRoot":"","sources":["../../src/figma/figmaTokens.ts"],"names":[],"mappings":"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"}

package/types/font.d.ts

@@ -0,0 +1,5 @@
+import type { GenericFont } from "@tamagui/web";
+export declare function createDefaultFont<A extends GenericFont>(font: Partial<A> & {
+    family: A["family"];
+}): A;
+//# sourceMappingURL=font.d.ts.map

package/types/font.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font.d.ts","sourceRoot":"","sources":["../src/font.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAiChD,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACrD,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;CAAE,GACzC,CAAC,CAWH"}