rastack 0.0.23 → 0.0.25

package/src/tokens/theme.ts

@@ -0,0 +1,180 @@
+/**
+ * `defineTheme` — the simple, non-designer entry point.
+ *
+ * State a handful of decisions in plain values — your brand colour, how round
+ * the corners are, which font — and get a **complete** design system back:
+ * colour scales, semantic tokens (background, surface, text, border, accent…),
+ * and both **light and dark** modes, with readable on-colours chosen for you.
+ *
+ * ```ts
+ * import { defineTheme } from "rastack/tokens";
+ *
+ * export default defineTheme({
+ *   brand: "#4F6BFF",     // one colour is enough — we build the 50–950 scale
+ *   radius: "rounded",    // "sharp" | "rounded" | "pill" | a px number
+ *   font: "Inter",
+ * });
+ * ```
+ *
+ * It returns the same {@link ThemedTokens} that `defineTokens` produces, so it
+ * plugs straight into `rastack tokens`, `rastack design`, and `rastack/theme`.
+ * `defineTheme` is sugar over `defineTokens`; reach for the raw DSL only when you
+ * want per-token control. Everything is overridable — pass `colors`, `radius`,
+ * `space`, or `extend` to adjust or add anything.
+ */
+
+import { readableOn, scale } from "./color";
+import { defineTokens } from "./define";
+import { mergeTokens } from "./resolve";
+import { ThemedTokens, TokenDocument } from "./types";
+
+export interface ThemeConfig {
+  /** Your main brand colour, as a hex string. The rest is derived from it. */
+  brand: string;
+  /** A secondary accent colour. Defaults to `brand`. */
+  accent?: string;
+  /** The neutral/grey seed used for backgrounds, surfaces, text and borders. */
+  neutral?: string;
+  /** Corner roundness: a keyword or a base radius in px. Default `"rounded"`. */
+  radius?: "sharp" | "rounded" | "pill" | number;
+  /** Body font family (name or stack). Default Inter/system-ui. */
+  font?: string | string[];
+  /** Which modes to generate. Default `"both"`. */
+  appearance?: "light" | "dark" | "both";
+  /** Status colours (sensible defaults provided). */
+  success?: string;
+  danger?: string;
+  warning?: string;
+  /**
+   * Override or add any semantic colour, e.g. `{ accent: "#e11d48" }` or
+   * `{ "text-muted": "#888" }`. Applied on top of the generated palette.
+   */
+  colors?: Record<string, string>;
+  /**
+   * Escape hatch: raw DTCG tokens deep-merged over everything (per mode via
+   * `{ modes: { dark: { … } } }`), for anything the simple config can't express.
+   */
+  extend?: Partial<ThemedTokens>;
+}
+
+const RADIUS_KEYWORDS = { sharp: 3, rounded: 10, pill: 18 } as const;
+
+const DEFAULT_FONT = ["Inter", "system-ui", "-apple-system", "Segoe UI", "Roboto", "sans-serif"];
+
+/** Turn a plain intent config into a full themed token document. */
+export function defineTheme(config: ThemeConfig): ThemedTokens {
+  const brand = scale(config.brand);
+  const accentSeed = config.accent ?? config.brand;
+  const accent = scale(accentSeed);
+  const neutral = scale(config.neutral ?? "#64748B");
+  const onAccent = readableOn(accentSeed);
+
+  const baseRadius =
+    typeof config.radius === "number"
+      ? config.radius
+      : RADIUS_KEYWORDS[config.radius ?? "rounded"];
+
+  const colorScale = (name: string, s: Record<string, string>) =>
+    Object.fromEntries(Object.entries(s).map(([step, hex]) => [step, { $value: hex }]));
+
+  // --- base tree (also the light appearance) ------------------------------
+  const base: TokenDocument = {
+    color: {
+      $type: "color",
+      brand: colorScale("brand", brand),
+      ...(config.accent ? { "accent-scale": colorScale("accent", accent) } : {}),
+      // Semantic tokens alias the scales, so overriding a scale flows through.
+      accent: { $value: config.accent ? "{color.accent-scale.500}" : "{color.brand.500}" },
+      "accent-strong": { $value: config.accent ? "{color.accent-scale.600}" : "{color.brand.600}" },
+      "on-accent": { $value: onAccent },
+      bg: { $value: "#FFFFFF" },
+      surface: { $value: "#FFFFFF" },
+      "surface-alt": { $value: neutral["100"] },
+      border: { $value: neutral["200"] },
+      text: { $value: neutral["900"] },
+      "text-muted": { $value: neutral["500"] },
+      success: { $value: config.success ?? "#1FA971" },
+      danger: { $value: config.danger ?? "#E5484D" },
+      warning: { $value: config.warning ?? "#F5A623" },
+    },
+    space: {
+      $type: "dimension",
+      xs: { $value: "4px" },
+      sm: { $value: "8px" },
+      md: { $value: "16px" },
+      lg: { $value: "24px" },
+      xl: { $value: "40px" },
+    },
+    radius: {
+      $type: "dimension",
+      sm: { $value: `${Math.round(baseRadius * 0.6)}px` },
+      md: { $value: `${baseRadius}px` },
+      lg: { $value: `${Math.round(baseRadius * 1.6)}px` },
+      xl: { $value: `${Math.round(baseRadius * 2.4)}px` },
+      pill: { $value: "999px" },
+    },
+    font: {
+      family: {
+        $type: "fontFamily",
+        sans: { $value: config.font ?? DEFAULT_FONT },
+      },
+      weight: {
+        $type: "fontWeight",
+        regular: { $value: 400 },
+        medium: { $value: 500 },
+        bold: { $value: 700 },
+      },
+    },
+  };
+
+  // Apply user colour overrides onto the semantic layer.
+  if (config.colors) {
+    for (const [name, hex] of Object.entries(config.colors)) {
+      (base.color as any)[name] = { $value: hex };
+    }
+  }
+
+  // --- dark appearance: only the tokens that differ ------------------------
+  const dark: TokenDocument = {
+    color: {
+      // In dark, the accent reads better a step lighter.
+      accent: { $value: config.accent ? "{color.accent-scale.400}" : "{color.brand.400}" },
+      "accent-strong": { $value: config.accent ? "{color.accent-scale.300}" : "{color.brand.300}" },
+      bg: { $value: neutral["950"] },
+      surface: { $value: neutral["900"] },
+      "surface-alt": { $value: neutral["800"] },
+      border: { $value: neutral["700"] },
+      text: { $value: neutral["50"] },
+      "text-muted": { $value: neutral["400"] },
+    },
+  };
+
+  const appearance = config.appearance ?? "both";
+  const modes: Record<string, TokenDocument> = {};
+  if (appearance !== "light") modes.dark = dark;
+
+  let themed: ThemedTokens = {
+    tokens: base,
+    modes,
+    defaultMode: appearance === "dark" ? "dark" : "light",
+  };
+
+  // dark-only: fold the dark overrides into the base so :root is dark.
+  if (appearance === "dark") {
+    themed = { tokens: mergeTokens(base, dark), modes: {}, defaultMode: "dark" };
+  }
+
+  // Escape hatch merges last.
+  if (config.extend) {
+    if (config.extend.tokens) themed.tokens = mergeTokens(themed.tokens, config.extend.tokens);
+    if (config.extend.modes) {
+      for (const [name, doc] of Object.entries(config.extend.modes)) {
+        themed.modes = themed.modes ?? {};
+        themed.modes[name] = themed.modes[name] ? mergeTokens(themed.modes[name], doc) : doc;
+      }
+    }
+  }
+
+  // Normalise through defineTokens so the result is identical in shape.
+  return defineTokens(themed);
+}

