@milesroxas/create-design-hub 0.0.0-stage → 0.1.0

package/setup/server.test.mjs

@@ -0,0 +1,99 @@
+// The server's guard rails, against the real process: it runs commands on this
+// machine, so only its own page may reach the actions.
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { request } from 'node:http';
+import { after, before, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+let server;
+let base;
+let token;
+
+before(async () => {
+  server = spawn(process.execPath, [fileURLToPath(new URL('server.mjs', import.meta.url)), '--no-open']);
+  base = await new Promise((resolve, reject) => {
+    let out = '';
+    server.stdout.on('data', (d) => {
+      out += d;
+      const url = out.match(/http:\/\/127\.0\.0\.1:\d+\//)?.[0];
+      if (url) resolve(url);
+    });
+    server.on('exit', () => reject(new Error(`server exited: ${out}`)));
+  });
+  token = (await (await fetch(base)).text()).match(/const TOKEN = '([0-9a-f]{32})'/)?.[1];
+});
+
+after(() => server.kill('SIGTERM'));
+
+const post = (path, body = {}, headers = { 'x-setup-token': token }) =>
+  fetch(new URL(path, base), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body: JSON.stringify(body),
+  });
+
+test('the page carries a fresh token and shares the naming rule', async () => {
+  assert.match(token, /^[0-9a-f]{32}$/);
+  const slug = await fetch(new URL('slug.mjs', base));
+  assert.match(slug.headers.get('content-type'), /javascript/);
+  assert.match(await slug.text(), /export function slugify/);
+});
+
+test('another host name is refused, so a rebound DNS name reaches nothing', async () => {
+  const { port } = new URL(base);
+  const status = await new Promise((resolve, reject) => {
+    request({ host: '127.0.0.1', port, path: '/', headers: { host: `evil.example:${port}` } }, (res) => {
+      res.resume();
+      resolve(res.statusCode);
+    })
+      .on('error', reject)
+      .end();
+  });
+  assert.equal(status, 403);
+});
+
+test('actions need the token and a POST', async () => {
+  assert.equal((await post('/api/state', {}, {})).status, 403);
+  assert.equal((await post('/api/state', {}, { 'x-setup-token': 'nope' })).status, 403);
+  assert.equal((await fetch(new URL('/api/state', base))).status, 403);
+  assert.equal((await post('/api/nothing')).status, 404);
+});
+
+test('state describes this machine', async () => {
+  const state = await (await post('/api/state')).json();
+  assert.equal(state.mode, 'create');
+  assert.match(state.defaults.parent, /\/Design$/);
+  assert.equal(typeof state.tools.git, 'boolean');
+});
+
+test('the name check uses the same rule as create', async () => {
+  const empty = await (await post('/api/path', { name: '---', parent: '/tmp' })).json();
+  assert.deepEqual(empty, { ok: false, error: 'Use at least one letter or number in the name.' });
+  const relative = await (await post('/api/path', { name: 'x', parent: 'Design' })).json();
+  assert.equal(relative.ok, false);
+});
+
+test('project actions refuse a folder this server did not create', async () => {
+  for (const action of ['start', 'stop', 'reveal', 'claude']) {
+    const res = await (await post(`/api/${action}`, { path: '/etc' })).json();
+    assert.deepEqual(res, { ok: false, message: 'Unknown project.' }, action);
+  }
+});
+
+test('a bad create request is answered by field, before anything runs', async () => {
+  const res = await post('/api/create', {
+    name: 'x',
+    parent: '/tmp',
+    visibility: 'everyone',
+    owner: '-bad',
+  });
+  const events = (await res.text())
+    .trim()
+    .split('\n')
+    .map((line) => JSON.parse(line));
+  assert.equal(events.length, 1);
+  assert.equal(events[0].step, 'invalid');
+  assert.ok(events[0].errors.visibility);
+  assert.ok(events[0].errors.owner);
+});

package/setup/slug.mjs

@@ -0,0 +1,15 @@
+// The one rule for turning a project name into a folder and repo name. No
+// imports, because the page loads this file too: the path it previews is the
+// path the server creates.
+
+/** The folder name for a project name: what create.mjs accepts as a repo name. */
+export function slugify(name) {
+  return String(name ?? '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, 80);
+}

package/template/.claude/launch.json

@@ -0,0 +1,18 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "prototypes",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": [
+        "dev"
+      ],
+      "port": 3101
+    },
+    {
+      "name": "prototypes-attach",
+      "url": "http://localhost:3101",
+      "port": 3101
+    }
+  ]
+}

