@starcier/create-builder 0.0.0-stage → 1.0.0-next.1

package/template/.claude/skills/prototype-page-builder/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: prototype-page-builder
+description: Create a new prototype page in this builder, composed only from the existing design tokens and design-system components, with local mock data, data-tour anchors and a guided tour — no APIs, auth or backend. Prototypes live in folders under src/prototypes/. Use when asked to "build/create a prototype/mockup", "add a prototype for <area>", or "prototype <screen>".
+---
+
+# Prototype Page Builder
+
+You are creating a new **prototype** in this Prototype Builder — a Vite + React 19 + TypeScript
+app whose prototypes compose the design system with mock data and never touch a backend. The
+builder adds review comments, guided tours and sharing around them. Follow this procedure exactly.
+
+## Golden rules
+
+- **Compose the existing design system. Never invent one.** Use the components in
+  `src/design-system/components/` and the tokens in `src/design-system/tokens.ts` (in CSS, through
+  the `--color-*`, `--space-*`, `--radius-*` and `--text-*` custom properties).
+- **No raw values.** No hex / `rgba` / named colors, no raw px design values, no one-off font
+  sizes, no bespoke primitives.
+- **No backend.** No API client, query hook, service, auth or `fetch`. All data is local mock data
+  in the prototype's own folder.
+- **Don't recreate app chrome.** The top bar, theme toggle and the review and tour controls come
+  from the builder shell, configured in `src/App.tsx`.
+- **This is not Next.js.** No `page.tsx`, no App Router, no `'use client'`. Imports are relative.
+- **Only create a new component if none fits** — generic ones go in
+  `src/design-system/components/`, token-only, and are flagged for review.
+
+## Folders
+
+Prototypes are grouped one level deep, e.g. `getting-started/welcome`, and open at
+`/prototypes/<folder>/<id>`. The reference to mirror is `src/prototypes/getting-started/welcome/`.
+
+## Procedure
+
+1. **Read `AGENTS.md`** and the `design-system` skill.
+2. **Decide the folder.** If none was named, ASK: an existing folder (see `registry.ts`), a new
+   one (ask for its name), or none. Derive `folder` (kebab-case) and `folderLabel` (Title Case).
+3. **Read the components** in `src/design-system/components/` you will compose.
+4. **Inspect the reference prototype** and match its shape.
+5. **Create `src/prototypes/<folder>/<id>/`** (`<id>` in kebab-case) with:
+   - `<PascalName>.tsx` — the page, composed from components and tokens;
+   - `<name>.css` — its layout, using the custom properties only;
+   - `data.ts` — all its mock data, static and typed;
+   - `workflows.ts` — at least one `OnboardingWorkflow` (type from `@starcier/collab-core`) with
+     `prototypeId` = `"<folder>/<id>"`, steps targeting `data-tour` selectors;
+   - `README.md` — what it shows and which tours it ships;
+   - `index.ts` — exports the page and its tours.
+6. **Add `data-tour` attributes** to the key regions: header, filters, lists, primary actions.
+7. **Register it:** an entry in `src/prototypes/registry.ts` (`slug`, `title`, `description`,
+   `folder`, `folderLabel`, `status`, `component`), and its tour in `src/prototypes/workflows.ts`.
+8. **Check it in both themes.**
+9. **Run the quality gate:** `npm run build` and `npm run lint`. Fix everything you introduced.
+10. **Summarise for review:** what it shows, its folder, the components and tokens used, where its
+    mock data lives, its tours, and any new component (with the reason).
+
+## Tour step options
+
+A `TourStep` targets a selector (prefer `[data-tour="…"]`) with a `title`, a `description` and an
+optional `placement`. Two power options:
+
+- **`initiateAction: true`** — pressing Next clicks the step's target, so the dialog or drawer it
+  opens is present for the next step, which should target something inside it.
+- **`populateInputs: true`** — fills every input inside the target with test data, e.g. to enable
+  a disabled submit button. Point the target at the form.
+
+Review comments cannot be placed inside dialogs; tours can step into them.
+
+## Self-check
+
+- [ ] Lives in `src/prototypes/<folder>/<id>/`, registered in `registry.ts` and `workflows.ts`,
+      visible in the catalogue.
+- [ ] `slug` and `prototypeId` are both exactly `<folder>/<id>`.
+- [ ] No raw colors, px or fonts; renders in light and dark.
+- [ ] Only existing components and tokens (or a new component, flagged).
+- [ ] All data local; no API, service, auth or `fetch`.
+- [ ] `data-tour` on key regions; a working tour.
+- [ ] `npm run build` and `npm run lint` pass.