package/src/tokens/ts.ts

@@ -0,0 +1,80 @@
+/**
+ * Typed-theme emitter — the ergonomic, autocompleted output.
+ *
+ * Emits a `.ts` module exporting a nested `theme` object that mirrors the token
+ * tree, whose leaves are `var(--…)` strings, plus a `TokenPath` union of every
+ * token name. Application code reads `theme.color.brand[500]` (a real CSS
+ * variable reference) with full type-safety and rename-refactoring, while the
+ * actual values live in the emitted CSS and stay swappable per mode.
+ */
+
+import { cssVarName } from "./resolve";
+import { ResolvedToken } from "./types";
+
+/** A key that is a safe JS identifier can be written bare; otherwise quote it. */
+function keyLiteral(key: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key);
+}
+
+/** Build a nested plain object from dotted paths → `var(--…)` leaf strings. */
+function nest(tokens: ResolvedToken[], prefix: string): Record<string, any> {
+  const root: Record<string, any> = {};
+  for (const tok of tokens) {
+    const segments = tok.path.split(".");
+    let node = root;
+    segments.forEach((seg, i) => {
+      if (i === segments.length - 1) {
+        node[seg] = `var(${cssVarName(tok.path, prefix)})`;
+      } else {
+        node[seg] = node[seg] ?? {};
+        node = node[seg];
+      }
+    });
+  }
+  return root;
+}
+
+function serialize(node: Record<string, any>, indent: string): string {
+  const inner = indent + "  ";
+  const entries = Object.entries(node).map(([key, val]) => {
+    const k = keyLiteral(key);
+    if (typeof val === "string") return `${inner}${k}: ${JSON.stringify(val)},`;
+    return `${inner}${k}: ${serialize(val, inner)},`;
+  });
+  return `{\n${entries.join("\n")}\n${indent}}`;
+}
+
+export interface TsOptions {
+  prefix?: string;
+}
+
+/** Emit the typed-theme `.ts` source for a resolved base token list. */
+export function emitTs(tokens: ResolvedToken[], options: TsOptions = {}): string {
+  const prefix = options.prefix ?? "";
+  const tree = nest(tokens, prefix);
+  const union =
+    tokens.map((t) => `  | ${JSON.stringify(t.path)}`).join("\n") || "  never";
+
+  return `/* Generated by \`rastack tokens\` — do not edit by hand. */
+
+/** Every design-token path, for type-safe lookups. */
+export type TokenPath =
+${union};
+
+/**
+ * The design system as a typed tree of CSS-variable references.
+ * \`theme.color.brand[500]\` → \`"var(--color-brand-500)"\`.
+ */
+export const theme = ${serialize(tree, "")} as const;
+
+/** The CSS custom-property name for a token path. */
+export function cssVar(path: TokenPath): string {
+  const body = path
+    .split(".")
+    .map((s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase())
+    .join("-")
+    .replace(/[^a-z0-9-]+/g, "-");
+  return ${JSON.stringify(prefix ? `--${prefix}-` : "--")} + body;
+}
+`;
+}