package/template/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && node_modules/.bin/design-hub hook md-writing",
+            "timeout": 10,
+            "statusMessage": "Checking Markdown edit"
+          },
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && node_modules/.bin/design-hub hook fidelity-guard",
+            "timeout": 15,
+            "statusMessage": "Fidelity guard"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && node_modules/.bin/design-hub hook skill-hint",
+            "timeout": 5,
+            "statusMessage": "Skill hint"
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.design-hub/checks.json

@@ -0,0 +1,9 @@
+{
+  "jev": { "model": "jev-1.14.0", "timeoutMs": 2000 },
+  "fidelity": { "warnAt": 0.7, "blockAt": 0.9 },
+  "states": { "blockAt": 0.8 },
+  "contacts": { "privateAt": 0.5, "allow": [] },
+  "skillHint": { "gateAt": 0.3, "fitsAt": 0.3 },
+  "triage": { "at": 0.5 },
+  "visual": { "warnAt": 0.7 }
+}

package/template/.env.example

@@ -0,0 +1,28 @@
+# Written by `pnpm bootstrap`: the dev server's port, checked free on this
+# machine at the time. Never commit .env.
+PORT=
+
+# Password gate for the deployed prototypes (proxy.ts). Set both in the Vercel
+# project's Environment Variables for Production and Preview; `pnpm bootstrap
+# --vercel <project>` does it. Never commit values.
+# GATE_PASSWORD: what a reviewer types. Rotating it signs every visitor out.
+GATE_PASSWORD=
+# GATE_SECRET: 32+ random bytes, base64 or hex (openssl rand -base64 32). Signs the
+# session cookie so a password guess cannot be turned into a forged cookie.
+GATE_SECRET=
+
+# Optional: TypeSafe's Jev checks (the fidelity guard, the pre-flight, comment
+# triage, the skill hint). Set by `pnpm bootstrap --typesafe-key <key>`. Only this
+# file turns it on, never a key in the shell. Absent, every Jev question is skipped.
+TYPESAFE_API_KEY=
+
+# Optional: the review store (comments and people) on the deployed site.
+# `pnpm bootstrap --vercel <project> --review` adds Upstash Redis through the
+# Vercel Marketplace and copies these two here, so `pnpm comments` and
+# `pnpm people` reach the same store. Absent, they use the local dev store.
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+
+# Optional: `pnpm fixtures-pull` reads a Webflow CMS collection with a site
+# token that has the cms:read scope.
+WEBFLOW_TOKEN=

package/template/.impeccable/config.json