package/template/.cursor/rules/code-review.mdc

@@ -0,0 +1,30 @@
+---
+description: How to code-review design work in this repo (a prototype, a design-system component, or tokens) — architecture, layering, reusability, design-system compliance, light and dark, quality gate. Use when asked to review a branch, a pull request, a change or a named component or prototype.
+alwaysApply: false
+---
+
+# Design work code review
+
+For a full review, use the `design-work-review` skill. This is the quick summary — cite
+`file:line`, and review only unless asked to fix.
+
+## Check, in order (PASS / FAIL / N/A each)
+
+1. **Design-system compliance** — zero raw hex / `rgba` / named colours and zero raw px design
+   values; tokens through the CSS custom properties or `tokens.ts`. Renders in light AND dark.
+   (A raw hex or px is ≥ High.)
+2. **Reuse, not duplication** — composes `src/design-system/components/`; no forked
+   near-duplicate. A new generic component lives in the design system and is flagged.
+   (A duplicated component is ≥ High.)
+3. **No backend** — no `fetch` / network / service / auth / query imports in prototypes; data is
+   local mock. (A backend import is ≥ High.)
+4. **Prototype features** (if applicable) — `data-tour` on key regions; a working tour
+   (`prototypeId` = `<folder>/<id>`, steps target real selectors); registered in `registry.ts`
+   and `workflows.ts`.
+5. **Quality gate** — `npm run build` and `npm run lint` pass; no `console.log` or dead code.
+
+## Report
+
+Verdict (✅ Approve / 🔧 Approve with changes / ❌ Request changes), one PASS/FAIL line per
+section, then ranked findings as `severity — file:line — problem — suggested fix`
+(Blocker / High / Medium / Low), plus the actual build and lint results.

package/template/.cursor/rules/prototype-authoring.mdc

