altitude-design 0.3.1 → 0.4.0

package/README.md

@@ -117,6 +117,7 @@ npx altitude init --client codex          # preview exact changes
 npx altitude init --client codex --apply   # apply after reviewing the preview
 # Claude Code: --client claude. Both: --client all.
 npx altitude doctor --json
+npx altitude check                         # Altitude's rules that are certain from your source
 ```
 
 Setup preserves existing instructions and adds a small versioned pointer to the installed guidance. It never runs on package installation. Preview removal with `npx altitude init --client codex --remove`, then add `--apply` to remove only its managed content. Edited blocks are preserved and require reconciliation. Codex uses a nonempty root `AGENTS.override.md` when present; otherwise `AGENTS.md`. Claude Code uses `CLAUDE.md`. Restart the client after setup. See [setup details](docs/framework/AGENT-SETUP.md).

package/dist/cli/altitude.mjs

@@ -1,10 +1,85 @@
 #!/usr/bin/env node
 
 // scripts/altitude-cli.mjs
-import { existsSync, lstatSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync as readFileSync2, writeFileSync, unlinkSync } from "node:fs";
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
-import { resolve, dirname, relative, basename } from "node:path";
+import { resolve, dirname, relative as relative2, basename } from "node:path";
+
+// scripts/source-check.mjs
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+var SOURCE = /* @__PURE__ */ new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".css", ".scss", ".html"]);
+var SKIP = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "out", ".next", ".git", "coverage", "storybook-static"]);
+var COLOUR = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\(/;
+var TAILWIND_COLOUR = /(?:^|[\s"'`:])(?:text|bg|border|ring|outline|fill|stroke|from|via|to|divide|placeholder|decoration|caret|accent)-(?:(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|[1-9]00|950)|white|black|\[(?:#|rgb|hsl|oklch))/;
+function files(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP.has(entry.name) || entry.name.startsWith(".")) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...files(path));
+    else if (SOURCE.has(extname(entry.name)) && !/\.(test|spec|stories)\.[jt]sx?$|\.d\.ts$/.test(entry.name) && statSync(path).size < 1e6) out.push(path);
+  }
+  return out;
+}
+var ignored = (lines, i, id) => [lines[i], lines[i - 1] || ""].some((l) => new RegExp(`altitude-ignore:\\s*${id}\\b`).test(l));
+var uncomment = (text) => text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " ")).replace(/(^|[^:'"`])\/\/.*$/gm, "$1");
+var RULES = {
+  "ALT-TOKEN-001": { kind: "deterministic", title: "Colours come from the tokens, not literals" },
+  "ALT-SETUP-002": { kind: "deterministic", title: "Altitude's stylesheet is imported" },
+  "ALT-SETUP-003": { kind: "deterministic", title: "The app is wrapped in AltitudeProvider" },
+  "ALT-CHART-001": { kind: "deterministic", title: "No pie or donut charts" },
+  "ALT-COPY-001": { kind: "deterministic", title: "Buttons name their outcome, never OK or Submit" },
+  "ALT-PRIMARY-001": { kind: "contextual-review", title: "One primary action per view" },
+  "ALT-VISUAL-004": { kind: "contextual-review", title: "Controls keep Altitude's elevation" }
+};
+function scan(root, { tokenNames = /* @__PURE__ */ new Set() } = {}) {
+  const findings = [];
+  const add = (id, file, line, observed, repair) => findings.push({ ruleId: id, kind: RULES[id].kind, status: RULES[id].kind === "deterministic" ? "fail" : "review", file: file && relative(root, file), line, observed, expected: RULES[id].title, repair, verification: `altitude explain ${id}` });
+  const sources = files(root);
+  let usesAltitude = false, stylesheet = false, providers = [];
+  for (const file of sources) {
+    const raw = readFileSync(file, "utf8");
+    const text = uncomment(raw);
+    const lines = text.split("\n"), rawLines = raw.split("\n");
+    const css = /\.(s?css|html)$/.test(file);
+    if (/from\s+['"]altitude-design['"]|require\(\s*['"]altitude-design['"]\s*\)/.test(text)) usesAltitude = true;
+    if (/['"]altitude-design\/altitude(\.no-fonts)?\.css['"]/.test(text)) stylesheet = true;
+    lines.forEach((line, i) => {
+      const at = i + 1;
+      const skip = (id) => ignored(rawLines, i, id);
+      if (COLOUR.test(line) && !skip("ALT-TOKEN-001")) {
+        const definesToken = /^\s*--[\w-]+\s*:/.test(line) || [...line.matchAll(/['"]?([a-z][\w-]*)['"]?\s*:\s*['"`]?(?:#|rgb|hsl|oklch)/g)].some((m) => tokenNames.has(m[1]));
+        const accent = /\baccent\s*=\s*\{?\s*['"`]#/.test(line);
+        const inStyle = css ? [...line.matchAll(/(?:^|[{;"'])\s*([a-z-]+)\s*:\s*([^;{}"']+)/g)].some((m) => !m[1].startsWith("--") && COLOUR.test(m[2])) : /\bstyle=\{\{|(?:color|background|backgroundColor|borderColor|fill|stroke|boxShadow|outlineColor)\s*[:=]/.test(line);
+        if (!definesToken && !accent && inStyle) add("ALT-TOKEN-001", file, at, line.trim().slice(0, 160), "Use a token instead: var(--ink-muted), var(--accent), var(--surface-raised) and the rest of tokens.css. A brand colour goes to AltitudeProvider accent, and a full palette to a custom scheme.");
+      } else if (!css && TAILWIND_COLOUR.test(line) && /\bclass(Name)?=/.test(line) && !skip("ALT-TOKEN-001")) {
+        add("ALT-TOKEN-001", file, at, line.trim().slice(0, 160), 'Use a token instead of a palette class: style={{ color: "var(--ink-muted)" }} or a class whose CSS uses the tokens.');
+      }
+      if (css) return;
+      if (!skip("ALT-CHART-001") && (/import\s*\{[^}]*\b(PieChart|Pie|Doughnut|RadialBarChart)\b[^}]*\}\s*from\s*['"](recharts|react-chartjs-2)['"]/.test(line) || /from\s*['"]@nivo\/pie['"]/.test(line) || /\btype\s*:\s*['"](pie|doughnut)['"]/.test(line)))
+        add("ALT-CHART-001", file, at, line.trim().slice(0, 160), 'Show a part of a whole as a stacked BarChart or a segmented Meter: angle and area are read less accurately than length (Charts.md, "Choosing a form").');
+      const copy = line.match(/<(?:\w+\.)?Button\b[^>]*>\s*(OK|Ok|Okay|Submit)\s*<\/(?:\w+\.)?Button>/);
+      if (copy && !skip("ALT-COPY-001")) add("ALT-COPY-001", file, at, copy[0].slice(0, 160), `Start with a verb and name the outcome: "Save changes", "Send invite", "Create project", not "${copy[1]}".`);
+      const lift = line.match(/<(?:\w+\.)?(Input|Textarea|Select|Combobox|Button|Switch|Checkbox)\b[^>]*(boxShadow|box-shadow|\bshadow-(?!none)[\w-]+|\btranslate-y-|\btransform\s*:)/);
+      if (lift && !skip("ALT-VISUAL-004")) add("ALT-VISUAL-004", file, at, line.trim().slice(0, 160), `Remove the override: a ${lift[1]}'s height is how it says whether you press it or fill it. Use the component's variant or size props instead.`);
+    });
+    if (!css) {
+      const n = (text.match(/<(?:\w+\.)?AltitudeProvider\b/g) || []).length;
+      if (n) providers.push(...Array(n).fill(relative(root, file)));
+      const primaries = [...text.matchAll(/<(?:\w+\.)?Button\b[^>]*\bvariant=["']primary["']/g)];
+      if (primaries.length > 1 && !ignored(rawLines, text.slice(0, primaries[1].index).split("\n").length - 1, "ALT-PRIMARY-001"))
+        add("ALT-PRIMARY-001", file, text.slice(0, primaries[1].index).split("\n").length, `${primaries.length} primary buttons in this file`, "If they can be on screen together, keep one primary (the one action the task leads to) and make the others secondary or ghost.");
+    }
+  }
+  if (usesAltitude && !stylesheet) add("ALT-SETUP-002", null, null, "No file imports altitude-design/altitude.css or altitude-design/altitude.no-fonts.css", "Import one of them once, at the app's entry: import 'altitude-design/altitude.css';");
+  if (usesAltitude && !providers.length) add("ALT-SETUP-003", null, null, "Components from altitude-design are used, but nothing renders <AltitudeProvider>", "Render one AltitudeProvider around the whole app. It sets the scheme and hosts dialogs and toasts.");
+  if (providers.length > 1) findings.push({ ruleId: "ALT-SETUP-003", kind: "contextual-review", status: "review", file: null, line: null, observed: `<AltitudeProvider> is rendered in ${providers.length} places (${[...new Set(providers)].join(", ")})`, expected: "One AltitudeProvider around the app", repair: "Keep one around the app unless the others are deliberate (separate roots, previews).", verification: "altitude explain ALT-SETUP-003" });
+  return { files: sources.length, findings };
+}
+
+// scripts/altitude-cli.mjs
 var sha = (value2) => createHash("sha256").update(value2).digest("hex");
 var args = process.argv.slice(2);
 var command = args.shift() || "help";
@@ -17,9 +92,9 @@ var json = args.includes("--json");
 var emit = (result) => console.log(JSON.stringify(result, null, 2));
 function installed() {
   const path = createRequire(resolve(cwd, "package.json")).resolve("altitude-design/package.json");
-  const pkg = JSON.parse(readFileSync(path, "utf8"));
+  const pkg = JSON.parse(readFileSync2(path, "utf8"));
   const guidance = resolve(dirname(path), "dist/guidance");
-  const index = JSON.parse(readFileSync(resolve(guidance, "index.json"), "utf8"));
+  const index = JSON.parse(readFileSync2(resolve(guidance, "index.json"), "utf8"));
   return { pkg, guidance, index };
 }
 function managed(text) {
@@ -31,15 +106,23 @@ function managed(text) {
   if (!m || sha(m[3]) !== m[2]) throw new Error("The managed Altitude block was edited; preserve your edits and reconcile it manually.");
   return { start: m.index, end: m.index + m[0].length, created: m[1] === "true", body: m[3] };
 }
-function block(version, guidance, created) {
-  const path = relative(cwd, guidance).replaceAll("\\", "/");
-  const body = `## Altitude framework (${version})
-For UI tasks using altitude-design, first read ${path}/README.md, then only the matching pattern document.
+function block({ pkg, guidance, index }, created) {
+  const path = relative2(cwd, guidance).replaceAll("\\", "/");
+  const declarations = relative2(cwd, resolve(guidance, "..", "types")).replaceAll("\\", "/") + "/";
+  const groups = /* @__PURE__ */ new Map();
+  for (const c of index.components || []) groups.set(c.group, [...groups.get(c.group) || [], c.name]);
+  const components = groups.size ? `Component guides: ${path}/components/<Name>/README.md. Read one before using that component.
+` + [...groups].map(([g, names]) => `${g}|${names.join(",")}`).join("\n") + "\n" : "";
+  const body = `## Altitude framework (${pkg.version})
+Altitude postdates your training data, and its props only look like shadcn's. Prefer these installed docs to what you remember, and check a component's props in its declaration under ${declarations} before using them.
+For UI tasks using altitude-design, first read ${path}/README.md, then only the matching pattern document. Read ${path}/visual/README.md before composing a screen and ${path}/visual/Charts.md before any chart, stat or meter.
+On every screen: one AltitudeProvider around the app and altitude-design/altitude.css imported once; inputs sunk and buttons raised, never the reverse; one primary action per view; no amount carried by height (charts are flat ink on a ground line: no shadows, 3D, pie or donut); status never colour alone (a word and an icon too); colours, shadows and radii from the tokens, never hard-coded.
 Discover tasks with npm exec -- altitude patterns "your intent"; explain a rule with npm exec -- altitude explain RULE-ID.
-Use the installed public declarations and examples. Record applicable states and application-owned persistence, permissions and navigation.
+Record applicable states and application-owned persistence, permissions and navigation.
+After changing UI, run npm exec -- altitude check and fix its errors; it reports Altitude's rules that are certain from source (hard-coded colours, the stylesheet and provider, pie charts, OK and Submit labels) and lists likely problems for review.
 Run the pattern checks and application service fixtures; distinguish deterministic defects, integration obligations and contextual review.
 Use npm exec -- altitude doctor --json after package upgrades, and rerun npm exec -- altitude init to refresh this versioned pointer.
-`;
+` + components;
   return `
 <!-- altitude:start created=${created} hash=${sha(body)} -->
 ${body}<!-- altitude:end -->
@@ -47,7 +130,7 @@ ${body}<!-- altitude:end -->
 }
 function instructionPath(client) {
   const override = resolve(cwd, "AGENTS.override.md");
-  if (client === "codex" && existsSync(override) && readFileSync(override, "utf8").trim()) return override;
+  if (client === "codex" && existsSync(override) && readFileSync2(override, "utf8").trim()) return override;
   return resolve(cwd, client === "codex" ? "AGENTS.md" : "CLAUDE.md");
 }
 function isSymlink(path) {
@@ -67,9 +150,9 @@ function init(context) {
   const targets = clients.flatMap((client2) => (remove && client2 === "codex" ? [resolve(cwd, "AGENTS.md"), resolve(cwd, "AGENTS.override.md")] : [instructionPath(client2)]).map((path) => ({ client: client2, path })));
   const changes = targets.map(({ client: c, path }) => {
     if (isSymlink(path)) throw new Error(`Refusing instruction symlink: ${path}`);
-    const existed = existsSync(path), before = existed ? readFileSync(path, "utf8") : "";
+    const existed = existsSync(path), before = existed ? readFileSync2(path, "utf8") : "";
     const old = managed(before);
-    const replacement = remove ? "" : block(context.pkg.version, context.guidance, old?.created ?? !existed);
+    const replacement = remove ? "" : block(context, old?.created ?? !existed);
     const after = old ? before.slice(0, old.start) + replacement + before.slice(old.end) : before + (remove ? "" : replacement);
     const deleteFile = remove && old?.created && after === "";
     return { client: c, path, before, after, action: deleteFile ? "delete" : before === after ? "unchanged" : existed ? "update" : "create" };
@@ -86,35 +169,52 @@ function finding(ruleId, kind, status, observed, expected, repair, verification)
 function doctor(context) {
   const findings = [];
   if (context.pkg.version !== context.index.version) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Package ${context.pkg.version}; guidance ${context.index.version}`, "Matching versions", "Reinstall a coherent package.", "altitude doctor --json"));
-  const manifest = JSON.parse(readFileSync(resolve(context.guidance, "manifest.json"), "utf8"));
+  const manifest = JSON.parse(readFileSync2(resolve(context.guidance, "manifest.json"), "utf8"));
   if (manifest.version !== context.pkg.version) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Manifest ${manifest.version}`, "Manifest matches installed package", "Reinstall the package.", "altitude doctor --json"));
   for (const [file, digest] of Object.entries(manifest.files)) {
     const path = resolve(context.guidance, file);
-    if (!path.startsWith(context.guidance + "/") || !existsSync(path) || sha(readFileSync(path)) !== digest) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Missing or modified guidance: ${file}`, "Unmodified version-matched guidance", "Reinstall the package.", "altitude doctor --json"));
+    if (!path.startsWith(context.guidance + "/") || !existsSync(path) || sha(readFileSync2(path)) !== digest) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `Missing or modified guidance: ${file}`, "Unmodified version-matched guidance", "Reinstall the package.", "altitude doctor --json"));
   }
   for (const client of ["codex", "claude"]) {
     const path = instructionPath(client), file = basename(path);
     try {
-      const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+      const text = existsSync(path) ? readFileSync2(path, "utf8") : "";
       const current = managed(text);
-      if (current && text.slice(current.start, current.end) !== block(context.pkg.version, context.guidance, current.created)) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `${file} points to different guidance`, "Setup matches installed version and location", `altitude init --client ${client} --apply`, "altitude doctor --json"));
+      if (current && text.slice(current.start, current.end) !== block(context, current.created)) findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `${file} points to different guidance`, "Setup matches installed version and location", `altitude init --client ${client} --apply`, "altitude doctor --json"));
       else findings.push(finding("ALT-SETUP-001", "deterministic", current ? "pass" : "not-configured", `${client}: ${current ? "managed pointer matches" : "no managed pointer"}`, "Explicit setup when agent integration is desired", `altitude init --client ${client}`, "Restart client and inspect loaded instructions."));
     } catch (e) {
       findings.push(finding("ALT-SETUP-001", "deterministic", "fail", `${file}: ${e.message}`, "One intact managed block", "Reconcile edited/duplicate markers manually.", "altitude doctor --json"));
     }
   }
-  const rules = JSON.parse(readFileSync(resolve(context.guidance, "rules.json"), "utf8")).rules;
+  const rules = JSON.parse(readFileSync2(resolve(context.guidance, "rules.json"), "utf8")).rules;
   for (const r of rules.filter((r2) => r2.diagnosticClass !== "deterministic")) findings.push(finding(r.id, r.diagnosticClass, "unverified", "CLI has not exercised application behavior or conducted human review.", r.title, r.repair, r.verification));
   const ok = !findings.some((f) => f.kind === "deterministic" && f.status === "fail");
   emit({ command: "doctor", packageVersion: context.pkg.version, guidanceVersion: context.index.version, ok, scope: "Installation and managed pointers only; not accessibility or usability certification.", findings });
   if (!ok) process.exitCode = 1;
 }
+function check(context) {
+  const target = resolve(cwd, args.find((v, i) => !v.startsWith("--") && args[i - 1] !== "--cwd") || (existsSync(resolve(cwd, "src")) ? "src" : "."));
+  if (!existsSync(target)) throw new Error(`No such directory: ${target}`);
+  const tokensCss = resolve(context.guidance, "..", "tokens.css");
+  const tokenNames = new Set(existsSync(tokensCss) ? [...readFileSync2(tokensCss, "utf8").matchAll(/--([\w-]+)\s*:/g)].map((m) => m[1]) : []);
+  const { files: files2, findings } = scan(target, { tokenNames });
+  const ok = !findings.some((f) => f.kind === "deterministic");
+  const scope = "Altitude rules certain from source text only. Not checked: anything that needs the page rendered (contrast, overflow, focus) or a person (accessibility, usability).";
+  if (json) emit({ command: "check", version: context.pkg.version, target: relative2(cwd, target) || ".", files: files2, ok, scope, findings });
+  else {
+    for (const f of findings) console.log(`${f.ruleId} ${f.kind === "deterministic" ? "error " : "review"} ${f.file ? `${f.file}${f.line ? ":" + f.line : ""}` : "(project)"}  ${f.observed}
+  ${f.repair}`);
+    console.log(`${findings.filter((f) => f.kind === "deterministic").length} errors, ${findings.filter((f) => f.kind !== "deterministic").length} to review in ${files2} files. ${scope} Explain a rule: npm exec -- altitude explain RULE-ID`);
+  }
+  if (!ok) process.exitCode = 1;
+}
 try {
-  if (command === "help" || command === "--help") console.log("altitude init --client codex|claude|all [--apply] [--remove]\naltitude patterns [intent] [--json]\naltitude explain RULE-ID [--json]\naltitude doctor [--json]\nAll commands resolve the installed package from --cwd PATH (default current directory).");
+  if (command === "help" || command === "--help") console.log("altitude init --client codex|claude|all [--apply] [--remove]\naltitude patterns [intent] [--json]\naltitude explain RULE-ID [--json]\naltitude doctor [--json]\naltitude check [dir] [--json]\nAll commands resolve the installed package from --cwd PATH (default current directory).");
   else {
     const context = installed();
     if (command === "init") init(context);
     else if (command === "doctor") doctor(context);
+    else if (command === "check") check(context);
     else if (command === "patterns") {
       const words = args.filter((v, i) => !v.startsWith("--") && args[i - 1] !== "--cwd").join(" ").toLowerCase().split(/\W+/).filter(Boolean);
       const patterns = context.index.patterns.map((p) => ({ ...p, score: words.reduce((n, w) => n + (p.intents.some((i) => i === w || i.startsWith(w)) ? 1 : 0), 0) })).filter((p) => !words.length || p.score).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
@@ -123,7 +223,7 @@ try {
   ${resolve(context.guidance, p.document)}`).join("\n") : "No pattern matched. Run altitude patterns to browse the catalog.");
     } else if (command === "explain") {
       const id = args[0];
-      const rule = JSON.parse(readFileSync(resolve(context.guidance, "rules.json"), "utf8")).rules.find((r) => r.id === id);
+      const rule = JSON.parse(readFileSync2(resolve(context.guidance, "rules.json"), "utf8")).rules.find((r) => r.id === id);
       if (!rule) throw new Error(`Unknown rule: ${id}`);
       emit({ version: context.pkg.version, ...rule });
     } else throw new Error(`Unknown command: ${command}`);

package/dist/guidance/README.md

@@ -2,6 +2,8 @@
 
 Start from the person's task. Read only the relevant pattern below, its linked rules, and the public declarations. The installed copy matches the package version; `altitude doctor --json` checks that connection. Guidance supports judgment; it does not certify an application.
 
+Every screen also follows the visual rules. Read the [design guide](visual/README.md) before composing one, [Elevation](visual/Elevation.md) for what height means, [Charts](visual/Charts.md) before drawing any chart, stat or meter, and [Motion](visual/Motion.md) before animating. Each component has its own guide (what it's for, how it uses height, what you provide); read it before using the component: for example [Button](components/Button/README.md) or [Select](components/Select/README.md). The `components` list in `index.json` has every component with its group, a one-line summary and its guide.
+
 Composing a new screen? Choose its frame from the task with [screen layout](patterns/screen-layout.md) first: name the task, the one thing that leads and the one primary action. The [app skeleton](app-skeleton.md) is one of its frames, for working through many similar records: shell, page header, a filtered and paged table, a record in a sheet, and settings, composed correctly.
 
 | Intent | Focused contract |
@@ -29,4 +31,6 @@ Use `altitude patterns "edit settings" --json` to discover contracts and `altitu
 
 Compose existing primitives and small workflow hooks from the main `altitude-design` export inside one `AltitudeProvider`. Import a package stylesheet. The application supplies routes, business validation and services. Verify delayed operations, rejection, retry, cancellation and stale responses where applicable; include keyboard and manual assistive-technology review. Automated checks cannot establish complete accessibility or task suitability.
 
+After changing UI, run `npm exec -- altitude check` (or `altitude check src --json`). It reports Altitude's rules that are certain from source text as errors (hard-coded colours instead of tokens, a missing stylesheet or `AltitudeProvider`, pie and donut charts, buttons labelled OK or Submit) and likely problems for review (several primary buttons in one file, elevation overrides on controls). Fix the errors; decide on the reviews. Each finding names a rule `altitude explain` describes. It doesn't check anything that needs the page rendered or a person.
+
 For explicit agent setup, preview `npm exec -- altitude init --client codex` (or `claude`), then use `--apply`. Full setup and removal instructions are shipped as `agent-setup.md`, generated from the repository’s `docs/framework/AGENT-SETUP.md`. No installation hook writes project instructions.

package/dist/guidance/agent-setup.md

@@ -9,14 +9,15 @@ npm exec -- altitude init --client claude --apply
 npm exec -- altitude patterns "edit settings" --json
 npm exec -- altitude explain ALT-EDIT-001
 npm exec -- altitude doctor --json
+npm exec -- altitude check --json
 npm exec -- altitude init --client codex --remove
 npm exec -- altitude init --client codex --remove --apply
 ```
 
 `init` defaults to a preview, including the exact before/after text. `--apply` applies that preview. `--client all` targets both clients. Repeating setup makes no change. Removal removes only the managed block, restoring surrounding bytes; a file created by setup is removed only if nothing else remains. User-edited managed blocks, malformed markers and symlinks are rejected for manual reconciliation. Existing instructions outside the block are preserved. Run setup again after upgrading the installed package. Use `--cwd PATH` to target an explicit project directory. Resolution uses that directory's installed `altitude-design/package.json`, never the version fetched by a different CLI invocation.
 
-The Codex adapter writes a compact routing block to project `AGENTS.md` (or an existing nonempty `AGENTS.override.md`, which Codex gives precedence); the Claude Code adapter writes it to project `CLAUDE.md`. Neither assumes instruction files under `node_modules` are automatically discovered. The routing block points at version-matched local focused documents rather than importing the complete manual. Restart the agent session after setup. Confirm Codex reports the project instruction file and Claude Code's `/context` lists it under Memory files; then ask an ordinary product question and check that the relevant pattern is read. Instructions are context, not enforcement, and broader or more specific instructions may affect discovery.
+The Codex adapter writes a compact routing block to project `AGENTS.md` (or an existing nonempty `AGENTS.override.md`, which Codex gives precedence); the Claude Code adapter writes it to project `CLAUDE.md`. Neither assumes instruction files under `node_modules` are automatically discovered. The routing block points at version-matched local focused documents rather than importing the complete manual. Because it's read on every turn, it carries only what an agent can't work out for itself: a reminder to prefer the installed docs and declarations to its memory, the rules that hold on every screen, and a compact index of every component (by group, with the path pattern of each component's guide), read on demand. The `agent-setup` check keeps it under 8 KB and verifies that every path it names is installed. Restart the agent session after setup. Confirm Codex reports the project instruction file and Claude Code's `/context` lists it under Memory files; then ask an ordinary product question and check that the relevant pattern is read. Instructions are context, not enforcement, and broader or more specific instructions may affect discovery.
 
 Mechanisms verified against official documentation on 2026-10-23: [Codex AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) describes root-to-working-directory instruction discovery, override precedence and size limits; [Claude Code memory](https://code.claude.com/docs/en/memory) documents project `CLAUDE.md` loading and `/context` inspection. The adapter tests verify files and round trips, not successful behavior of every client release. Claude Code also documents AGENTS.md support; CLAUDE.md remains the explicit adapter target.
 
-`doctor` reports stable rule IDs, observed evidence, expected behavior, repairs and verification. It returns a failing exit code only for deterministic installation/setup defects; service integration and contextual obligations remain visibly unverified. It does not inspect an application's service behavior or certify accessibility. Guidance remains usable offline through `altitude-design/guidance`, `altitude-design/guidance/*`, and physical `node_modules/altitude-design/dist/guidance` files. Tooling stays outside browser imports.
+`doctor` reports stable rule IDs, observed evidence, expected behavior, repairs and verification. It returns a failing exit code only for deterministic installation/setup defects; service integration and contextual obligations remain visibly unverified. It does not inspect an application's service behavior or certify accessibility. `check [dir]` (default `src`, else the project) scans an application's own source for Altitude's rules that are certain from text: hard-coded colours instead of tokens (`ALT-TOKEN-001`), the stylesheet and `AltitudeProvider` (`ALT-SETUP-002`, `ALT-SETUP-003`), pie and donut charts (`ALT-CHART-001`) and buttons labelled OK or Submit (`ALT-COPY-001`). Those fail the run. Several primary buttons in one file (`ALT-PRIMARY-001`) and elevation overrides on controls (`ALT-VISUAL-004`) are listed for review and never fail. A finding a team keeps is marked `altitude-ignore: <ID> <reason>` on its line or the line above. It reads text only: nothing that needs the page rendered or a person is checked. Guidance remains usable offline through `altitude-design/guidance`, `altitude-design/guidance/*`, and physical `node_modules/altitude-design/dist/guidance` files. Tooling stays outside browser imports.

package/dist/guidance/components/AILabel/README.md

@@ -0,0 +1,25 @@
+# AILabel
+
+Says when content was generated or changed by AI, and explains how when asked: for trust, and under transparency rules such as the EU AI Act. Carbon for AI made its label the entry point to explainability; this follows that, without the gradient.
+
+**Elevation: a label is part of the record.** It's a flush `Badge` plate, a small static icon and a word: "AI", or **"Drafted with AI"** once a person has reviewed it.
+- **No gradient, no glow, no shimmer.** A glow is light from below, and the light never moves. A gradient rim is also easily mistaken for focus.
+- **It acts**, so it lifts one level when pointed at, like any plate that acts.
+- **The explanation** is a `Popover` at level 3, "About this content": the model, when it was generated (`RelativeTime`), confidence in words, who reviewed or edited it, and the sources it was based on.
+- **Provenance stays.** Accepting AI content doesn't remove its label; the plate changes to "Drafted with AI" and the explanation says who reviewed it.
+
+**Accessibility.** A button with `aria-haspopup="dialog"` opening a non-modal popover. Its name says what it marks ("Summary generated with AI. Show details", or "drafted with AI and reviewed"). Tab, Enter and Escape. Under forced colours the plate has a border, and the icon and word carry the meaning. Under `contrast="more"` the plate's border is `line-control`.
+
+**Props:** `subject` (what it marks, default "Content"); `model`; `generatedAt`; `sources` (`{ title, url? }[]`); `confidence`; `reviewedBy`; `editedBy`; `children` (anything else about how it was made).
+
+**You provide:** the provenance. Place the label beside what it marks, such as a heading or a field label.
+
+```tsx
+<h3>Summary <AILabel subject="Summary" model="Opus 5.5" generatedAt={summary.at}
+  sources={summary.sources} reviewedBy={summary.reviewer} confidence="Medium: two sources disagreed" /></h3>
+```
+
+- Do keep the label once a person accepts the content.
+- Do say confidence in words.
+- Don't decorate AI content with gradients, glows or shimmer.
+- Don't use the label as the only place AI involvement is disclosed when your rules require more.

package/dist/guidance/components/Accordion/README.md

@@ -0,0 +1,7 @@
+# Accordion
+
+Reveals sections one at a time. Closed items are **lids** lying flush on the page; opening one lifts its lid into a raised card and opens the **compartment** underneath, where the content sits.
+
+Closed rows sit on the ground divided by `line` hairlines. Hovering one raises a ghost of its lid (a faint raised tint with a hairline), so you can see what will open. Opening raises the item to level 2 (`surface-raised`, `elev-2`), opens a gap around it and hides the neighbouring dividers. Inside, the content sits in a compartment: an opening sunk into the lid (`surface-well`) with its back wall showing just below the rim, the same camera as an empty `Input`. The panel grows on `ease-glide`, the content emerges 60ms later, and the chevron turns on `ease-settle`. Closed panels are inert to keyboard and assistive tech.
+
+**You provide:** `items` (`value`, `title`, `content`), `type` (`single` closes the others; `multiple` doesn't), `defaultValue` as an array of open values.

package/dist/guidance/components/AgentFleet/README.md

@@ -0,0 +1,34 @@
+# AgentFleet
+
+Every agent working on one job, as a roster: grouped by what they need from you (needs you, working, done), each row saying the agent's state in words, what it's doing in one line, how long it has waited or run, where it is in its plan and what it has spent, with warnings for trouble that's coming (two agents changing one file, an agent making no progress). For supervising several agents at once; see [the research](https://github.com/richlaconte/altitude/blob/v0.4.0/docs/research/agent-orchestration/README.md).
+
+**Elevation: a record of agents, with live rows.**
+- **Rows** are the record: flush at rest, lifting one level when pointed at because selecting one opens it. The open agent is selected, as a table's row is: `accent-soft`, raised one level, `aria-current`.
+- **Working** isn't pending (nothing you sent is in flight), so it never hovers: a plate with a steady accent lamp says "Working". No spinner.
+- **Needs you** ("Needs approval", "Has a question", "Ready for review") is a caution plate with a lamp, and "waiting 6 min". It doesn't rise: a row can't lift into a card inside a list, and `AgentRequests` holds the raised card.
+- **Stalled** ("No progress for 7 min", "Retried the same step 3 times") is a caution plate and a clock mark, in the working group: a suspicion, not a request.
+- **Blocked** says on what ("Waiting on Billing API"); **queued** is a neutral plate. **Failed** is a critical plate and leads with the agents that need you, since nothing happens until someone retries or stops it.
+- **Done** is stamped: a check, the name in muted ink, "took 9 min". The done group folds away.
+- **A conflict** is a flush `caution-soft` strip under the row naming the file and the other agent: never colour alone.
+- **Agents an agent started** hang under it in a 1px `line-control` bracket, as `TraceParallel` draws subagents.
+
+**Accessibility.** A region named by `aria-label` ("Agents"). Each group is a list named with its count ("Needs you, 2"); a collapsible group's heading is a button with `aria-expanded`. Each row is a button whose name says everything in order: "Billing API, waiting 6 min, Wants to run the migration on staging, Needs approval, Step 3 of 4, spent $0.38". Up and Down move between rows across groups; Home and End go to the first and last. An agent that starts needing you (or fails) is announced politely once; starting, progress, stalling and finishing aren't.
+
+**Parts:** `AgentFleet` (`aria-label`, `now`, `summary`); `AgentFleetGroup` (`label`, `count`, `collapsible`, `defaultOpen`, `empty`); `AgentFleetItem` (`name`, `state`: `'queued' | 'working' | 'needs-input' | 'blocked' | 'stalled' | 'failed' | 'done' | 'stopped'`, `needs`: `'approval' | 'question' | 'review'`, `activity`, `since`, `startedAt`, `endedAt`, `step`, `blockedBy`, `conflict`, `stalledReason`, `cost`, `output`, `selected`, `onSelect`, `children`). Helpers: `groupAgents(agents, get)` sorts into needs you (longest wait first), working (stalled first) and finished (newest first); `summarizeFleet(states)` writes "2 need you · 3 working · 4 done"; `formatSpan(ms)` writes "6 min".
+
+**You provide:** the agents and their states, a one-line `activity` for each (the agent's last status, or a summary from a small model), when each entered its state, and what selecting does (open it beside the fleet). Detecting a stall or a conflict is yours too: pass `state="stalled"` when an agent has made no progress for a while or repeats a step, and `conflict` when two agents change the same file.
+
+```tsx
+const g = groupAgents(agents, (a) => a);
+const row = (a) => <AgentFleetItem key={a.id} {...a} selected={a.id === open} onSelect={() => setOpen(a.id)} />;
+<AgentFleet summary={summarizeFleet(agents.map((a) => a.state))}>
+  <AgentFleetGroup label="Needs you" empty="Nothing needs you.">{g.needsYou.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Working">{g.working.map(row)}</AgentFleetGroup>
+  <AgentFleetGroup label="Done" collapsible defaultOpen={false}>{g.finished.map(row)}</AgentFleetGroup>
+</AgentFleet>
+```
+
+- Do sort by need: the agent waiting longest on you goes first.
+- Do say every state in words; the lamp and mark only repeat it.
+- Don't show a spinner, a ticking counter or make a working row hover.
+- Don't lay agents out as a grid of equal cards: the one that needs you gets lost among the ones that don't.

package/dist/guidance/components/AgentLanes/README.md

@@ -0,0 +1,21 @@
+# AgentLanes
+
+Where each agent's time went, one lane per agent on a shared clock: working, waiting on you, waiting on another agent, failed. Its takeaway leads with how long agents have waited on you, the bottleneck a fleet of agents hides: once several run, the person is usually the slowest part.
+
+**Elevation: a chart, so nothing has height** (see [Charts](../../visual/Charts.md)).
+- **Stretches** are equal-height flat bars lying on each lane's ground line: working is `data-1`; waiting on you is `caution` hatched at 45°; waiting on another agent is a 1px dashed outline; failed is `critical`. A gap is time the agent wasn't running.
+- **Every fill is named** in the key, in words, and each bar's title says its agent, state and span.
+- **"Now"** is a 1px `line-control` rule at the end of the record; the axis says "31 min ago", "15 min ago", "Now".
+- **The selected lane** is its name in `accent-ink` and 650, with `aria-pressed`; lanes never lift.
+- **Forced colours**: working solid, waiting hatched, blocked dashed, failed cross-hatched with a thick border.
+
+**Accessibility.** A `figure` captioned by its takeaway. The lane names are buttons when `onSelect` is set; the bars and axis are hidden from assistive technology and a table gives the same data (agent; time working, waiting on you, waiting on another agent, failed).
+
+**Props:** `lanes` (`{ id, name, segments: { from, to?, state }[] }[]`; a segment without `to` runs to now), `start` (default the earliest segment), `now`, `takeaway` (default "Agents have waited on you for 15 min in all; the longest wait was Pricing page, 5 min."), `aria-label`, `selected`, `onSelect`. Time spent failed counts as waiting on you in the takeaway, since a failed agent waits for a retry.
+
+```tsx
+<AgentLanes start={job.startedAt} lanes={agents.map((a) => ({ id: a.id, name: a.name, segments: a.history }))} selected={open} onSelect={setOpen} />
+```
+
+- Do keep it below the roster: it explains the past, the roster and requests are for now.
+- Don't draw dependencies as arrows between lanes; say them on the waiting agent ("Waiting on Billing API").

package/dist/guidance/components/AgentRequests/README.md

@@ -0,0 +1,29 @@
+# AgentRequests
+
+Every decision your agents are waiting on, in one queue: approvals, questions, reviews and failures, oldest first, each answerable where it is. Beside an `AgentFleet`, it lets a person supervising several agents clear what's waiting in a row, without opening each agent.
+
+**Elevation: status that asks for action.**
+- **A request** is a raised card (level 1), because it asks for action; it arrives lifted and settles with the afterglow. It isn't pending: nothing has been dispatched until it's answered.
+- **Its kind** is a plate in words: "Needs approval", "Has a question", "Ready for review" (caution, with a lamp) or "Couldn't finish" (critical). Who's asking and "waiting 6 min" sit beside it.
+- **Its answers** are secondary and ghost buttons: the view keeps its one primary. Open is a ghost at the end.
+- **Nothing waiting** is said flush with a check ("Nothing needs you"): an all-clear is settled, not an opening.
+- **The count** beside the heading is the one part that floats, as any count that wants you does.
+
+**Accessibility.** A section named by its heading ("Needs you"). Requests are an ordered list, longest wait first; each is an `article` named by its ask and described by its kind, agent and wait. Open is named for the agent ("Open Billing API"). A request that arrives is announced politely once ("Billing API: Run the migration on staging?").
+
+**Parts:** `AgentRequests` (`title`, `now`, `empty`); `AgentRequest` (`agent`, `kind`: `'approval' | 'question' | 'review' | 'failed'`, `title`, `detail`, `since`, `actions`, `onOpen`).
+
+**You provide:** the requests (give each a stable `key`), what each answer does, and removing a request once it's answered. For a question with many options or your own answer, or an approval with scopes or edits, use Open and answer in the agent's own `Question` or `Confirmation`.
+
+```tsx
+<AgentRequests>
+  {waiting.map((r) => (
+    <AgentRequest key={r.id} agent={r.agent} kind={r.kind} since={r.since} title={r.title} detail={r.consequence} onOpen={() => open(r.agentId)}
+      actions={<><Button size="sm" variant="secondary" onClick={() => approve(r)}>Run migration</Button><Button size="sm" variant="ghost" onClick={() => reject(r)}>Don't run</Button></>} />
+  ))}
+</AgentRequests>
+```
+
+- Do say the consequence of an approval in `detail`.
+- Don't offer "approve all": answer each with its consequence in view.
+- Don't make an answer primary; the view's one primary stays where it is.

package/dist/guidance/components/Alert/README.md

@@ -0,0 +1,22 @@
+# Alert
+
+Tells the person something about the current context. An alert is **a sheet laid on the page**: it rests on the ground, you can see its paper edge and the contact shadow under it, and it never floats. When it asks the person to act it becomes a raised card.
+
+**Page banners.** `placement="page"` lays the alert edge to edge across the top of the app or page: "Your trial ends in 3 days", "Scheduled maintenance Sunday 02:00 UTC", "We're seeing delays in email delivery". It has no side rounding and no side edges, and its text wraps on narrow screens. The elevation rule is the same at page scope: one that informs is a flat sheet, and one that asks for action is raised. `sticky` keeps it at the top while the page scrolls. It sits in a `region` named by its title, so it can be found and skipped. `dismissLabel` gives the dismiss button words ("Remind me tomorrow"), and dismissing moves focus to the page's `main`. Several page banners go in `AlertStack placement="page"`, most severe first. Put a banner above `AppShell`, or at the top of the page.
+
+- `variant="flat"` (default): a thin sheet in the tone's `-soft` colour (neutral is `surface-raised`), with a tone-tinted hairline, a 1px paper edge and a contact shadow. It informs.
+- `variant="raised"`: a card at level 2 with the sheen of something you can act on, the icon in the tone colour. Use it when the alert has an `action` or blocks progress.
+- `onDismiss`: adds a dismiss button. Dismissing **lifts the sheet off the page**: it rises 8px as its shadow spreads, fades, and then the gap closes; `onDismiss` is called once it's gone.
+- `settle`: an afterglow when the alert first appears or changes.
+
+`critical` renders `role="alert"`; the others use `role="status"`.
+
+## AlertStack
+
+Several alerts as a **stack of sheets**, the same language as `Pile`. The first alert lies on top; up to two more peek out beneath it, each tinted by its own tone, so you can see what kind of news is waiting without reading it. A floating "+N more" sits on the stack's edge. Opening it fans the alerts out into a column, one after another; "Show less" tucks them back. Dismiss the top alert and it lifts off while the next one comes up from under it.
+
+**You provide:** for `Alert`, `tone`, `title`, optional body as children, optional `action` (a small Button), `variant`, `onDismiss`. For `AlertStack`, keyed `Alert` children in order of importance, and optionally `expanded`/`onExpandedChange`, `moreLabel`, `lessLabel`.
+
+- Keep it to a title and one sentence.
+- Generic action-completion messages belong in a Toast. When an action removes an item from a list (‘Brand guidelines.pdf archived’ with Undo), don't add an Alert below the list: show the result in the item's own slot with [RemovalReceipt](../RemovalReceipt/README.md), then hand Undo to a Toast. Keep a durable recovery destination such as Archived → Restore; a timed notification must not be the only recovery path. See [Actions in place](../../visual/ActionsInPlace.md).
+- An Alert still suits a failure or a changed record that can't be shown beside its item (it's outside the current view). Key it by its operation ID, and let its delayed `onDismiss` clear state only when that ID is still current. Dismissing an old Alert must not hide a newer action's feedback.

package/dist/guidance/components/AltitudeProvider/README.md

@@ -0,0 +1,48 @@
+# AltitudeProvider
+
+Sets the color scheme, accent and motion preference for everything inside it, and hosts the layers that rise above the page.
+
+Wrap the app once, near the root. It renders a themed root, a **stage** (your app, which recedes behind dialogs) and a **layer host** (where dialogs and toasts render, so they stay inside the theme but outside the receding stage).
+
+It also sets the high-contrast rendering: with `contrast="more"` (or the system's `prefers-contrast: more`), shadows become hard ink slabs whose thickness is the height.
+
+It runs the **approach** tracker too, which lets openings react to a pointer before it arrives: an empty field deepens to receive, and a bottom sheet's finger pull opens. Raised things (buttons, cards, piles, steps) never react before the pointer is on them and never follow it. It only follows a mouse or pen, never touch, and reduced motion turns every approach effect off. `approach={false}` turns it off for everything inside.
+
+**Your own scheme.** `scheme` also takes a custom scheme: `{ name, base, tokens }`, your colour and shadow tokens laid over a built-in scheme (`base`, which supplies anything you leave out and the light or dark handling). The provider scopes them to itself in a stylesheet, so they nest like the built-in schemes and still give way to high contrast. If the scheme breaks the invariants in [Theming](../../visual/Theming.md) (the surface ladder, contrast on every surface, the data palette's gates), it says which in a console warning; `checkScheme(el, { include: ['core', 'data'] })` runs the same test in your own tests. A plain string names your own `[data-theme="…"]` block instead.
+
+**You provide:** `scheme` (a built-in name, your own, a custom scheme, or nothing, to inherit `data-theme` from the page), optionally `accent` as a hex color, `motion`, `approach`, `loading="breath"` to try the experimental breathing imprints (see `Await`), and `recede={false}` if your layout can't tolerate a transform on the app root (for example a `position: fixed` header that must not scale).
+
+- Do nest a provider to theme a region differently: a `nightfall` sidebar in a `daylight` app.
+- Do pass your brand color as `accent`; legibility is derived for you, and the chart palette's first series and magnitude ramp follow it (the other series re-order so neighbours stay apart for colour-blind readers).
+- Do reach for a custom scheme only when the brand needs its own grounds and ink, and keep `checkScheme` passing in your tests.
+- Don't render `Dialog` or `Toaster` outside a provider unless you accept them portaling to `document.body` without the receding page.
+
+Modal ownership is coordinated privately per document. A nested themed Dialog keeps the nearest provider's portal host and blocks background branches throughout the document. Ancestors containing that portal are never transformed or made inert as a whole. Each provider's own `recede` setting remains independent. A stationary Dialog suppresses recession and blur on participating lower modal layers until it finishes closing.
+
+Isolation preserves application-owned inertness and restores the original inline scroll style after the last modal exits. Reopening during exit retains the same ownership; route/provider unmount releases it immediately. Applications do not need a competing inert wrapper. The legacy `useAltitude().pushLayer()` helper remains compatible as a visual recession vote with an idempotent release. It does not acquire modal isolation or focus ownership; use Dialog and modal Sheet for those behaviors. `useAltitude()` supplies the nearest portal `host`, and the ownership registry remains private.
+
+**Density.** `density` sets how large controls are. `'auto'` (default) uses the mouse sizes and steps up under a coarse pointer, so controls are big enough to hit with a finger; `'comfortable'` uses the larger sizes everywhere; `'compact'` keeps the mouse sizes on touch. Hit areas reach 44px under a coarse pointer either way. See [Theming](../../visual/Theming.md), "Density and target size".
+
+## App modes
+
+`mode` marks the whole app as being in a state people must never mistake for the normal app: Stripe-style **test mode**, a support agent **viewing as a customer**, a **read-only** workspace, a **preview** of unpublished content.
+
+```tsx
+<AltitudeProvider mode={{ tone: 'caution', label: 'Test mode', description: 'Payments are simulated.',
+  action: <Button size="sm" onClick={exit}>Leave test mode</Button> }}>
+```
+
+**Elevation: a word and a border.** The page is the ground, so height can't say "this whole ground is different". The mode is carried by the non-height cues instead (law 7 as the primary channel):
+- **A flush strip** at the top, on the tone's soft colour, naming the mode, with your way out. It can't be dismissed.
+- **A 2px frame around the viewport** in the mode's tone. It stays while scrolling, and above dialogs and sheets.
+- **A plate in every `Dialog` and `Sheet` header** naming the mode, so a refund confirmed in test mode says so.
+
+Nothing moves: a mode is there from load. Entering it is announced once, politely ("Test mode on"). The strip is a region named by the mode, first in the tab order. Under forced colours the frame is a 4px double `CanvasText` border. Under `contrast="more"` it's 3px. `ModeContext` gives your own floating parts the mode.
+
+- Do use a mode for anything that changes what actions do (simulated payments, acting as someone else).
+- Don't use a page banner for a mode; a banner can be dismissed and scrolls away.
+
+## One primary per view
+
+Law 1 says the primary action rests at level 2, one per view. With `devChecks` (on by default when `process.env.NODE_ENV` isn't `'production'`), a `Button variant="primary"` registers with the provider while it's mounted. When more than one *visible* primary sits in the same view, one grouped warning names them and law 1. The page is one view, and each `Dialog`, `Sheet` and `Popover` is its own. Wrap independent parts (cards on a dashboard, each with its own task) in `<PrimaryScope>` to make them views of their own. The check is a warning only, it's gone from production builds, and the rule is `ALT-VISUAL-002` (`altitude explain ALT-VISUAL-002`). `PageHeader`'s `primary` slot is where a page's one primary belongs.
+

package/dist/guidance/components/AppShell/README.md

@@ -0,0 +1,51 @@
+# AppShell and Sidebar
+
+The frame of an app: a sidebar of destinations (grouped, collapsible), a top bar with search and the user's menu, and the page.
+
+**Elevation: the frame lies on the ground.** Where you are is part of the record, so the sidebar, top bar and page are all `surface-ground`, divided by `line`. Don't float the sidebar as a raised card. Only the things in it that act are live:
+- **A destination** lifts one level when pointed at, because it navigates.
+- **The current one** sits on a raised pill (segmented `Tabs`' build) that glides from destination to destination as you move.
+- **Only a count floats** (`Badge variant="count"`). A status ("Beta") would be a flush plate.
+- **Collapsing to a rail** changes width on `ease-glide`, not level. In the rail, each destination is an icon with its name in a tooltip to the right.
+- **The top bar** rises one level while content passes under it, as `ScrollArea`'s header does.
+- **On narrow screens** (below `mobileBreakpoint`, default 640px, the compact breakpoint) the sidebar moves into a `Sheet` drawer from the left (level 4), titled "Navigation". Choosing a destination closes it.
+
+**Parts** (shadcn/ui's names):
+- `AppShell`: `sidebar`, `topBar` and the page. It includes a `SidebarProvider`, a skip link, and a `SidebarTrigger` at the start of the top bar.
+- `SidebarProvider`: `collapsed`, `defaultCollapsed`, `onCollapsedChange`, `mobileBreakpoint`. ⌘B or Ctrl+B toggles. `useSidebar()` reads and changes the state.
+- `Sidebar`: a `nav` (`aria-label`, default "Main") with `collapsible` (`'icon' | 'none'`). Inside it go `SidebarHeader`, `SidebarContent` (scrolls, and holds the pill), `SidebarFooter`.
+- `SidebarGroup`: `label`; `collapsible` makes the label a disclosure button. Also `SidebarGroupLabel`.
+- `SidebarMenu` › `SidebarMenuItem` › `SidebarMenuButton` (`href`, `current`, `icon`, `asChild` for a router's link) and `SidebarMenuBadge` (`label`, such as "4 unread").
+- `SidebarTrigger`, and `SidebarInset` (the `main` landmark; it sets `--alt-page-pad` for `PageHeader`).
+
+**Open questions, answered.** Persisting the collapsed state is up to your app (use `collapsed` and `onCollapsedChange` with a cookie or `localStorage`). The workspace switcher is a recipe, a `DropdownMenu` whose trigger is an `Avatar` and a name, not a part (see the preview).
+
+**Accessibility.** [Landmarks](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/): `nav` with a label, `header`, `main`. A skip link ("Skip to content") comes first. The current destination has `aria-current="page"`. **A count is part of the destination's name** ("Inbox, 4 unread"). In the rail, each destination keeps its name as `aria-label` and in a tooltip. Collapsible groups use the disclosure pattern. `SidebarTrigger` says what it will do ("Collapse sidebar", "Open navigation") and carries `aria-keyshortcuts`. Under forced colours the pill gets a 1px border. Under `contrast="more"` it gets a 2px slab and the dividers are `line-control`. Under reduced motion the pill appears in place and the rail changes width at once.
+
+```tsx
+<AppShell
+  sidebar={
+    <Sidebar>
+      <SidebarHeader><WorkspaceMenu /></SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup label="Workspace">
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton href="/inbox" current icon={<Inbox />}>Inbox</SidebarMenuButton>
+              <SidebarMenuBadge label="4 unread">4</SidebarMenuBadge>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarFooter><UserMenu /></SidebarFooter>
+    </Sidebar>
+  }
+  topBar={<SearchEntry />}>
+  {page}
+</AppShell>
+```
+
+- Do give every destination an icon if the sidebar can collapse to a rail.
+- Do say what a count counts (`label="4 unread"`).
+- Don't raise the sidebar into a card or give it a shadow.
+- Don't put actions in the sidebar's destinations; they navigate.

package/dist/guidance/components/AreaChart/README.md

@@ -0,0 +1,43 @@
+# AreaChart
+
+A total over time and the parts that make it up (requests by region, storage by type), or a single volume over time. Stacked areas answer "how big, and from where"; `stack="expand"` answers "what share". It renders inside a [`ChartContainer`](../ChartContainer/README.md).
+
+**Why it's flat.** Bands are the record. Each is a flat `data-*` fill, stacked on the ground line in config order from the bottom, and parted from the band above by a 2px line in the plot's own colour, the same gap a stacked bar's segments have. The topmost band carries a 2px top line in its colour. A single area is a flat `data-1` fill at reduced opacity under a 2px `data-1` line.
+
+**No gradient fill.** Most libraries fade an area to transparent by default. Altitude's only face gradient is `--alt-sheen`, and it means "press it" (E4), so an area never has one.
+
+**Stack order never changes.** Bands stack in config order, so a band never jumps to a new position when values change, and its colour stays its own. In a stack a missing value adds nothing (the bands above rest on the one below); in a single area it's a gap, as in a line.
+
+**Named in place.** Stacked bands are labelled inside themselves in `ink`, on a halo of the plot's colour, at their thickest point, where they're at least 20px tall; thin bands rely on the legend and the readout. `labels={false}` turns this off.
+
+**Without colour.** Under forced colours and in print, and with `patterns` on the container, each band takes its slot's hatch (the first band is solid). With `contrast="more"` the separators are 3px `ink`.
+
+**Motion.** As `LineChart`: when the x values are the same, bands glide to their new values on `ease-glide`, after any rescale; when they differ, the old chart and the new one cross-fade. Nothing grows from the ground on first render ([Motion](../../visual/Motion.md), "Charts"). While data loads, the imprint is an area pressed into the page.
+
+**Accessibility.** The keyboard path is the container's (#63): ←/→ along x and, in a stack, ↑/↓ through the bands at that x, from the bottom up, so ↑ goes to the band above. Each point names its band's value and its share of the total: "Oct 1, 2026, EU, 1.1K. 34% of 3.2K. 1 of 14." The table view (`views`) has a column per band and a Total.
+
+**Not yet the record.** `status` marks partial or projected records. From the last settled point on, every band is hatched in its colour on the plot's own, with no solid fill, and the top line is dashed. A 1px `line-control` rule named "Today" (`boundary`) marks where the record ends, and the readout, point names and table say "Projected" or "So far". While patterns are on, a band with its own hatch keeps it there, faded, so bands stay told apart.
+
+**Selecting and drilling.** `selected` and `onSelect` make the marks a selection that cross-filters the rest of a dashboard, and `drill` opens a level down inside a `Drilldown`. Hover only promises what a click does. See [ChartContainer](../ChartContainer/README.md), "Marks you can select or drill into".
+
+**Filtering in place.** `relevance` recedes the bands to 35% around each missing record, so the stack keeps its shape; `rescale` fits the axis to the matches. See [ChartContainer](../ChartContainer/README.md), "Filtering in place".
+
+**A sliding window.** `window` works as `LineChart`'s: the latest stretch of x, gliding one step in a `live` container, or a chosen `{ start, end }`, which a `ChartBrush` sets (`onWindowChange`).
+
+**Props:** `data` and `x`; `window` and `onWindowChange`; `stack` (`true` or `'expand'`); `curve` (`'linear'` or `'monotone'`); `y={{ format }}`; `labels`; `tooltip`; `status` and `boundary`; and a `ChartTooltip` or `ChartLegend` as children.
+
+**Focus.** `focus={['team']}` keeps those bands' colours and draws the rest in `data-context`, their labels in `ink-muted`. The stack's order doesn't change. See [ChartContainer](../ChartContainer/README.md), "Focus".
+
+**You provide:** a `ChartContainer` whose `config` names each band in stacking order (the base first), the `data` in x order, and usually a `summary`.
+
+```tsx
+<ChartContainer config={{ us: { label: 'US' }, eu: { label: 'EU' }, apac: { label: 'APAC' } }}>
+  <AreaChart data={requests} x="day" stack />          {/* stack="expand" for 100% */}
+</ChartContainer>
+```
+
+- Do put the largest or steadiest part at the bottom, where it stands on the ground line and reads most accurately.
+- Do use `stack="expand"` only when the share is the point; the totals disappear.
+- Do keep to six bands or fewer; fold the rest into one "Other" series.
+- Don't overlay several unstacked areas; compare trends with a `LineChart`.
+- Don't add a gradient, a glow or a shadow to make it look richer.