package/src/tokens/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Design-token model — the **W3C Design Tokens (DTCG) format**.
+ *
+ * A design token is the smallest, named, platform-agnostic decision about how
+ * the UI looks: a colour, a spacing step, a radius, a font family. The DTCG
+ * community-group spec (https://tr.designtokens.org) is the industry standard
+ * serialization: a nested JSON tree of **groups** whose leaves are **tokens**,
+ * each carrying a `$value`, an optional `$type`, and an optional
+ * `$description`. Values may be literals or **aliases** — a `"{group.token}"`
+ * reference to another token.
+ *
+ * ```jsonc
+ * {
+ *   "color": {
+ *     "$type": "color",
+ *     "brand": { "500": { "$value": "#4F6BFF" } },
+ *     "text":  { "$value": "{color.brand.500}" }   // alias
+ *   }
+ * }
+ * ```
+ *
+ * This module is the pure data model shared by the compiler
+ * (`tools/src/tokens/{resolve,css,ts}.ts`) and the React runtime
+ * (`rastack/theme`). It has no filesystem or React dependency, so it builds for
+ * the browser exactly like `rastack/define`.
+ */
+
+/** The DTCG `$type`s this framework understands. */
+export type TokenType =
+  | "color"
+  | "dimension"
+  | "fontFamily"
+  | "fontWeight"
+  | "duration"
+  | "cubicBezier"
+  | "number"
+  | "shadow"
+  | "border"
+  | "typography"
+  | "transition";
+
+/** A shadow token value (single shadow or a stack of them). */
+export interface ShadowValue {
+  offsetX: string | number;
+  offsetY: string | number;
+  blur?: string | number;
+  spread?: string | number;
+  color: string;
+  inset?: boolean;
+}
+
+/** Anything that can appear as a token `$value` (including aliases as strings). */
+export type TokenValue =
+  | string
+  | number
+  | boolean
+  | ShadowValue
+  | ShadowValue[]
+  | string[]
+  | Record<string, unknown>;
+
+/** A single design token — a group leaf. Identified by the presence of `$value`. */
+export interface DesignToken {
+  $value: TokenValue;
+  $type?: TokenType;
+  $description?: string;
+  $extensions?: Record<string, unknown>;
+}
+
+/**
+ * A group node: named children (tokens or nested groups) plus optional group
+ * metadata. `$type` set on a group is **inherited** by descendant tokens that
+ * don't declare their own — the standard DTCG type-inheritance rule.
+ *
+ * Typed loosely (`any` children) on purpose: the tree is arbitrary-depth data,
+ * mirroring how the codebase types OpenAPI documents.
+ */
+export interface TokenGroup {
+  $type?: TokenType;
+  $description?: string;
+  [child: string]: DesignToken | TokenGroup | TokenType | string | undefined;
+}
+
+/** The root of a token tree. */
+export type TokenDocument = TokenGroup;
+
+/**
+ * A themeable token document: a base tree plus named **modes** (e.g. `light`,
+ * `dark`) that override a subset of tokens. Modes compile to CSS selector
+ * scopes, so a running app flips theme by toggling one attribute.
+ */
+export interface ThemedTokens {
+  /** Base tokens — the values that apply in every mode. */
+  tokens: TokenDocument;
+  /** Per-mode overrides, deep-merged over the base. */
+  modes?: Record<string, TokenDocument>;
+  /** Which mode is the default (emitted onto `:root`). */
+  defaultMode?: string;
+}
+
+/** A token after alias resolution and `$type` inheritance — ready to emit. */
+export interface ResolvedToken {
+  /** Dotted path, e.g. `color.brand.500`. */
+  path: string;
+  /** The token's `$type` (inherited or inferred). */
+  type: TokenType | undefined;
+  /** The literal value with every alias followed to its source. */
+  value: TokenValue;
+  /**
+   * If this token is a direct alias of another, the target's dotted path.
+   * Emitters use it to preserve the reference (CSS `var(--target)`), so theming
+   * cascades instead of being flattened away.
+   */
+  aliasOf?: string;
+  $description?: string;
+}
+
+/** True when a node is a token leaf (has `$value`) rather than a group. */
+export function isToken(node: unknown): node is DesignToken {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    Object.prototype.hasOwnProperty.call(node, "$value")
+  );
+}

