basis-design 0.0.0-stage → 0.1.0

package/server/export.ts

@@ -0,0 +1,180 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { strToU8, zipSync } from "fflate";
+import type { Design } from "../shared/design.ts";
+import { PAGES, type SourceFolder } from "../shared/frame.ts";
+import type { ExportFile, ExportWriteResult } from "../shared/protocol.ts";
+import { exportCss, exportJson, exportTailwind } from "../shared/tokens.ts";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+
+export function slug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .normalize("NFKD")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "design-system"
+  );
+}
+
+/**
+ * Workspace code imports siblings with explicit extensions ("./util.ts"),
+ * which needs a TypeScript flag most projects do not set. Exported code uses
+ * extensionless relative imports, which every bundler resolves.
+ */
+function stripImportExtensions(source: string): string {
+  return source.replace(/(\bfrom\s+|\bimport\s*\(\s*|\bimport\s+)(["'])(\.{1,2}\/[^"']+?)\.(tsx?|jsx?)\2/g, "$1$2$3$2");
+}
+
+function readme(design: Design, paths: string[]): string {
+  const families = paths
+    .filter((file) => file.endsWith(".tsx") && !file.includes(".specimen.") && !file.endsWith("icons.tsx"))
+    .map((file) => `- \`${file}\``)
+    .join("\n");
+  return `# ${design.name}
+
+${design.description || "A design system generated with Basis."}
+
+## Contents
+
+- \`tokens.css\`: every design token as a CSS custom property. Light by default, dark under
+  \`data-theme="dark"\` or the operating system's dark preference. Font imports are included.
+- \`theme.tailwind.css\`: the same tokens as a Tailwind v4 entry stylesheet, for Tailwind projects.
+- \`design-system.json\`: the source tokens, for tooling or for importing back into Basis.
+- \`components/\`: React components styled with CSS Modules and the token variables. The
+  \`*.specimen.tsx\` files describe every component in every state; they are living documentation and
+  a ready-made source for stories or visual tests, and nothing imports them by default.
+- \`patterns/\`: larger building blocks composed from the components (navigation, data tables, forms,
+  empty states, page layouts). They import only from \`../components\`, so you can take what you need.
+
+${families}
+
+## Use it
+
+1. Copy this folder into your project, for example as \`src/design-system/\`.
+2. Load the tokens once, at the root of the app:
+   - without Tailwind: \`import "./design-system/tokens.css";\`
+   - with Tailwind v4: use \`theme.tailwind.css\` as the app's main stylesheet instead of \`@import "tailwindcss"\`.
+     Utilities such as \`bg-primary\`, \`text-text-muted\` and \`rounded-md\` then use the design tokens.
+3. Use the components:
+
+   \`\`\`tsx
+   import { Button, Field, TextInput } from "./design-system/components";
+
+   <Field label="Email">
+     <TextInput placeholder="name@company.com" />
+   </Field>
+   <Button variant="primary">Continue</Button>
+   \`\`\`
+
+   Patterns work the same way: \`import { Navbar, DataTable } from "./design-system/patterns";\`
+
+4. For dark mode, set \`data-theme="dark"\` (or \`"light"\`) on \`<html>\`, or leave it unset to follow the OS.
+
+Requirements: React 18 or newer and a bundler with CSS Modules support (Vite, Next.js, Remix and
+webpack's css-loader all qualify). The components have no other dependencies.
+
+The \`data-ds\`, \`data-force\` and \`force\` hooks exist so the Basis gallery can show every state at once.
+They are harmless in an app, and \`force\` is handy in your own stories or visual tests.
+
+Generated by Basis on ${new Date().toISOString().slice(0, 10)}.
+`;
+}
+
+async function sourceFiles(workspaceDir: string, folder: SourceFolder): Promise<ExportFile[]> {
+  const root = path.join(workspaceDir, folder);
+  if (!existsSync(root)) return [];
+  const entries = (await readdir(root, { recursive: true })).map((entry) => entry.split(path.sep).join("/"));
+  const files: ExportFile[] = [];
+  for (const entry of entries.sort()) {
+    const full = path.join(root, entry);
+    if (!(await stat(full)).isFile()) continue;
+    let content = await readFile(full, "utf8");
+    if (/\.(tsx?|jsx?)$/.test(entry)) content = stripImportExtensions(content);
+    // The workspace's index.ts talks about the Basis gallery; in a project it is just the public entry point.
+    if (folder === "components" && entry === "index.ts") {
+      content = content.replace(
+        /^\/\/ Every component the Basis gallery renders\..*\n/,
+        "// Public entry point of the design system's components.\n",
+      );
+    }
+    files.push({ path: `${folder}/${entry}`, content });
+  }
+  return files;
+}
+
+/** Everything a new project needs: components, patterns, tokens in three forms, and a README. */
+export async function buildStarterKit(design: Design, workspaceDir: string): Promise<ExportFile[]> {
+  // Views are prototypes of a product's screens, not part of the design system a project installs.
+  const folders = PAGES.filter((page) => page.kind !== "view").map((page) => page.folder);
+  const files = (await Promise.all(folders.map((folder) => sourceFiles(workspaceDir, folder)))).flat();
+  return [
+    {
+      path: "README.md",
+      content: readme(
+        design,
+        files.map((file) => file.path),
+      ),
+    },
+    { path: "tokens.css", content: exportCss(design) },
+    { path: "theme.tailwind.css", content: exportTailwind(design) },
+    { path: "design-system.json", content: exportJson(design) },
+    ...files,
+  ];
+}
+
+/** Re-exporting an unchanged kit only differs in the README's date line; that is not a conflict. */
+function withoutStamp(text: string): string {
+  return text.replace(/^Generated by Basis on .*$/m, "");
+}
+
+export function zipStarterKit(files: ExportFile[], folder: string): Uint8Array {
+  return zipSync(Object.fromEntries(files.map((file) => [`${folder}/${file.path}`, strToU8(file.content)])), {
+    level: 6,
+  });
+}
+
+/**
+ * Writes the kit into a folder of the user's choosing. Refuses to touch Basis
+ * itself, and reports files that would change instead of overwriting them
+ * unless the user confirmed.
+ */
+export async function writeStarterKit(
+  files: ExportFile[],
+  target: string,
+  overwrite: boolean,
+): Promise<ExportWriteResult> {
+  const trimmed = target.trim();
+  if (!trimmed || !path.isAbsolute(trimmed)) {
+    return { ok: false, target: trimmed, written: [], conflicts: [], error: "Enter an absolute folder path." };
+  }
+  const dir = path.resolve(trimmed);
+  const relativeToBasis = path.relative(repoRoot, dir);
+  if (!relativeToBasis.startsWith("..") && !path.isAbsolute(relativeToBasis)) {
+    return {
+      ok: false,
+      target: dir,
+      written: [],
+      conflicts: [],
+      error: "That folder is inside Basis itself. Pick a folder in your project.",
+    };
+  }
+  const conflicts: string[] = [];
+  for (const file of files) {
+    const destination = path.join(dir, file.path);
+    if (!existsSync(destination)) continue;
+    const current = await readFile(destination, "utf8").catch(() => null);
+    if (current === null || withoutStamp(current) !== withoutStamp(file.content)) conflicts.push(file.path);
+  }
+  if (conflicts.length && !overwrite) return { ok: false, target: dir, written: [], conflicts };
+  const written: string[] = [];
+  for (const file of files) {
+    const destination = path.join(dir, file.path);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await writeFile(destination, file.content);
+    written.push(file.path);
+  }
+  return { ok: true, target: dir, written, conflicts: [] };
+}

package/server/guidelines.md

@@ -0,0 +1,379 @@
+# Design guidelines
+
+<!-- Generated by Basis on every start (from server/guidelines.md). Edits here are overwritten. -->
+
+Distilled from WCAG 2.2, the WAI-ARIA Authoring Practices, Material Design 3, Apple's Human Interface Guidelines,
+GOV.UK Design System, IBM Carbon, Atlassian, Shopify Polaris, Adobe Spectrum, Nielsen Norman Group research and
+practitioners on visual craft (sources at the end). Read the section for what you are about to design before you
+start, and run "Before you reply" on what you made.
+
+Labels: **must** is a WCAG A/AA requirement or a consensus every system shares; **default** is the choice Basis makes
+where the big systems disagree, so every design system made here is consistent; everything else is strong practice.
+When the user asks for something else, do what they ask and say which guideline it departs from.
+
+Contents: Before you reply · States · Focus, targets and keyboard · Buttons · Text fields and selects · Checkboxes,
+radios and switches · Tabs and navigation · Overlays · Feedback · Data · Forms · Screens and flows · Writing · AI
+assistants · Colour · Dark mode · Depth · Typography · Spacing and shape · Motion · Mood requests · Sources
+
+## Before you reply
+
+Go through what you made, in both themes and every state the gallery shows:
+
+- One focal point per region: a single primary button per view or panel, one accent hue, one key number per card.
+- Every state reads differently from its neighbours: hover is a hint, pressed a step beyond hover, focus a ring,
+  selected/checked/invalid shown by more than colour, disabled clearly unavailable yet legible.
+- The focus ring is visible on the component's own fill and on every surface it sits on, in both themes, and no
+  `overflow: hidden` ancestor clips it.
+- Hit areas are at least 24 × 24 px (icon buttons, chip and toast close buttons, row actions, pagination).
+- Boundaries that identify a control (input border, checkbox box, switch track, radio ring, selected-tab
+  indicator) are at least 3:1 against what is next to them.
+- Nothing has a fixed height that clips text: use min-height and padding; the component survives a long label,
+  a missing value, 200% zoom and a 320 px wide frame.
+- Motion stays under the durations below, never blocks the next click, and has a `prefers-reduced-motion` path.
+- Every effect has a counterpart in the other theme (see Dark mode); no colour is fixed outside the roles.
+- Labels are verbs plus nouns in sentence case; no "Submit", "OK", "Click here", lorem ipsum or "John Doe".
+- Patterns and views show their empty, loading and error states, not only the happy path.
+- It has its own identity: do not reproduce the recognisable look of a well-known product.
+
+## States
+
+Applies to every interactive component. Style (variant) and state are separate axes: the variant sets emphasis,
+states move through time on top of it.
+
+- Hover: a slight change only, since touch never sees it. Filled components step to their `xHover` role
+  (darker in light, usually lighter in dark: the same step size, not the same direction). Transparent and surface
+  components (ghost buttons, list rows, menu items, table rows) use a state layer instead: the content colour mixed
+  over the container, `color-mix(in oklab, var(--color-text) 8%, transparent)` for hover and 10–12% for pressed.
+  Material uses 8% hover, 10% focus and pressed, 16% dragged.
+- Pressed: a step beyond hover (`xActive`), within about 100 ms of the press. Optionally a small physical cue
+  (scale 0.97–0.99 or `translateY(1px)`), never one that moves layout.
+- Focus: a ring, never only a colour change (see the next section).
+- Selected, checked, current: colour plus a second cue (weight, indicator bar, check mark, filled shape).
+- Invalid: danger border plus an icon and a text message. Colour alone is not enough (must).
+- Disabled: `disabledBg` and `disabledText`; the control drops its brand colour but its label stays legible.
+  Disabled controls are exempt from contrast rules, which is exactly why they hide the reason: prefer an enabled
+  control that explains on use, or visible text that says why it is unavailable.
+- Loading: keep the size and the label (for screen readers), block repeat activation, keep focus where it is.
+- Every custom control needs a visible pressed state; without one it feels dead.
+
+## Focus, targets and keyboard
+
+- Visible focus on everything focusable (must). Style `:focus-visible` (and `[data-force="focus"]`), not `:focus`.
+- The ring: at least `--focus-ring-width` (2 px) around the whole control, in `focusRing` at 3:1 against the
+  surfaces it sits on (must) and clearly apart from the control's own fill. Use `outline` with `--focus-ring-offset`, or
+  keep `outline: 2px solid transparent` next to a box-shadow ring so it survives forced-colours mode. An inset ring
+  only where a container clips overflow (rows in a scroll area), and then thicker.
+- A focused element must not be hidden under sticky headers, toasts or composers: give scroll containers
+  `scroll-padding` equal to those bars (must).
+- Targets at least 24 × 24 px, or spaced so a 24 px circle around each does not touch another (must). 44 px for
+  touch-first controls. Grow the hit area with padding or a pseudo-element rather than the glyph.
+- Native elements first: `<button>`, `<a href>`, `<input type=checkbox|radio>`, `<select>`, `<dialog>`, `<table>`.
+  A `<div>` with a click handler is never a control.
+- Composite widgets (tabs, radio group, listbox, menu, toolbar, grid) are one Tab stop; arrow keys move inside them.
+- A control's accessible name contains its visible label and starts with it (must). Icon-only controls need an
+  `aria-label`, and their SVG `aria-hidden="true"`.
+- Changing a control never navigates, submits or opens a window by itself (must).
+- Anything shown on hover is also shown on focus (`:focus-within`), dismissible with Esc, and stays while the
+  pointer moves onto it (must). Row actions that appear only on hover are invisible to keyboard and touch users.
+- Every drag has a click alternative: move buttons or a menu for sortable lists, track clicks and arrow keys for
+  sliders (must).
+
+## Buttons
+
+- Hierarchy: one primary per view, dialog or panel. More actions step down: secondary, then outline or ghost, then
+  an overflow menu. Mark the preferred action by style, not size; buttons in one group share a size.
+- Variants: primary (the main action), secondary (alternatives), outline/ghost (low emphasis, Cancel), danger (only
+  for serious, hard-to-undo actions, rarely needed). Danger is never the default or the primary of a dialog and is
+  never icon-only; its label says what happens.
+- Sizes: 32 / 40 / 48 px (default 40). Match the height of inputs it sits beside. Small buttons keep a 24 px
+  minimum hit area.
+- Labels: verb plus object in sentence case ("Save draft", "Delete project"); single words only for Done, Close,
+  Cancel. No punctuation. Wrap long labels rather than truncate.
+- Icons: only when the meaning is established and tied to the action; 16–20 px, in the label's colour; if one
+  button in a group has an icon, all do. Icon-only buttons need an accessible name and a tooltip.
+- Loading: keep the width and keep the label in the DOM (spinner over or beside it), `aria-busy`, ignore repeat
+  presses, keep focus. Acknowledge the press at once; show the spinner only if it takes over about 1 s. Announce
+  the result through a status region, not the button.
+- Disabled: default is to keep buttons enabled and validate when pressed. Never disable without a visible reason.
+- Buttons act on the page, links navigate. Do not dress one as the other.
+- "Premium" or tactile: a medium weight, slightly tighter label tracking, a layered tinted shadow, a top highlight
+  and fast press feedback, all theme-aware (see Depth). Not more saturation, not gradients everywhere.
+
+## Text fields and selects
+
+- A visible label above every field, short, sentence case, no colon (must). The placeholder is never the label:
+  it disappears, fails contrast and is not reliably announced. Use placeholders for format examples at most.
+- Hint text between the label and the field, one short sentence, connected with `aria-describedby`.
+- Default marking: ask only what is needed, so most fields are required; mark the optional ones "(optional)".
+- Width hints at the answer: postcode, year, amount and code fields are narrow; names and addresses wide.
+- Height 40 px by default, matching buttons; the input border is at least 3:1 against its surface (must).
+- Errors: the message sits by the field (between hint and input), says what is wrong and how to fix it in the
+  label's words ("Enter a date in the past", not "Invalid date"), with a danger border, an icon and
+  `aria-invalid="true"` plus `aria-describedby` pointing at the message. Keep what the user typed.
+- Default validation: on submit; after that, a field that showed an error re-checks as the user types and clears as
+  soon as it is valid. Never flag an untouched field or a field while it is first being filled.
+- Prefix and suffix for units and currency, and say the unit in the label too. Prefer a character counter over a
+  silent `maxlength`; `inputmode` over `type=number`.
+- Selects: native `<select>` unless the design needs search or rich options; a custom one carries the full
+  combobox keyboard model (arrows, Enter, Esc, type-ahead, `aria-expanded`, `aria-activedescendant`).
+
+## Checkboxes, radios and switches
+
+- Radio: exactly one of a few options. Checkbox: any number, or one setting saved on submit. Switch: an on/off
+  setting that takes effect immediately; never inside a form with a submit button.
+- Stack options vertically, control left of label; the label is part of the click target. Inline only for two
+  short options.
+- Groups get a `fieldset` and `legend`, usually phrased as a question; add "Select all that apply" when it helps.
+- Do not preselect; offer an explicit "None" when that is a valid answer.
+- Indeterminate is a parent whose children are partly checked; checking it checks all.
+- Switch labels name what "on" means ("Email notifications") and do not change with the state; state shows by thumb
+  position plus colour. The off track and the box/ring of unchecked controls need 3:1 (must).
+
+## Tabs and navigation
+
+- Selected tab: two cues, such as an indicator bar plus stronger text, or a filled pill. One row, labels of one or
+  two words, no all caps. Tabs switch content within a page; page navigation is links with
+  `aria-current="page"`.
+- Keyboard: Tab lands on the active tab, arrows move between tabs, the next Tab goes into the panel.
+- Do not hide content users must compare or read in order behind tabs.
+- Navigation always shows where the user is (active item matching the page heading) and how to get back
+  (breadcrumb or Back link on detail screens).
+- Application navigation on the left on wide screens; do not hide it behind a hamburger on desktop. Submenus open
+  on click. Icons support labels, they do not replace them.
+- Segmented controls: two to five short options of equal weight, with a clear selected fill.
+
+## Overlays
+
+- Modal dialogs only for a critical warning, required input or a short focused task. Not for details (use a side
+  panel so the list stays visible), not for field errors, not to confirm routine actions (offer Undo instead).
+- Dialog: a title that matches the button that opened it, at most three buttons with the primary last on the
+  trailing side, only the body scrolls. Focus moves in (first field, or the least destructive button for confirms),
+  is trapped, Esc closes, focus returns to the trigger. `role="dialog"`, `aria-modal`, labelled by its title.
+- Confirmations name the item and the consequence and label buttons with outcomes ("Delete 3 invoices" /
+  "Keep invoices"), never Yes/No; the destructive button is never the default.
+- Popovers and menus open on click, close on Esc and outside click, return focus to their trigger, and sit on
+  `surfaceRaised` with the overlay shadow. Action menus use the menu keyboard model; site navigation does not.
+- Tooltips: short supplementary text on hover and focus, Esc dismisses, never on disabled controls, never the only
+  place information lives, nothing interactive inside.
+
+## Feedback
+
+- Badges and status labels pair colour with text (and an icon where the meaning is established), sentence case.
+  Status colours have matched lightness so none shouts louder than another.
+- Inline alerts sit next to what they concern, do not auto-dismiss and have at most one action. Info, success,
+  warning and error each use their role (`xSubtle` background, `xStrong` text, `x` icon or border).
+- Toasts are for passive confirmations only, never errors or anything essential. At least 5 s, paused on hover
+  and focus; a toast with an action (Undo) stays until the user acts, and its action is reachable elsewhere too.
+  `role="status"` in a region that exists before the message arrives. One consistent position per product.
+- Loading: under about 1 s show nothing extra beyond the pressed state; up to 10 s a spinner for one element or a
+  skeleton that mirrors the real layout for a view; over 10 s determinate progress with a way to cancel.
+  Skeleton shimmer is subtle and stops under reduced motion.
+- Empty states are designed, never blank, and never shown while data is still loading. First use: what will appear
+  here and a button to create the first item. No results: the query, and a way to broaden it or clear filters.
+- Errors say what happened and what to do next, keep the valid data on screen, and match prominence to severity:
+  inline for a field, a banner for a section or page, a dialog only when the user cannot continue.
+
+## Data
+
+- Tables: the first column is a human-readable identifier (a name, an invoice number), never an internal id.
+  Numbers right-aligned with `font-variant-numeric: tabular-nums`, text left-aligned, headers aligned with their
+  data. Row heights 32 / 40 / 48 px by density.
+- Sorting has three states; only the sorted column keeps its arrow visible; sortable headers are buttons with
+  `aria-sort` on the `th`. Long headers wrap to two lines before truncating.
+- One or two row actions inline; more go behind checkbox selection and a bulk action bar. Row actions stay visible
+  on focus, not only on hover.
+- Sticky header (and first column on wide tables), row hover, skeleton rows while loading, and the empty, no-results
+  and error states.
+- Pagination or "Load more" when users look for or compare items; infinite scroll only for browsing feeds.
+- Stat cards and dashboards: every number answers a question and shows a comparison (target, previous period,
+  threshold) and links to the records behind it. Bars and lines, not pies, donuts, gauges or 3D. Fit what is
+  monitored on one screen. Invented trends must add up.
+
+## Forms
+
+- One column; only short related fields share a row (city and postcode). Group fields under short headings.
+- Spacing: about 24–32 px between fields on a page, 16–24 px in dialogs and panels, about 48 px before the buttons.
+- Default button placement: in page forms the primary sits at the start (left), Cancel or Back after it; in dialogs,
+  side panels and wizards the primary is last on the trailing side.
+- On a failed submit, an error summary at the top titled "There is a problem" takes focus and links each item to
+  its field, using the same words as the field's message.
+- Multi-step: one question or decision per step, a Back link at the top, "Continue" as the button, a check-answers
+  step before the final submit, and a confirmation that says what happens next.
+- Ask only what you need; prefill what the user already gave in the flow; allow paste and password managers.
+
+## Screens and flows
+
+These apply to views and to patterns that make up a screen.
+
+- One primary action per screen. Spend contrast on one thing per region; everything else steps down in size,
+  weight and colour.
+- Headings carry the information (users scan headings, then dip in), lead with the important words, and match the
+  navigation label that leads there.
+- Group by proximity and enclosure: space inside a group is clearly smaller than between groups (1:2 or more).
+- Every action shows feedback within 0.1 s; anything over 1 s shows progress where it happens; over 10 s shows
+  determinate progress and a way out.
+- Every modal, drawer, step and edit mode has a labelled way out; destructive results can be undone. Prefer Undo to
+  confirmation; confirm only what is irreversible and costly.
+- Before a commit, the screen shows the current state: draft or published, unsaved changes, selection count,
+  active filters.
+- List and detail: a side panel or split view on wide screens, push navigation on narrow ones. Keep the same content
+  and features at every size; change the layout, not the substance.
+- Design all the states a screen meets: first use, populated, loading, error, no results, success.
+- Every interactive element leads somewhere in the flow or is visibly out of scope; nothing invented leads nowhere.
+- Progressive disclosure for rare options: at most two levels, behind a clearly named control.
+
+## Writing
+
+- Sentence case everywhere: buttons, headings, labels, menus, tabs. No all caps for emphasis (small uppercase
+  labels are a typographic style with added tracking, not emphasis).
+- Buttons are verb plus noun naming the outcome, the same verb throughout a flow ("Add product" ends in "Add
+  product", not "Create item"). Links make sense on their own; no "Learn more" without what about.
+- One term per concept across list, detail, form and messages.
+- Errors: what happened and how to fix it, specific, plain, no blame ("invalid", "illegal"), no humour, no codes
+  unless they help; apologise only for real system failures.
+- Short sentences, important words first, "you" for the user. Headings and labels without end punctuation. No
+  exclamation marks in success messages.
+- Numbers, dates and money follow the product's locale, identical on every screen. In Swedish: "4 juni 2025",
+  "9 000 kr", "12,5 %". In English: "4 June 2025", "9,000", "£75.50".
+- Sample data is realistic and from the product's domain and language: plausible names and ids, amounts that add
+  up, dates in order, statuses spread realistically. Include edge cases: a very long name, a missing optional
+  value, zero and negative amounts, one item and many, non-ASCII characters (å, ä, ö, é).
+
+## AI assistants
+
+For chat and assistant patterns and views.
+
+- The empty state says what the assistant can do here, without overpromising, with suggested prompts as buttons.
+- Distinct states: waiting for the first token, streaming, working on a named step ("Searching invoices…"), done,
+  failed. Stop is prominent while generating and keeps the partial answer.
+- Do not auto-scroll past the start of a new answer while it streams.
+- Per message: copy, regenerate, edit the prompt, feedback (thumbs with an optional reason); labelled controls,
+  grouped.
+- Answers lead with the answer; sources are linked and say what the answer is based on ("Based on 14 invoices
+  from March").
+- Before the assistant changes data it says what will change; afterwards it offers Undo.
+- Errors explain plainly, keep the prompt for a retry and offer a manual path.
+- One assistant entry point; do not rebuild search, filters or navigation as chat.
+
+## Colour
+
+- Components read semantic roles only; palette changes happen in the roles' values. "Warmer" or "calmer" changes
+  the neutrals' hue and chroma and maybe the accent hue, in both themes; the role mapping stays.
+- One accent hue for the primary action, selection, focus and links; neutrals carry about 90% of the pixels.
+  Several competing accents are the most common amateur signal.
+- Tint neutrals slightly toward the brand or a warm/cool direction (OKLCH chroma about 0.005–0.02). It is the
+  cheapest lever for mood.
+- Work in OKLCH: keep the hue, vary lightness, lower chroma at the light and dark ends. Relative colour
+  (`oklch(from var(--color-primary) calc(l - 0.06) c h)`) derives steps that follow the theme.
+- State steps: about 0.04–0.08 OKLCH lightness for hover on large fills, about double for pressed.
+- Status colours (info, success, warning, danger) at matched lightness and chroma, each with a subtle background,
+  strong text, solid fill and on-colour, in both themes.
+- Muted text still needs 4.5:1; `textSubtle` is for large or non-essential text only.
+
+## Dark mode
+
+Both themes are first-class siblings: same hues, same number of surface levels, same radius, spacing and type, same
+accent-to-neutral ratio. Only lightness, chroma and alpha change. If light has an effect, dark has a translated
+version of it, not an absence.
+
+- No pure black or white: a dark grey page (around OKLCH L 0.15–0.2) and off-white text (L 0.93–0.97).
+- Elevation by lightness: in dark, each raised level a little lighter (about 0.02–0.05 OKLCH L per step), in order
+  `surfaceSunken` < `bg` < `surface` < `surfaceRaised`. In light, raised surfaces are white or near-white and lean
+  on the shadow; the page and sunken wells step down by about 0.01–0.03.
+- Shadows nearly vanish on dark surfaces: the `shadow` role is stronger in dark, and the lighter surface or a faint
+  border carries the depth. Design so the element still separates with the shadow barely visible.
+- Borders in dark: a step lighter than the surface or a translucent light mix (6–12%), never bright lines.
+- Brand and status colours lighter and less saturated in dark (keep the hue, drop chroma 20–40%, raise L) when
+  used as text or icons; a solid primary fill may stay saturated.
+- Hover and pressed: same step size as light, usually the opposite direction (lighter).
+- Light text on dark looks bolder: avoid hairline weights.
+- Images and illustrations: contain them, dim slightly or provide dark versions; icons use `currentColor`.
+
+## Depth
+
+- One light source, from above: all shadows share direction; highlights sit on the top edge.
+- Elevation levels: sunken (wells, tracks), flat (page content; cards with a border or a lightness step), raised
+  (emphasised or draggable cards), overlay (menus, popovers, dialogs, toasts). As elevation rises, offset and blur
+  grow and opacity falls.
+- Layered shadows (two to four layers, offsets and blurs doubling: 1, 2, 4, 8 px) read more naturally than one big
+  blur. Mix them from the `shadow` role, never plain black: `0 2px 4px color-mix(in srgb, var(--color-shadow) 20%,
+  transparent)`.
+- One edge cue per surface: a border, a shadow or a lightness step; combine only a hairline with a soft shadow.
+- Tactile or "premium" controls: a top inner highlight, an optional bottom inner shade and a tight outer shadow, all
+  derived from the fill or the roles. A highlight that is 15–30% light on a light-theme fill must drop to about
+  4–10% in dark or it glows; the bottom shade usually disappears in dark. Pressed removes the highlight and shrinks
+  the outer shadow.
+- Do not animate layered `box-shadow`; fade a pseudo-element's shadow or animate transform instead.
+
+## Typography
+
+- Five to seven sizes. Product UI scales by about 1.125–1.2 per step; editorial and marketing by 1.25–1.333.
+- Body at least 14 px in dense product UI and 16 px for reading; labels and captions at least 11–12 px.
+- Line height falls as size rises: about 1.5 for body, 1.2–1.3 for headings, 1.0–1.1 for display.
+- Measure 45–90 characters, ideally 60–75 for body copy (`max-width: 65ch`).
+- Letter-spacing: normal for body; +0.05–0.12em for all caps and small labels; -0.01 to -0.03em for large display.
+- Two or three weights. Hierarchy from size, weight and colour together, not weight alone; not everything bold.
+- Tabular numbers for tables, prices, timers and anything that updates or aligns.
+
+## Spacing and shape
+
+- A 4 px base with an 8 px rhythm (the `space` tokens). Small steps inside components, large steps for layout.
+- Components carry no outer margins; parents set gaps (`gap`, stacks). Padding inside a container is at least the
+  gap between its children.
+- Density moves control and row heights one step (32 / 40 / 48 px); type size stays.
+- Left-align text in product UI; centre only short standalone blocks (empty states, hero headings).
+- A small radius scale tied to size: small controls smaller, containers larger. Nested corners are concentric:
+  inner radius = outer radius − padding − border width.
+- Patterns respond to their container (container queries), so they work in any column width and at 320 px.
+
+## Motion
+
+- Durations: micro feedback (toggles, button states) about 70–120 ms; small expansions and dropdowns about
+  150–250 ms; dialogs, sheets and large moves about 250–400 ms. Over 500 ms feels slow; frequent motion is shorter.
+- Easing: entering decelerates, exiting accelerates and runs 20–30% shorter, things that stay use a standard
+  ease-in-out; linear only for spinners and progress. Use the `ease` tokens.
+- Animate `transform` and `opacity`; never `transition: all` or layout properties.
+- Press feedback almost instant; hover-in about 100–200 ms. Never make the user wait for an animation to finish.
+- Reduced motion (default): under `@media (prefers-reduced-motion: reduce)` remove slides, zooms, parallax, shimmer
+  and loops; keep state changes as short fades or instant switches.
+- Anything that moves or updates by itself for more than 5 s has a way to pause it, and nothing flashes more than
+  three times a second (must).
+
+## Mood requests
+
+Taste, built from the levers above; always in both themes.
+
+- Warmer: neutrals toward hue 60–80 at chroma 0.01–0.02, warmer shadow tint, perhaps a warmer accent.
+- Calmer: lower chroma throughout, one restrained accent, more space, flatter elevation, slower but short motion.
+- Premium: restraint. Fewer colours, tighter tracking on labels, medium weights, layered tinted shadows, a subtle
+  theme-aware highlight, precise alignment and fast press feedback.
+- Playful: a brighter accent, rounder radius, springier but still short motion, more saturated status colours.
+- Fintech or data-heavy: low-chroma neutrals, one blue or green accent, tabular numbers, compact density options,
+  productive motion (100–240 ms), status colours with matched lightness.
+- Editorial: a serif or high-contrast display face, a larger type ratio, generous measure and leading, few borders.
+
+## Sources
+
+- WCAG 2.2 and its Understanding documents: https://www.w3.org/WAI/WCAG22/Understanding/
+- WAI-ARIA Authoring Practices, patterns: https://www.w3.org/WAI/ARIA/apg/patterns/
+- Focus indicators (Sara Soueidan): https://www.sarasoueidan.com/blog/focus-indicators/
+- Toasts and accessibility (Scott O'Hara): https://www.scottohara.me/blog/2019/07/08/a-toast-to-a11y-toasts.html
+- Material Design 3: https://m3.material.io/ (state layers, colour roles, elevation, motion)
+- Apple Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines/
+- GOV.UK Design System and Service Manual: https://design-system.service.gov.uk/,
+  https://www.gov.uk/service-manual/design/writing-for-user-interfaces
+- IBM Carbon: https://carbondesignsystem.com/ (buttons, forms, data table, notifications, spacing, motion)
+- Atlassian Design System: https://atlassian.design/ (buttons, lozenges, elevation)
+- Shopify Polaris: https://polaris-react.shopify.com/
+- Adobe React Spectrum: https://react-spectrum.adobe.com/ (button loading, toasts)
+- Nielsen Norman Group: https://www.nngroup.com/articles/ (heuristics, response times, button states, forms,
+  error messages, toasts, tooltips, dialogs, tabs, menus, data tables, dashboards, empty states, skeletons, AI chat)
+- Laws of UX: https://lawsofux.com/
+- Microsoft HAX guidelines: https://www.microsoft.com/en-us/haxtoolkit/library/
+- Google PAIR guidebook: https://pair.withgoogle.com/
+- Radix Colors, the 12-step scale: https://www.radix-ui.com/colors/docs/palette-composition/understanding-the-scale
+- OKLCH in CSS (Evil Martians): https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl
+- Designing shadows (Josh W. Comeau): https://www.joshwcomeau.com/css/designing-shadows/
+- Practical Typography: https://practicaltypography.com/
+- Utopia, fluid type and space: https://utopia.fyi/
+- Nested radius: https://cloudfour.com/thinks/the-math-behind-nesting-rounded-corners/