@heyramzi/ui 1.54.2 → 2.0.1

package/COMPONENTS.md

@@ -67,6 +67,7 @@ Generic pieces built on the primitives, imported from `@heyramzi/ui/components/<
 - `icon` — Icon, a Phosphor component at a size
 - `language-flag` — LanguageFlag
 - `list-page` — ListPageShell, MasterDetail, GroupedList, RailRow and the rest of the master-detail page kit, NoticeBar, EmptyState, FilterPopover, setSectionHost
+- `toolbar` — Toolbar: one row at any width; search, tabs and the view switch fold into menus in a narrow pane
 - `locale-switch` — LocaleSwitch, a language switch on SegmentedFilter
 - `mark` — Mark, a logo or photo glyph with an initial fallback
 - `open-in` — OpenIn, a link out to a tool that takes the tool's name, label and mark as a prop
@@ -134,6 +135,6 @@ Generic pieces built on the primitives, imported from `@heyramzi/ui/components/<
 
 ---
 
-Skipped on purpose: brand assets (logos, marks, brand renderer), kanban, list, gantt and status (they live in `@heyramzi/tasks`), and charts
-(they live in `@heyramzi/charts`). The bot avatars
+Skipped on purpose: brand assets (logos, marks, brand renderer), kanban, list, gantt and status (they live in `@heyramzi/ui/tasks`), and charts
+(they live in `@heyramzi/ui/charts`). The bot avatars
 are in `src/agents`, imported from `@heyramzi/ui/agents`.

package/README.md