@@ -0,0 +1,31 @@
+---
+description: Rules for authoring prototypes under src/prototypes/ — no backend, local mock data, data-tour anchors, workflows, registration. Read when creating or editing a prototype.
+globs: src/prototypes/**
+alwaysApply: false
+---
+
+# Prototype authoring rules
+
+Full procedure: the `prototype-page-builder` skill. Reference implementation to mirror:
+`src/prototypes/getting-started/welcome/`.
+
+## Non-negotiables
+
+- **No backend.** No `fetch` / network / API client / service / auth / query hook. All data is
+  **local mock data** in the prototype's own folder (`data.ts`).
+- **This is Vite + react-router, NOT Next.js.** No `page.tsx`, no App Router, no
+  `'use client'`. Imports are relative — there is no `@/` alias.
+- **Follow the design-system rules** (see the `ui-system` rule): tokens only, reuse components,
+  renders in light + dark.
+- **Folder shape** `src/prototypes/<folder>/<id>/`: `<PascalName>.tsx`, `data.ts`,
+  `workflows.ts` (`prototypeId` = `"<folder>/<id>"`), `README.md`, `index.ts`.
+- **`data-tour` anchors** on the key regions (header, filters, lists, primary actions).
+- **Register it:** add an entry to `src/prototypes/registry.ts` (`slug` = `"<folder>/<id>"`),
+  and its tour to `src/prototypes/workflows.ts`.
+- **Never rename the slug of a prototype that has comments** — the slug is its key in the API.
+- **Don't recreate app chrome** (top bar, theme toggle, review and tour controls) — the builder
+  shell provides it.
+
+## Before finishing
+
+Run `npm run build` and `npm run lint`; fix everything you introduced.

package/template/.cursor/rules/tokens.mdc

@@ -0,0 +1,36 @@
+---
+description: How the design tokens are structured and consumed. Read when editing src/design-system/tokens.ts, theme.ts, ThemeProvider.tsx or palette.ts, or wiring token values into components.
+globs: src/design-system/**
+alwaysApply: false
+---
+
+# Design tokens
+
+## The source
+
+`src/design-system/tokens.ts` holds every design value:
+
+- **`colors`** — a `light` and a `dark` set. They MUST stay key-for-key identical (the
+  `ColorTokens` type enforces it), so every colour has a value in both themes.
+- **`space`**, **`radius`** — the scales.
+- **`typography`** — text styles by role (`heading`, `title`, `body`, `label`, `caption`,
+  `overline`, `mono`).
+- **`zIndex`** — overlays sit between the builder's top bar (200) and its comments and tours
+  (9140).
+
+## Consuming tokens (never bypass this)
+
+- **In CSS:** `ThemeProvider` (`ThemeProvider.tsx`) sets each token as a custom property on the
+  document, switching with the theme. Paths become names: `colors.bg.page` →
+  `--color-bg-page`, `space.m` → `--space-m`, `typography.body.fontSize` → `--text-body-size`.
+- **In TypeScript:** import the token objects; for colours, read `colors[theme]` with the theme
+  from `useTheme()`.
+- **Never hardcode a colour or px value** in a component or prototype.
+
+## Changing tokens
+
+1. Change or add the value in `tokens.ts` — in both colour sets, if it is a colour.
+2. If the change affects the builder's chrome, update `palette.ts`, which maps tokens onto
+   `BuilderPalette`. Its slot names are a contract with the Starcier packages and do not change;
+   only the right-hand sides do.
+3. Reference the token by name at call sites; never inline its value.

package/template/.cursor/rules/ui-system.mdc

@@ -0,0 +1,39 @@
+---
+description: UI quality non-negotiables for this design system — tokens only, reuse existing components, single home for reusables, light + dark. Read when building or editing any component or screen.
+globs: src/**/*.tsx
+alwaysApply: false
+---
+
+# UI system rules
+
+`AGENTS.md` is the source of truth; this is the summary. For a new prototype use the
+`prototype-page-builder` skill; for any design decision, the `design-system` skill.
+
+## Non-negotiables
+
+- **Compose the existing design system; never invent one.** Reuse the components in
+  `src/design-system/components/` (`Button`, `Card`, `Field`, `Modal`, `ThemeToggle`, and
+  whatever has been added since). Never fork a near-duplicate.
+- **Tokens only — no raw values.** In CSS, use the custom properties `ThemeProvider` sets
+  (`var(--color-text-secondary)`, `var(--space-m)`, `var(--radius-s)`,
+  `var(--text-body-size)`). In TypeScript, import from `src/design-system/tokens.ts`. A raw hex /
+  `rgba` / named colour, or a raw px design value, is a failure.
+- **Single home for reusables.** Every generic component lives in
+  `src/design-system/components/<Name>/` (`<Name>.tsx`, `<name>.css`, `index.ts`), never inside
+  a prototype.
+- **Light AND dark.** Everything renders in both themes; colours from tokens make that automatic.
+- **No raw interactive elements** where a component exists: `Button` (not `<button>`), `Field`
+  (not `<input>`), `Modal` (not a bespoke fixed-position panel).
+- **New component only when nothing fits** — token-only, in the design system, and flagged in
+  the pull request.
+
+## Example
+
+```tsx
+// ❌ BAD — raw colour, raw px, raw button
+<button style={{ background: "#4F46E5", padding: "8px 16px" }}>Save</button>
+
+// ✅ GOOD — design-system component, styled by tokens
+import { Button } from "../../design-system/components/Button";
+<Button variant="primary" onClick={onSave}>Save</Button>
+```

package/template/.env.example