package/test/tokens.spec.ts

@@ -0,0 +1,302 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  defineTheme,
+  defineTokens,
+  emitCss,
+  emitTs,
+  cssVarName,
+  formatCssValue,
+  ref,
+  resolveTokens,
+  resolveTheme,
+  t,
+  ThemedTokens,
+  TokenDocument,
+} from "../src/tokens";
+import { compileTokens, loadTokens } from "../src/tokens/compile";
+import { renderStudio } from "../src/tokens/studio";
+
+const workRoot = join(__dirname, "tokens-fixtures");
+
+function findTok<T extends { path: string }>(list: T[], path: string): T {
+  const found = list.find((x) => x.path === path);
+  if (!found) throw new Error(`missing token ${path}`);
+  return found;
+}
+
+describe("design tokens — resolution", () => {
+  it("inherits a group $type down to its tokens", () => {
+    const doc: TokenDocument = {
+      color: { $type: "color", brand: { 500: { $value: "#4F6BFF" } } },
+    };
+    const resolved = resolveTokens(doc);
+    expect(findTok(resolved, "color.brand.500").type).toBe("color");
+  });
+
+  it("resolves alias values transitively and records the immediate target", () => {
+    const doc: TokenDocument = {
+      color: {
+        $type: "color",
+        brand: { 500: { $value: "#4F6BFF" } },
+        accent: { $value: ref("color.brand.500") },
+        cta: { $value: ref("color.accent") },
+      },
+    };
+    const resolved = resolveTokens(doc);
+    const accent = findTok(resolved, "color.accent");
+    const cta = findTok(resolved, "color.cta");
+    expect(accent.value).toBe("#4F6BFF");
+    expect(accent.aliasOf).toBe("color.brand.500");
+    // transitive: cta -> accent -> brand.500
+    expect(cta.value).toBe("#4F6BFF");
+    expect(cta.aliasOf).toBe("color.accent");
+  });
+
+  it("throws on a dangling alias", () => {
+    const doc: TokenDocument = { color: { a: { $type: "color", $value: ref("color.missing") } } };
+    expect(() => resolveTokens(doc)).toThrow(/unknown token "color.missing"/);
+  });
+
+  it("throws on an alias cycle", () => {
+    const doc: TokenDocument = {
+      a: { $type: "color", $value: ref("b") },
+      b: { $type: "color", $value: ref("a") },
+    };
+    expect(() => resolveTokens(doc)).toThrow(/cycle/i);
+  });
+
+  it("names CSS variables from dotted paths (kebab, camel-split, prefix)", () => {
+    expect(cssVarName("color.brand.500")).toBe("--color-brand-500");
+    expect(cssVarName("color.surfaceAlt")).toBe("--color-surface-alt");
+    expect(cssVarName("color.accent", "rs")).toBe("--rs-color-accent");
+  });
+});
+
+describe("design tokens — DSL builders", () => {
+  it("t.dimension coerces bare numbers to px; t.duration to ms", () => {
+    const doc = defineTokens({
+      space: { md: t.dimension(16) },
+      motion: { fast: t.duration(150) },
+    }).tokens;
+    const resolved = resolveTokens(doc);
+    expect(findTok(resolved, "space.md").value).toBe("16px");
+    expect(findTok(resolved, "motion.fast").value).toBe("150ms");
+  });
+
+  it("defineTokens normalises a bare tree and a themed shape alike", () => {
+    const bare = defineTokens({ color: { bg: t.color("#fff") } });
+    expect(bare.tokens.color).toBeDefined();
+    expect(bare.modes).toEqual({});
+
+    const themed = defineTokens({ tokens: { color: { bg: t.color("#fff") } }, defaultMode: "light" });
+    expect(themed.defaultMode).toBe("light");
+  });
+});
+
+describe("design tokens — CSS emission", () => {
+  const themed: ThemedTokens = {
+    tokens: {
+      color: {
+        $type: "color",
+        brand: { 500: { $value: "#4F6BFF" } },
+        accent: { $value: ref("color.brand.500") },
+        bg: { $value: "#FFFFFF" },
+      },
+      space: { $type: "dimension", md: { $value: "16px" } },
+      font: { family: { $type: "fontFamily", sans: { $value: ["Inter", "sans-serif"] } } },
+      shadow: { $type: "shadow", sm: { $value: { offsetX: "0", offsetY: "1px", blur: "2px", color: "#0001" } } },
+    },
+    modes: { dark: { color: { bg: { $value: "#06080F" } } } },
+    defaultMode: "light",
+  };
+
+  const css = emitCss(themed);
+
+  it("emits :root custom properties", () => {
+    expect(css).toMatch(/:root\s*\{/);
+    expect(css).toContain("--color-brand-500: #4F6BFF;");
+    expect(css).toContain("--space-md: 16px;");
+  });
+
+  it("preserves aliases as var() references so themes cascade", () => {
+    expect(css).toContain("--color-accent: var(--color-brand-500);");
+  });
+
+  it("quotes font families with spaces and joins the stack", () => {
+    expect(css).toContain('--font-family-sans: Inter, sans-serif;');
+  });
+
+  it("renders shadows as box-shadow strings", () => {
+    expect(css).toContain("--shadow-sm: 0 1px 2px #0001;");
+  });
+
+  it("scopes a mode override to its selector and omits unchanged tokens", () => {
+    expect(css).toContain('[data-theme="dark"]');
+    // only bg changed in dark
+    const darkBlock = css.slice(css.indexOf('[data-theme="dark"]'));
+    expect(darkBlock).toContain("--color-bg: #06080F;");
+    expect(darkBlock).not.toContain("--color-brand-500");
+  });
+
+  it("respects a variable prefix", () => {
+    expect(emitCss(themed, { prefix: "rs" })).toContain("--rs-color-brand-500:");
+  });
+});
+
+describe("design tokens — typed TS emission", () => {
+  const base = resolveTokens({
+    color: { $type: "color", brand: { 500: { $value: "#4F6BFF" } }, surfaceAlt: { $value: "#eee" } },
+  });
+  const source = emitTs(base);
+
+  it("emits a nested theme tree of var() references", () => {
+    expect(source).toContain('"500": "var(--color-brand-500)"');
+    expect(source).toContain('surfaceAlt: "var(--color-surface-alt)"');
+  });
+
+  it("emits a TokenPath union of every token", () => {
+    expect(source).toContain('| "color.brand.500"');
+    expect(source).toContain('| "color.surfaceAlt"');
+  });
+});
+
+describe("design tokens — compile to disk", () => {
+  const outDir = join(workRoot, "out");
+  const jsonSrc = join(workRoot, "sample.tokens.json");
+
+  beforeAll(() => {
+    mkdirSync(workRoot, { recursive: true });
+    writeFileSync(
+      jsonSrc,
+      JSON.stringify({
+        tokens: { color: { $type: "color", accent: { $value: "#4F6BFF" } } },
+        modes: { dark: { color: { accent: { $value: "#8BA4FF" } } } },
+        defaultMode: "light",
+      }),
+    );
+  });
+  afterAll(() => rmSync(workRoot, { recursive: true, force: true }));
+
+  it("writes tokens.rastack.json, tokens.css and tokens.ts", () => {
+    const { files } = compileTokens(jsonSrc, outDir);
+    expect(files.map((f) => f.split("/").pop())).toEqual([
+      "tokens.rastack.json",
+      "tokens.css",
+      "tokens.ts",
+    ]);
+    for (const f of files) expect(existsSync(f)).toBe(true);
+    expect(readFileSync(join(outDir, "tokens.css"), "utf8")).toContain("--color-accent: #4F6BFF;");
+    expect(readFileSync(join(outDir, "tokens.ts"), "utf8")).toContain('| "color.accent"');
+  });
+
+  it("loadTokens parses a bare DTCG tree as well as a themed doc", () => {
+    const bareSrc = join(workRoot, "bare.tokens.json");
+    writeFileSync(bareSrc, JSON.stringify({ color: { $type: "color", bg: { $value: "#fff" } } }));
+    const themed = loadTokens(bareSrc);
+    expect(themed.tokens.color).toBeDefined();
+  });
+});
+
+describe("design tokens — studio page", () => {
+  const themed = defineTokens({
+    tokens: { color: { brand: { 500: t.color("#4F6BFF") }, accent: t.color(ref("color.brand.500")) } },
+    modes: { dark: { color: { brand: { 500: t.color("#8BA4FF") } } } },
+    defaultMode: "light",
+  });
+
+  it("renders a self-contained HTML page embedding the tokens + CSS", () => {
+    const html = renderStudio(themed, { editable: true });
+    expect(html).toMatch(/^<!doctype html>/);
+    expect(html).toContain("--color-brand-500: #4F6BFF;");
+    expect(html).toContain('id="studio-data"');
+    // the embedded payload carries the layers + raw doc for the editor
+    expect(html).toContain('"color.accent"');
+    expect(html).toContain('"editable":true');
+  });
+});
+
+describe("design tokens — defineTheme() intent layer", () => {
+  it("derives a full 50–950 brand scale from one colour, with 500 = the seed", () => {
+    const resolved = resolveTheme(defineTheme({ brand: "#4F6BFF" }));
+    expect(findTok(resolved.base, "color.brand.500").value).toBe("#4F6BFF");
+    for (const step of ["50", "100", "200", "300", "400", "600", "700", "800", "900", "950"]) {
+      expect(findTok(resolved.base, `color.brand.${step}`).value).toMatch(/^#[0-9A-F]{6}$/);
+    }
+  });
+
+  it("generates semantic tokens plus a dark mode by default", () => {
+    const themed = defineTheme({ brand: "#4F6BFF" });
+    expect(Object.keys(themed.modes ?? {})).toEqual(["dark"]);
+    const resolved = resolveTheme(themed);
+    for (const name of ["bg", "surface", "border", "text", "text-muted", "accent", "on-accent"]) {
+      expect(findTok(resolved.base, `color.${name}`)).toBeDefined();
+    }
+    // The accent is an alias of the brand ramp, and reads lighter in dark.
+    expect(findTok(resolved.base, "color.accent").aliasOf).toBe("color.brand.500");
+    expect(findTok(resolved.modes.dark, "color.accent").aliasOf).toBe("color.brand.400");
+    // dark bg is dark, light bg is white
+    expect(findTok(resolved.base, "color.bg").value).toBe("#FFFFFF");
+    expect(findTok(resolved.modes.dark, "color.bg").value).not.toBe("#FFFFFF");
+  });
+
+  it("picks a readable on-accent colour by contrast", () => {
+    expect(findTok(resolveTheme(defineTheme({ brand: "#FACC15" })).base, "color.on-accent").value).toBe("#0B1020");
+    expect(findTok(resolveTheme(defineTheme({ brand: "#1D4ED8" })).base, "color.on-accent").value).toBe("#FFFFFF");
+  });
+
+  it("maps radius keywords and honours a numeric radius", () => {
+    expect(findTok(resolveTheme(defineTheme({ brand: "#4F6BFF", radius: "sharp" })).base, "color.brand.500")).toBeDefined();
+    const r = resolveTheme(defineTheme({ brand: "#4F6BFF", radius: 20 }));
+    expect(findTok(r.base, "radius.md").value).toBe("20px");
+  });
+
+  it("lowers to the same ThemedTokens shape and compiles to valid CSS", () => {
+    const css = emitCss(defineTheme({ brand: "#4F6BFF", font: "Poppins" }));
+    expect(css).toContain("--color-brand-500: #4F6BFF;");
+    expect(css).toContain("--color-accent: var(--color-brand-500);");
+    expect(css).toContain('[data-theme="dark"]');
+    expect(css).toContain("--font-family-sans: Poppins;");
+  });
+
+  it("applies colour overrides and the extend escape hatch", () => {
+    const themed = defineTheme({
+      brand: "#4F6BFF",
+      colors: { success: "#00A86B" },
+      extend: { tokens: { z: { index: { modal: { $type: "number", $value: 1000 } } } } },
+    });
+    const base = resolveTheme(themed).base;
+    expect(findTok(base, "color.success").value).toBe("#00A86B");
+    expect(findTok(base, "z.index.modal").value).toBe(1000);
+  });
+
+  it("appearance:'light' emits no dark mode; 'dark' makes :root dark", () => {
+    expect(Object.keys(defineTheme({ brand: "#4F6BFF", appearance: "light" }).modes ?? {})).toEqual([]);
+    const dark = defineTheme({ brand: "#4F6BFF", appearance: "dark" });
+    expect(dark.defaultMode).toBe("dark");
+    expect(findTok(resolveTheme(dark).base, "color.bg").value).not.toBe("#FFFFFF");
+  });
+});
+
+describe("design tokens — the repo's own theme.tokens.ts + .json agree", () => {
+  it("the TS authoring source resolves and matches the JSON source", () => {
+    // Executed by ts-jest, importing the package by its subpath name.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const tsThemed = require("../../tokens/theme.tokens").default as ThemedTokens;
+    const jsonThemed = loadTokens(join(__dirname, "..", "..", "tokens", "theme.tokens.json"));
+
+    const fromTs = resolveTheme(tsThemed);
+    const fromJson = resolveTheme(jsonThemed);
+
+    // Same set of token paths and the same emitted CSS values (composite types
+    // like shadows may be authored with numbers in TS and strings in JSON, but
+    // must render identically).
+    const map = (r: ReturnType<typeof resolveTheme>) =>
+      Object.fromEntries(r.base.map((tok) => [tok.path, formatCssValue(tok)]));
+    expect(map(fromTs)).toEqual(map(fromJson));
+
+    // Alias cascades through the dark mode (accent follows brand.500).
+    const darkAccent = findTok(fromTs.modes.dark, "color.accent");
+    expect(darkAccent.value).toBe("#8BA4FF");
+  });
+});