@@ -0,0 +1,16 @@
+{
+  "buildPath": "prototypes",
+  "detector": {
+    "extensions": [],
+    "designSystem": {
+      "enabled": true
+    },
+    "ignoreRules": [],
+    "ignoreFiles": [],
+    "ignoreValues": []
+  },
+  "hook": {
+    "enabled": true,
+    "quiet": true
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1,133 @@
+# Agent guide
+
+The contract for every coding agent in this project (Claude, Codex, Cursor, others). `CLAUDE.md` points here.
+
+This project holds prototypes, the materials they are drawn with, and the documents around them. The hub that lists and serves them, the review panel, the password gate and the `design-hub` command are the `@milesroxas/design-hub` package in `node_modules`: never edit it, never read it to do prototype work. Everything an agent touches is in this folder.
+
+## Why it works this way
+
+Code here is for sketching, not shipping. Following Karri Saarinen's [Design is more than code](https://linear.app/now/design-is-more-than-code), a prototype answers a question that was written down first, in words. Speed comes from removing production constraints, never from skipping the problem.
+
+1. **Problem first.** `README.md` states the problem and the one question before any code exists. Restate it when you present the prototype.
+2. **Two places to stand.** Pick one per prototype: the disposable shell (`AppShell` for a product, `SiteShell` for a website), the project's chrome from `kit/shell.ts` and `DESIGN.md`, Shell; or the low-gravity space (`Space`), one thing alone on a quiet canvas with the picker and live dials.
+3. **Low gravity.** A prototype imports only `@kit/*` and its own folder. Never another prototype. No tests, no stories, no abstractions for later. The fidelity ceiling is in the `miles-prototype` skill, and the fidelity guard hook says so when a write goes over it.
+4. **Fork, don't flex.** If a kit piece needs to behave differently, copy it into the prototype folder and change the copy. Never add a prop or a variant to `kit/` for one prototype.
+5. **Promote on second use.** When a second prototype copies the same thing, move it into `kit/` and point both at it.
+6. **Real materials, worst content.** Real tokens, fonts and icons. The content comes from `fixtures.json`: `real` pulled from the CMS or copied from the comp, `missing` written by hand, and `longest`, `empty` and `max` derived by `@kit/fixtures`.
+7. **Done means decided.** When the user picks, write the decision in the prototype's README: what was chosen, its values, what was rejected and why. Then delete the folder, or set `status: archived` if the user wants it kept.
+8. **The floor never moves.** Accessibility and performance are not polish passes. The `miles-prototype` skill carries the rules.
+
+## Stack (fixed)
+
+| Need | Use | Not |
+| --- | --- | --- |
+| UI | React 19 function components, TypeScript strict | class components |
+| Styling | Plain CSS beside the component, `kit/tokens.css` variables | Tailwind, CSS-in-JS, CSS modules, UI libraries |
+| Motion | CSS transitions, `@starting-style`, keyframes, WAAPI first; `motion/react` only when it earns it | GSAP, react-spring |
+| Live values, controls | DialKit through `@kit/dials` | custom panels, testing aids inside the product chrome |
+| Data | `fixtures.json` in the prototype folder | fetching, a server, localStorage as a store |
+| State, routing | `useState`, a module store with `useSyncExternalStore`, `@kit/hooks` `useHashRoute` | state libraries, React Router |
+| Tests | none in a prototype | Vitest, Jest, Playwright, Storybook |
+
+Adding a dependency needs the user's OK. Ask, with the reason and the bundle cost.
+
+## Commands
+
+Run from the project root. Every command prints one JSON object; `--help` prints its schema; `ok: false` comes with `fix`. Read the JSON; never parse prose.
+
+```bash
+pnpm dev                                  # http://localhost:<PORT>, review panel and all
+pnpm new <slug> --feature <feature>       # a space prototype with the picker and dials
+pnpm new <slug> --app --sprint --feature <feature>   # the feature's one primary prototype, in the shell
+pnpm new <slug> --app --alternate --feature <feature>   # another take on the primary
+pnpm guide <feature>                      # the feature's walkthrough, docs/sprints/<feature>/guide.md
+pnpm check                                # TypeScript and Biome; must pass before you report done
+pnpm fix                                  # Biome format and safe fixes
+pnpm preflight                            # every check a share link needs (miles-deploy)
+pnpm comments pull                        # review comments into docs/sprints/<feature>/comments.md (miles-review)
+pnpm fixtures-pull <slug> --collection <id> --map key=field   # real fixtures from Webflow (miles-get-hostile)
+pnpm commands                             # every command, with its flags, as JSON
+```
+
+The port is Conductor's `$CONDUCTOR_PORT` in a workspace, else the `PORT` in `.env` that `pnpm bootstrap` picked. A taken port is refused. Never pass another port: a second port silently serves the wrong project.
+
+## Layout
+
+```
+prototypes/<slug>/   one prototype: README.md, index.tsx, styles.css, fixtures.json
+kit/                 the project's materials: tokens.css, shell.ts (brand, nav), icons.ts, AppShell, SiteShell
+docs/sprints/<feature>/   design-doc.md, guide.md, comments.md (generated), port.md, assets/
+DESIGN.md  PRODUCT.md     the design system's named rules; who the product is for
+.design-hub/checks.json   the Jev thresholds (design-hub calibrate --write rewrites it)
+api/review.ts  proxy.ts  vercel.json   the deploy entries; one line each, never edited
+```
+
+`prototypes/sample-list/` is the reference for every convention; delete it once the project has a feature.
+
+## A prototype
+
+README frontmatter, all fields required (`feature` may be empty for a one-off): `title`, `summary`, `context` (space | app), `status` (exploring | decided | archived), `kind` (sprint | alternate | exploration), `feature`, `created`. `pnpm new` writes it.
+
+The README's `## States` table lists every state the prototype holds and how to reach it. The fidelity guard asks whether a write adds a state that is not there, and `miles-port` refuses a folder without the table.
+
+- Sub-pages are hash routes (`/sample-list/#/items/42`) via `useHashRoute`. The path belongs to the hub, and `/guide/` is taken.
+- Persist with `useStoredState(key, initial)`, keys prefixed with the slug. A preference, never a store.
+- Only the open prototype's code and CSS load. Kit class names are shared: never reuse one for something else.
+
+## A feature
+
+One slug in two places: `docs/sprints/<feature>/` and the `feature:` line of every prototype that belongs to it. The hub serves `docs/sprints/<feature>/guide.md` at `/guide/<feature>/`; inside any prototype of the feature, **Open the walkthrough** is the last row of Controls. Nothing is wired by hand.
+
+## Kit
+
+`@kit/<name>` is `kit/<name>` when the project has that file, else the package's copy. Copying a package file into `kit/` under the same name replaces it everywhere.
+
+| Import | What |
+| --- | --- |
+| `@kit/shell` | `BRAND`, `PRODUCT` (nav, workspace, user), `SITE` (nav, footer): the one place the chrome is written. |
+| `@kit/AppShell`, `@kit/SiteShell` | The disposable shells. Mount the dialog, sheet and toast hosts and the View dials. `PageHead({ title, desc, back, actions })`. |
+| `@kit/Space` | `<Space title lede width>`: the low-gravity canvas. |
+| `@kit/ui` | `Button`, `Chevron`, `Segmented`, `Badge`, `Checkbox`, `useMenu`, `Select`, `openDialog`, `confirmDialog`, `openSheet`, `toast()`, `notInPrototype(what)`. Card, table and empty-state classes in `ui.css`. |
+| `@kit/fixtures` | `fixtureSets({ real, missing }, { max, text })` returns `{ real, longest, empty, max, missing }`; `SET_NAMES` for the dial. |
+| `@kit/Variants` | `<Variants options={{ Quiet, Editorial }}>`: the picker. Keys 1-N, arrows, R; `?v=N`. |
+| `@kit/dials` | `useDials(name, config, { hints })` for values JS reads; `<DialVars name config target?>` writes CSS variables without re-rendering. Every dial carries a hint. |
+| `@kit/Icon`, `@kit/icons` | `<Icon name size label?>`. Add a glyph in `kit/icons.ts`. |
+| `@kit/prefs`, `@kit/hooks`, `@kit/format`, `@kit/motion` | Theme and motion preferences; `useHashRoute`, `useStoredState`; `fmtDate`, `plural`; `ease.*` and `spring.*`. |
+| `@kit/tokens.css` | The design's tokens, light and `.dark-mode`. Loaded globally. |
+
+URL switches on any prototype: `?v=2`, `?theme=dark|light|system`, `?motion=reduce`, `?lapse`, `?a11y=0`.
+
+## Code
+
+- TypeScript strict. `any` is allowed when it saves time; never `// @ts-ignore`.
+- Comments: none by default. One line when the reason is not obvious. Rationale, values and rejected options go in the README.
+- Colors, radii, shadows, type and motion come from tokens. A raw value is a decision: name it in the README or add a token and note it in `DESIGN.md`.
+- Copy follows `DESIGN.md` and the product voice: plain, specific, no em dashes.
+- **The Scope Toast Rule.** Anything a control would do that the prototype does not build says so in the prototype's own voice: `notInPrototype('Model history')`, or `toast(message, { kind: 'scope' })`. A product toast with a green check for something that did not happen is a bug.
+
+## Definition of done
+
+1. `pnpm check` passes.
+2. The page loads with no console errors and no `[a11y]` warnings.
+3. The main path works by keyboard alone.
+4. `?motion=reduce` and `?theme=dark` look right, when the prototype has motion or should support dark.
+5. README is current: problem, question, flows or directions, states, fixtures, and the decision once there is one.
+
+Say what you could not verify. Do not commit unless asked.
+
+## Skills
+
+The `miles-*` skills in `.claude/skills/` come from the `@milesroxas/design-hub` package (`pnpm skills` refreshes them; never edit the copies). Load one when its trigger matches.
+
+| Skill | Load when |
+| --- | --- |
+| `miles-prototype` | Writing or changing any prototype code: the fidelity ceiling, DialKit, motion, accessibility, performance. |
+| `miles-new-feature` | Starting a feature or a prototype: the folder, the README, `docs/sprints/<feature>/`. |
+| `miles-get-hostile` | Writing `fixtures.json` or deciding what an edge case looks like. |
+| `miles-paper-to-prototype` | Every Paper MCP read. Maps Paper output onto the kit's tokens and components. |
+| `miles-deploy` | Deploying, sharing a link, the password, checking the work before either. |
+| `miles-review` | Comments from the deployed prototypes, and who may comment. |
+| `miles-port` | Turning an approved prototype into production. |
+| `miles-conductor` | Conductor workspaces and port collisions. |
+
+Existing skills these lean on: `emil-prototype`, `emil-animations`, `emil-touch-and-accessibility`, `emil-performance`, `emil-writing-skills` for every Markdown file, `impeccable` for a design pass. If a skill disagrees with this file, this file wins.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/DESIGN.md

@@ -0,0 +1,126 @@
+---
+name: Project name
+description: The product design system this project builds on, recorded from the design (Paper) and, where one exists, the live product
+colors:
+  brand: "#2b57cc"
+  brand-hover: "#2246a6"
+  ink: "#101828"
+  ink-secondary: "#344054"
+  ink-tertiary: "#475467"
+  ink-quaternary: "#667085"
+  surface: "#ffffff"
+  surface-secondary: "#f9fafb"
+  surface-tertiary: "#f2f4f7"
+  line: "#d0d5dd"
+  line-secondary: "#eaecf0"
+  error: "#d92d20"
+  warning: "#dc6803"
+  success: "#079455"
+typography:
+  display:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontSize: "24px"
+    fontWeight: 600
+    lineHeight: "32px"
+  headline:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontSize: "18px"
+    fontWeight: 600
+    lineHeight: "28px"
+  body:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontSize: "14px"
+    fontWeight: 400
+    lineHeight: "20px"
+  label:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontSize: "14px"
+    fontWeight: 600
+    lineHeight: "20px"
+  caption:
+    fontFamily: "Inter, system-ui, sans-serif"
+    fontSize: "12px"
+    fontWeight: 400
+    lineHeight: "18px"
+rounded:
+  xs: "4px"
+  sm: "6px"
+  md: "8px"
+  lg: "10px"
+  xl: "12px"
+  full: "9999px"
+spacing:
+  2xs: "4px"
+  xs: "8px"
+  sm: "12px"
+  md: "16px"
+  lg: "20px"
+  xl: "24px"
+  2xl: "32px"
+---
+
+# Design System: Project name
+
+This file is the template's. Replace every value and every sentence below with the project's own the first time `miles-paper-to-prototype` reads the design, and keep it current after: `kit/tokens.css` holds the same values as CSS variables, and the two must agree. The frontmatter is what Impeccable reads (`/impeccable doctor` checks it); the prose is what a person or an agent reads before touching the product.
+
+## Overview
+
+One paragraph on what the product is for and how the interface serves that. Name the creative north star in a phrase, then the two or three characteristics that follow from it (one typeface and why; where saturated colour is allowed; how edges are drawn). Say whether light and dark are equal citizens.
+
+## Shell
+
+Every project has a shell: a product's sidebar, top bar and content, or a website's header and footer, with a pre-footer when the design treats one as a global. Record the answer `miles-design-hub` collected so it is built once and never asked again:
+
+- **Kind:** product or website.
+- **Paper frames:** the link to each frame that holds the shell (header, sidebar, footer, pre-footer). Empty when the design has no shell and prototypes stand in the Space.
+- **Where it is built:** `kit/shell.ts` (brand, navigation, people) and `AppShell.tsx` or `SiteShell.tsx`. A prototype never rebuilds the shell inside its own folder.
+
+## Colors
+
+Group by role: primary, neutral, status, any utility family. For each colour, its name, hex, token, what it is for and its dark value. Then the named rules, each a bold name and a paragraph that says the rule and why it holds.
+
+### Named Rules
+
+**The Labelled Hue Rule.** Colour never carries meaning alone. A status gets a dot or a word, a chart series a legend entry, a tier its name. Why: a reviewer in grayscale, a printout and a screen reader all lose the hue.
+
+**The Hover Rule.** A hovered row or menu item lifts on `--bg-primary_hover`, never on a brand tint. Why: a brand tint on hover reads as selection, and the two states must stay distinct.
+
+## Typography
+
+The faces, the weights, and the hierarchy as a ladder: display, headline, title, body, label, caption, each with size, line height, weight and where it appears. Then the named rules.
+
+### Named Rules
+
+**The Weight Ladder Rule.** Hierarchy climbs 400 to 500 to 600 before it climbs in size. Two sizes apart with the same weight is a mistake. Why: weight separates levels at the same measure; size alone makes every level a new line length.
+
+## Layout
+
+The shell's dimensions, the content measure, the breakpoints, the spacing steps observed and which to prefer.
+
+## Elevation & Depth
+
+How edges are drawn (hairline first, shadow second), the shadow vocabulary by name, and what dark mode does instead.
+
+### Named Rules
+
+**The Hairline First Rule.** An edge is a 1px border in `--border-primary` or `--border-secondary`; a shadow may reinforce it but never replaces it. Why: dark mode draws no shadows, and the border has to be enough on its own.
+
+**The Hit Area Rule.** Nothing clickable is smaller than 40px on a side on desktop, 44px on touch. A small glyph gets padding or a pseudo-element, never a smaller target. Why: a target that is hard to hit is a defect the reviewer blames on the design.
+
+## Shapes
+
+Radii by element, border placement, icon size and set.
+
+## Components
+
+Buttons, badges, cards, inputs, navigation, tables: the shape, the states, the motion, in that order. Rules decided in a prototype land here as named rules the day they are decided, with the date and the prototype that decided them.
+
+## Do's and Don'ts
+
+### Do:
+- **Do** take every value from `kit/tokens.css` and keep this file in step with it.
+- **Do** design every screen in light and dark and preview both before calling it done.
+
+### Don't:
+- **Don't** use raw hex in a prototype. A raw value is a decision: name it in the README or add a token and note it here.
+- **Don't** restyle the shell inside a prototype. Change `kit/shell.ts` and say so here.

package/template/Design Hub.command

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Double-click to open this project's Design Hub in the browser. Keep the
+# window open while you work; closing it stops the hub.
+cd "$(dirname "$0")" || exit 1
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+if [ ! -x node_modules/.bin/design-hub ]; then
+  echo "Installing the project first (one time)."
+  command -v pnpm >/dev/null 2>&1 && pnpm install || npx --yes pnpm@12 install
+fi
+[ -f .env ] && grep -q '^PORT=[0-9]' .env || node_modules/.bin/design-hub bootstrap --no-install >/dev/null
+exec node_modules/.bin/design-hub open

package/template/PRODUCT.md

@@ -0,0 +1,65 @@
+# Product
+
+<!-- impeccable:product-schema 1 -->
+
+This file is the template's. Fill every section the first time `miles-design-hub` sets the project up, from the kickoff and the design; an empty section is a question Claude will answer by guessing.
+
+## Platform
+
+web
+
+## Stack
+
+Disposable prototypes in `prototypes/`, one folder per prototype, with the design's tokens in `kit/tokens.css`. The comps are Paper frames (`DESIGN.md`, Shell, names the ones that hold the shell). The live product is built elsewhere and is not in this repo; `miles-port` carries an approved prototype into it.
+
+## Users
+
+Who uses the product, in what role, how often, and to what end. Then the secondary readers: who sees the output without opening the product.
+
+## Product Purpose
+
+What the product does, in two or three sentences a new engineer could repeat. What success looks like for a user, and what the repeat loop is.
+
+## Positioning
+
+What the product claims that its alternatives do not, in the product's own words.
+
+## Operating Context
+
+- The shell: the navigation items in order, and what sits at the foot.
+- The object model: the nouns, what holds what.
+- The journey, in order.
+- Dense or sparse, which units, which appearance modes.
+- Work in progress, with the feature slug under `docs/sprints/`.
+
+## Capabilities and Constraints
+
+- Terminology as the product writes it: the abbreviations, the series names, the tiers.
+- UI copy conventions: case, numbers, missing values, units.
+- Undecided product facts. Do not invent these; name who decides.
+- Known product gaps to design around, not hide.
+
+## Brand Commitments
+
+- Name and company.
+- Typeface, as shipped. Binding.
+- Brand colours, by token.
+- Voice: plain, specific, sentence case, no hype.
+
+## Evidence on Hand
+
+- The live product and who has access to what.
+- Reference screenshots and where they are.
+- Research and kickoff notes under `docs/research/`.
+- What does not exist (testimonials, pricing, real figures), so nothing is presented as real that is not.
+
+## Product Principles
+
+1. Lead with the answer.
+2. Every number traces to its inputs.
+3. Preserve the product's system; add controls only where the journey needs them.
+4. Warn before side effects.
+
+## Accessibility & Inclusion
+
+WCAG 2.2 AA. Colour never carries meaning alone. Everything works by keyboard. State the product's own additions here (print, grayscale, screen reader paths).

package/template/README.md

@@ -0,0 +1,20 @@
+# Design work
+
+Prototypes for one product or website, built on [Design Hub](https://github.com/milesroxas/design-hub). One repo holds the prototypes, the design rules, the walkthroughs reviewers read, and their comments.
+
+```bash
+pnpm bootstrap     # once per clone: a free port into .env, install
+pnpm dev           # http://localhost:<PORT>
+```
+
+Or double-click `Design Hub.command`.
+
+| Path | What goes there |
+| --- | --- |
+| `prototypes/<slug>/` | One prototype: its README, code, styles and fixtures. `sample-list/` is the reference; delete it once the project has a feature. |
+| `kit/` | The project's materials: `tokens.css`, `shell.ts` (brand and navigation), `icons.ts`, the disposable `AppShell` and `SiteShell`. |
+| `docs/sprints/<feature>/` | A feature's design doc, walkthrough, pulled comments and port report. |
+| `DESIGN.md`, `PRODUCT.md` | The recorded design system and who the product is for. |
+| `.claude/` | Claude Code hooks and the `miles-*` skills (`pnpm skills` refreshes them from the package). |
+
+The rules for people and agents are in [AGENTS.md](AGENTS.md). Deploying, the password gate and review comments: the `miles-deploy` and `miles-review` skills, or `pnpm commands` for every command.

package/template/_gitattributes

@@ -0,0 +1,2 @@
+# Generated by `pnpm elyx` from kit/tokens.css; reviews skip it.
+design-system/** linguist-generated=true

package/template/_gitignore

@@ -0,0 +1,41 @@
+# macOS
+.DS_Store
+._*
+
+# Editors
+.vscode/
+.idea/
+
+# Dependencies and builds
+node_modules/
+dist/
+.vercel/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log
+
+# Local state: the Jev log and its labels, the dev review store. checks.json is the project's thresholds and stays.
+.design-hub/*
+!.design-hub/checks.json
+
+# Obsidian per-machine state (docs/ is an Obsidian vault)
+docs/.obsidian/workspace*.json
+
+# Impeccable per-developer overrides and generated caches
+.impeccable/config.local.json
+.impeccable/live/
+.impeccable/hook.cache.json
+
+# Claude Code worktrees
+.claude/worktrees/
+
+# Conductor per-developer settings
+.conductor/settings.local.toml
+
+# Elyx add-on: fetched dependencies
+design-system/elyx_deps/

package/template/api/review.ts

@@ -0,0 +1,5 @@
+// The review API on Vercel. The project's thresholds travel with it.
+import { reviewFunction } from '@milesroxas/design-hub/vercel';
+import checks from '../.design-hub/checks.json' with { type: 'json' };
+
+export default reviewFunction(checks);

package/template/docs/.obsidian/app.json

@@ -0,0 +1,6 @@
+{
+  "useMarkdownLinks": true,
+  "newLinkFormat": "relative",
+  "attachmentFolderPath": "assets",
+  "promptDelete": false
+}

package/template/docs/.obsidian/appearance.json

@@ -0,0 +1 @@
+{}