@@ -0,0 +1,19 @@
+# This builder's configuration. None of it is secret: every VITE_ value is
+# compiled into the browser bundle. `npm create @starcier/builder` writes the
+# real values into `.env`; this file documents them.
+#
+# Leave the API and Auth0 values empty to run offline: comments and tours are
+# then kept in the browser, and nobody signs in.
+
+# The Starcier API's origin, without /v1.
+VITE_API_BASE_URL=
+# This builder's tenant. Assigned when the builder was created; keep it set even
+# offline, so this builder's local data stays apart from other builders'.
+VITE_TENANT_SLUG=
+# Auth0 sign-in: the tenant's domain, the single-page application's client id,
+# and the API's audience.
+VITE_AUTH0_DOMAIN=
+VITE_AUTH0_CLIENT_ID=
+VITE_AUTH0_AUDIENCE=
+# The passwordless email connection invited reviewers sign in with. Defaults to "email".
+# VITE_AUTH0_PASSWORDLESS_CONNECTION=email

package/template/AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS.md — Prototype Builder
+
+Portable guidance for any coding agent (Cursor, Codex, Claude). Cursor also has file-scoped
+rules in `.cursor/rules/`; this file is the always-on summary and the source of truth.
+
+Skills (`SKILL.md`) are duplicated per tool because each discovers its own folder only: Cursor
+reads `.cursor/skills/`, Claude Code reads `.claude/skills/`. Keep the two copies in sync.
+Available skills: `design-system` (design principles for every component change),
+`design-system-audit`, `prototype-page-builder`, `design-work-review`, `process-interviewer`.
+
+## What this repo is
+
+A **Vite + React 19 + TypeScript** app with two parts:
+
+1. **The design system** (`src/design-system/`) — tokens and components.
+2. **The prototypes** (`src/prototypes/`) — screens composed from the design system, with mock
+   data, shown in a builder that adds review comments, guided tours and sharing.
+
+The builder itself — routing, catalogue, sign-in, comments, tours — comes from the
+`@starcier/builder-shell`, `@starcier/collab-ui` and `@starcier/collab-core` packages, configured
+in `src/App.tsx`. **Never copy or reimplement what those packages do.**
+
+Styling is plain CSS driven by design tokens. Not Next.js, not Tailwind, no CSS-in-JS runtime.
+
+## Commands
+
+- `npm run dev` — the builder at http://localhost:5173 (the port is fixed; see `vite.config.ts`)
+- `npm run build` — `tsc -b && vite build`
+- `npm run lint` — ESLint
+
+## Design system
+
+- **Tokens** live in `src/design-system/tokens.ts`: `colors` (a `light` and a `dark` set with
+  identical keys), `space`, `radius`, `typography`, `zIndex`. `ThemeProvider`
+  (`src/design-system/ThemeProvider.tsx`, with `useTheme` in `theme.ts`) exposes every token
+  as a CSS custom property:
+  `colors.bg.page` → `--color-bg-page`, `space.m` → `--space-m`, `typography.body` →
+  `--text-body-size` / `-weight` / `-line` / `-tracking` / `-case`.
+- **Components** live in `src/design-system/components/<Name>/` as `<Name>.tsx`, `<name>.css`
+  and `index.ts`. Class names are prefixed `ds-`.
+- **`src/design-system/palette.ts`** maps the tokens onto `BuilderPalette`, which colours the
+  builder's chrome. When a token is renamed or added, update it there too.
+
+## Non-negotiables (UI)
+
+- **Compose the existing design system; never invent a parallel one.** Reuse
+  `src/design-system/components/`. Never fork a near-duplicate.
+- **Tokens only — no raw values.** Colours, spacing, radii and text styles come from the tokens,
+  in CSS through the custom properties. No raw hex / `rgba` / named colours and no raw px design
+  values in components or prototypes.
+- **Light AND dark.** Everything must render in both themes; that is why colours come from tokens.
+- **Single home for reusables.** A generic component belongs in `src/design-system/components/`,
+  never inside a prototype folder.
+- **No raw interactive elements** where a component exists: `Button` not `<button>`, `Field` not
+  `<input>`, `Modal` not a bespoke fixed panel.
+- **Overlays stack between 200 and 9140.** The builder's top bar is at 200 and its comments and
+  tours start at 9140. Use `zIndex` from the tokens.
+- **Overlay roots and field wrappers are declared in `src/App.tsx`** (`COLLAB`). A new overlay
+  or field component whose root class changes must be added there, or recorded tours and review
+  mode will not recognise it.
+
+## Non-negotiables (prototypes — `src/prototypes/`)
+
+- **No backend.** No `fetch`, API client, service, auth or query hook. All data is local mock
+  data in the prototype's own folder.
+- **Folder** `src/prototypes/<folder>/<id>/`: `<PascalName>.tsx`, `data.ts`, `workflows.ts`,
+  `README.md`, `index.ts`. Mirror `src/prototypes/getting-started/welcome/`.
+- **`data-tour` anchors** on the key regions, so tours can target stable selectors.
+- **Register it** in `src/prototypes/registry.ts` (`slug` = `"<folder>/<id>"`), and its tour in
+  `src/prototypes/workflows.ts` (`prototypeId` = the same slug).
+- **Never rename a slug that has comments**: the slug is the prototype's key in the API.
+- **Don't recreate app chrome** (top bar, theme toggle, review and tour controls): the builder
+  shell provides it.
+
+## Before you finish
+
+Run `npm run build` and `npm run lint`; fix everything you introduced.