@@ -33,21 +33,46 @@ Import the style layer once, after Tailwind:
 @import "@heyramzi/ui/animations";
 ```
 
-`tokens.css` carries the palette, the semantic tokens and the craft layer
+`tokens.css` carries a neutral palette, the semantic tokens and the craft layer
 (radius, elevation, focus, motion). `animations` carries the keyframes the
 components reference. If you use the Attachment or Message component, also
 import `@heyramzi/ui/shadcn/utilities.css`.
 
-Retheme by overriding any variable on `:root`, for example
-`--color-brand-indigo` or `--radius-lg`. Dark mode keys off a `.dark`
-class on `html`.
+## A brand
 
-Rich text lives in [`@heyramzi/rich-editor`](https://github.com/heyramzi/ui/tree/main/packages/rich-editor),
-so the kit doesn't pull Tiptap into every app.
+The default look is neutral, and its colours are named by role: `brand`, `ink`, `surface`,
+`line`, `raised`, `paper`, `highlight` and `signal` (`bg-brand`, `text-ink`, `border-line`).
+A client's look is one typed file with no build step:
 
-Charts live in their own package now,
-[`@heyramzi/charts`](https://github.com/heyramzi/ui/tree/main/packages/charts). It reads
-the same tokens, so import `tokens.css` once and both work.
+```ts
+// brand.ts
+import { defineBrand } from "@heyramzi/ui/brand";
+
+export const brand = defineBrand({
+  colors: { brand: "oklch(0.5 0.2 272)", ink: "oklch(0.12 0.04 258)" },
+  fonts: { sans: '"Satoshi", system-ui, sans-serif' },
+});
+```
+
+Apply it with `brandStyle(brand)` on `<html style>` (right on first paint), `applyBrand(brand)`
+in the browser, or `brandCss(brand)` in a stylesheet. A brand names only the roles it changes; light
+and dark both follow from the tokens, and the tint scales (`brand-100` to `brand-800`) derive
+from the three hues.
+
+## Subpaths
+
+One package, six larger parts, each imported from its own subpath:
+
+| Subpath | What it is |
+| --- | --- |
+| `@heyramzi/ui/tasks` | Board, list, gantt, status badges, task detail, record, time tracker, inbox |
+| `@heyramzi/ui/charts` | LayerChart charts, sparklines, stat cards, and `/charts/dashboard` |
+| `@heyramzi/ui/slides` | Decks on a fixed canvas, plus `/slides/model` and `/slides/export` |
+| `@heyramzi/ui/editor` | The Tiptap editor, its renderer, `/editor/markdown`, `/editor/block-ops` |
+| `@heyramzi/ui/onboarding` | Page tours |
+| `@heyramzi/ui/canvas` | The xyflow canvas with a pen and headless ops. Add `@xyflow/svelte` yourself |
+
+Each has a README next to its source under `src/<subpath>/`.
 
 React and other framework ports are out of scope. The source is Svelte 5
 runes only.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@heyramzi/ui",
-  "version": "1.54.2",
-  "description": "Svelte 5 UI primitives: effects, animations, and shared component CSS.",
+  "version": "2.0.1",
+  "description": "Svelte 5 UI for apps: primitives, effects and animations, plus tasks, charts, slides, an editor, onboarding and a canvas as subpaths.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,6 +29,11 @@
       "default": "./src/index.ts"
     },
     "./tokens.css": "./src/tokens/index.css",
+    "./brand": {
+      "svelte": "./src/brand/index.ts",
+      "types": "./src/brand/index.ts",
+      "default": "./src/brand/index.ts"
+    },
     "./lib/*.js": {
       "svelte": "./src/lib/*.ts",
       "types": "./src/lib/*.ts",
@@ -166,28 +171,210 @@
       "types": "./src/agents/index.ts",
       "default": "./src/agents/index.ts"
     },
-    "./agents/demo.svelte": "./src/agents/demo.svelte"
+    "./agents/demo.svelte": "./src/agents/demo.svelte",
+    "./tasks": {
+      "svelte": "./src/tasks/index.ts",
+      "types": "./src/tasks/index.ts",
+      "default": "./src/tasks/index.ts"
+    },
+    "./tasks/kanban": {
+      "svelte": "./src/tasks/kanban-board.svelte",
+      "types": "./src/tasks/kanban-board.svelte",
+      "default": "./src/tasks/kanban-board.svelte"
+    },
+    "./tasks/list": {
+      "svelte": "./src/tasks/task-list.svelte",
+      "types": "./src/tasks/task-list.svelte",
+      "default": "./src/tasks/task-list.svelte"
+    },
+    "./tasks/gantt": {
+      "svelte": "./src/tasks/task-gantt.svelte",
+      "types": "./src/tasks/task-gantt.svelte",
+      "default": "./src/tasks/task-gantt.svelte"
+    },
+    "./tasks/status": {
+      "svelte": "./src/tasks/status-badge.svelte",
+      "types": "./src/tasks/status-badge.svelte",
+      "default": "./src/tasks/status-badge.svelte"
+    },
+    "./tasks/status-dot": {
+      "svelte": "./src/tasks/status-dot.svelte",
+      "types": "./src/tasks/status-dot.svelte",
+      "default": "./src/tasks/status-dot.svelte"
+    },
+    "./tasks/statuses": {
+      "svelte": "./src/tasks/define-statuses.ts",
+      "types": "./src/tasks/define-statuses.ts",
+      "default": "./src/tasks/define-statuses.ts"
+    },
+    "./tasks/time": {
+      "svelte": "./src/tasks/time/time-tracker.svelte",
+      "types": "./src/tasks/time/time-tracker.svelte",
+      "default": "./src/tasks/time/time-tracker.svelte"
+    },
+    "./tasks/inbox": {
+      "svelte": "./src/tasks/inbox/index.ts",
+      "types": "./src/tasks/inbox/index.ts",
+      "default": "./src/tasks/inbox/index.ts"
+    },
+    "./tasks/side-panel": {
+      "svelte": "./src/tasks/side-panel.svelte",
+      "types": "./src/tasks/side-panel.svelte",
+      "default": "./src/tasks/side-panel.svelte"
+    },
+    "./tasks/presets/sales": {
+      "svelte": "./src/tasks/presets/sales.ts",
+      "types": "./src/tasks/presets/sales.ts",
+      "default": "./src/tasks/presets/sales.ts"
+    },
+    "./tasks/detail": {
+      "svelte": "./src/tasks/detail/task-detail.svelte",
+      "types": "./src/tasks/detail/task-detail.svelte",
+      "default": "./src/tasks/detail/task-detail.svelte"
+    },
+    "./tasks/detail-demo.svelte": "./src/tasks/detail/detail-demo.svelte",
+    "./tasks/record": {
+      "svelte": "./src/tasks/record/index.ts",
+      "types": "./src/tasks/record/index.ts",
+      "default": "./src/tasks/record/index.ts"
+    },
+    "./tasks/record-demo.svelte": "./src/tasks/record/record-demo.svelte",
+    "./tasks/demo": {
+      "svelte": "./src/tasks/demo.svelte",
+      "default": "./src/tasks/demo.svelte"
+    },
+    "./tasks/demo.svelte": "./src/tasks/demo.svelte",
+    "./charts": {
+      "svelte": "./src/charts/index.ts",
+      "types": "./src/charts/index.ts",
+      "default": "./src/charts/index.ts"
+    },
+    "./charts/dashboard": {
+      "svelte": "./src/charts/dashboard/index.ts",
+      "types": "./src/charts/dashboard/index.ts",
+      "default": "./src/charts/dashboard/index.ts"
+    },
+    "./slides": {
+      "types": "./src/slides/index.ts",
+      "svelte": "./src/slides/index.ts",
+      "default": "./src/slides/index.ts"
+    },
+    "./slides/model": {
+      "types": "./src/slides/model.ts",
+      "default": "./src/slides/model.ts"
+    },
+    "./slides/export": {
+      "types": "./src/slides/export/index.ts",
+      "default": "./src/slides/export/index.ts"
+    },
+    "./slides/demo": {
+      "svelte": "./src/slides/demo.svelte",
+      "default": "./src/slides/demo.svelte"
+    },
+    "./slides/demo.svelte": "./src/slides/demo.svelte",
+    "./slides/demo-slides": {
+      "svelte": "./src/slides/demo-slides.svelte",
+      "default": "./src/slides/demo-slides.svelte"
+    },
+    "./slides/demo-slides.svelte": "./src/slides/demo-slides.svelte",
+    "./editor": {
+      "svelte": "./src/editor/index.ts",
+      "types": "./src/editor/index.ts",
+      "default": "./src/editor/index.ts"
+    },
+    "./editor/serializer": {
+      "types": "./src/editor/serializer.ts",
+      "default": "./src/editor/serializer.ts"
+    },
+    "./editor/markdown": {
+      "types": "./src/editor/markdown.ts",
+      "default": "./src/editor/markdown.ts"
+    },
+    "./editor/block-ops": {
+      "types": "./src/editor/block-ops.ts",
+      "default": "./src/editor/block-ops.ts"
+    },
+    "./editor/inline-editor": {
+      "svelte": "./src/editor/inline-editor.svelte",
+      "default": "./src/editor/inline-editor.svelte"
+    },
+    "./editor/content.css": {
+      "style": "./src/editor/content.css",
+      "default": "./src/editor/content.css"
+    },
+    "./onboarding": {
+      "svelte": "./src/onboarding/index.ts",
+      "types": "./src/onboarding/index.ts",
+      "default": "./src/onboarding/index.ts"
+    },
+    "./onboarding/stores": {
+      "svelte": "./src/onboarding/stores.ts",
+      "types": "./src/onboarding/stores.ts",
+      "default": "./src/onboarding/stores.ts"
+    },
+    "./onboarding/demo": {
+      "svelte": "./src/onboarding/demo.svelte",
+      "default": "./src/onboarding/demo.svelte"
+    },
+    "./onboarding/demo.svelte": "./src/onboarding/demo.svelte",
+    "./canvas": {
+      "types": "./src/canvas/index.ts",
+      "svelte": "./src/canvas/index.ts",
+      "default": "./src/canvas/index.ts"
+    },
+    "./canvas/*.svelte": {
+      "types": "./src/canvas/*.svelte",
+      "svelte": "./src/canvas/*.svelte",
+      "default": "./src/canvas/*.svelte"
+    },
+    "./canvas/*.css": "./src/canvas/*.css",
+    "./canvas/*.js": {
+      "types": "./src/canvas/*.ts",
+      "svelte": "./src/canvas/*.ts",
+      "default": "./src/canvas/*.ts"
+    }
   },
   "dependencies": {
+    "@dagrejs/dagre": "^3.1.1",
     "@shadcn-svelte/primitives": "^0.0.1",
+    "@tiptap/core": "^3.32.0",
+    "@tiptap/extension-drag-handle": "^3.32.0",
+    "@tiptap/extension-image": "^3.32.0",
+    "@tiptap/extension-placeholder": "^3.32.0",
+    "@tiptap/pm": "^3.32.0",
+    "@tiptap/starter-kit": "^3.32.0",
+    "@zag-js/svelte": "^1.46.0",
+    "@zag-js/tour": "^1.46.0",
     "clsx": "^2.1.1",
-    "marked": "^18.1.0",
-    "phosphor-svelte": "^3.1.0",
+    "d3-scale": "^4.0.2",
+    "d3-shape": "^3.2.0",
+    "layerchart": "^2.8.1",
+    "markdown-it": "^15.0.3",
+    "marked": "^18.1.1",
+    "perfect-freehand": "^1.2.3",
+    "phosphor-svelte": "^3.1.1",
+    "roughjs": "^4.6.6",
     "shiki": "^4.5.0",
     "tailwind-merge": "^3.7.0",
-    "tailwind-variants": "^3.3.1"
+    "tailwind-variants": "^3.3.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@internationalized/date": "^3.12.4",
     "@sveltejs/vite-plugin-svelte": "^7.3.1",
-    "@types/node": "^26.6.4",
-    "bits-ui": "^2.19.5",
-    "jsdom": "^30.1.2",
+    "@types/d3-scale": "^4.0.9",
+    "@types/d3-shape": "^3.2.0",
+    "@types/node": "^26.6.5",
+    "@xyflow/svelte": "^1.7.0",
+    "bits-ui": "^2.20.0",
+    "jsdom": "^30.1.3",
     "mode-watcher": "^1.1.0",
     "svelte": "^5.57.2",
+    "svelte-check": "^4.7.7",
     "svelte-sonner": "^1.2.1",
-    "vite-plus": "^1.0.0",
-    "vitest": "^5.0.3"
+    "typescript": "~7.0.2",
+    "vite-plus": "^1.3.0",
+    "vitest": "^5.0.5"
   },
   "peerDependencies": {
     "@internationalized/date": "^3.12.4",
@@ -195,7 +382,8 @@
     "bits-ui": "^2.19.5",
     "mode-watcher": "^1.1.0",
     "svelte": "^5.57.2",
-    "svelte-sonner": "^1.2.1"
+    "svelte-sonner": "^1.2.1",
+    "@xyflow/svelte": "^1.7.0"
   },
   "peerDependenciesMeta": {
     "mode-watcher": {
@@ -209,6 +397,9 @@
     },
     "@tabler/icons-svelte-runes": {
       "optional": true
+    },
+    "@xyflow/svelte": {
+      "optional": true
     }
   },
   "scripts": {
@@ -216,6 +407,7 @@
     "sync:transitions": "node scripts/sync-transitions.mjs",
     "sync:shadcn": "node scripts/sync-shadcn.mjs",
     "sync": "pnpm sync:transitions && pnpm sync:shadcn",
-    "sync:check": "node scripts/sync-transitions.mjs --check && node scripts/sync-shadcn.mjs --check"
+    "sync:check": "node scripts/sync-transitions.mjs --check && node scripts/sync-shadcn.mjs --check",
+    "check": "svelte-check --tsconfig ./tsconfig.json"
   }
 }

package/scripts/sync-shadcn.mjs

@@ -69,6 +69,8 @@ const DEMO_ALIASES = [
   ["$lib/utils.js", "@heyramzi/utils"],
   // The peer here is the runes build, published under its own name.
   ["@tabler/icons-svelte/", "@tabler/icons-svelte-runes/"],
+  // Upstream's docs live under /docs/components; ours are at /components, and the prerender follows the link.
+  ['href="/docs/components"', 'href="/components"'],
 ];
 
 /* Registry primitives this package does not ship: no product imports them. Skipped, so a sync does not bring them back. */

package/src/ai/generation-progress/GenerationProgress.svelte

@@ -111,10 +111,10 @@
 	/* ── Surface ─────────────────────────────────────────── */
 	.gen {
 		--shimmer-dur: 2200ms;
-		--shimmer-base: var(--color-brand-indigo);
+		--shimmer-base: var(--color-brand);
 		/* The band is darker than the base on a pale tint and lighter on ink.
 		   Otherwise the sweep looks like the label dropping out. */
-		--shimmer-highlight: color-mix(in oklab, black 45%, var(--color-brand-indigo));
+		--shimmer-highlight: color-mix(in oklab, black 45%, var(--color-brand));
 		--shimmer-band: 400%;
 		--shimmer-ease: linear;
 		--digit-dur: var(--duration-very-slow);
@@ -126,11 +126,11 @@
 
 		padding: 0.625rem 0.875rem;
 		border-radius: var(--radius-lg);
-		background: color-mix(in oklab, var(--color-brand-indigo) 10%, transparent);
+		background: color-mix(in oklab, var(--color-brand) 10%, transparent);
 	}
 
 	:global(.dark) .gen {
-		--shimmer-highlight: color-mix(in oklab, white 70%, var(--color-brand-indigo));
+		--shimmer-highlight: color-mix(in oklab, white 70%, var(--color-brand));
 	}
 
 	.gen-failed {
@@ -150,7 +150,7 @@
 		width: 0.375rem;
 		height: 0.375rem;
 		border-radius: 9999px;
-		background: var(--color-brand-indigo);
+		background: var(--color-brand);
 		animation: gen-pulse 1.8s var(--ease-in-out, ease-in-out) infinite;
 	}
 
@@ -166,14 +166,14 @@
 		line-height: 1.4;
 	}
 
-	/* terra-600, not --color-destructive: that token is tuned for fills, and at
+	/* signal-600, not --color-destructive: that token is tuned for fills, and at
 	   L=0.6 small text on the pale tint fails. Dark mode uses the lighter step. */
 	.gen-failed .gen-label {
-		color: var(--color-terra-600);
+		color: var(--color-signal-600);
 	}
 
 	:global(.dark) .gen-failed .gen-label {
-		color: var(--color-terra-400);
+		color: var(--color-signal-400);
 	}
 
 	.gen-meta {
@@ -183,7 +183,7 @@
 		font-size: 0.75rem;
 		font-weight: 500;
 		font-variant-numeric: tabular-nums;
-		color: var(--color-brand-indigo);
+		color: var(--color-brand);
 	}
 
 	.gen-count {
@@ -203,7 +203,7 @@
 		margin-top: 0.5rem;
 		height: 0.25rem;
 		border-radius: 9999px;
-		background: color-mix(in oklab, var(--color-brand-indigo) 22%, transparent);
+		background: color-mix(in oklab, var(--color-brand) 22%, transparent);
 	}
 
 	.gen-fill {
@@ -211,7 +211,7 @@
 		height: 100%;
 		transform-origin: left;
 		border-radius: 9999px;
-		background: var(--color-brand-indigo);
+		background: var(--color-brand);
 		transition: transform var(--duration-slow, 400ms) var(--ease-smooth-out, ease);
 	}
 
@@ -232,7 +232,7 @@
 		text-overflow: ellipsis;
 		/* Mix toward the foreground, not transparent: a 70% indigo wash on its
 		   own track measured 2.9:1. This stays quieter than the label and AA. */
-		color: color-mix(in oklab, var(--color-brand-indigo) 70%, var(--color-foreground));
+		color: color-mix(in oklab, var(--color-brand) 70%, var(--color-foreground));
 		animation: gen-step-in var(--duration-quick, 150ms) var(--ease-in-out, ease-in-out) both;
 	}
 

package/src/ambient.d.ts

@@ -2,3 +2,11 @@
  * A stylesheet imported for its side effect, bundled by the consumer's Vite.
  */
 declare module "*.css";
+
+/**
+ * An SVG imported as a URL, resolved by the consumer's Vite.
+ */
+declare module "*.svg" {
+  const src: string;
+  export default src;
+}

package/src/brand/brand.test.ts

@@ -0,0 +1,67 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vite-plus/test";
+import { BRAND_COLOR_VARS, applyBrand, brandCss, brandStyle, brandVars, defineBrand } from "./index.js";
+
+const TOKENS = join(import.meta.dirname, "..", "tokens");
+const palette = readFileSync(join(TOKENS, "palette.css"), "utf8");
+
+describe("brandVars", () => {
+  it("sets only the roles a brand names", () => {
+    const brand = defineBrand({ colors: { brand: "oklch(0.5 0.2 272)", signal: "#f0503d" } });
+    expect(brandVars(brand)).toEqual({ "--brand": "oklch(0.5 0.2 272)", "--brand-signal": "#f0503d" });
+  });
+
+  it("maps fonts and extra properties", () => {
+    const brand = defineBrand({
+      colors: { brand: "red" },
+      fonts: { sans: '"Satoshi", system-ui', mono: "ui-monospace" },
+      vars: { "--logo-height": "24px" },
+    });
+    expect(brandVars(brand)).toEqual({
+      "--brand": "red",
+      "--font-sans": '"Satoshi", system-ui',
+      "--font-mono": "ui-monospace",
+      "--logo-height": "24px",
+    });
+  });
+
+  it("refuses a value that would break out of its declaration", () => {
+    expect(() => brandVars({ colors: { brand: "red; } body { display: none" } })).toThrow(/--brand/);
+  });
+});
+
+describe("the three ways to apply one", () => {
+  const brand = defineBrand({ colors: { brand: "blue", ink: "black" } });
+
+  it("writes a style attribute and a rule", () => {
+    expect(brandStyle(brand)).toBe("--brand:blue;--brand-ink:black");
+    expect(brandCss(brand, ".client")).toBe(".client {\n  --brand: blue;\n  --brand-ink: black;\n}\n");
+  });
+
+  it("applies to an element and puts back what it found", () => {
+    const root = document.createElement("div");
+    root.style.setProperty("--brand", "green");
+    const reset = applyBrand(brand, root);
+    expect(root.style.getPropertyValue("--brand")).toBe("blue");
+    expect(root.style.getPropertyValue("--brand-ink")).toBe("black");
+    reset();
+    expect(root.style.getPropertyValue("--brand")).toBe("green");
+    expect(root.style.getPropertyValue("--brand-ink")).toBe("");
+  });
+});
+
+describe("the tokens", () => {
+  it("define a neutral default for every role a brand can set", () => {
+    for (const name of Object.values(BRAND_COLOR_VARS)) {
+      expect(palette, name).toMatch(new RegExp(`^\\s+${name}: `, "m"));
+    }
+  });
+
+  it("carry no client palette", () => {
+    for (const file of readdirSync(TOKENS).filter((f) => f.endsWith(".css"))) {
+      const css = readFileSync(join(TOKENS, file), "utf8");
+      expect(css, file).not.toMatch(/brand-(indigo|sand|terra|night|veil|dusk|cream|linen|mist)|--(indigo|sand|terra)-\d/);
+    }
+  });
+});

package/src/brand/index.ts

@@ -0,0 +1,137 @@
+/**
+ * A client's brand is a typed object in its own `brand.ts`, with no build step:
+ *
+ *   export const brand = defineBrand({ colors: { brand: "oklch(0.5 0.2 272)" } });
+ *
+ * `@heyramzi/ui/tokens.css` ships a neutral look. A brand replaces only the roles it names:
+ *   - on the server, put `brandStyle(brand)` on the `<html style>` so the first paint is right;
+ *   - or call `applyBrand(brand)` once in the browser;
+ *   - or write `brandCss(brand)` into a stylesheet.
+ * Light and dark come from the tokens, which read these roles, so a brand never types both.
+ */
+
+/** Any CSS colour: oklch(), hex, a named colour or a var(). */
+export type CssColor = string;
+
+export type BrandColors = {
+  /** The signature colour: focus ring, links, active states, the mark. */
+  brand: CssColor;
+  /** The same colour lifted for a dark page. Falls back to the neutral default. */
+  brandOnDark?: CssColor;
+  /** Warmth: badges, highlights, soft accents. */
+  highlight?: CssColor;
+  /** Attention: warnings, errors, energy. */
+  signal?: CssColor;
+  /** The dark page background. */
+  ink?: CssColor;
+  /** Cards and panels on a dark page. */
+  surface?: CssColor;
+  /** Borders and dividers on a dark page. */
+  line?: CssColor;
+  /** Hover surfaces and inputs on a dark page. */
+  raised?: CssColor;
+  /** Text on a dark page, and a light page's background tone. */
+  paper?: CssColor;
+  /** Cards on a light page. */
+  surfaceLight?: CssColor;
+  /** Borders on a light page. */
+  lineLight?: CssColor;
+};
+
+export type BrandFonts = {
+  /** The body family, as CSS: `"Satoshi", system-ui, sans-serif`. */
+  sans?: string;
+  /** Headings. Falls back to the body family. */
+  heading?: string;
+  /** Code and figures. */
+  mono?: string;
+  /** Quotes. Falls back to the mono family. */
+  quote?: string;
+};
+
+export type Brand = {
+  colors: BrandColors;
+  fonts?: BrandFonts;
+  /** Extra custom properties the brand owns, such as a logo size. Each key starts with `--`. */
+  vars?: Record<`--${string}`, string>;
+};
+
+const COLOR_VARS = {
+  brand: "--brand",
+  brandOnDark: "--brand-on-dark",
+  highlight: "--brand-highlight",
+  signal: "--brand-signal",
+  ink: "--brand-ink",
+  surface: "--brand-surface",
+  line: "--brand-line",
+  raised: "--brand-raised",
+  paper: "--brand-paper",
+  surfaceLight: "--brand-surface-light",
+  lineLight: "--brand-line-light",
+} as const satisfies Record<keyof BrandColors, string>;
+
+const FONT_VARS = {
+  sans: "--font-sans",
+  heading: "--font-heading",
+  mono: "--font-mono",
+  quote: "--font-quote",
+} as const satisfies Record<keyof BrandFonts, string>;
+
+/** The custom property each colour role sets. The tokens read these and nothing else. */
+export const BRAND_COLOR_VARS: Readonly<Record<keyof BrandColors, string>> = COLOR_VARS;
+
+/** Keeps a typed brand typed at the call site. It returns the object unchanged. */
+export function defineBrand<const B extends Brand>(brand: B): B {
+  return brand;
+}
+
+function checked(name: string, value: string): string {
+  if (/[;{}<>]/.test(value)) throw new Error(`brand: ${name} holds a character CSS would read as more than a value`);
+  return value;
+}
+
+/** The custom properties a brand sets, by name. Roles the brand leaves out keep the neutral default. */
+export function brandVars(brand: Brand): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, name] of Object.entries(COLOR_VARS)) {
+    const value = brand.colors[key as keyof BrandColors];
+    if (value !== undefined) out[name] = checked(name, value);
+  }
+  for (const [key, name] of Object.entries(FONT_VARS)) {
+    const value = brand.fonts?.[key as keyof BrandFonts];
+    if (value !== undefined) out[name] = checked(name, value);
+  }
+  for (const [name, value] of Object.entries(brand.vars ?? {})) out[name] = checked(name, value);
+  return out;
+}
+
+/** The brand as a `style` attribute value: put it on `<html>` in `app.html` or a layout. */
+export function brandStyle(brand: Brand): string {
+  return Object.entries(brandVars(brand))
+    .map(([name, value]) => `${name}:${value}`)
+    .join(";");
+}
+
+/** The brand as a rule, for a stylesheet or a `<style>` in `<svelte:head>`. */
+export function brandCss(brand: Brand, selector = ":root"): string {
+  const body = Object.entries(brandVars(brand))
+    .map(([name, value]) => `  ${name}: ${value};`)
+    .join("\n");
+  return `${selector} {\n${body}\n}\n`;
+}
+
+/** Sets the brand on the page in the browser. Returns a function that puts the neutral look back. */
+export function applyBrand(brand: Brand, root: HTMLElement = document.documentElement): () => void {
+  const vars = brandVars(brand);
+  const before = new Map<string, string>();
+  for (const [name, value] of Object.entries(vars)) {
+    before.set(name, root.style.getPropertyValue(name));
+    root.style.setProperty(name, value);
+  }
+  return () => {
+    for (const [name, value] of before) {
+      if (value) root.style.setProperty(name, value);
+      else root.style.removeProperty(name);
+    }
+  };
+}