package/template/CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+Guidance for Claude Code in this repo. The authoritative, tool-agnostic rules live in
+`AGENTS.md` (shared with Codex and Cursor), imported below so there is a single source of truth.
+
+@AGENTS.md
+
+## Skills
+
+Project skills live in `.claude/skills/` and are discovered by Claude Code:
+
+- `design-system` — design principles applied to every component change.
+- `design-system-audit` — a systematic audit of existing components against those principles.
+- `prototype-page-builder` — how to author a new prototype.
+- `design-work-review` — senior front-end review of a branch, a component or a prototype.
+- `process-interviewer` — sharpens a fuzzy idea into a plan before building.
+
+They are kept in sync with the Cursor copies in `.cursor/skills/`. If you change one, update the
+other.

package/template/README.md

@@ -0,0 +1,65 @@
+# Example Client — Prototype Builder
+
+A prototype builder: your design system, your prototypes, and Starcier's review comments,
+guided tours and sharing on top. The collaboration features come from the `@starcier/*`
+packages; this repository holds only what is yours.
+
+## Run it
+
+Node 20 or later.
+
+```bash
+npm install
+npm run dev        # http://localhost:5173
+```
+
+`npm run build` type-checks and builds into `dist/`; `npm run lint` lints.
+
+The builder signs you in and stores comments in the Starcier API. To work without either, empty
+the API and Auth0 values in `.env`: comments and tours are then kept in your browser.
+
+## What is where
+
+| Path | What |
+| --- | --- |
+| `src/design-system/tokens.ts` | Every colour, size and text style. Start here to make it yours. |
+| `src/design-system/palette.ts` | Maps the tokens onto the builder's chrome. Update it with the tokens. |
+| `src/design-system/components/` | Your components. |
+| `src/prototypes/` | Your prototypes, listed in `registry.ts`, their tours in `workflows.ts`. |
+| `src/App.tsx` | The builder itself; you rarely need to touch it. |
+| `.env` | This builder's settings. Nothing in it is secret, so it is committed. |
+| `AGENTS.md`, `.cursor/`, `.claude/` | Instructions and skills for coding agents. |
+
+To add a prototype, copy `src/prototypes/getting-started/welcome/`, rename it, and add it to
+`registry.ts` (and its tour to `workflows.ts`). Prototypes use mock data only, never a backend.
+
+## Going live
+
+Three things cannot be automated. Do them in this order.
+
+1. **Deploy.** Any static host works. The build command is `npm run build`, the output folder is
+   `dist`, and every path must fall back to `index.html` (share and invite links are opened
+   directly). `vercel.json` does that on Vercel; elsewhere, configure the equivalent. Set no
+   environment variables: they come from `.env`.
+2. **Tell Starcier the address** it is deployed at. They set it as this builder's base URL, which
+   does two things: the API starts accepting requests from it, and password links and email
+   invites start pointing at it. Until then, "Share with password" is disabled. Preview
+   deployments need their addresses registered too, or the API refuses them.
+3. **Ask Starcier to allow the address for sign-in**, so Auth0 returns there after login. For local
+   development, `http://localhost:5173` must be allowed as well.
+
+Who can sign in is decided in the Starcier API: your team members are added to this builder, and
+outside reviewers are invited by email to the prototypes they should see.
+
+## Updating
+
+```bash
+npm install @starcier/collab-core@next @starcier/collab-ui@next @starcier/builder-shell@next
+```
+
+Until `1.0.0` is released the packages are prereleases and need `@next`. If a version is too old
+for the API, comments and tours switch off and a message names the version you need and this
+command; your prototypes keep working.
+
+The review and tour controls keep their own colours rather than taking yours. That is deliberate:
+they are a tool on top of your product, and look the same in every builder.

package/template/_gitignore

@@ -0,0 +1,15 @@
+node_modules
+dist
+*.tsbuildinfo
+*.log
+
+# .env holds this builder's public configuration and is committed: every VITE_
+# value ends up in the browser bundle anyway. Anything private goes in a
+# *.local file, which is never committed.
+.env.local
+.env.*.local
+
+.DS_Store
+.idea
+.vscode/*
+!.vscode/extensions.json

package/template/docs/design-system-log.md

@@ -0,0 +1,17 @@
+# Design system log
+
+Kept by the `design-system-audit` skill: what was built, what each audit found, and the tech debt
+deliberately deferred. Newest entries first.
+
+## Changes
+
+- Created from the Starcier builder template: tokens, `Button`, `Card`, `Field`, `Modal`,
+  `ThemeToggle`, and the Welcome example prototype.
+
+## Audits
+
+None yet.
+
+## Tech debt
+
+None yet.

package/template/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+import { defineConfig, globalIgnores } from 'eslint/config';
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2022,
+      globals: globals.browser,
+    },
+  },
+]);

package/template/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Example Client Prototype Builder</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@starcier/builder-template",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@auth0/auth0-react": "^2.22.1",
+    "@starcier/builder-shell": "^1.0.0-next.1",
+    "@starcier/collab-core": "^1.0.0-next.3",
+    "@starcier/collab-ui": "^1.0.0-next.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router": "^8.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^7.3.1"
+  }
+}

package/template/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#4F46E5"/><rect x="8" y="8" width="16" height="16" rx="3" fill="#FFFFFF"/></svg>

package/template/src/App.tsx

@@ -0,0 +1,65 @@
+import { useMemo } from 'react';
+import { BuilderShell, type BuilderAuthConfig } from '@starcier/builder-shell';
+import { BUILDER_NAME } from './brand';
+import {
+  API_BASE_URL,
+  AUTH0_AUDIENCE,
+  AUTH0_CLIENT_ID,
+  AUTH0_DOMAIN,
+  AUTH0_PASSWORDLESS_CONNECTION,
+  TENANT_SLUG,
+} from './config';
+import { ThemeToggle } from './design-system/components/ThemeToggle';
+import { resolveBuilderPalette } from './design-system/palette';
+import { useTheme } from './design-system/theme';
+import { ThemeProvider } from './design-system/ThemeProvider';
+import { prototypes } from './prototypes/registry';
+import { workflows } from './prototypes/workflows';
+import './app.css';
+
+/** Sign-in, when Auth0 is configured; without it the builder runs offline. */
+const AUTH: BuilderAuthConfig | null =
+  AUTH0_DOMAIN && AUTH0_CLIENT_ID
+    ? {
+        domain: AUTH0_DOMAIN,
+        clientId: AUTH0_CLIENT_ID,
+        audience: AUTH0_AUDIENCE,
+        passwordlessConnection: AUTH0_PASSWORDLESS_CONNECTION,
+      }
+    : null;
+
+/**
+ * What the review layer needs to know about this design system: the roots of
+ * its overlays, and the wrappers around its form fields. Update these when the
+ * design system's class names change.
+ */
+const COLLAB = {
+  overlaySelectors: ['.ds-modal'],
+  fieldWrapperSelectors: ['.ds-field'],
+};
+
+function Builder() {
+  const { theme } = useTheme();
+  const palette = useMemo(() => resolveBuilderPalette(theme), [theme]);
+  return (
+    <BuilderShell
+      palette={palette}
+      prototypes={prototypes}
+      workflowSeeds={workflows}
+      apiBaseUrl={API_BASE_URL}
+      tenant={TENANT_SLUG}
+      auth={AUTH}
+      collab={COLLAB}
+      brand={<span className="app-brand">{BUILDER_NAME}</span>}
+      headerActions={<ThemeToggle />}
+    />
+  );
+}
+
+export function App() {
+  return (
+    <ThemeProvider>
+      <Builder />
+    </ThemeProvider>
+  );
+}

package/template/src/app.css

@@ -0,0 +1,5 @@
+.app-brand {
+  font-size: var(--text-title-size);
+  font-weight: var(--text-title-weight);
+  line-height: var(--text-title-line);
+}

package/template/src/brand.ts

@@ -0,0 +1,2 @@
+/** The client this builder belongs to, shown in the top bar. */
+export const BUILDER_NAME = 'Example Client';

package/template/src/config.ts

@@ -0,0 +1,15 @@
+/**
+ * Configuration from the VITE_* values in `.env`. All optional: without the API
+ * and Auth0 values the builder runs offline, keeping comments and tours in the
+ * browser, which is enough for design work.
+ */
+
+const read = (value: string | undefined) => value?.trim() || undefined;
+
+export const API_BASE_URL = read(import.meta.env.VITE_API_BASE_URL)?.replace(/\/+$/, '');
+export const TENANT_SLUG = read(import.meta.env.VITE_TENANT_SLUG);
+export const AUTH0_DOMAIN = read(import.meta.env.VITE_AUTH0_DOMAIN);
+export const AUTH0_CLIENT_ID = read(import.meta.env.VITE_AUTH0_CLIENT_ID);
+export const AUTH0_AUDIENCE = read(import.meta.env.VITE_AUTH0_AUDIENCE);
+/** The passwordless email connection invited reviewers sign in with. */
+export const AUTH0_PASSWORDLESS_CONNECTION = read(import.meta.env.VITE_AUTH0_PASSWORDLESS_CONNECTION) ?? 'email';

package/template/src/design-system/ThemeProvider.tsx

@@ -0,0 +1,25 @@
+import { useCallback, useLayoutEffect, useMemo, useState, type ReactNode } from 'react';
+import { cssVariables, initialTheme, THEME_STORAGE_KEY, ThemeContext } from './theme';
+import type { ThemeName } from './tokens';
+
+/** The active theme, applied to the document as CSS custom properties. */
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState<ThemeName>(initialTheme);
+
+  useLayoutEffect(() => {
+    const root = document.documentElement;
+    root.dataset.theme = theme;
+    root.style.colorScheme = theme;
+    for (const [name, value] of Object.entries(cssVariables(theme))) root.style.setProperty(name, value);
+    try {
+      localStorage.setItem(THEME_STORAGE_KEY, theme);
+    } catch {
+      /* not remembered: harmless */
+    }
+  }, [theme]);
+
+  const toggle = useCallback(() => setTheme((current) => (current === 'light' ? 'dark' : 'light')), []);
+  const value = useMemo(() => ({ theme, toggle }), [theme, toggle]);
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}

package/template/src/design-system/components/Button/Button.tsx

@@ -0,0 +1,15 @@
+import type { ButtonHTMLAttributes } from 'react';
+import './button.css';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+export type ButtonSize = 'small' | 'medium';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+export function Button({ variant = 'primary', size = 'medium', className, type = 'button', ...rest }: ButtonProps) {
+  const classes = ['ds-button', `ds-button--${variant}`, `ds-button--${size}`, className].filter(Boolean).join(' ');
+  return <button type={type} className={classes} {...rest} />;
+}