diff --git a/.changeset/filtergroup-label-contrast.md b/.changeset/filtergroup-label-contrast.md
new file mode 100644
index 00000000..2610b2dc
--- /dev/null
+++ b/.changeset/filtergroup-label-contrast.md
@@ -0,0 +1,5 @@
+---
+"@codeatlasdev/ui": patch
+---
+
+`FilterGroup` draws its label with `--ca-text-secondary` instead of `--ca-text-hint`. The hint role can be set low by a custom preset, and the label failed the 4.5:1 axe check on a raised surface in dark mode.
diff --git a/.changeset/kpicard-on-card.md b/.changeset/kpicard-on-card.md
new file mode 100644
index 00000000..40665fdb
--- /dev/null
+++ b/.changeset/kpicard-on-card.md
@@ -0,0 +1,5 @@
+---
+"@codeatlasdev/ui": patch
+---
+
+`KpiCard` is built on `Card` instead of the deprecated `GlassCard`, so rendering it no longer logs the `[ca-ui]` deprecation warning in dev. The look is unchanged (elevation 3).
diff --git a/.gitignore b/.gitignore
index 59b8e9e8..400f9c42 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,3 +40,6 @@ site/src/generated/
 
 # wrangler local state
 .wrangler/
+
+# docs sample type-check output
+/site/.cache/
diff --git a/biome.json b/biome.json
index 1220d8e2..e0b222bd 100644
--- a/biome.json
+++ b/biome.json
@@ -37,6 +37,7 @@
 			"!**/.turbo",
 			"!**/.svelte-kit",
 			"!**/.astro",
+			"!**/.cache",
 			"!**/__screenshots__",
 			"!**/.vitest",
 			"!**/test-results",
diff --git a/packages/ui/scripts/check-docs-samples.ts b/packages/ui/scripts/check-docs-samples.ts
new file mode 100644
index 00000000..6b27bd70
--- /dev/null
+++ b/packages/ui/scripts/check-docs-samples.ts
@@ -0,0 +1,184 @@
+/**
+ * Type-checks the `svelte` code fences of the docs site with svelte-check, against the built package
+ * types (`dist`), exactly as a consumer app would compile them.
+ *
+ * A fence is checked when it imports from `@codeatlasdev/ui*`: those are the ones that claim API
+ * usage. Docs samples are often fragments, so the extractor makes them compilable without hiding
+ * real mistakes:
+ *  - `…` and `/* … *\/` placeholders are removed;
+ *  - names the sample uses but never declares (`users`, `save`, `page`, a `bind:` target) become
+ *    ambient `any` declarations: a docs sample may assume app state;
+ *  - a bare markup fence (no `<script>`) gets an import-free wrapper only when it names no package
+ *    component, so it is skipped.
+ * Unknown components and exports, props a component does not declare, wrong prop types, unclosed
+ * blocks and TypeScript syntax in a non-`lang="ts"` script all fail.
+ *
+ *   bun scripts/check-docs-samples.ts
+ */
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const DOCS = join(REPO, "site/src/content/docs");
+const OUT = join(REPO, "site/.cache/docs-samples");
+const SVELTE_CHECK = join(REPO, "packages/ui/node_modules/.bin/svelte-check");
+
+export interface Sample {
+	/** Docs page, relative to the docs root. */
+	page: string;
+	/** 0-based position among the page's checked fences. */
+	index: number;
+	/** 1-based line of the opening fence in the MDX file. */
+	line: number;
+	file: string;
+}
+
+const walk = (dir: string): string[] =>
+	readdirSync(dir).flatMap((f) => {
+		const p = join(dir, f);
+		return statSync(p).isDirectory() ? walk(p) : p.endsWith(".mdx") ? [p] : [];
+	});
+
+/** Free identifiers the sample reads but does not declare, found cheaply from the markup and script. */
+function ambientNames(code: string): string[] {
+	const declared = new Set<string>();
+	for (const m of code.matchAll(
+		/\b(?:const|let|var|function|class|import|type|interface)\s+(?:\{([^}]*)\}|(\w+))/g
+	)) {
+		for (const n of (m[1] ?? m[2] ?? "").split(",")) {
+			const name = n
+				.trim()
+				.split(/\s+as\s+/)
+				.pop()
+				?.replace(/^type\s+/, "");
+			if (name) declared.add(name);
+		}
+	}
+	for (const m of code.matchAll(/\{#snippet\s+(\w+)/g)) declared.add(m[1]);
+	const used = new Set<string>();
+	// `bind:value={x}`, `onclick={x}`, `{x}`, `{@render x()}`, `data={x}`
+	for (const m of code.matchAll(
+		/(?:bind:\w+|\bon\w+|\b[a-z][\w-]*)=\{\s*([A-Za-z_$][\w$]*)\s*[}(.[]/g
+	))
+		used.add(m[1]);
+	for (const m of code.matchAll(/(?<![\w$.])\{\s*([A-Za-z_$][\w$]*)\s*\}/g)) used.add(m[1]);
+	for (const m of code.matchAll(/\bbind:(\w+)(?![=\w])/g)) used.add(m[1]);
+	for (const m of code.matchAll(/<[A-Z]\w*\b[^>]*?\{(?:\.\.\.)?\s*([A-Za-z_$][\w$]*)\s*\}/g))
+		used.add(m[1]);
+	const skip = new Set(["children", "true", "false", "null", "undefined", "$props", "$state"]);
+	return [...used].filter((n) => !declared.has(n) && !skip.has(n) && !n.startsWith("$"));
+}
+
+/** Turns a docs fence into a compilable component, or `null` when it is not a checkable sample. */
+export function normalize(raw: string): string | null {
+	if (!/from\s+["']@codeatlasdev\/ui/.test(raw)) return null;
+	let code = raw
+		.replace(/\/\*\s*…\s*\*\//g, "")
+		.replace(/<!--[\s\S]*?-->/g, "")
+		.replace(/…/g, "");
+	// A fence that mixes several top-level scripts shows separate files; check only the first part.
+	const scripts = [...code.matchAll(/<script\b[^>]*>[\s\S]*?<\/script>/g)];
+	if (scripts.length > 1) {
+		const second = scripts[1].index ?? code.length;
+		code = code.slice(0, second);
+	}
+	// Placeholders for app state the sample assumes. `$state()` makes them valid `bind:` targets. In a
+	// `lang="ts"` script they are typed `any` so they fit any prop; a plain script gets no annotation,
+	// so TypeScript syntax written in it is still reported.
+	const names = ambientNames(code);
+	const tag = code.match(/<script\b[^>]*>/);
+	const isTs = !tag || /\blang=["']ts["']/.test(tag[0]);
+	const decl = names.map((n) => `let ${n}${isTs ? ": any" : ""} = $state();`).join("\n");
+	if (!tag) return `<script lang="ts">\n${decl}\n</script>\n${code}`;
+	return decl ? code.replace(tag[0], `${tag[0]}\n${decl}`) : code;
+}
+
+export function extractSamples(): Sample[] {
+	rmSync(OUT, { recursive: true, force: true });
+	mkdirSync(OUT, { recursive: true });
+	const samples: Sample[] = [];
+	for (const mdx of walk(DOCS)) {
+		const src = readFileSync(mdx, "utf8");
+		const page = relative(DOCS, mdx);
+		let index = 0;
+		for (const m of src.matchAll(/^([ \t]*)```svelte[^\n]*\n([\s\S]*?)^[ \t]*```/gm)) {
+			const indent = m[1].length;
+			const body = m[2]
+				.split("\n")
+				.map((l) => l.slice(Math.min(indent, l.length - l.trimStart().length)))
+				.join("\n");
+			const code = normalize(body);
+			if (code === null) continue;
+			const line = src.slice(0, m.index).split("\n").length;
+			const file = `${page.replace(/\.mdx$/, "").replace(/[/.]/g, "_")}_${index}.svelte`;
+			writeFileSync(join(OUT, file), code);
+			samples.push({ page, index: index++, line, file });
+		}
+	}
+	writeFileSync(
+		join(OUT, "tsconfig.json"),
+		JSON.stringify({ extends: "../../tsconfig.json", include: ["./*.svelte"] })
+	);
+	return samples;
+}
+
+export interface SampleError {
+	page: string;
+	line: number;
+	message: string;
+}
+
+/** Runs svelte-check over the extracted samples; returns one entry per error, mapped back to its docs page. */
+export async function checkDocsSamples(
+	extra: Record<string, string> = {}
+): Promise<{ checked: number; errors: SampleError[] }> {
+	const samples = extractSamples();
+	// Extra fences (tests feed known-bad ones to prove the check can fail), reported under their own name.
+	for (const [name, body] of Object.entries(extra)) {
+		const code = normalize(body);
+		if (code === null) continue;
+		const file = `extra_${name}.svelte`;
+		writeFileSync(join(OUT, file), code);
+		samples.push({ page: name, index: 0, line: 0, file });
+	}
+	const proc = Bun.spawn(
+		[
+			SVELTE_CHECK,
+			"--tsconfig",
+			join(OUT, "tsconfig.json"),
+			"--workspace",
+			OUT,
+			"--output",
+			"machine",
+		],
+		{ cwd: join(REPO, "site"), stdout: "pipe", stderr: "pipe" }
+	);
+	const [out, err] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+	]);
+	await proc.exited;
+	if (!/COMPLETED/.test(out)) throw new Error(`svelte-check did not complete:\n${out}${err}`);
+	const byFile = new Map(samples.map((s) => [s.file, s]));
+	const errors: SampleError[] = [];
+	for (const m of out.matchAll(/^\d+ ERROR "([^"]+)" (\d+):\d+ "((?:[^"\\]|\\.)*)"/gm)) {
+		const sample = byFile.get(m[1]);
+		errors.push({
+			page: sample?.page ?? m[1],
+			line: (sample?.line ?? 0) + Number(m[2]),
+			message: (JSON.parse(`"${m[3]}"`) as string)
+				.replace(/\n/g, " ")
+				.split("https://svelte.dev")[0]
+				.trim(),
+		});
+	}
+	return { checked: samples.length, errors };
+}
+
+if (import.meta.main) {
+	const { checked, errors } = await checkDocsSamples();
+	for (const e of errors) console.log(`${e.page}:${e.line}  ${e.message}`);
+	console.log(`${checked} samples checked, ${errors.length} errors`);
+	process.exit(errors.length ? 1 : 0);
+}
diff --git a/packages/ui/src/lib/components/FilterGroup/FilterGroup.svelte b/packages/ui/src/lib/components/FilterGroup/FilterGroup.svelte
index 82875ab9..dd643560 100644
--- a/packages/ui/src/lib/components/FilterGroup/FilterGroup.svelte
+++ b/packages/ui/src/lib/components/FilterGroup/FilterGroup.svelte
@@ -74,7 +74,7 @@
     .ca-filter-group__label {
       font-size: var(--ca-font-size-micro);
       font-weight: var(--ca-font-weight-semibold);
-      color: var(--ca-text-hint);
+      color: var(--ca-text-secondary);
       text-transform: uppercase;
       letter-spacing: var(--ca-overline-tracking);
       padding: 0 var(--ca-space-1-5) 0 var(--ca-space-1);
diff --git a/packages/ui/src/lib/components/KpiCard/KpiCard.svelte b/packages/ui/src/lib/components/KpiCard/KpiCard.svelte
index 72a793c6..370b38cb 100644
--- a/packages/ui/src/lib/components/KpiCard/KpiCard.svelte
+++ b/packages/ui/src/lib/components/KpiCard/KpiCard.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
   import { useT } from '../../i18n/state.svelte.js';
   import type { IconComponent } from '../../types.js';
-  import GlassCard from '../GlassCard/GlassCard.svelte';
+  import Card from '../Card/Card.svelte';
   const t = useT();
 
   interface Props {
@@ -23,7 +23,7 @@
   );
 </script>
 
-<GlassCard class="ca-kpi {className}">
+<Card elevation={3} class="ca-kpi {className}">
   <div class="ca-kpi__inner">
     <div class="ca-kpi__top">
       <p class="ca-kpi__title">{title}</p>
@@ -50,7 +50,7 @@
       </span>
     {/if}
   </div>
-</GlassCard>
+</Card>
 
 <style>
 @layer ca.reset, ca.tokens, ca.themes, ca.base, ca.materials, ca.utilities, ca.components;
diff --git a/packages/ui/src/lib/components/KpiCard/KpiCard.svelte.test.ts b/packages/ui/src/lib/components/KpiCard/KpiCard.svelte.test.ts
index a29f4467..9cfe294e 100644
--- a/packages/ui/src/lib/components/KpiCard/KpiCard.svelte.test.ts
+++ b/packages/ui/src/lib/components/KpiCard/KpiCard.svelte.test.ts
@@ -1,5 +1,5 @@
 import { TrendingUp } from "@lucide/svelte";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { render } from "vitest-browser-svelte";
 import { checkA11y } from "../../../../tests/a11y";
 import { q } from "../../../../tests/dom";
@@ -64,4 +64,18 @@ describe("KpiCard", () => {
 		expect(icon.querySelector("svg")).not.toBeNull();
 		expect(await checkA11y(screen.container)).toHaveNoViolations();
 	});
+
+	it("is built on Card, so it never triggers a deprecation warning", async () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		try {
+			const screen = await render(KpiCard, { title: "Revenue", value: 1 });
+			expect(screen.container.querySelector(".ca-glass-card")).toBeNull();
+			expect(screen.container.querySelector(".ca-card.ca-kpi")).not.toBeNull();
+			expect(
+				warn.mock.calls.map((c) => String(c[0])).filter((m) => m.includes("deprecated"))
+			).toEqual([]);
+		} finally {
+			warn.mockRestore();
+		}
+	});
 });
diff --git a/packages/ui/src/lib/components/Sheet/Sheet.svelte b/packages/ui/src/lib/components/Sheet/Sheet.svelte
index 5e9a8b9e..1841fc25 100644
--- a/packages/ui/src/lib/components/Sheet/Sheet.svelte
+++ b/packages/ui/src/lib/components/Sheet/Sheet.svelte
@@ -12,7 +12,7 @@
 	/**
 	 * Sheet: mobile-first bottom sheet.
 	 *
-	 * Below 768px it slides up from the bottom edge (drag handle, safe-area padding, rounded top);
+	 * Below 900px it slides up from the bottom edge (drag handle, safe-area padding, rounded top);
 	 * from 900px up it renders as a centered dialog. A native modal <dialog> supplies the top layer, inert
 	 * page, focus restore, Escape, backdrop dismissal and scroll lock. Motion is off under reduced-motion.
 	 *
diff --git a/packages/ui/tests/contrast.test.ts b/packages/ui/tests/contrast.test.ts
index ceaac1e0..29bdaefa 100644
--- a/packages/ui/tests/contrast.test.ts
+++ b/packages/ui/tests/contrast.test.ts
@@ -331,3 +331,29 @@ describe("--ca-state-indicator: selected markers (#24)", () => {
 		}
 	});
 });
+
+// FilterGroup draws its caption on a `--ca-action-hover` pill that sits on any surface. The caption
+// is readable content, and `--ca-text-hint` is the role for placeholders and disabled-adjacent hints
+// that an app may set low (a custom preset gave it 4.1:1 on the raised surface and failed axe), so the
+// caption must use the role that holds AA in every preset: `--ca-text-secondary`.
+describe("FilterGroup label on its pill", () => {
+	const css = readFileSync(new URL("components/FilterGroup/FilterGroup.svelte", LIB), "utf8");
+	const token = css.match(/\.ca-filter-group__label\s*\{[^}]*?color:\s*var\((--ca-[\w-]+)\)/)?.[1];
+
+	it("is drawn with a text role that is not the hint role", () => {
+		expect(token).toBe("--ca-text-secondary");
+	});
+
+	for (const src of sources)
+		for (const scheme of ["light", "dark"] as const)
+			it(`${src.id} ${scheme}: its role is >= 4.5:1 on the pill over every surface`, () => {
+				const t = resolved(src, scheme);
+				const fill = resolve(t, "--ca-action-hover");
+				for (const s of SURFACES) {
+					const pill = over(fill, surfaceRgb(t, s));
+					expect(ratio(over(resolve(t, token as string), pill), pill), s).toBeGreaterThanOrEqual(
+						4.5
+					);
+				}
+			});
+});
diff --git a/packages/ui/tests/docs-accuracy.test.ts b/packages/ui/tests/docs-accuracy.test.ts
new file mode 100644
index 00000000..bc45077e
--- /dev/null
+++ b/packages/ui/tests/docs-accuracy.test.ts
@@ -0,0 +1,394 @@
+/**
+ * Guards the docs site against drifting from the package. Everything is checked against the
+ * generated manifest (the same data the MCP server and API.md serve), never against a copy:
+ *
+ *  - every `<Props for="…">` row names a prop (or snippet) the component really has, and a
+ *    documented default equals the one in the source;
+ *  - every `@codeatlasdev/ui*` import in a code fence resolves to a real export of that entry;
+ *  - every capitalised component used in a `svelte` fence passes only props it declares;
+ *  - every exported component appears in the docs (a short allowlist of internals is explicit).
+ */
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import ts from "typescript";
+import { buildManifest, type ManifestComponent } from "../scripts/build-manifest.ts";
+
+const DOCS = join(import.meta.dir, "../../../site/src/content/docs");
+const manifest = buildManifest();
+const components = new Map(manifest.components.map((c) => [c.name, c]));
+
+const walk = (dir: string): string[] =>
+	readdirSync(dir).flatMap((f) => {
+		const p = join(dir, f);
+		return statSync(p).isDirectory() ? walk(p) : p.endsWith(".mdx") ? [p] : [];
+	});
+const pages = walk(DOCS).map((file) => ({
+	file,
+	rel: relative(DOCS, file),
+	src: readFileSync(file, "utf8"),
+}));
+
+// ── <Props> blocks ───────────────────────────────────────────────────────────
+
+interface PropsBlock {
+	page: string;
+	title: string;
+	/** Components the table describes: `for="A, B"`, else the component named by the title, else the page. */
+	targets: string[];
+	rows: { name: string; default?: string }[];
+}
+
+/** Native attributes a component forwards through `...rest`, which the manifest lists only as `extends`. */
+const INHERITED: Record<string, string[]> = { Image: ["srcset", "sizes"] };
+
+/** Props the document element carries for free; documenting them on a component page is fine. */
+const NATIVE = /^(aria-[a-z]+|data-[a-z-]+|id|class|style|role|tabindex|title|lang|dir|hidden)$/;
+
+function propsBlocks(): PropsBlock[] {
+	const out: PropsBlock[] = [];
+	for (const p of pages) {
+		for (const m of p.src.matchAll(/<Props\b([\s\S]*?)rows=\{\[([\s\S]*?)\]\}\s*\/>/g)) {
+			const attrs = m[1];
+			const title = attrs.match(/title="([^"]*)"/)?.[1] ?? "Props";
+			const forAttr = attrs.match(/for="([^"]*)"/)?.[1];
+			// A row may name several props at once ("p, px, py", "leading / trailing"): one entry per prop.
+			const rows = [...m[2].matchAll(/\{\s*name:\s*"((?:[^"\\]|\\.)*)"([^}]*)\}/g)].flatMap((r) => {
+				const dflt = r[2].match(/default:\s*"((?:[^"\\]|\\.)*)"/)?.[1]?.replace(/\\"/g, '"');
+				const names = r[1].split(/\s*[,/]\s*/).filter(Boolean);
+				return names.map((name) => ({ name, default: names.length === 1 ? dflt : undefined }));
+			});
+			const pageName = p.rel
+				.replace(/^.*\//, "")
+				.replace(/\.mdx$/, "")
+				.replace(/(^|-)(\w)/g, (_, __, c: string) => c.toUpperCase());
+			const titled = title
+				.replace(/\s+props$/i, "")
+				.replace(/\(.*$/, "")
+				.trim();
+			const targets = forAttr
+				? forAttr.split(",").map((s) => s.trim())
+				: components.has(titled)
+					? [titled]
+					: [pageName];
+			out.push({ page: p.rel, title, targets, rows });
+		}
+	}
+	return out;
+}
+
+const blocks = propsBlocks();
+
+/** Props a component owns plus the ones its `extends` clause adds from a known type (`Pick<LayoutProps, …>`, another component). */
+function owned(c: ManifestComponent, seen = new Set<string>()): Map<string, { default?: string }> {
+	const out = new Map<string, { default?: string }>(
+		[...c.props, ...c.snippets].map((prop) => [prop.name, prop])
+	);
+	for (const n of INHERITED[c.name] ?? []) out.set(n, {});
+	if (seen.has(c.name)) return out;
+	seen.add(c.name);
+	for (const m of c.extends?.matchAll(/Pick<LayoutProps,\s*([^>]+)>/g) ?? [])
+		for (const n of m[1].matchAll(/'(\w+)'/g)) out.set(n[1], {});
+	for (const m of c.extends?.matchAll(/ComponentProps<typeof (\w+)>/g) ?? []) {
+		const base = components.get(m[1]);
+		if (base) for (const [k, v] of owned(base, seen)) out.set(k, v);
+	}
+	return out;
+}
+
+describe("docs <Props> tables", () => {
+	it("finds the tables (the parser is not silently empty)", () => {
+		expect(blocks.length).toBeGreaterThan(40);
+	});
+
+	it("has rows that are valid JavaScript (an unescaped quote breaks the MDX build)", () => {
+		const bad: string[] = [];
+		for (const p of pages)
+			for (const m of p.src.matchAll(/<Props\b[\s\S]*?rows=\{(\[[\s\S]*?\])\}\s*\/>/g)) {
+				// The rows are plain object literals, so evaluating them is the strictest parse there is.
+				try {
+					new Function(`return ${m[1]};`)();
+				} catch (e) {
+					bad.push(`${p.rel}: ${(e as Error).message}`);
+				}
+			}
+		expect(bad).toEqual([]);
+	});
+
+	it('targets only exported components (use for="A, B" or for="none" when the title does not name one)', () => {
+		const bad: string[] = [];
+		for (const b of blocks)
+			for (const t of b.targets)
+				if (t !== "none" && !components.has(t)) bad.push(`${b.page} [${b.title}]: ${t}`);
+		expect(bad).toEqual([]);
+	});
+
+	it("documents only props the component has", () => {
+		const bad: string[] = [];
+		for (const b of blocks) {
+			const targets = b.targets.filter((t) => t !== "none");
+			if (!targets.length) continue;
+			const comps = targets
+				.map((t) => components.get(t))
+				.filter((c): c is ManifestComponent => !!c);
+			for (const row of b.rows) {
+				// "PhoneField.value" names the component it belongs to.
+				const [only, prop] = row.name.includes(".") ? row.name.split(".") : [undefined, row.name];
+				if (NATIVE.test(prop)) continue;
+				const scope = only ? comps.filter((c) => c.name === only) : comps;
+				if (!scope.some((c) => owned(c).has(prop)))
+					bad.push(`${b.page} [${b.title}] ${targets.join("/")}: ${row.name}`);
+			}
+		}
+		expect(bad).toEqual([]);
+	});
+
+	it("documents the default the source declares", () => {
+		const norm = (s: string) => s.replace(/\s+/g, "").replace(/"/g, "'");
+		const bad: string[] = [];
+		for (const b of blocks) {
+			const targets = b.targets.filter((t) => t !== "none");
+			if (targets.length !== 1) continue;
+			const c = components.get(targets[0]);
+			if (!c) continue;
+			for (const row of b.rows) {
+				const prop = owned(c).get(row.name);
+				if (!prop || row.default === undefined || prop.default === undefined) continue;
+				// Identifiers and function expressions (`DEFAULT_ZONES`, `(_item, i) => i`) cannot be compared as text.
+				if (
+					!/^(['"`].*['"`]|-?[\d.]+|true|false|null|undefined|\[.*\]|\{.*\})$/s.test(prop.default)
+				)
+					continue;
+				if (norm(row.default) !== norm(prop.default))
+					bad.push(`${b.page} ${c.name}.${row.name}: docs ${row.default}, source ${prop.default}`);
+			}
+		}
+		expect(bad).toEqual([]);
+	});
+});
+
+// ── code fences ──────────────────────────────────────────────────────────────
+
+interface Fence {
+	page: string;
+	lang: string;
+	code: string;
+}
+
+function fences(): Fence[] {
+	const out: Fence[] = [];
+	for (const p of pages)
+		for (const m of p.src.matchAll(/^[ \t]*```(\w+)[^\n]*\n([\s\S]*?)^[ \t]*```/gm))
+			out.push({ page: p.rel, lang: m[1], code: m[2] });
+	return out;
+}
+
+const allFences = fences();
+
+const LIB = join(import.meta.dir, "../src/lib");
+const ENTRY_FILES: Record<string, string> = {
+	"@codeatlasdev/ui": join(LIB, "index.ts"),
+	"@codeatlasdev/ui/charts": join(LIB, "charts/index.ts"),
+	"@codeatlasdev/ui/table": join(LIB, "components/DataTable/index.ts"),
+	"@codeatlasdev/ui/code": join(LIB, "components/CodeSnippet/index.ts"),
+	"@codeatlasdev/ui/forms": join(LIB, "forms/index.ts"),
+};
+
+/** Names each entry point really exports (components and every other runtime/type export). */
+function exportsByEntry(): Map<string, Set<string>> {
+	const by = new Map<string, Set<string>>();
+	const add = (entry: string, name: string) => {
+		if (!by.has(entry)) by.set(entry, new Set());
+		by.get(entry)?.add(name);
+	};
+	for (const c of manifest.components) add(c.import, c.name);
+	for (const e of manifest.exports) add(e.import, e.name);
+	// Names an entry re-exports from a dependency (`CalendarDate`): the manifest only follows own declarations.
+	for (const [entry, file] of Object.entries(ENTRY_FILES)) {
+		const sf = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.ESNext, true);
+		for (const st of sf.statements)
+			if (ts.isExportDeclaration(st) && st.exportClause && ts.isNamedExports(st.exportClause))
+				for (const el of st.exportClause.elements) add(entry, el.name.text);
+	}
+	return by;
+}
+const exportsOf = exportsByEntry();
+
+/** Entries whose exports are not in the manifest (assets, subpath files, bin). */
+const NON_API_ENTRY = /\/(styles|presets|testing|i18n|primitives)(\/|$)|\.css$|\.json$/;
+
+describe("docs code samples", () => {
+	it("finds the fences (the parser is not silently empty)", () => {
+		expect(allFences.length).toBeGreaterThan(100);
+	});
+
+	it("imports only names that the entry point exports", () => {
+		const bad: string[] = [];
+		for (const f of allFences) {
+			if (!["svelte", "ts", "js", "astro", "tsx", "mdx"].includes(f.lang)) continue;
+			for (const m of f.code.matchAll(
+				/import\s+(?:type\s+)?\{([^}]*)\}\s+from\s+["'](@codeatlasdev\/ui[^"']*)["']/g
+			)) {
+				m[1] = m[1].replace(/\/\/[^\n]*/g, "");
+				const entry = m[2];
+				if (NON_API_ENTRY.test(entry)) continue;
+				const known = exportsOf.get(entry);
+				if (!known) {
+					bad.push(`${f.page}: unknown entry ${entry}`);
+					continue;
+				}
+				for (const raw of m[1].split(",")) {
+					const name = raw
+						.trim()
+						.replace(/^type\s+/, "")
+						.split(/\s+as\s+/)[0]
+						.trim();
+					if (name && !known.has(name)) bad.push(`${f.page}: ${name} is not exported by ${entry}`);
+				}
+			}
+		}
+		expect(bad).toEqual([]);
+	});
+
+	it("passes only declared props to components in svelte samples", () => {
+		const bad: string[] = [];
+		for (const f of allFences) {
+			if (f.lang !== "svelte") continue;
+			// Attribute names of each `<Component …>` opening tag, brace-aware so `{…}` values with `>` do not end it.
+			for (const tag of f.code.matchAll(/<([A-Z][A-Za-z0-9]*)\b/g)) {
+				const c = components.get(tag[1]);
+				if (!c) continue;
+				const attrs = readAttributes(f.code, (tag.index ?? 0) + tag[0].length);
+				const known = owned(c);
+				for (const a of attrs) {
+					if (
+						NATIVE.test(a) ||
+						(/^(on[a-z]+|bind:.+|use:.+|class:.+|style:.+|transition:.+)$/.test(a) && c.extends)
+					)
+						continue;
+					const base = a.replace(/^bind:/, "");
+					if (!known.has(base) && !known.has(a)) bad.push(`${f.page}: <${c.name} ${a}>`);
+				}
+			}
+		}
+		expect(bad).toEqual([]);
+	});
+});
+
+/** Attribute names of the tag whose name just ended at `from`. Skips string and `{…}` values. */
+function readAttributes(src: string, from: number): string[] {
+	const names: string[] = [];
+	let i = from;
+	while (i < src.length) {
+		const ch = src[i];
+		if (ch === ">" || (ch === "/" && src[i + 1] === ">")) break;
+		if (/\s/.test(ch)) {
+			i++;
+			continue;
+		}
+		if (ch === "{") {
+			// `{...rest}` / `{shorthand}`: shorthand names a prop, spread does not.
+			const end = matching(src, i);
+			const inner = src.slice(i + 1, end).trim();
+			if (/^[A-Za-z_$][\w$]*$/.test(inner)) names.push(inner);
+			i = end + 1;
+			continue;
+		}
+		const m = src.slice(i).match(/^[A-Za-z_:@][\w:.\-@]*/);
+		if (!m) {
+			i++;
+			continue;
+		}
+		names.push(m[0]);
+		i += m[0].length;
+		if (src[i] === "=") {
+			i++;
+			if (src[i] === '"' || src[i] === "'") i = src.indexOf(src[i], i + 1) + 1;
+			else if (src[i] === "{") i = matching(src, i) + 1;
+		}
+	}
+	return names;
+}
+
+/** Index of the `}` that closes the `{` at `open`, skipping strings and template literals. */
+function matching(src: string, open: number): number {
+	let depth = 0;
+	for (let i = open; i < src.length; i++) {
+		const ch = src[i];
+		if (ch === '"' || ch === "'" || ch === "`") {
+			for (i++; i < src.length && src[i] !== ch; i++) if (src[i] === "\\") i++;
+		} else if (ch === "{") depth++;
+		else if (ch === "}" && --depth === 0) return i;
+	}
+	return src.length;
+}
+
+// ── coverage ─────────────────────────────────────────────────────────────────
+
+/** Exported components with no page of their own and no mention worth making (internals of a documented parent). */
+const UNDOCUMENTED_OK = new Set<string>([]);
+
+describe("docs coverage", () => {
+	it("mentions every exported component", () => {
+		const all = pages.map((p) => p.src).join("\n");
+		const missing = manifest.components
+			.map((c) => c.name)
+			.filter((n) => !UNDOCUMENTED_OK.has(n) && !new RegExp(`\\b${n}\\b`).test(all));
+		expect(missing).toEqual([]);
+	});
+
+	it("has no stale allowlist entries", () => {
+		const names = new Set(manifest.components.map((c) => c.name));
+		expect([...UNDOCUMENTED_OK].filter((n) => !names.has(n))).toEqual([]);
+	});
+});
+
+// ── internal links ───────────────────────────────────────────────────────────
+
+/** GitHub-style slug used by Astro for heading ids. */
+const slug = (h: string) =>
+	h
+		.toLowerCase()
+		.replace(/`/g, "")
+		.replace(/[^\p{L}\p{N}\s-]/gu, "")
+		.trim()
+		.replace(/\s+/g, "-");
+
+describe("docs links", () => {
+	const slugs = new Set(
+		pages.map((p) =>
+			`/docs/${p.rel.replace(/\.mdx$/, "").replace(/(^|\/)index$/, "")}/`.replace("//", "/")
+		)
+	);
+	slugs.add("/docs/");
+	const anchors = new Map(
+		pages.map((p) => {
+			const path = `/docs/${p.rel.replace(/\.mdx$/, "")}/`
+				.replace(/\/index\/$/, "/")
+				.replace("//", "/");
+			const body = p.src.replace(/^[ \t]*```[\s\S]*?^[ \t]*```/gm, "");
+			const heads = [...body.matchAll(/^#{2,4}\s+(.+)$/gm)].map((m) => slug(m[1]));
+			// <Demo title="…"> renders an <h2 id="slug">.
+			for (const d of body.matchAll(/<(?:Demo|Props)\b[^>]*?title="([^"]+)"/g))
+				heads.push(slug(d[1]));
+			return [path, new Set(heads)];
+		})
+	);
+
+	it("resolves every /docs/ link and #anchor in the prose", () => {
+		const bad: string[] = [];
+		for (const p of pages) {
+			const here = `/docs/${p.rel.replace(/\.mdx$/, "")}/`
+				.replace(/\/index\/$/, "/")
+				.replace("//", "/");
+			const prose = p.src.replace(/^[ \t]*```[\s\S]*?^[ \t]*```/gm, "");
+			for (const m of prose.matchAll(/\]\((\/docs\/[^)\s]*|#[^)\s]+)\)/g)) {
+				const [path, hash] = m[1].startsWith("#") ? [here, m[1].slice(1)] : m[1].split("#");
+				if (!anchors.has(path)) bad.push(`${p.rel}: ${m[1]} (no such page)`);
+				else if (hash && !anchors.get(path)?.has(hash))
+					bad.push(`${p.rel}: ${m[1]} (no such heading)`);
+			}
+		}
+		expect(bad).toEqual([]);
+	});
+});
diff --git a/packages/ui/tests/docs-samples.test.ts b/packages/ui/tests/docs-samples.test.ts
new file mode 100644
index 00000000..4e89b359
--- /dev/null
+++ b/packages/ui/tests/docs-samples.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "bun:test";
+import { checkDocsSamples, normalize } from "../scripts/check-docs-samples.ts";
+
+describe("docs code samples compile", () => {
+	it("type-checks every svelte fence that imports the package", async () => {
+		const { checked, errors } = await checkDocsSamples();
+		expect(checked).toBeGreaterThan(80);
+		expect(errors.map((e) => `${e.page}:${e.line} ${e.message}`)).toEqual([]);
+	}, 120_000);
+
+	it("fails on an unknown export and on a wrong prop value", async () => {
+		const bad =
+			'<script lang="ts">\n  import { Button, NopeComponent } from "@codeatlasdev/ui";\n</script>\n<Button variant="shiny">x</Button>\n<NopeComponent />';
+		const { errors } = await checkDocsSamples({ bad });
+		const mine = errors.filter((e) => e.page === "bad").map((e) => e.message);
+		expect(mine.join("\n")).toContain("no exported member 'NopeComponent'");
+		expect(mine.join("\n")).toContain("Type '\"shiny\"' is not assignable");
+	}, 120_000);
+
+	it("skips fences that do not import the package", () => {
+		expect(normalize("<table><tr><td>x</td></tr></table>")).toBeNull();
+	});
+
+	it("declares app state the fragment assumes, as bindable state", () => {
+		const out = normalize(
+			'<script>\n  import { Pagination } from "@codeatlasdev/ui";\n</script>\n<Pagination count={100} bind:page />'
+		);
+		expect(out).toContain("let page = $state();");
+	});
+
+	it("keeps a plain script plain, so TypeScript syntax in it is an error", () => {
+		const out = normalize(
+			'<script>\n  import { Button } from "@codeatlasdev/ui";\n</script>\n<Button onclick={save} />'
+		);
+		expect(out).toContain("let save = $state();");
+		expect(out).not.toContain(": any");
+	});
+});
diff --git a/site/src/content/docs/charts/bar.mdx b/site/src/content/docs/charts/bar.mdx
index ba8139b0..c471a5f4 100644
--- a/site/src/content/docs/charts/bar.mdx
+++ b/site/src/content/docs/charts/bar.mdx
@@ -30,7 +30,7 @@ Multiple series render grouped by default. Set `stacked` to stack them into one
 <Demo title="Stacked bars" src={StackedSrc}><Stacked client:visible /></Demo>
 <Demo title="Grouped and stacked" description="Toggling stacked animates between both layouts." src={ToggleSrc}><Toggle client:visible /></Demo>
 
-<Props rows={[
+<Props for="BarChart" rows={[
   { name: "series", type: "ChartSeries[]", description: "Named series sharing one category axis. Each is { name, data: number[], color? }." },
   { name: "categories", type: "string[]", description: "Category labels, one per bar group." },
   { name: "valueFormatter", type: "(value: number) => string", description: "Formats value-axis ticks and tooltip values." },
diff --git a/site/src/content/docs/charts/gauge.mdx b/site/src/content/docs/charts/gauge.mdx
index 0a1fff07..cc7a15a3 100644
--- a/site/src/content/docs/charts/gauge.mdx
+++ b/site/src/content/docs/charts/gauge.mdx
@@ -29,9 +29,9 @@ The default gauge colors its arc in three zones (error, warning, success). Overr
 <Demo title="Simple gauge" src={SimpleSrc}><Simple client:visible /></Demo>
 <Demo title="Progress ring" description="variant ring draws a single brand-colored arc with the value in the center." src={RingSrc}><Ring client:visible /></Demo>
 <Demo title="Custom zones" description="Reverse the default zones when a high value is bad, such as CPU load." src={ZonesSrc}><Zones client:visible /></Demo>
-<Demo title="Animated counter" description="Updating value animates the ring and the number." src={CounterSrc}><Counter client:visible /></Demo>
+<Demo title="Animated counter" description="Updating value animates the ring and counts the number." src={CounterSrc}><Counter client:visible /></Demo>
 
-<Props rows={[
+<Props for="GaugeChart" rows={[
   { name: "value", type: "number", description: "Current value." },
   { name: "min", type: "number", default: "0", description: "Lower bound of the scale." },
   { name: "max", type: "number", default: "100", description: "Upper bound of the scale." },
@@ -39,7 +39,7 @@ The default gauge colors its arc in three zones (error, warning, success). Overr
   { name: "zones", type: "GaugeZone[]", default: "error to 0.3, warning to 0.7, success to 1", description: "Colored arc zones as { until, color }. until is a fraction of min to max; color is success, warning, error, info, brand or any CSS color." },
   { name: "label", type: "string", description: "Caption shown above the value in the default variant." },
   { name: "formatter", type: "(value: number) => string", default: "v => `${v}%`", description: "Formats the displayed value." },
-  { name: "animated", type: "boolean", default: "true", description: "Animates the displayed value between updates." },
+  { name: "animated", type: "boolean", default: "true", description: "Counts the displayed number up or down when value changes. The arc always animates." },
   { name: "height", type: "string", default: "'280px'", description: "CSS height of the chart." },
   { name: "class", type: "string", default: "''", description: "Extra class names." },
 ]} />
diff --git a/site/src/content/docs/charts/heatmap.mdx b/site/src/content/docs/charts/heatmap.mdx
index 570a7694..87f07e21 100644
--- a/site/src/content/docs/charts/heatmap.mdx
+++ b/site/src/content/docs/charts/heatmap.mdx
@@ -28,7 +28,7 @@ import YearToggleSrc from "~/demos/charts/heatmap/YearToggle.svelte?raw";
 <Demo title="Hour by day matrix" description="Points are [xIndex, yIndex, value] into xCategories and yCategories." src={MatrixSrc}><Matrix client:visible /></Demo>
 <Demo title="Year toggle" description="Swap data and range to move between years." src={YearToggleSrc}><YearToggle client:visible /></Demo>
 
-<Props rows={[
+<Props for="HeatmapChart" rows={[
   { name: "variant", type: "'calendar' | 'matrix'", description: "Which layout to render. Required." },
   { name: "data", type: "CalendarHeatmapPoint[]", default: "[]", description: "Calendar variant: [date as YYYY-MM-DD, value] per day." },
   { name: "range", type: "[string, string]", description: "Calendar variant: first and last date shown." },
diff --git a/site/src/content/docs/charts/index.mdx b/site/src/content/docs/charts/index.mdx
index a661654d..81a13c7e 100644
--- a/site/src/content/docs/charts/index.mdx
+++ b/site/src/content/docs/charts/index.mdx
@@ -17,7 +17,7 @@ import DashboardSrc from "~/demos/charts/overview/Dashboard.svelte?raw";
 <LineChart series={[{ name: "Revenue", data: [42, 58, 51, 74] }]} categories={["Jan", "Feb", "Mar", "Apr"]} />
 ```
 
-Charts live in the `@codeatlasdev/ui/charts` subpath and need the optional peer dependency `echarts` (`bun add echarts`). Every chart takes data and a few semantic props. There are no color, font or style props on purpose: the palette follows the active preset, tooltips use the glass material, and charts re-theme when the color scheme, preset or surface style changes. Chart components render on the client, so hydrate them with `client:visible` in Astro.
+Charts live in the `@codeatlasdev/ui/charts` subpath and need the optional peer dependency `echarts` (`bun add echarts`, version 6). Every chart takes data and a few semantic props. There is no style or font prop on purpose: the palette follows the active preset, axes, legend and tooltips read the `--ca-*` tokens, and charts re-theme when the color scheme, preset or surface style changes. Series can take an explicit `color`; use hex or rgb, because ECharts paints on a canvas and cannot parse `oklch()`. Charts render on the client, so hydrate them with `client:visible` in Astro.
 
 |Component|Use for|
 |---|---|
@@ -34,7 +34,7 @@ All chart components also accept `height` (CSS length, each chart has its own de
 
 <Demo title="Dashboard" description="Every chart type together inside glass cards." src={DashboardSrc}><Dashboard client:visible /></Demo>
 
-<Props title="Shared props" rows={[
+<Props for="LineChart, BarChart, PieChart, ScatterChart, RadarChart, GaugeChart, HeatmapChart, Sparkline" title="Shared props" rows={[
   { name: "height", type: "string", description: "CSS height of the chart. Defaults differ per chart (320px for line, bar and scatter; 300px for pie; 340px for radar; 280px for gauge; 240px for heatmap; 48px for sparkline)." },
   { name: "class", type: "string", default: "''", description: "Extra class names on the chart container." },
 ]} />
diff --git a/site/src/content/docs/charts/line.mdx b/site/src/content/docs/charts/line.mdx
index 498c2a96..4609ac76 100644
--- a/site/src/content/docs/charts/line.mdx
+++ b/site/src/content/docs/charts/line.mdx
@@ -32,7 +32,7 @@ import StreamSrc from "~/demos/charts/line/Stream.svelte?raw";
 <Demo title="Area with gradient fill" description="area fills under each line with a gradient that fades to transparent." src={AreaSrc}><Area client:visible /></Demo>
 <Demo title="Real-time stream" description="Replace the data array and the chart updates in place." src={StreamSrc}><Stream client:visible /></Demo>
 
-<Props rows={[
+<Props for="LineChart" rows={[
   { name: "series", type: "ChartSeries[]", description: "Named series sharing one category axis. Each is { name, data: number[], color? }." },
   { name: "categories", type: "string[]", description: "X-axis labels, one per data point." },
   { name: "valueFormatter", type: "(value: number) => string", description: "Formats y-axis ticks and tooltip values." },
diff --git a/site/src/content/docs/charts/pie.mdx b/site/src/content/docs/charts/pie.mdx
index 7431384e..f448b291 100644
--- a/site/src/content/docs/charts/pie.mdx
+++ b/site/src/content/docs/charts/pie.mdx
@@ -28,7 +28,7 @@ import AnimatedSrc from "~/demos/charts/pie/Animated.svelte?raw";
 <Demo title="Rose chart" description="Nightingale rose: the radius of each slice scales with its value." src={RoseSrc}><Rose client:visible /></Demo>
 <Demo title="Animated proportions" description="Swap the data and the slices animate to the new proportions." src={AnimatedSrc}><Animated client:visible /></Demo>
 
-<Props rows={[
+<Props for="PieChart" rows={[
   { name: "data", type: "ChartSlice[]", description: "Slices as { name, value }." },
   { name: "donut", type: "boolean", default: "false", description: "Renders a ring instead of a solid pie." },
   { name: "rose", type: "boolean", default: "false", description: "Nightingale rose, where the slice radius scales with the value." },
diff --git a/site/src/content/docs/charts/radar.mdx b/site/src/content/docs/charts/radar.mdx
index 5dea54f9..49b55737 100644
--- a/site/src/content/docs/charts/radar.mdx
+++ b/site/src/content/docs/charts/radar.mdx
@@ -30,7 +30,7 @@ import InteractiveSrc from "~/demos/charts/radar/Interactive.svelte?raw";
 <Demo title="Comparison" description="Two series with a legend and focus on hover." src={CompareSrc}><Compare client:visible /></Demo>
 <Demo title="Interactive team builder" description="Drag the sliders and the radar updates live." src={InteractiveSrc}><Interactive client:visible /></Demo>
 
-<Props rows={[
+<Props for="RadarChart" rows={[
   { name: "indicators", type: "RadarIndicator[]", description: "Axes as { name, max }." },
   { name: "series", type: "RadarSeries[]", description: "Named series as { name, values: number[], color? }, aligned to indicators." },
   { name: "height", type: "string", default: "'340px'", description: "CSS height of the chart." },
diff --git a/site/src/content/docs/charts/scatter.mdx b/site/src/content/docs/charts/scatter.mdx
index 6b24e811..5eaa0742 100644
--- a/site/src/content/docs/charts/scatter.mdx
+++ b/site/src/content/docs/charts/scatter.mdx
@@ -27,7 +27,7 @@ Points are `[x, y]` or `[x, y, size]`. When any point has a third value the char
 <Demo title="Bubble chart" description="The third value of each point sets the bubble size." src={BubbleSrc}><Bubble client:visible /></Demo>
 <Demo title="Clustered by tier" description="One series per group, each with its own palette color." src={ClustersSrc}><Clusters client:visible /></Demo>
 
-<Props rows={[
+<Props for="ScatterChart" rows={[
   { name: "series", type: "ScatterSeries[]", description: "Named series as { name, data: [x, y] | [x, y, size][], color? }." },
   { name: "xName", type: "string", description: "Label of the x axis." },
   { name: "yName", type: "string", description: "Label of the y axis." },
diff --git a/site/src/content/docs/charts/sparklines.mdx b/site/src/content/docs/charts/sparklines.mdx
index dbf9f205..cc57f440 100644
--- a/site/src/content/docs/charts/sparklines.mdx
+++ b/site/src/content/docs/charts/sparklines.mdx
@@ -30,7 +30,7 @@ A sparkline has no axes, legend or tooltip. `trend` picks the color: success for
 <Demo title="Bar sparklines" description="variant bar draws narrow columns instead of a line." src={BarsSrc}><Bars client:visible /></Demo>
 <Demo title="Live streaming micro charts" src={LiveSrc}><Live client:visible /></Demo>
 
-<Props rows={[
+<Props for="Sparkline" rows={[
   { name: "data", type: "number[]", description: "Values to plot." },
   { name: "variant", type: "'line' | 'bar'", default: "'line'", description: "Line with a soft area, or narrow bars." },
   { name: "trend", type: "'up' | 'down' | 'neutral'", description: "Colors the series: success, error or neutral." },
diff --git a/site/src/content/docs/display/alert.mdx b/site/src/content/docs/display/alert.mdx
index 15b66664..c91bdc8e 100644
--- a/site/src/content/docs/display/alert.mdx
+++ b/site/src/content/docs/display/alert.mdx
@@ -21,7 +21,7 @@ import ClosableSrc from "~/demos/display/alert/Closable.svelte?raw";
 <Alert severity="success" title="Saved">Your changes were saved.</Alert>
 ```
 
-The parent owns visibility: render the alert conditionally and hide it from `onclose`. Alerts are announced by assistive technology as status messages.
+The parent owns visibility: render the alert conditionally and hide it from `onclose`. The root has `role="alert"` with `aria-live="polite"`, so assistive technology announces it.
 
 <Demo title="Severities" description={"All four semantic variants."} src={SeveritiesSrc}><Severities /></Demo>
 <Demo title="With title" description={"An optional title adds a bold heading above the message."} src={WithTitleSrc}><WithTitle /></Demo>
diff --git a/site/src/content/docs/display/badge.mdx b/site/src/content/docs/display/badge.mdx
index 5d013de2..b1082a1a 100644
--- a/site/src/content/docs/display/badge.mdx
+++ b/site/src/content/docs/display/badge.mdx
@@ -15,13 +15,13 @@ import ColorsSrc from "~/demos/display/badge/Colors.svelte?raw";
 
 ```svelte
 <script>
-  import { Badge } from "@codeatlasdev/ui";
+  import { Badge, IconButton } from "@codeatlasdev/ui";
 </script>
 
 <Badge count={3}><IconButton aria-label="Messages">…</IconButton></Badge>
 ```
 
-Badge wraps its child and positions the indicator on the corner. Pass `count` for a number (hidden at 0, capped at `99+`) or `dot` for a plain status dot. Add an accessible label to the wrapped control, since the indicator itself is visual.
+Badge wraps its child and positions the indicator on the corner. Pass `count` for a number (hidden at 0, capped at `99+`) or `dot` for a plain status dot. The indicator is a `role="status"` element labelled "New" (dot) or "N notifications" (count) from the i18n catalog; still give the wrapped control its own accessible name.
 
 <Demo title="Dot and counts" description={"`dot` shows a plain indicator, `count` shows a number capped at `99+`."} src={CountsSrc}><Counts /></Demo>
 <Demo title="On avatars" description={"Status dots on avatars."} src={OnAvatarsSrc}><OnAvatars /></Demo>
diff --git a/site/src/content/docs/display/chip.mdx b/site/src/content/docs/display/chip.mdx
index 3e1de2c2..8c3a93b1 100644
--- a/site/src/content/docs/display/chip.mdx
+++ b/site/src/content/docs/display/chip.mdx
@@ -38,7 +38,7 @@ A chip becomes a keyboard-focusable toggle button when `onclick` is set: Enter a
 <Demo title="StatusChip" description={"Semantic status indicators with dot and label."} src={StatusSrc}><Status /></Demo>
 
 
-<Props title="Chip props" rows={[
+<Props for="Chip" title="Chip props" rows={[
   { name: "label", type: "string", description: "Text content of the chip. Required." },
   { name: "icon", type: "Component", default: "undefined", description: "Icon component rendered before the label." },
   { name: "variant", type: "'default' | 'success' | 'error' | 'warning' | 'info' | 'brand'", default: "'default'", description: "Color variant." },
@@ -51,7 +51,7 @@ A chip becomes a keyboard-focusable toggle button when `onclick` is set: Enter a
 ]} />
 
 
-<Props title="StatusChip props" rows={[
+<Props for="StatusChip" title="StatusChip props" rows={[
   { name: "status", type: "'success' | 'warning' | 'error' | 'info' | 'neutral'", description: "Semantic status. Required." },
   { name: "label", type: "string", description: "Text shown next to the dot. Required." },
   { name: "class", type: "string", default: "''", description: "Extra class names." },
diff --git a/site/src/content/docs/display/data-table.mdx b/site/src/content/docs/display/data-table.mdx
index de57ecb9..5ce17ec0 100644
--- a/site/src/content/docs/display/data-table.mdx
+++ b/site/src/content/docs/display/data-table.mdx
@@ -2,7 +2,7 @@
 title: DataTable
 description: "Table with global search, column sorting, pagination and a column visibility toggle, built on TanStack Table."
 group: Display
-order: 6
+order: 7
 ---
 import Demo from "~/components/docs/Demo.astro";
 import CodeGroup from "~/components/docs/CodeGroup.astro";
@@ -19,6 +19,8 @@ DataTable lives in its own entry point so that TanStack Table stays out of bundl
 ```svelte
 <script lang="ts">
   import { DataTable, createCaColumnHelper } from "@codeatlasdev/ui/table";
+  type User = { name: string };
+  const users: User[] = [{ name: "Ana Souza" }, { name: "Bruno Lima" }];
 
   const col = createCaColumnHelper<User>();
   const columns = col.columns([
@@ -34,7 +36,7 @@ There are two modes. In simple mode you pass `columns` and `data` and the table
 <Demo title="Simple mode" description={"Pass `columns` and `data`. Search, sort and pagination are managed automatically."} src={SimpleSrc}><Simple client:visible /></Demo>
 <Demo title="Controlled mode" description={"Own the state to drive server-side filtering, sorting and pagination."} src={ControlledSrc}><Controlled client:visible /></Demo>
 
-<Props rows={[
+<Props for="DataTable" rows={[
   { name: "columns", type: "ColumnDef[]", description: "Column definitions created with `createCaColumnHelper`. Required." },
   { name: "data", type: "TData[]", description: "Row data. In simple mode pass all rows; in controlled mode pass the current page. Required." },
   { name: "total", type: "number", default: "data.length", description: "Total row count after filtering, used to compute the page count. Ignored in simple mode." },
@@ -55,3 +57,69 @@ There are two modes. In simple mode you pass `columns` and `data` and the table
   { name: "children", type: "Snippet", default: "undefined", description: "Filter chips such as `DataTableFacetedFilter`, rendered in the toolbar." },
   { name: "class", type: "string", default: "''", description: "Extra class names on the wrapper." },
 ]} />
+
+## Building blocks
+
+`DataTable` is assembled from the parts below, all exported from `@codeatlasdev/ui/table`. You rarely need them: use them standalone when you render your own `<table>` markup around a table instance made with `createCaTable`, for example a layout `DataTable` does not offer. Inside `DataTable` the toolbar, pagination and column toggle are already wired. Use `DataTableColumnHeader` as a column `header` to get a sortable header, and pass `DataTableFacetedFilter` as `children` of `DataTable`.
+
+```svelte
+<script lang="ts">
+  import { renderComponent } from "@tanstack/svelte-table";
+  import { createCaColumnHelper, DataTableColumnHeader } from "@codeatlasdev/ui/table";
+  type User = { name: string };
+
+  const col = createCaColumnHelper<User>();
+  const columns = col.columns([
+    col.accessor("name", {
+      header: ({ column }) =>
+        renderComponent(DataTableColumnHeader<User, string>, { column, title: "Name" }),
+      meta: { label: "Name" },
+    }),
+  ]);
+</script>
+```
+
+`createCaColumnHelper`, `createCaTable`, `caTableFeatures` and the `CaColumn`, `CaColumnDef`, `CaColumnMeta`, `CaTable` and `CaTableFeatures` types are exported from the same entry point. `meta.label` is the name shown in the column visibility menu.
+
+<Props for="DataTableToolbar" title="DataTableToolbar props" rows={[
+  { name: "table", type: "CaTable<TData>", description: "Table instance from `createCaTable`. Required." },
+  { name: "total", type: "number", description: "Result count shown in the toolbar. Required." },
+  { name: "globalFilter", type: "string", description: "Current search value. Required." },
+  { name: "onGlobalFilterChange", type: "(v: string) => void", description: "Called when the user types in the search box. Required." },
+  { name: "searchPlaceholder", type: "string", default: "undefined", description: "Placeholder and accessible name of the search input." },
+  { name: "isLoading", type: "boolean", default: "undefined", description: "Shows a spinner." },
+  { name: "isExporting", type: "boolean", default: "undefined", description: "Disables the export button and shows a spinner in it." },
+  { name: "onExport", type: "() => void", default: "undefined", description: "Renders the export button. It is disabled while `total` is 0." },
+  { name: "children", type: "Snippet", default: "undefined", description: "Filter controls rendered next to the search box." },
+]} />
+
+The toolbar always includes `DataTableColumnToggle` on its right side.
+
+<Props for="DataTablePagination" title="DataTablePagination props" rows={[
+  { name: "table", type: "CaTable<TData>", description: "Table instance from `createCaTable`. Required." },
+  { name: "total", type: "number", description: "Total row count shown next to the page indicator. Required." },
+]} />
+
+It renders a page size select (10, 20, 50 or 100 rows), a `page / pages` indicator and previous and next buttons.
+
+<Props for="DataTableColumnHeader" title="DataTableColumnHeader props" rows={[
+  { name: "column", type: "CaColumn<TData, TValue>", description: "Column the header belongs to. Required." },
+  { name: "title", type: "string", description: "Header text. Required." },
+  { name: "class", type: "string", default: "''", description: "Extra class names." },
+]} />
+
+A sortable column renders a button that toggles sorting and shows the direction icon. A column that cannot sort renders the plain title.
+
+<Props for="DataTableColumnToggle" title="DataTableColumnToggle props" rows={[
+  { name: "table", type: "CaTable<TData>", description: "Table instance from `createCaTable`. Required." },
+]} />
+
+A menu of checkboxes, one per column that can be hidden. It follows the menu keyboard pattern: arrow keys move, Space and Enter toggle, Escape closes.
+
+<Props for="DataTableFacetedFilter" title="DataTableFacetedFilter props" rows={[
+  { name: "title", type: "string", description: "Label of the filter button. Required." },
+  { name: "facets", type: "Record<string, number>", default: "{}", description: "Option key to result count. Options are sorted by count, highest first." },
+  { name: "labelMap", type: "Record<string, string>", default: "{}", description: "Maps option keys to display labels." },
+  { name: "selected", type: "string[]", default: "[]", description: "Selected option keys." },
+  { name: "onSelectionChange", type: "(values: string[]) => void", description: "Called with the new selection. Required." },
+]} />
diff --git a/site/src/content/docs/display/divider.mdx b/site/src/content/docs/display/divider.mdx
index 1aada35b..4df27751 100644
--- a/site/src/content/docs/display/divider.mdx
+++ b/site/src/content/docs/display/divider.mdx
@@ -2,7 +2,7 @@
 title: Divider
 description: "Horizontal and vertical separators drawn with outline tokens."
 group: Display
-order: 7
+order: 8
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
@@ -20,7 +20,7 @@ import VerticalSrc from "~/demos/display/divider/Vertical.svelte?raw";
 <Divider orientation="vertical" />
 ```
 
-A vertical divider stretches to the height of its flex container, so place it inside a `Row` with `align="center"` or a fixed height.
+A vertical divider stretches to the height of its flex container, so place it inside a `Flex` with `align="center"` or give it a fixed height.
 
 <Demo title="Horizontal" src={HorizontalSrc}><Horizontal /></Demo>
 <Demo title="Vertical" src={VerticalSrc}><Vertical /></Demo>
diff --git a/site/src/content/docs/display/external-link.mdx b/site/src/content/docs/display/external-link.mdx
index 3b6c6a77..27ddd6ff 100644
--- a/site/src/content/docs/display/external-link.mdx
+++ b/site/src/content/docs/display/external-link.mdx
@@ -2,7 +2,7 @@
 title: External Link
 description: A link that opens in a new tab with the right rel, an icon and a screen reader hint, ready for table cells.
 group: Display
-order: 13
+order: 17
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
diff --git a/site/src/content/docs/display/image.mdx b/site/src/content/docs/display/image.mdx
index 7110e27c..02ce9ff0 100644
--- a/site/src/content/docs/display/image.mdx
+++ b/site/src/content/docs/display/image.mdx
@@ -2,7 +2,7 @@
 title: Image
 description: "A responsive image that reserves its space (no layout shift), loads lazily, and preloads the one above-the-fold image."
 group: Display
-order: 5
+order: 6
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
@@ -32,16 +32,16 @@ For AVIF and WebP generation at build time see [Performance](/docs/getting-start
 
 `alt` is required. An image that carries no meaning passes `decorative` instead of `alt=""`; it renders `alt=""` with `aria-hidden="true"`. In development the component warns when `alt=""` is passed without `decorative`, when `width` or `height` is missing, and when `decorative` is combined with a non-empty `alt`.
 
-<Props rows={[
+<Props for="Image" rows={[
   { name: "src", type: "string", description: "Image URL." },
   { name: "alt", type: "string", description: "Text alternative. Required; use `decorative` for decoration." },
   { name: "width", type: "number", description: "Intrinsic width in pixels. Required, with `height` it reserves the space." },
   { name: "height", type: "number", description: "Intrinsic height in pixels. Required." },
   { name: "decorative", type: "boolean", default: "false", description: "Renders `alt=\"\"` and `aria-hidden=\"true\"`." },
   { name: "priority", type: "boolean", default: "false", description: "Eager load, `fetchpriority=\"high\"` and a preload link in `<head>`. One per page, for the LCP image." },
-  { name: "srcset", type: "string", default: "undefined", description: "Candidate renditions. Also set on the preload link when `priority` is on." },
-  { name: "sizes", type: "string", default: "undefined", description: "Rendered width hint for `srcset`." },
   { name: "loading", type: "'lazy' | 'eager'", default: "'lazy' ('eager' with priority)", description: "Overrides the default." },
   { name: "decoding", type: "'async' | 'sync' | 'auto'", default: "'async'", description: "Decode hint." },
   { name: "class", type: "string", default: "''", description: "Extra class names." },
 ]} />
+
+Other `<img>` attributes are forwarded as they are. `srcset` and `sizes` are the ones you will use most: `srcset` lists the candidate renditions and `sizes` tells the browser the rendered width. With `priority`, both are copied onto the preload link in `<head>`. `fetchpriority` is controlled by `priority`.
diff --git a/site/src/content/docs/display/kbd.mdx b/site/src/content/docs/display/kbd.mdx
new file mode 100644
index 00000000..fa267179
--- /dev/null
+++ b/site/src/content/docs/display/kbd.mdx
@@ -0,0 +1,27 @@
+---
+title: Kbd
+description: A keycap for keyboard shortcuts in prose, menus and tooltips.
+group: Display
+order: 10
+---
+import Demo from "~/components/docs/Demo.astro";
+import Props from "~/components/docs/Props.astro";
+import Basic from "~/demos/display/kbd/Basic.svelte";
+import BasicSrc from "~/demos/display/kbd/Basic.svelte?raw";
+
+```svelte
+<script>
+  import { Kbd } from "@codeatlasdev/ui";
+</script>
+
+<Kbd>Esc</Kbd>
+```
+
+`Kbd` renders a native `<kbd>` element. Use one per key and join combinations with a plain `+`. The keycap is not selectable, so double clicks on a shortcut do not select it.
+
+<Demo title="Shortcuts in text" src={BasicSrc}><Basic /></Demo>
+
+<Props rows={[
+  { name: "children", type: "Snippet", description: "The key label, for example Ctrl or K." },
+  { name: "class", type: "string", default: "''", description: "Extra classes on the `<kbd>` element." },
+]} />
diff --git a/site/src/content/docs/display/live-list.mdx b/site/src/content/docs/display/live-list.mdx
index 6fe29f75..ca03438d 100644
--- a/site/src/content/docs/display/live-list.mdx
+++ b/site/src/content/docs/display/live-list.mdx
@@ -2,7 +2,7 @@
 title: Live List
 description: A list that fills while rows stream in over SSE, WebSocket or a bulk job, with progress, batched screen reader announcements and auto-scroll that never steals focus.
 group: Display
-order: 12
+order: 15
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
diff --git a/site/src/content/docs/display/notification-bell.mdx b/site/src/content/docs/display/notification-bell.mdx
index 19575ec3..3cbf2e06 100644
--- a/site/src/content/docs/display/notification-bell.mdx
+++ b/site/src/content/docs/display/notification-bell.mdx
@@ -2,7 +2,7 @@
 title: NotificationBell
 description: "Bell button with an unread badge that opens a notification center, designed for app shell headers."
 group: Display
-order: 8
+order: 9
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
@@ -19,14 +19,14 @@ import ControlledSrc from "~/demos/display/notification-bell/Controlled.svelte?r
 <NotificationBell notifications={items} onRead={markRead} onReadAll={markAll} onClear={clear} />
 ```
 
-The unread count is derived from `notifications` where `read` is falsy. The component is controlled: update your list in `onRead`, `onReadAll` and `onClear`. Every visible string can be replaced through `labels`.
+The unread count is derived from `notifications` where `read` is falsy. The component is controlled: update your list in `onRead`, `onReadAll` and `onClear`. Every visible string can be replaced through `labels`. The panel is a popover layer anchored below the bell, aligned to its end edge, and closes on Escape or an outside press.
 
 <Demo title="Default" description={"With notifications and with an empty list."} src={DefaultSrc}><Default client:visible /></Demo>
 <Demo title="Controlled" description={"Mark items as read, mark all as read and clear the list."} src={ControlledSrc}><Controlled client:visible /></Demo>
 
 <Props rows={[
   { name: "notifications", type: "NotificationItem[]", default: "[]", description: "Items shown in the panel: `{ id, title, body?, time?, read?, variant? }`. `variant` is `'default' | 'info' | 'success' | 'warning' | 'error'`." },
-  { name: "onRead", type: "(id: string) => void", default: "undefined", description: "Called when an item is clicked." },
+  { name: "onRead", type: "(id: string) => void", default: "undefined", description: "Called when an unread item is clicked. Items already read do not call it." },
   { name: "onReadAll", type: "() => void", default: "undefined", description: "Called by the mark all as read action." },
   { name: "onClear", type: "() => void", default: "undefined", description: "Called by the clear action." },
   { name: "labels", type: "{ title?, markAll?, clear?, empty? }", default: "{}", description: "String overrides for i18n." },
diff --git a/site/src/content/docs/display/pagination.mdx b/site/src/content/docs/display/pagination.mdx
index 9282e9a4..028dc19b 100644
--- a/site/src/content/docs/display/pagination.mdx
+++ b/site/src/content/docs/display/pagination.mdx
@@ -2,7 +2,7 @@
 title: Pagination
 description: "Navigation between pages of a data set, with a bindable current page."
 group: Display
-order: 9
+order: 11
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
@@ -21,7 +21,7 @@ import FewItemsSrc from "~/demos/display/pagination/FewItems.svelte?raw";
 <Pagination count={100} perPage={10} bind:page />
 ```
 
-`count` is the total number of items, not the number of pages. Pages are numbered from 1.
+`count` is the total number of items, not the number of pages. Pages are numbered from 1, and the first and last page always show. The nav buttons and page buttons form one keyboard group: arrow keys move between them (wrapping at the ends, mirrored in right-to-left layouts), Home and End jump to the first and last enabled control. The current page has `aria-current="page"`.
 
 <Demo title="Basic" src={BasicSrc}><Basic client:visible /></Demo>
 <Demo title="More siblings" description={"`siblingCount` controls how many pages show around the current one."} src={SiblingsSrc}><Siblings client:visible /></Demo>
@@ -32,6 +32,6 @@ import FewItemsSrc from "~/demos/display/pagination/FewItems.svelte?raw";
   { name: "perPage", type: "number", default: "10", description: "Items per page." },
   { name: "page", type: "number", default: "1", description: "Current page, 1-based. Bindable." },
   { name: "siblingCount", type: "number", default: "1", description: "Pages shown on each side of the current page." },
-  { name: "onPageChange", type: "(page: number) => void", default: "undefined", description: "Called when the page changes." },
+  { name: "onPageChange", type: "(page: number) => void", default: "undefined", description: "Called with the new page when the user changes it. It does not fire when you set `page` yourself." },
   { name: "class", type: "string", default: "''", description: "Extra class names." },
 ]} />
diff --git a/site/src/content/docs/display/scroll-area.mdx b/site/src/content/docs/display/scroll-area.mdx
index 7f38b944..41e4fb4d 100644
--- a/site/src/content/docs/display/scroll-area.mdx
+++ b/site/src/content/docs/display/scroll-area.mdx
@@ -2,7 +2,7 @@
 title: ScrollArea
 description: "Scrollable container with overlay scrollbars styled by the theme."
 group: Display
-order: 10
+order: 12
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
@@ -19,7 +19,7 @@ import HorizontalSrc from "~/demos/display/scroll-area/Horizontal.svelte?raw";
 <ScrollArea maxHeight="240px">…</ScrollArea>
 ```
 
-The area scrolls once its content exceeds `maxHeight` or `maxWidth`, so set one of them (or a height through `class`). Native scrolling, touch momentum and keyboard scrolling are preserved.
+The area scrolls once its content exceeds `maxHeight` or `maxWidth`, so set one of them (or a height through `class`). Native scrolling and touch momentum are preserved. The viewport is focusable (`tabindex="0"`), so keyboard users can scroll it with the arrow keys.
 
 <Demo title="Vertical scroll" description={"Capped with `maxHeight`."} src={VerticalSrc}><Vertical client:visible /></Demo>
 <Demo title="Horizontal scroll" description={"`orientation=\"horizontal\"` with always-visible scrollbars."} src={HorizontalSrc}><Horizontal client:visible /></Demo>
diff --git a/site/src/content/docs/display/table.mdx b/site/src/content/docs/display/table.mdx
index ead46170..d63b7186 100644
--- a/site/src/content/docs/display/table.mdx
+++ b/site/src/content/docs/display/table.mdx
@@ -1,8 +1,8 @@
 ---
 title: Table
-description: "SimpleTable adds a sticky header, hover rows and an optional card layout on small screens."
+description: "SimpleTable styles plain table markup with a sticky header, hover rows and an optional card layout in narrow containers."
 group: Display
-order: 11
+order: 13
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
@@ -22,13 +22,13 @@ import CardsSrc from "~/demos/display/table/Cards.svelte?raw";
 </SimpleTable>
 ```
 
-SimpleTable styles plain `thead` and `tbody` markup. For search, sorting and pagination use [DataTable](/docs/display/data-table/). In `cards` mode the header row stays available to screen readers.
+SimpleTable styles plain `thead` and `tbody` markup inside a focusable, horizontally scrolling region. For search, sorting and pagination use [DataTable](/docs/display/data-table/). It is exported from `@codeatlasdev/ui`. `@codeatlasdev/ui/table` also exports a `Table`, a bordered wrapper around a plain `<table>` that forwards native table attributes.
 
 <Demo title="Default (scroll)" description={"A regular table at every width."} src={ScrollSrc}><Scroll /></Demo>
-<Demo title="Cards on mobile" description={"Below 900px each row becomes a card. Put `data-label` on every `td`; it is rendered as the field name. Resize the window to see it."} src={CardsSrc}><Cards /></Demo>
+<Demo title="Cards on narrow containers" description={"When the table's own container is narrower than 600px each row becomes a card. Every cell is captioned with its column header; `data-label` only overrides that. Resize the window to see it."} src={CardsSrc}><Cards /></Demo>
 
-<Props rows={[
-  { name: "responsive", type: "'scroll' | 'cards'", default: "'scroll'", description: "`cards` turns each row into a card below the md breakpoint (900px). Requires `data-label` on each `td`." },
+<Props for="SimpleTable" rows={[
+  { name: "responsive", type: "'scroll' | 'cards'", default: "'scroll'", description: "`scroll` keeps a regular table. `cards` turns each row into a card when the table's own width is below the `sm` breakpoint (600px). Cell captions come from the `thead` headers automatically." },
   { name: "class", type: "string", default: "''", description: "Extra class on the wrapper." },
   { name: "children", type: "Snippet", default: "undefined", description: "`thead` and `tbody` markup." },
 ]} />
diff --git a/site/src/content/docs/display/timeline.mdx b/site/src/content/docs/display/timeline.mdx
index e1383daf..8b62992a 100644
--- a/site/src/content/docs/display/timeline.mdx
+++ b/site/src/content/docs/display/timeline.mdx
@@ -2,7 +2,7 @@
 title: Timeline
 description: "Chronological list of events with colored markers."
 group: Display
-order: 12
+order: 14
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
diff --git a/site/src/content/docs/display/tooltip.mdx b/site/src/content/docs/display/tooltip.mdx
index a6220252..21e8698a 100644
--- a/site/src/content/docs/display/tooltip.mdx
+++ b/site/src/content/docs/display/tooltip.mdx
@@ -2,7 +2,7 @@
 title: Tooltip
 description: "Floating label shown on hover and focus, with four placements and a configurable delay."
 group: Display
-order: 13
+order: 16
 ---
 import Demo from "~/components/docs/Demo.astro";
 import Props from "~/components/docs/Props.astro";
@@ -27,7 +27,7 @@ import ChildrenSrc from "~/demos/display/tooltip/Children.svelte?raw";
 </Tooltip>
 ```
 
-When the trigger is an interactive control, use `triggerChild` and spread the received `props` onto it so no extra wrapper button is created. `children` is for non-interactive content such as text, which the tooltip wraps in its own button. Tooltips open on keyboard focus too, but never put essential information only in a tooltip, because touch devices have no hover.
+When the trigger is an interactive control, use `triggerChild` and spread the received `props` onto it so no extra wrapper button is created. `children` is for non-interactive content such as text, which the tooltip wraps in its own button. Tooltips open on keyboard focus without the delay and close on Escape. Pointer hover waits for `delay`, touch never opens them, and moving between tooltips within 300ms skips the delay. Never put essential information only in a tooltip.
 
 <Demo title="All sides" description={"top, right, bottom and left placement."} src={SidesSrc}><Sides client:visible /></Demo>
 <Demo title="On icon buttons" description={"Gives icon-only buttons a visible label."} src={OnIconsSrc}><OnIcons client:visible /></Demo>
diff --git a/site/src/content/docs/docs-kit/docs.mdx b/site/src/content/docs/docs-kit/docs.mdx
index c1e02295..759fee59 100644
--- a/site/src/content/docs/docs-kit/docs.mdx
+++ b/site/src/content/docs/docs-kit/docs.mdx
@@ -44,7 +44,7 @@ The sidebar keeps its place between pages, also on a static site where every lin
 <Demo title="DocsNav and TableOfContents" description="The sidebar tree and the page index. The inline variant is shown; DocsShell uses the rail variant on desktop." src={NavTocSrc}><NavToc client:visible /></Demo>
 <Demo title="DocsSearch" description="Full-text search. A dialog on desktop and a full-height sheet with a 16px input on phones. Pass entries or an async loader." src={SearchSrc}><Search client:visible /></Demo>
 
-<Props title="DocsShell" rows={[
+<Props for="DocsShell" title="DocsShell" rows={[
   { name: "sections", type: "DocsSection[]", description: "{ id, label, href } entries shown as header tabs and in the mobile Sheet." },
   { name: "active", type: "string", description: "id of the current section." },
   { name: "groups", type: "DocsNavGroup[]", default: "[]", description: "Sidebar tree of the current section. Empty hides the sidebar and the page index." },
@@ -57,24 +57,25 @@ The sidebar keeps its place between pages, also on a static site where every lin
   { name: "brand", type: "Snippet", description: "Required. Brand mark and name inside the header link." },
   { name: "actions", type: "Snippet", description: "Extra header actions on the right. Keep to one or two icon buttons." },
   { name: "menuFooter", type: "Snippet", description: "Content below the sidebar tree in the mobile Sheet, such as external links." },
+  { name: "pager", type: "{ prev?: DocsPagerLink; next?: DocsPagerLink }", description: "Previous and next pages, as { href, title }. Cards at the end of the article on wide screens, a fixed bottom action bar on narrow ones." },
   { name: "children", type: "Snippet", description: "Required. Page content." },
 ]} />
 
-<Props title="DocsNav" rows={[
-  { name: "groups", type: "DocsNavGroup[]", description: "Labelled groups of { href, title, badge? } links." },
+<Props for="DocsNav" title="DocsNav" rows={[
+  { name: "groups", type: "DocsNavGroup[]", description: "Groups of { label?, items } where an item is { href, title, badge? }. A badge is an HTTP method shown as a MethodBadge." },
   { name: "pathname", type: "string", description: "Current path, marks the current page with aria-current." },
   { name: "label", type: "string", description: "Accessible label of the nav landmark." },
   { name: "onNavigate", type: "() => void", description: "Called after a link is followed, to close the mobile Sheet." },
 ]} />
 
-<Props title="TableOfContents" rows={[
+<Props for="TableOfContents" title="TableOfContents" rows={[
   { name: "headings", type: "DocsHeading[]", description: "{ id, text, depth: 2 | 3 } entries. Renders nothing for fewer than 2 headings." },
   { name: "variant", type: "'rail' | 'inline'", default: "'rail'", description: "A sticky list, or a collapsible disclosure that shows the current section." },
   { name: "label", type: "string", description: "Accessible label of the nav landmark." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
 ]} />
 
-<Props title="DocsSearch" rows={[
+<Props for="DocsSearch" title="DocsSearch" rows={[
   { name: "open", type: "boolean", default: "false", description: "Bindable open state." },
   { name: "index", type: "DocsSearchEntry[] | () => Promise<DocsSearchEntry[]>", description: "Required. Entries, or a loader called once on first open." },
   { name: "onselect", type: "(href: string) => void", description: "Required. Called with the picked result's href." },
@@ -82,8 +83,9 @@ The sidebar keeps its place between pages, also on a static site where every lin
   { name: "hint", type: "string", description: "Footer hint text. Defaults to the localized string." },
 ]} />
 
-<Props title="Prose blocks" rows={[
+<Props for="none" title="Prose blocks" rows={[
   { name: "CodeTabs.sync", type: "string", default: "'lang'", description: "Groups with the same key follow the chosen label. An empty string disables sync." },
+  { name: "CodeTabs.tabs", type: "{ label: string; code?: string; html?: string }[]", description: "Tabs as data instead of CodeTab children, for Astro and MDX pages where each island is its own Svelte tree. `html` is pre-highlighted markup." },
   { name: "CodeTab.label", type: "string", description: "Tab text and sync key, for example 'cURL' or 'Node.js'." },
   { name: "Callout.type", type: "'note' | 'tip' | 'caution' | 'danger'", default: "'note'", description: "Maps to Alert severity (info, success, warning, error)." },
   { name: "Callout.title", type: "string", description: "Overrides the default localized title." },
diff --git a/site/src/content/docs/feedback/alert-dialog.mdx b/site/src/content/docs/feedback/alert-dialog.mdx
index ade24fdb..fc4e0886 100644
--- a/site/src/content/docs/feedback/alert-dialog.mdx
+++ b/site/src/content/docs/feedback/alert-dialog.mdx
@@ -29,13 +29,13 @@ import ControlledSrc from "~/demos/feedback/alert-dialog/Controlled.svelte?raw";
 />
 ```
 
-Unlike [Dialog](/docs/feedback/dialog/), there is no close button and a click outside does not dismiss it. Escape and Cancel close it and fire `oncancel`. Both are ignored while a request is pending.
+Unlike [Dialog](/docs/feedback/dialog/), there is no close button and a click outside does not dismiss it, and initial focus lands on the dialog itself instead of the first control. Escape and Cancel close it and fire `oncancel`. Both are ignored while a request is pending.
 
 <Demo title="Basic and destructive" description="Confirm and cancel, with the destructive variant for irreversible actions." src={BasicSrc}><Basic client:visible /></Demo>
 <Demo title="Async onconfirm" description="While the promise is pending the confirm button shows a spinner, Cancel is disabled and Escape is ignored. The dialog closes when it resolves and stays open if it throws." src={AsyncSrc}><Async client:visible /></Demo>
 <Demo title="Controlled pending" description="Pass pending when the loading state lives outside, for example a mutation from your query client." src={ControlledSrc}><Controlled client:visible /></Demo>
 
-<Props rows={[
+<Props for="AlertDialog" rows={[
   { name: "open", type: "boolean", default: "false", description: "Bindable open state." },
   { name: "title", type: "string", description: "Required. Dialog title and accessible name." },
   { name: "description", type: "string", description: "Supporting text below the title." },
@@ -43,7 +43,7 @@ Unlike [Dialog](/docs/feedback/dialog/), there is no close button and a click ou
   { name: "cancelLabel", type: "string", default: "'Cancel' (localized)", description: "Label of the cancel button. Defaults to the active locale's string." },
   { name: "destructive", type: "boolean", default: "false", description: "Confirm button uses the destructive variant." },
   { name: "pending", type: "boolean", default: "false", description: "Controls the loading state externally. Without it, pending is automatic while onconfirm is awaited." },
-  { name: "onconfirm", type: "() => void | Promise<void>", description: "Required. Closes the dialog when it resolves; if it throws, the dialog stays open and the error is rethrown." },
+  { name: "onconfirm", type: "() => void | Promise<void>", description: "Required. Closes the dialog when it resolves; if it throws, the dialog stays open and the error propagates." },
   { name: "oncancel", type: "() => void", description: "Fires on Cancel or Escape. Never fires while pending." },
   { name: "class", type: "string", default: "''", description: "Extra classes on the panel." },
 ]} />
diff --git a/site/src/content/docs/feedback/dialog.mdx b/site/src/content/docs/feedback/dialog.mdx
index 16355b78..d4b88522 100644
--- a/site/src/content/docs/feedback/dialog.mdx
+++ b/site/src/content/docs/feedback/dialog.mdx
@@ -31,19 +31,19 @@ import SplitSrc from "~/demos/feedback/dialog/Split.svelte?raw";
 </Dialog>
 ```
 
-The dialog renders a native modal `<dialog>`: focus is trapped, Escape closes and the panel carries `aria-modal`. For decisions that need an explicit answer use [AlertDialog](/docs/feedback/alert-dialog/). On phones, prefer [Sheet](/docs/feedback/sheet/) for bottom-anchored content.
+The dialog renders a native modal `<dialog>` opened with `showModal()`: the page behind is inert, focus is trapped, scrolling is locked and Escape closes it. Clicking the overlay closes it too. For decisions that need an explicit answer use [AlertDialog](/docs/feedback/alert-dialog/). On phones, prefer [Sheet](/docs/feedback/sheet/) for bottom-anchored content.
 
 <Demo title="Confirmation" description="The destructive confirm and cancel pattern." src={ConfirmationSrc}><Confirmation client:visible /></Demo>
 <Demo title="Info" description="Informational content with a single action." src={InfoSrc}><Info client:visible /></Demo>
 <Demo title="Form" description="A dialog holding a form, at the md size." src={FormSrc}><Form client:visible /></Demo>
 <Demo title="Chromeless" description="No header, description or actions, and the body has no padding. The title becomes the visually hidden accessible name." src={ChromelessSrc}><Chromeless client:visible /></Demo>
-<Demo title="Split" description='size="split" is 1100 by 720 with two columns from the md breakpoint and a single column below it. Combine it with chromeless.' src={SplitSrc}><Split client:visible /></Demo>
+<Demo title="Split" description='size="split" is 1100 by 720 with two columns from the md breakpoint (900px) and a single column below it. Combine it with chromeless.' src={SplitSrc}><Split client:visible /></Demo>
 
-<Props rows={[
+<Props for="Dialog" rows={[
   { name: "open", type: "boolean", default: "false", description: "Bindable open state." },
   { name: "title", type: "string", description: "Header title. With chromeless it is the hidden accessible name." },
   { name: "description", type: "string", description: "Subtitle below the title." },
-  { name: "size", type: "'sm' | 'md' | 'lg' | 'xl' | 'split'", default: "'md'", description: "Width: 400, 480, 600 or 820px. split is 1100 by 720 in two columns from md." },
+  { name: "size", type: "'sm' | 'md' | 'lg' | 'xl' | 'split'", default: "'md'", description: "Width: 400, 480, 600 or 820px. split is 1100 by 720 in two columns from 900px." },
   { name: "chromeless", type: "boolean", default: "false", description: "Omits header, description and actions; the body has no padding. title and description stay available to screen readers." },
   { name: "children", type: "Snippet", description: "Dialog body." },
   { name: "actions", type: "Snippet", description: "Footer buttons." },
@@ -57,16 +57,17 @@ Dialogs, sheets, drawers, menus, popovers and tooltips share one layer stack. Mo
 
 Escape and outside presses go to the topmost layer only, so a menu inside a dialog closes first and the dialog on the next press. Focus returns to the trigger when a layer closes.
 
-A host that draws outside the DOM (a native view over a webview) can follow the stack with `onLayerChange`. It fires on every open and close with the open layers, bottom to top, and their rectangles:
+A host that draws outside the DOM (a native view over a webview) can follow the stack with `onLayerChange`. It fires on every open and close with the open layers, bottom to top, and their rectangles, and returns the function that unsubscribes:
 
 ```ts
-import { onLayerChange } from "@codeatlasdev/ui";
+import { onLayerChange, type LayerChange } from "@codeatlasdev/ui";
 
-const stop = onLayerChange(({ count, modal, layers }) => {
-  nativeView.setParked(count > 0);
-  // layers: [{ kind: "modal" | "popover" | "hint", rect: DOMRect }]
+const stop = onLayerChange((change: LayerChange) => {
+  nativeView.setParked(change.count > 0);
+  // change.layers: LayerInfo[], bottom to top
+  // each LayerInfo is { kind: LayerKind, rect: DOMRect }
 });
 ```
 
-The same signal is a `layerchange` `CustomEvent` on `document`, with the detail as `event.detail`.
+The same signal is a `layerchange` `CustomEvent` on `document`, with the detail as `event.detail`. `LayerChange` is `{ layers: LayerInfo[]; count: number; modal: boolean }`, where `modal` is true while at least one modal layer is open. `LayerKind` is `"modal"` for Dialog, AlertDialog, Drawer and Sheet, `"popover"` for menus and popovers, and `"hint"` for tooltips. All three types are exported from `@codeatlasdev/ui`.
 
diff --git a/site/src/content/docs/feedback/drawer.mdx b/site/src/content/docs/feedback/drawer.mdx
index ea1b39b1..7c0fcb95 100644
--- a/site/src/content/docs/feedback/drawer.mdx
+++ b/site/src/content/docs/feedback/drawer.mdx
@@ -15,7 +15,7 @@ import NotificationsSrc from "~/demos/feedback/drawer/Notifications.svelte?raw";
 
 ```svelte
 <script>
-  import { Drawer } from "@codeatlasdev/ui";
+  import { Drawer, Button } from "@codeatlasdev/ui";
   let open = $state(false);
 </script>
 
@@ -31,7 +31,7 @@ Same architecture as [Dialog](/docs/feedback/dialog/): the overlay blurs the pag
 <Demo title="Left and bottom" description="Left suits mobile navigation. Bottom is a simple bottom panel without gestures." src={SidesSrc}><Sides client:visible /></Demo>
 <Demo title="Notification panel" description="A real-world use: a 400px wide panel on the right." src={NotificationsSrc}><Notifications client:visible /></Demo>
 
-<Props rows={[
+<Props for="Drawer" rows={[
   { name: "open", type: "boolean", default: "false", description: "Bindable open state." },
   { name: "side", type: "'left' | 'right' | 'bottom'", default: "'right'", description: "Edge the panel slides from." },
   { name: "title", type: "string", description: "Header title." },
diff --git a/site/src/content/docs/feedback/lightbox.mdx b/site/src/content/docs/feedback/lightbox.mdx
new file mode 100644
index 00000000..15e0ca5f
--- /dev/null
+++ b/site/src/content/docs/feedback/lightbox.mdx
@@ -0,0 +1,32 @@
+---
+title: Lightbox
+description: A full-screen image viewer on a native modal dialog.
+group: Feedback
+order: 9
+---
+import Demo from "~/components/docs/Demo.astro";
+import Props from "~/components/docs/Props.astro";
+import Basic from "~/demos/feedback/lightbox/Basic.svelte";
+import BasicSrc from "~/demos/feedback/lightbox/Basic.svelte?raw";
+
+```svelte
+<script>
+  import { Lightbox } from "@codeatlasdev/ui";
+
+  let open = $state(false);
+</script>
+
+<button onclick={() => (open = true)}>View photo</button>
+<Lightbox bind:open src={url} alt="Photo sent by Maria" />
+```
+
+The image is contained in the viewport and respects the device safe areas. Escape, the close button and a click on the backdrop close it. Because it is a native modal `<dialog>`, the page behind is inert, focus returns to the trigger and scrolling is locked while it is open. `alt` is required.
+
+<Demo title="Open from a button" src={BasicSrc}><Basic client:visible /></Demo>
+
+<Props rows={[
+  { name: "open", type: "boolean", default: "false", description: "Bindable open state." },
+  { name: "src", type: "string", description: "Image URL. Required." },
+  { name: "alt", type: "string", description: "Image description. Required." },
+  { name: "onclose", type: "() => void", description: "Called after the viewer closes." },
+]} />
diff --git a/site/src/content/docs/feedback/progress.mdx b/site/src/content/docs/feedback/progress.mdx
index 0a2b0db3..30ca9298 100644
--- a/site/src/content/docs/feedback/progress.mdx
+++ b/site/src/content/docs/feedback/progress.mdx
@@ -22,16 +22,16 @@ import AnimatedSrc from "~/demos/feedback/progress/Animated.svelte?raw";
 <Progress indeterminate label="Loading" />
 ```
 
-Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`. Always pass `label` so screen readers know what is progressing. The indeterminate state omits `aria-valuenow`.
+Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin` (always 0) and `aria-valuemax` (from `max`). Always pass `label` so screen readers know what is progressing. The indeterminate state omits `aria-valuenow`.
 
 <Demo title="Determinate" description="An explicit value from 0 to max (100 by default)." src={DeterminateSrc}><Determinate /></Demo>
 <Demo title="Indeterminate" description="Use when progress cannot be determined." src={IndeterminateSrc}><Indeterminate /></Demo>
 <Demo title="Animated" description="Start a simulated upload." src={AnimatedSrc}><Animated client:visible /></Demo>
 
-<Props rows={[
+<Props for="Progress" rows={[
   { name: "value", type: "number", default: "0", description: "Current progress value." },
-  { name: "max", type: "number", default: "100", description: "Maximum value. The fill is clamped between 0 and 100%." },
+  { name: "max", type: "number", default: "100", description: "Maximum value, also exposed as `aria-valuemax`. The fill width is clamped between 0 and 100%." },
   { name: "indeterminate", type: "boolean", default: "false", description: "Plays the shimmer animation when progress is unknown." },
-  { name: "label", type: "string", description: "Accessible aria-label for screen readers." },
+  { name: "label", type: "string", default: "undefined", description: "Accessible name, set as `aria-label`." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
 ]} />
diff --git a/site/src/content/docs/feedback/sheet.mdx b/site/src/content/docs/feedback/sheet.mdx
index ddb51283..1354cbac 100644
--- a/site/src/content/docs/feedback/sheet.mdx
+++ b/site/src/content/docs/feedback/sheet.mdx
@@ -1,6 +1,6 @@
 ---
 title: Sheet
-description: A mobile-first bottom sheet with swipe to dismiss that becomes a centered dialog from 768px.
+description: A mobile-first bottom sheet with swipe to dismiss that becomes a centered dialog from 900px.
 group: Feedback
 order: 4
 ---
@@ -23,14 +23,14 @@ import FooterSrc from "~/demos/feedback/sheet/Footer.svelte?raw";
 </Sheet>
 ```
 
-Below 768px the sheet rises from the bottom edge with a drag handle, safe-area padding and rounded top corners. From 768px up it renders as a centered dialog. Focus trap, focus restore, Escape, overlay dismissal and scroll lock come from the native modal `<dialog>` the sheet renders.
+Below 900px the sheet rises from the bottom edge with a drag handle, safe-area padding and rounded top corners. From 900px up it renders as a centered dialog. Focus trap, focus restore, Escape, overlay dismissal and scroll lock come from the native modal `<dialog>` the sheet renders.
 
 **Swipe to dismiss.** Drag the handle or the header down. Releasing past 30% of the panel height, or faster than 0.5 px/ms, closes the sheet; otherwise it springs back. The gesture is off under `prefers-reduced-motion` and in the centered desktop layout. Keyboard users close it with Escape or the close button. Open the demos below on a phone or in a mobile viewport to try the gesture.
 
-<Demo title="Swipe to dismiss" description="Drag the handle or header down on a viewport below 768px. Above that, it is a centered dialog." src={SwipeSrc}><Swipe client:visible /></Demo>
+<Demo title="Swipe to dismiss" description="Drag the handle or header down on a viewport below 900px. Above that, it is a centered dialog." src={SwipeSrc}><Swipe client:visible /></Demo>
 <Demo title="Footer and swipeToDismiss" description="A pinned footer, and swipeToDismiss set to false so only the close button, Escape and the overlay dismiss it." src={FooterSrc}><Footer client:visible /></Demo>
 
-<Props rows={[
+<Props for="Sheet" rows={[
   { name: "open", type: "boolean", default: "false", description: "Bindable open state." },
   { name: "title", type: "string", description: "Header title. Without it the panel falls back to a localized generic aria-label." },
   { name: "description", type: "string", description: "Supporting text under the title." },
diff --git a/site/src/content/docs/feedback/skeleton.mdx b/site/src/content/docs/feedback/skeleton.mdx
index ccf2d38a..f87274de 100644
--- a/site/src/content/docs/feedback/skeleton.mdx
+++ b/site/src/content/docs/feedback/skeleton.mdx
@@ -23,13 +23,13 @@ import ImageSrc from "~/demos/feedback/skeleton/Image.svelte?raw";
 <Skeleton rows={3} />
 ```
 
-Skeletons are `aria-hidden`. Announce the loading state on the container (for example `aria-busy="true"`) rather than on each placeholder.
+Skeletons are `aria-hidden`. Announce the loading state on the container, for example with `aria-busy="true"`, and leave the placeholders silent.
 
 <Demo title="Text lines" description="With rows, the last line is shortened to 60% for a natural paragraph." src={TextLinesSrc}><TextLines /></Demo>
 <Demo title="Card layout" src={CardLayoutSrc}><CardLayout /></Demo>
 <Demo title="Image placeholder" src={ImageSrc}><Image /></Demo>
 
-<Props rows={[
+<Props for="Skeleton" rows={[
   { name: "variant", type: "'text' | 'circular' | 'rectangular' | 'rounded'", default: "'text'", description: "Shape of the placeholder." },
   { name: "width", type: "string | number", description: "CSS width. Numbers are treated as pixels." },
   { name: "height", type: "string | number", description: "CSS height. Numbers are treated as pixels." },
diff --git a/site/src/content/docs/feedback/spinner.mdx b/site/src/content/docs/feedback/spinner.mdx
index b03000bc..f16b11f8 100644
--- a/site/src/content/docs/feedback/spinner.mdx
+++ b/site/src/content/docs/feedback/spinner.mdx
@@ -27,7 +27,7 @@ The spinner has `role="status"` and a localized `aria-label`. Under `prefers-red
 <Demo title="In a button" description="Use the loading prop of Button instead of placing a Spinner by hand." src={InButtonSrc}><InButton client:visible /></Demo>
 <Demo title="Section loader" src={SectionLoaderSrc}><SectionLoader /></Demo>
 
-<Props rows={[
+<Props for="Spinner" rows={[
   { name: "size", type: "number | string", default: "24", description: "Diameter. Numbers are pixels; strings are any CSS length." },
   { name: "label", type: "string", default: "'Loading…' (localized)", description: "Accessible label. Defaults to the active locale's string." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
diff --git a/site/src/content/docs/feedback/toast.mdx b/site/src/content/docs/feedback/toast.mdx
index bb36db7f..aefbfac8 100644
--- a/site/src/content/docs/feedback/toast.mdx
+++ b/site/src/content/docs/feedback/toast.mdx
@@ -9,25 +9,34 @@ import Props from "~/components/docs/Props.astro";
 import Toasts from "~/demos/feedback/toast/Toasts.svelte";
 import ToastsSrc from "~/demos/feedback/toast/Toasts.svelte?raw";
 
+Mount `Toaster` once in the root layout:
+
 ```svelte
-<!-- +layout.svelte: mount once -->
+<!-- +layout.svelte -->
 <script>
   import { Toaster } from "@codeatlasdev/ui";
+  let { children } = $props();
 </script>
+
+{@render children()}
 <Toaster />
+```
 
-<!-- anywhere -->
+Then call `toast` from anywhere:
+
+```svelte
 <script>
   import { toast } from "@codeatlasdev/ui";
 </script>
+
 <button onclick={() => toast.success("Changes saved.")}>Save</button>
 ```
 
-`toast` is a global store, so the calls need no component context. The Toaster is a polite live region (`role="region"`, `aria-live="polite"`) and each toast is a `role="status"`. Toasts stack in the bottom right corner. The demo below mounts its own `Toaster` because every demo is an independent island.
+`toast` is a global store, so the calls need no component context. The Toaster is a polite live region (`role="region"`, `aria-live="polite"`) and each toast is a `role="status"` with a dismiss button. Toasts stack in the bottom right corner, up to 380px wide, in a fixed container layered with `--ca-z-snackbar` (they are not in the browser top layer, unlike dialogs and popovers). `toast.show` accepts `variant` and `duration` in its options; the shortcut methods take the duration as a second argument. The demo below mounts its own `Toaster` because every demo is an independent island.
 
 <Demo title="Variants and duration" description="Five variants, plus persistent (duration 0) and custom durations. The default auto-dismiss is 4 seconds." src={ToastsSrc}><Toasts client:visible /></Demo>
 
-<Props title="API" rows={[
+<Props for="none" title="API" rows={[
   { name: "toast.show(message, opts?)", type: "(message: string, opts?: { variant?: ToastVariant; duration?: number }) => string", description: "Shows a toast and returns its id. Variant defaults to 'default'." },
   { name: "toast.success(message, duration?)", type: "(message: string, duration?: number) => string", description: "Success toast." },
   { name: "toast.error(message, duration?)", type: "(message: string, duration?: number) => string", description: "Error toast." },
diff --git a/site/src/content/docs/foundation/materials.mdx b/site/src/content/docs/foundation/materials.mdx
index 3b707f28..c8ce8190 100644
--- a/site/src/content/docs/foundation/materials.mdx
+++ b/site/src/content/docs/foundation/materials.mdx
@@ -1,6 +1,6 @@
 ---
 title: Materials
-description: Liquid Glass material tiers from ultra-thin translucency to opaque chrome, plus tint, glow and button variants.
+description: The five material tiers behind every surface, from ultra-thin translucency to chrome, and how the surface style changes them.
 group: Foundation
 order: 4
 ---
@@ -13,7 +13,7 @@ import GlassButtonsSrc from "~/demos/foundation/materials/GlassButtons.svelte?ra
 import Tinted from "~/demos/foundation/materials/Tinted.svelte";
 import TintedSrc from "~/demos/foundation/materials/Tinted.svelte?raw";
 
-Materials are CSS classes (`glass-ultra-thin`, `glass-thin`, `glass-regular`, `glass-thick`, `glass-chrome`) backed by `backdrop-filter`. [Surface](/docs/surfaces/surface/) applies a material for you from its `material` and `elevation` props, and adds the refraction layer for `material="liquid"`.
+Materials are CSS classes (`glass-ultra-thin`, `glass-thin`, `glass-regular`, `glass-thick`, `glass-chrome`) that read `--ca-mat-<tier>-*` tokens (blur, fill and shadow). [Surface](/docs/surfaces/surface/) paints the same five tiers for you from its `material` and `elevation` props (elevation 1 to 5 maps to ultra-thin to chrome), and adds the refraction layer for `material="liquid"`. Use the classes only for markup that is not a Surface.
 
 ```svelte
 <script>
@@ -23,8 +23,8 @@ Materials are CSS classes (`glass-ultra-thin`, `glass-thin`, `glass-regular`, `g
 <Surface material="glass" elevation={4} tone="brand">Content</Surface>
 ```
 
-The surface style on `<html data-style>` changes every material at once: `solid` (default: no blur, no glow, hairline edges), `flat` (no blur, no shadows), `frosted` (less blur) and `glass` (the opt-in `liquid` look: blur, mesh, glow). Switch it with `colorScheme.setStyle()`, see [Theming](/docs/getting-started/theming/#surface-styles). Browsers with `prefers-reduced-transparency: reduce` automatically get opaque surfaces.
+The surface style on `<html data-style>` rewrites the `--ca-mat-*` tokens, so every material changes at once. `solid` is the default: no blur, opaque fills, no glow, hairline edges, so the tiers below differ only by fill and shadow. `flat` also drops the shadows, `frosted` keeps a lighter blur, and `glass` (the opt-in `liquid` look) has the full blur, mesh and glow. The demos on this page use `material="glass"`, so they look the same under any style. Switch the style with `colorScheme.setStyle()`, see [Theming](/docs/getting-started/theming/#surface-styles). Browsers with `prefers-reduced-transparency: reduce` get opaque surfaces.
 
 <Demo title="Glass tiers" description="All five thickness levels on a gradient backdrop." src={TiersSrc}><Tiers /></Demo>
-<Demo title="Button glass variants" description="glass-btn, glass-btn-prominent and glass-btn-clear for custom controls." src={GlassButtonsSrc}><GlassButtons /></Demo>
-<Demo title="Tinted and glowing" description={"`tone=\"brand\"` tints the fill, `glow` adds a backlit halo."} src={TintedSrc}><Tinted /></Demo>
+<Demo title="Button glass variants" description="glass-btn, glass-btn-prominent and glass-btn-clear for custom controls. They follow `data-style`, so the halo and blur disappear under `solid`." src={GlassButtonsSrc}><GlassButtons /></Demo>
+<Demo title="Tinted and glowing" description={"`tone=\"brand\"` tints the fill, `glow` adds a halo that only shows under styles that keep one."} src={TintedSrc}><Tinted /></Demo>
diff --git a/site/src/content/docs/foundation/shadows.mdx b/site/src/content/docs/foundation/shadows.mdx
index c77f45b1..4714db45 100644
--- a/site/src/content/docs/foundation/shadows.mdx
+++ b/site/src/content/docs/foundation/shadows.mdx
@@ -14,6 +14,6 @@ import ScaleSrc from "~/demos/foundation/shadows/Scale.svelte?raw";
 }
 ```
 
-Light mode uses soft warm shadows, dark mode uses deeper black ones, so one token works in both. Glass surfaces rely on inset highlights and borders instead of drop shadows, see [Materials](/docs/foundation/materials/).
+The default shadows are neutral black with no hue: soft in light mode, deeper in dark mode, so one token works in both. The `flat`, `outlined` and similar styles replace them with none or a hairline ring, and the `liquid` recipe uses hue-tinted ones. [Surface](/docs/surfaces/surface/) takes its drop shadow from `elevation` (`--ca-elevation-0` to `--ca-elevation-5`), not from these tokens, see [Materials](/docs/foundation/materials/).
 
 <Demo title="Shadow scale" description="xs for hairline lift up to xl for modal depth." src={ScaleSrc}><Scale /></Demo>
diff --git a/site/src/content/docs/foundation/typography.mdx b/site/src/content/docs/foundation/typography.mdx
index efcb56f6..ef00d685 100644
--- a/site/src/content/docs/foundation/typography.mdx
+++ b/site/src/content/docs/foundation/typography.mdx
@@ -12,7 +12,7 @@ import HeadingsSrc from "~/demos/foundation/typography/Headings.svelte?raw";
 import Body from "~/demos/foundation/typography/Body.svelte";
 import BodySrc from "~/demos/foundation/typography/Body.svelte?raw";
 
-Type sizes are `rem` tokens, so they follow the user's browser font size. Fonts are stacks: load Inter and JetBrains Mono yourself (for example with `@fontsource-variable`) or replace them in your theme.
+Type sizes are `rem` tokens multiplied by `--ca-font-scale`, so they follow the user's browser font size. Fonts are stacks: the defaults name Inter and JetBrains Mono but the kit does not load them, so load them yourself (for example with `@fontsource-variable`) or replace them in your theme. `--ca-font-display` defaults to `--ca-font-sans`.
 
 ```ts
 import { defineTheme } from "@codeatlasdev/ui";
@@ -24,7 +24,7 @@ export const theme = defineTheme({
 
 `fonts.body`, `fonts.mono` and `fonts.display` set `--ca-font-sans`, `--ca-font-mono` and `--ca-font-display`. See [Theming](/docs/getting-started/theming/).
 
-Text-entry controls use `--ca-input-font-size`, which is raised to at least 16px on touch and small screens so iOS Safari does not zoom into focused fields. See [Mobile](/docs/getting-started/mobile/).
+Text-entry controls use `--ca-input-font-size`, which is raised to at least 16px on touch devices and below 900px so iOS Safari does not zoom into focused fields. See [Mobile](/docs/getting-started/mobile/).
 
 <Demo title="Font families" src={FamiliesSrc}><Families /></Demo>
 <Demo title="Heading scale" description="--ca-font-size-h1 to h6." src={HeadingsSrc}><Headings /></Demo>
diff --git a/site/src/content/docs/getting-started/accessibility.mdx b/site/src/content/docs/getting-started/accessibility.mdx
index 467f865f..c5f7e437 100644
--- a/site/src/content/docs/getting-started/accessibility.mdx
+++ b/site/src/content/docs/getting-started/accessibility.mdx
@@ -15,7 +15,7 @@ Interactive components run on a headless layer of our own that implements the WA
 | Area | Behavior |
 |---|---|
 | Focus ring | Every focusable component draws a 2px outline in `--ca-focus-ring` with a 2px offset. The generator solves the token per preset and scheme to keep 3:1 against every surface and the hover/selected fills; override the one token (never `--ca-brand-main`) to recolor all rings. Never remove it. |
-| Overlays | `Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `Popover` and menus trap focus, restore it on close, close on Escape and lock page scroll. |
+| Overlays | Modal layers (`Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `CommandPalette`, `Lightbox`) are native `<dialog>` elements: the page behind is inert, focus is trapped and restored on close, Escape closes and page scroll is locked. Popovers and menus (`Popover`, `DropdownMenu`, `Select`, `Combobox`, date pickers) sit in the top layer without making the page inert: Escape or a press outside closes them and focus returns to the trigger. |
 | Keyboard | Tabs, menus, selects, comboboxes, the command palette, date pickers, toggle groups and segmented controls follow their WAI-ARIA keyboard patterns. |
 | Names | `IconButton` requires `aria-label` at the type level. Built-in strings (close, dismiss, copy, loading) come from the [i18n catalog](/docs/getting-started/i18n/), so they are announced in the active language. |
 | Status | `Alert` uses `role="alert"`. `Toast` items use `role="status"` inside a polite live region. `Spinner` has `role="status"` with a label, `Progress` has `role="progressbar"` with `aria-valuenow`. `CopyButton` announces "Copied" through the shared [live region](#announcements). |
@@ -23,13 +23,13 @@ Interactive components run on a headless layer of our own that implements the WA
 | Forms | `TextField` and the other fields link hint and error text with `aria-describedby` and set `aria-invalid` on error. Errors render with `role="alert"`. |
 | Touch targets | Controls grow to 44px (`--ca-touch-target`) under `(pointer: coarse)`. |
 | Zoom | The package never disables zoom. Fields are 16px on touch so iOS does not zoom on focus, see [Mobile](/docs/getting-started/mobile/#input-font-size). |
-| Skip link | `AppShellLayout`, `DocsShell` and `AuthLayout` render a [`SkipLink`](#skip-link) as the first focusable element and own the `#main` target. |
+| Skip link | `AppShellLayout`, `DocsShell` and `AuthLayout` render a [`SkipLink`](#skip-link-and-landmarks) as the first focusable element and own the `#main` target. |
 | Forced colors | Under `forced-colors: active` glass, blur and shadows are removed, surfaces get a `CanvasText` border and focus uses `Highlight`. |
 | Increased contrast | Under `prefers-contrast: more`, `--ca-text-secondary`, `--ca-text-hint` and `--ca-outline-*` reach at least 7:1 (outlines 3:1 or more) in every built-in and brand preset. |
 
 ## Motion
 
-When the user prefers reduced motion, `--ca-duration-fast`, `--ca-duration-base` and `--ca-duration-slow` become `0ms`, so every token-driven transition is instant. Components with JavaScript-driven motion check the `reducedMotion` store: `Sheet` disables its swipe spring and `SegmentedControl` turns off its indicator animation.
+When the user prefers reduced motion, `--ca-motion-scale` becomes `0`. Every duration token (`--ca-duration-fast`, `--ca-duration-base`, `--ca-duration-slow`, `--ca-duration-press`) is multiplied by it, so every token-driven transition is instant. Components with JavaScript-driven motion check the `reducedMotion` store: `Sheet` disables its swipe, `AppShellLayout` skips the panel spring and `SegmentedControl` turns off its indicator animation.
 
 ```ts
 import { reducedMotion, reducedTransparency } from "@codeatlasdev/ui";
diff --git a/site/src/content/docs/getting-started/ai-agents.mdx b/site/src/content/docs/getting-started/ai-agents.mdx
index 2c10bc38..e4303c28 100644
--- a/site/src/content/docs/getting-started/ai-agents.mdx
+++ b/site/src/content/docs/getting-started/ai-agents.mdx
@@ -19,20 +19,20 @@ This site publishes its documentation in plain text for tools that cannot render
 |---|---|
 | [`/llms.txt`](/llms.txt) | Index: one line per documentation page with title, link and description. |
 | [`/llms-full.txt`](/llms-full.txt) | Every page concatenated as markdown, with code fences intact, followed by the full `AGENTS.md`. Paste it, or let a tool fetch it, when you want everything in one context. |
-| [Agent guide](https://github.com/codeatlasdev/ui/blob/main/AGENTS.md) | `AGENTS.md` in the repository: critical rules, spacing and token reference, page template patterns, store and theme setup. Written in Portuguese. |
+| [Agent guide](https://github.com/codeatlasdev/ui/blob/main/AGENTS.md) | `AGENTS.md` in the repository: critical rules, spacing and token reference, page template patterns, store and theme setup. |
 
 Every page is also linked with `<link rel="alternate" type="text/plain" href="/llms.txt">` in its head.
 
 ## MCP server
 
-`ca-ui-mcp` is a local [Model Context Protocol](https://modelcontextprotocol.io) server that ships with the package. It reads the manifests generated from the component source at build time, so it works offline and always matches the installed version.
+`ca-ui-mcp` is a local [Model Context Protocol](https://modelcontextprotocol.io) stdio server that ships with the package. It reads the manifests generated from the component source at build time (`components.json`, `tokens.json` and `guides.json`), so it works offline and always matches the installed version.
 
 | Tool | Returns |
 |---|---|
 | `list_components` | Every component with its import path and a one-line description. Optional `query` filter. |
-| `get_component` | One component's props (type, default, `bind:` or not, docs), snippets and public `ca-*` classes. The name is case-insensitive: `get_component("app list")` finds `AppList`. |
+| `get_component` | One component's import path, props (type, default, `bind:` or not, docs), snippets and public `ca-*` classes. The name is case-insensitive and forgives spaces, `-` and `_`: `get_component("app list")` finds `AppList`. |
 | `get_export` | Signature and summary of any non-component export: functions, stores, constants and types of every entry point (`setLocale`, `toast`, `caErrorPlugin` from `/vite`, `createErrorHandler` and `nativeFeel` from `/kit`, `primeKeyboard` from `/actions`). Without a name it lists them all with their import path. |
-| `search_tokens` | `--ca-*` design tokens matching a name, value or section, with light and dark values. |
+| `search_tokens` | `--ca-*` design tokens matching a name, value or section, with light and dark values (the first 60 matches). |
 | `get_guide` | A documentation page as markdown, by slug (`getting-started/theming`) or title. Without a name it lists every guide. |
 
 Prop names are never guessed: an agent asks the server and gets the types the compiler sees.
@@ -53,14 +53,14 @@ The same data is available as files: `@codeatlasdev/ui/components.json` (compone
 bunx @codeatlasdev/ui init
 ```
 
-`init` detects SvelteKit or Astro and wires up what the [installation](/docs/getting-started/installation/) page describes: `src/lib/theme.ts`, the theme hook or integration, the `global.css` import, `colorScheme.init()` in the root layout and a mobile-ready viewport meta. It creates files that are missing and **never overwrites** one that exists: it prints a diff instead, and `--write` applies it. Running it twice changes nothing.
+`init` detects SvelteKit or Astro and wires up what the [installation](/docs/getting-started/installation/) page describes: the theme file, the theme hook or integration, the `global.css` import, `colorScheme.init()` and a mobile-ready viewport meta. It creates files that are missing and never overwrites one that exists: it prints a diff instead, and `--write` applies it. `--dir <path>` runs it on another project directory. Running it twice changes nothing.
 
 ```sh
 bunx @codeatlasdev/ui migrate          # print the diff
 bunx @codeatlasdev/ui migrate --write  # apply it
 ```
 
-`migrate` rewrites code for renamed APIs by parsing `.svelte`, `.ts` and `.astro` files, so only real references change (not strings or same-named identifiers from other packages). Today it renames the `BrandPreset` type to `PresetDefinition`.
+`migrate` rewrites code for renamed APIs by parsing `.svelte`, `.ts`, `.js` and `.astro` files (it walks `src` by default, or the paths you pass), so only real references change (not strings or same-named identifiers from other packages). It renames the `BrandPreset` type to `PresetDefinition` and moves the deprecated `GlassCard`, `GlassSurface` and `Row` to `Card`, `Surface` and `Flex`; an element with a dynamic prop it cannot map is left as it was.
 
 ## Install the skills
 
@@ -84,7 +84,7 @@ npx skills add codeatlasdev/ui
 
    ```md
    This project uses @codeatlasdev/ui (Svelte 5). Docs for agents: https://ui.codeatlas.com.br/llms.txt
-   Read https://ui.codeatlas.com.br/llms-full.txt before writing UI. Never write layout CSS; use Grid, Row, Stack and --ca-* tokens.
+   Read https://ui.codeatlas.com.br/llms-full.txt before writing UI. Never write layout CSS; use Grid, Flex, Stack and --ca-* tokens.
    ```
 
 2. **Cursor.** Add `https://ui.codeatlas.com.br/llms-full.txt` as a custom doc source in Cursor's settings, or put the same instructions in a project rule so every chat starts with them.
@@ -99,7 +99,7 @@ These come from the agent guide and prevent the most common mistakes:
 
 - Import everything from `@codeatlasdev/ui`, never from internal paths. Charts, DataTable and CodeSnippet come from the `/charts`, `/table` and `/code` subpaths.
 - Import `global.css` once, in the root layout, and call `colorScheme.init()` there.
-- No layout CSS and no hardcoded colors. Use `Grid`, `Row` and `Stack` with a numeric `gap`, and `--ca-*` tokens.
+- No layout CSS and no hardcoded colors. Use `Grid`, `Flex` and `Stack` with a numeric `gap`, and `--ca-*` tokens.
 - No inline `padding` or `margin`. Inline styles are only for dynamic custom properties such as `style="--bar-w:{pct}%"`.
 - Build pages with `AppList`, `AppForm`, `AppSettings` or `PageShell`, not hand-made wrappers. Put `AppShellLayout` only in authenticated route layouts.
 - Svelte 5 runes only (`$state`, `$derived`, `$props`). No stores from `svelte/store`, no `svelte:component`.
@@ -112,7 +112,7 @@ These come from the agent guide and prevent the most common mistakes:
 
 ## Why it works
 
-- **Page-level components.** The agent chooses a template, not forty primitives.
-- **Closed prop vocabularies.** `variant`, `size` and `severity` are string unions, not free-form classes.
-- **One token system.** There is one place for color, radius, spacing and type, so output stays consistent across generations.
-- **Tested for accessibility.** Components are checked with axe, so generated pages start from an accessible baseline, see [Accessibility](/docs/getting-started/accessibility/).
+- Page-level components: the agent chooses a template, not forty primitives.
+- Closed prop vocabularies: `variant`, `size` and `severity` are string unions, not free-form classes.
+- One token system: there is one place for color, radius, spacing and type, so output stays consistent across generations.
+- Tested for accessibility: components are checked with axe, so generated pages start from an accessible baseline, see [Accessibility](/docs/getting-started/accessibility/).
diff --git a/site/src/content/docs/getting-started/i18n.mdx b/site/src/content/docs/getting-started/i18n.mdx
index 3ab9a030..ab799a8d 100644
--- a/site/src/content/docs/getting-started/i18n.mdx
+++ b/site/src/content/docs/getting-started/i18n.mdx
@@ -64,6 +64,8 @@ Then use it with `<I18nProvider locale="es">` or `setLocale("es")`. Region tags
 
 ```svelte
 <I18nProvider locale="en" messages={{ docs: { toc: "In this article" }, common: { copy: "Copy link" } }}>
+  {@render children()}
+</I18nProvider>
 ```
 
 A later `setLocale` call replaces the previous overrides. Message functions (strings with runtime values) keep their signature:
@@ -114,7 +116,7 @@ Inside an `I18nProvider`, read the active locale and messages from context with
 
 ## Catalog
 
-The catalog is grouped by component, for example `docs.search.placeholder`, `dialog.close`, `pagination.nextPage`, `fileUpload`, `dataTable` and `toast`. English (`en.ts`) is the source of truth; `pt-BR.ts` is typed against it, so a missing key is a type error. Both locales are tested to have identical keys.
+The catalog is grouped by component, for example `docs.search.placeholder`, `dialog.close`, `pagination.next`, `fileUpload`, `dataTable` and `toast`. English (`en.ts`) is the source of truth; `pt-BR.ts` is typed as `Messages`, so a missing key is a type error. A test checks that both locales have identical keys.
 
 ## Server errors
 
diff --git a/site/src/content/docs/getting-started/installation.mdx b/site/src/content/docs/getting-started/installation.mdx
index ca657329..7f0ebf94 100644
--- a/site/src/content/docs/getting-started/installation.mdx
+++ b/site/src/content/docs/getting-started/installation.mdx
@@ -7,7 +7,7 @@ order: 1
 import { Callout, Steps } from "@codeatlasdev/ui";
 import CodeGroup from "~/components/docs/CodeGroup.astro";
 
-CodeAtlas UI needs Svelte 5 (runes mode). In a SvelteKit or Astro app, `bunx @codeatlasdev/ui init` does the whole setup below for you, and prints a diff instead of overwriting any file that already exists. Setup is three things: import the stylesheet once, inject the theme script before first paint, and start the `colorScheme` store in your root layout.
+CodeAtlas UI needs Svelte 5 (runes mode). In a SvelteKit or Astro app, `bunx @codeatlasdev/ui init` does the whole setup below for you (see [The `init` command](#the-init-command)). Setup is three things: import the stylesheet once, inject the theme script before first paint, and start the `colorScheme` store in your root layout.
 
 <CodeGroup sync="pm" tabs={[
   { label: "bun", code: "bun add @codeatlasdev/ui" },
@@ -23,34 +23,64 @@ The core bundle stays small. Heavy features are separate entry points with optio
 | DataTable | `@codeatlasdev/ui/table` | `@tanstack/svelte-table` |
 | CodeSnippet | `@codeatlasdev/ui/code` | `shiki` |
 | Masked and money fields | `@codeatlasdev/ui/forms` | nothing |
+| Accessibility test helpers | `@codeatlasdev/ui/testing` | `axe-core` |
+| Brand icons (`caBrandPlugin`) | `@codeatlasdev/ui/vite` | `@resvg/resvg-js` and `png-to-ico` |
+| `migrate` command | `bunx @codeatlasdev/ui migrate` | `typescript` |
 
-Icons come from `@lucide/svelte`, which the package already depends on.
+`@sveltejs/kit` and `astro` are optional peers too: install the one your app uses. Icons come from `@lucide/svelte`, which the package already depends on.
 
 ### Release channels
 
-| Channel | Install | When to use it |
+Releases are published by version tag (`@codeatlasdev/ui@X.Y.Z`), not from branches. The prerelease id in the version is the npm dist-tag.
+
+| Version | Install | When to use it |
 |---|---|---|
-| `latest` | `bun add @codeatlasdev/ui` | Production. Semver: breaking changes only in a major. |
-| `beta` | `bun add @codeatlasdev/ui@beta` | The next minor, feature-complete. Try it before it ships. |
-| `alpha` | `bun add @codeatlasdev/ui@alpha` | The next major while it is still moving. Expect breaking changes between alphas. |
+| `X.Y.Z` | `bun add @codeatlasdev/ui` (dist-tag `latest`) | Production. Semver: breaking changes only in a major. |
+| `X.Y.Z-beta.N` | `bun add @codeatlasdev/ui@beta` | A prerelease of the next version. It never moves `latest`. Try it before it ships. |
+
+A prerelease with another id (`X.Y.Z-alpha.N`, for example) is published under a dist-tag with that id. Pin an exact version (`bun add @codeatlasdev/ui@3.1.0-beta.2`) to keep a prerelease stable.
 
 Every version is published from CI with an npm provenance statement, so you can check which commit and workflow built it (`npm audit signatures`).
 
+## The `init` command
+
+```sh
+bunx @codeatlasdev/ui init [--write] [--dir <path>]
+```
+
+`init` detects the framework from `package.json` (`@sveltejs/kit` means SvelteKit, otherwise `astro` means Astro) and prints `Detected SvelteKit.` or `Detected Astro.`. With neither it prints an error and exits with code 1. Then it goes through the files of that framework, one line each:
+
+| Line | Meaning |
+|---|---|
+| `create  <file>` | The file was missing and is now written. |
+| `ok      <file> (already set up)` | Nothing to change. Running `init` again on a finished setup prints only `ok` lines. |
+| `diff    <file> (exists, not modified)` | The file exists and needs a change. A unified diff follows; nothing is written until you re-run with `--write`. |
+| `patch   <file>` | The change was applied (`--write`). |
+| `manual  <file>: could not patch safely.` | `init` could not edit the file safely (no `plugins: [...]` array, an existing `handle` of your own, no `</body>`). It says what to add by hand and exits with code 1. |
+| `skip    <file> (not found)` | The file does not exist and `init` does not create it (`vite.config.ts`, `src/app.html` and the Astro config). |
+
+| Flag | Effect |
+|---|---|
+| `--write` | Apply the proposed changes to existing files. Files that do not exist yet are always created. |
+| `--dir <path>` | Project directory. Defaults to the current directory. |
+
+When diffs are pending it ends with `N existing file(s) left untouched. Re-run with --write to apply the diffs above.` A clean run ends with `Done. Run your dev server: the theme paints on the first frame.`
+
 ## SvelteKit
 
-`@codeatlasdev/ui` supports SvelteKit 2 (`^2.12`) and SvelteKit 3. The steps below are the same on both; the differences are in [SvelteKit 3](#sveltekit-3). `bunx @codeatlasdev/ui init` reads the installed Kit version and writes the right imports.
+`@codeatlasdev/ui` supports SvelteKit 2 (`^2.12`) and SvelteKit 3. The steps below are the same on both; the differences are in [SvelteKit 3](#sveltekit-3). `init` reads the installed Kit major (`node_modules/@sveltejs/kit`, or the range in `package.json` before `install` ran; anything it cannot parse counts as 2) and writes the right theme import.
 
 ### What `init` writes
 
-`bunx @codeatlasdev/ui init` creates the files below when they are missing. A file that already exists is never overwritten: `init` prints a diff and applies it only with `--write`. Re-running it changes nothing once the setup is complete.
+For each file below, `init` creates it when it is missing, except `vite.config.ts` and `src/app.html`, which it only patches (it prints `skip` when they are not there). A file that already exists is never overwritten: `init` prints a diff and applies it only with `--write`. Re-running it changes nothing once the setup is complete.
 
 | File | What `init` puts there | If the file exists |
 |---|---|---|
-| `src/lib/theme.ts` | the shared `theme` object | left alone |
-| `vite.config.ts` | `caThemePlugin(theme)` and `caErrorPlugin({ scaffold: true })`, after `sveltekit()`, in one `@codeatlasdev/ui/vite` import | adds only the plugin that is missing |
+| `src/lib/theme.ts` | the shared `theme` object (`defaultPreset: "amber"`, `defaultScheme: "system"`) | left alone |
+| `vite.config.ts` | `caThemePlugin(theme)` and `caErrorPlugin({ scaffold: true })`, appended to `plugins`, in one `@codeatlasdev/ui/vite` import (plus `import { theme } from "./src/lib/theme.ts"`) | adds only the plugin that is missing |
 | `src/hooks.server.ts` | `handle = sequence(caThemeHandle(theme))` and `handleError = createErrorHandler()` | adds only what is missing; reports `manual` if you already define a `handle` of your own; never touches your `handleError` |
 | `src/routes/+layout.svelte` | the stylesheet import and `colorScheme.init()` in `onMount` | adds only the missing import or call |
-| `src/app.html` | the viewport meta with `viewport-fit=cover, interactive-widget=resizes-content` | rewrites only the viewport meta |
+| `src/app.html` | the viewport meta with `viewport-fit=cover, interactive-widget=resizes-content` | rewrites only the viewport meta; reports `manual` when there is none |
 
 `caErrorPlugin({ scaffold: true })` then creates `src/routes/+error.svelte` and `src/error.html` the first time Vite runs (dev or build), and never overwrites them. The result is the setup below, which you can also write by hand.
 
@@ -129,7 +159,7 @@ Every version is published from CI with an npm provenance statement, so you can
 
 ### SvelteKit 3
 
-Kit 3 changed three things this setup touches. `init` handles the first and reports the other two (it never rewrites `svelte.config.js` or `tsconfig.json`).
+Kit 3 changed three things this setup touches. `init` handles the third (the theme import in the hook) and, for the other two, prints a `note` line instead of rewriting `svelte.config.js` or `tsconfig.json`: it reports `svelte.config.js`/`.ts`/`.mjs` when one exists, and a `tsconfig.json` that does not mention `$app/tsconfig`. On a clean Kit 3 run you get no `Done.` line while a note is pending.
 
 1. **Configuration moves into the Vite plugin.** `svelte.config.js` is ignored (`config_file_unsupported`) and the `kit` namespace is gone (`config_kit_namespace`). Pass the options directly to `sveltekit()`, next to the two plugins:
 
@@ -163,7 +193,14 @@ Kit 3 changed three things this setup touches. `init` handles the first and repo
 
 ## Astro
 
-Use the integration together with `@astrojs/svelte`. `caUI` injects the theme into the `<head>` of every page and handles the SSR bundling.
+Use the integration together with `@astrojs/svelte`. `caUI` injects the theme into the `<head>` of every page and handles the SSR bundling. `bunx @codeatlasdev/ui init` sets this up for an Astro project:
+
+| File | What `init` puts there | If the file exists |
+|---|---|---|
+| `src/theme.ts` | the shared `theme` object (`defaultPreset: "amber"`, `defaultScheme: "system"`) | left alone |
+| `astro.config.mjs` (or `.ts`, `.js`, `.mts`) | `caUI(theme)` first in `integrations`, with its two imports | adds `caUI(theme)` unless `caUI(` is already there; reports `manual` when there is no `integrations: [` array |
+| the first `.astro` file in `src/layouts` that renders `<html>` | the stylesheet import, the viewport meta and a client `<script>` that calls `colorScheme.init()` | adds only what is missing; reports `manual` when there is no `</body>` for the script |
+| `src/layouts/Base.astro` | created only when `src/layouts` has no layout that renders `<html>` | not applicable |
 
 ```sh
 bun add @codeatlasdev/ui @astrojs/svelte svelte
@@ -183,26 +220,34 @@ export default defineConfig({ integrations: [svelte(), caUI(theme)] });
 // src/theme.ts
 import type { ThemeOptions } from "@codeatlasdev/ui/astro";
 
-export const theme: ThemeOptions = { defaultPreset: "amber", defaultScheme: "dark" };
+export const theme: ThemeOptions = { defaultPreset: "amber", defaultScheme: "system" };
 ```
 
-Import the stylesheet once in your base layout and add the viewport meta:
+Import the stylesheet once in your base layout, add the viewport meta and start the store from a client script, so theme switches and OS scheme changes stay in sync on the page:
 
 ```astro
 ---
 // src/layouts/Base.astro
 import "@codeatlasdev/ui/styles/global.css";
 ---
+<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
+    <title>My app</title>
   </head>
-  <body><slot /></body>
+  <body>
+    <slot />
+    <script>
+      import { colorScheme } from "@codeatlasdev/ui";
+      colorScheme.init();
+    </script>
+  </body>
 </html>
 ```
 
-Components are Svelte islands. Add a client directive to anything interactive (`client:visible` or `client:load`); purely visual components render on the server with no JavaScript. In islands, call `colorScheme.init()` from one island that is always on the page, such as your header, or from a small script.
+Components are Svelte islands. Add a client directive to anything interactive (`client:visible` or `client:load`); purely visual components render on the server with no JavaScript. Call `colorScheme.init()` once per page, from that layout script or from one island that is always present.
 
 <Callout type="note">
   Astro needs `astro` 5, 6 or 7 as a peer. Components that read `colorScheme` render correctly on the server because the init script sets `class="dark"` and `data-preset` before the stylesheet applies.
diff --git a/site/src/content/docs/getting-started/mobile.mdx b/site/src/content/docs/getting-started/mobile.mdx
index b0a6cc6b..3489765c 100644
--- a/site/src/content/docs/getting-started/mobile.mdx
+++ b/site/src/content/docs/getting-started/mobile.mdx
@@ -98,7 +98,7 @@ On a touch device, `autofocus` and `focusTextField` only focus when the keyboard
 
 ## Input font size
 
-Safari zooms the page when a focused field computes under 16px. `base.css` raises every text-entry control (`input`, `textarea`, `select`, `[contenteditable]`) to `max(16px, 1em)` under `(pointer: coarse), (max-width: 767px)`, with zero specificity (`:where()`) so an app can still opt a field out. Package controls read `--ca-input-font-size`, which does the same. In your own fields, use the token:
+Safari zooms the page when a focused field computes under 16px. `base.css` raises every text-entry control (`input` except checkbox, radio, range, file, color and hidden, plus `textarea`, `select` and `[contenteditable]`) to `max(16px, 1em)` under `(pointer: coarse), (max-width: 899.98px)`, with zero specificity (`:where()`) so an app can still opt a field out. Package controls read `--ca-input-font-size`, which does the same under that query. In your own fields, use the token:
 
 ```css
 .my-field input {
@@ -110,10 +110,10 @@ Safari zooms the page when a focused field computes under 16px. `base.css` raise
 
 Mobile browsers tint their status bar and toolbar from the page. The package feeds each engine what it reads:
 
-- **`<html>` has a solid background.** `base.css` sets `html { background-color: var(--ca-surface-base) }` and keeps `body` transparent. The decorative mesh lives in `body::before`, because browsers sample the real background and never pseudo-elements. The same color shows in the overscroll area.
-- **`--ca-chrome-surface` is opaque.** `MobileHeader` and `BottomNav` use it as `background-color`, so the strip under the notch and the home indicator matches the bar.
-- **`<meta name="theme-color">` follows what is painted.** The init script sets it from the preset before first paint. After `colorScheme.init()`, a small sync keeps it equal to the opaque color under the top edge of the screen: an opaque header, a [theme island](/docs/getting-started/theming/#theme-islands) or the page itself. It updates on theme changes, route changes and scroll. This is what Chrome and Samsung Internet on Android, Safari 18 and earlier, and installed PWAs use.
-- **Safari 26** ignores `theme-color` and instead samples the background of the root and of fixed or sticky elements at the screen edges. Because those are solid colors, both paths show the same result.
+- `<html>` has a solid background. `base.css` sets `html { background-color: var(--ca-surface-base) }` and keeps `body` transparent. The decorative mesh (drawn only by the `glass` and `frosted` styles, or by `paper: "mesh"`) lives in `body::before`, because browsers sample the real background and never pseudo-elements. The same color shows in the overscroll area.
+- `--ca-chrome-surface` is opaque. `MobileHeader` and `BottomNav` use it as `background-color`, so the strip under the notch and the home indicator matches the bar.
+- `<meta name="theme-color">` follows what is painted. The init script sets it from the preset before first paint. After `colorScheme.init()`, a small sync keeps it equal to the opaque color under the top edge of the screen: an opaque header, a [theme island](/docs/getting-started/theming/#theme-islands) or the page itself. It re-samples on theme and DOM changes, scroll, resize and when the tab returns to the foreground. This is what Chrome and Samsung Internet on Android, Safari 18 and earlier, and installed PWAs use.
+- Safari 26 ignores `theme-color` and instead samples the background of the root and of fixed or sticky elements at the screen edges. Because those are solid colors, both paths show the same result.
 
 <Callout type="caution" title="Keep edge elements opaque">
   A translucent glass header at the top edge cannot be sampled correctly. Use `--ca-chrome-surface` (or any opaque color) for fixed bars on the top and bottom edges, and keep `backdrop-filter` for surfaces inside the page.
@@ -127,7 +127,7 @@ Below 900px `AppShellLayout` swaps the Rail and Panel for a `MobileHeader` and a
 
 ### MobilePane
 
-A full-screen layer above the shell for drill-down views (chat thread, history, detail), instead of a hand-written `position: fixed`. It has a header with a back button, its own scroll with `overscroll-behavior: contain`, safe areas on every side and keyboard awareness. Escape closes it, focus moves in on open and returns on close.
+A full-screen layer above the shell for drill-down views (chat thread, history, detail), instead of a hand-written `position: fixed`. It has a header with a back button, its own scroll with `overscroll-behavior: contain`, safe areas on every side and keyboard awareness. The back button and Escape set `open` to `false` and then call `onback`. Focus moves in on open and returns on close.
 
 ```svelte
 <script>
@@ -135,7 +135,7 @@ A full-screen layer above the shell for drill-down views (chat thread, history,
   let open = $state(false);
 </script>
 
-<MobilePane bind:open title="Maria" onback={() => (chatId = null)}>
+<MobilePane bind:open title="Maria" onback={() => console.log("closed")}>
   {#snippet actions()}<IconButton aria-label="More">…</IconButton>{/snippet}
   <Messages />
 </MobilePane>
@@ -145,7 +145,7 @@ Use `scroll={false}` when the body has its own scroll area and a fixed composer
 
 ### StickyActions
 
-A bar for form actions that sticks to the bottom of the scroll container, with glass chrome, safe-area padding and keyboard awareness. On wide screens it becomes an inline row.
+A bar for form actions that sticks to the bottom of the scroll container, with glass chrome, safe-area padding and keyboard awareness. From 900px up it becomes an inline row with no chrome.
 
 ```svelte
 <StickyActions align="stretch" show={dirty}>
@@ -158,7 +158,7 @@ A bar for form actions that sticks to the bottom of the scroll container, with g
 
 ### Sheet
 
-A bottom sheet below 768px and a centered dialog from 768px up. It keeps the focus trap, Escape, backdrop dismissal and scroll lock of the underlying dialog. In the bottom layout, dragging the handle or header down dismisses it (`swipeToDismiss`, default `true`). It closes past 30% of the sheet height or a fast fling, animates with a spring, and is disabled when the user prefers reduced motion.
+A bottom sheet below 900px and a centered dialog from 900px up. It keeps the focus trap, Escape, backdrop dismissal and scroll lock of the underlying dialog. In the bottom layout, dragging the handle or header down dismisses it (`swipeToDismiss`, default `true`). It closes past 30% of the sheet height or a release faster than 0.5 px/ms, otherwise it springs back, and the swipe is disabled when the user prefers reduced motion.
 
 ```svelte
 <Sheet bind:open title="Switch account" description="Choose the active session">
@@ -169,7 +169,7 @@ A bottom sheet below 768px and a centered dialog from 768px up. It keeps the foc
 
 ### AuthLayout
 
-Shows a brand strip below 768px (`mobileBrand`, default `true`). Do not build a local brand header for small screens.
+Shows a brand strip when the side panel is hidden, below 900px (`mobileBrand`, default `true`). Do not build a local brand header for small screens.
 
 ## Native feel
 
@@ -181,6 +181,6 @@ import { nativeFeel } from "@codeatlasdev/ui/kit";
 onMount(() => nativeFeel());
 ```
 
-It shows focus rings only while the user navigates with the keyboard (`html[data-kbd]`), removes the context menu and text selection on chrome (buttons, nav, tabs) while keeping them in fields and in `.ca-selectable` content, and blocks dragging links and images. `blockZoom: true` also blocks page zoom, meant for desktop shells such as Tauri only: on the web, zoom is an accessibility feature.
+It shows focus rings only while the user navigates with the keyboard (`html[data-kbd]`), removes the context menu and text selection on chrome (buttons, links, nav, header, tabs, menu items, options) while keeping them in fields and in `.ca-selectable` content, and blocks dragging links and images. `blockZoom: true` also blocks page zoom, meant for desktop shells such as Tauri only: on the web, zoom is an accessibility feature.
 
-Controls already apply `touch-action: manipulation` and a transparent tap highlight, grow to 44px under `(pointer: coarse)`, and scale slightly on press under `(hover: none)` unless the user prefers reduced motion.
+Every element gets `touch-action: manipulation` and a transparent tap highlight from `base.css`. Under `(pointer: coarse)` the control heights (`--ca-control-height`) grow to 44px, and `Button` scales slightly on press under `(hover: none)` unless the user prefers reduced motion.
diff --git a/site/src/content/docs/getting-started/performance.mdx b/site/src/content/docs/getting-started/performance.mdx
index 899c02e6..8f110d95 100644
--- a/site/src/content/docs/getting-started/performance.mdx
+++ b/site/src/content/docs/getting-started/performance.mdx
@@ -68,12 +68,12 @@ Rule of thumb: enhanced-img or `astro:assets` for photos and marketing art (they
 
 ## Fonts
 
-A web font causes two kinds of jank: the late swap that re-flows text, and the late request. `defineTheme({ fonts })` handles both. A font is either a plain stack string (as before) or a descriptor:
+A web font causes two kinds of jank: the late swap that re-flows text, and the late request. The `fonts` option of the theme handles both. A font is either a plain stack string or a descriptor:
 
 ```ts
-import { defineTheme } from "@codeatlasdev/ui";
+import type { ThemeOptions } from "@codeatlasdev/ui/vite";
 
-export const theme = defineTheme({
+export const theme: ThemeOptions = {
   fonts: {
     body: {
       family: "Inter",
@@ -86,7 +86,7 @@ export const theme = defineTheme({
     },
     mono: "ui-monospace, SFMono-Regular, Menlo, monospace", // strings still work
   },
-});
+};
 ```
 
 | Field | Effect |
diff --git a/site/src/content/docs/getting-started/pwa.mdx b/site/src/content/docs/getting-started/pwa.mdx
index 655a8b88..7a8da2f8 100644
--- a/site/src/content/docs/getting-started/pwa.mdx
+++ b/site/src/content/docs/getting-started/pwa.mdx
@@ -14,7 +14,7 @@ A progressive web app needs three pieces: a manifest (name, icons, colors), the
 
 ## Manifest
 
-`manifest()` returns the manifest object. `theme_color` and `background_color` come from the same theme definition you give `caThemeHandle`, so the splash screen and the browser chrome match the first paint.
+`manifest()` returns the manifest object. `theme_color` and `background_color` come from the same theme definition you give `caThemeHandle`: they are the surface color of the default preset in the default scheme (the dark one unless `defaultScheme` is `"light"`), the value the init script puts in `<meta name="theme-color">`. The splash screen and the browser chrome therefore match the first paint.
 
 ```ts
 // src/routes/manifest.webmanifest/+server.ts
@@ -43,10 +43,10 @@ export const GET = () =>
   );
 ```
 
-Defaults are `display: "standalone"`, `start_url: "/"` and `scope: "/"`. Pass `themeColor` or `backgroundColor` to override the derived colors.
+Defaults are `display: "standalone"`, `start_url: "/"`, `scope: "/"` and `short_name` equal to `name`. Each icon gets `type: "image/png"` unless you set one. Pass `themeColor` or `backgroundColor` (as `#rrggbb`) to override the derived colors, and `extra` for members the builder does not cover (`categories`, `screenshots`, `id`).
 
 <Callout type="caution" title="Provide a maskable icon">
-  Android crops other icons into a white tile. Keep the artwork of the `maskable` icon inside the central 80% of the canvas. `manifest()` warns when none is present.
+  Android crops other icons into a white tile. Keep the artwork of the `maskable` icon inside the central 80% of the canvas. `manifest()` logs a warning when no icon has `purpose: "maskable"`.
 </Callout>
 
 Link it from the page head with `<Seo manifest="/manifest.webmanifest" ... />`.
@@ -67,9 +67,10 @@ Safari ignores most manifest fields. `appleMeta()` returns the tags it does read
 
 | Tag | Effect |
 |---|---|
-| `apple-mobile-web-app-capable` | Opens without Safari chrome. |
-| `apple-mobile-web-app-status-bar-style` | `black-translucent` (default) draws the page under the status bar. Needs `viewport-fit=cover`; pad with `var(--ca-safe-top)`. |
-| `apple-touch-icon` | 180x180 PNG. Use an opaque image: iOS fills transparency with black. |
+| `mobile-web-app-capable` and `apple-mobile-web-app-capable` | Opens without browser chrome. |
+| `apple-mobile-web-app-status-bar-style` | `black-translucent` (default), `default` or `black`. The default draws the page under the status bar: it needs `viewport-fit=cover`; pad with `var(--ca-safe-top)`. |
+| `apple-mobile-web-app-title` | The label under the icon, emitted when you pass `title`. |
+| `apple-touch-icon` | 180x180 PNG, from `touchIcon`. Use an opaque image: iOS fills transparency with black. |
 
 ## Service worker
 
diff --git a/site/src/content/docs/getting-started/seo.mdx b/site/src/content/docs/getting-started/seo.mdx
index dc621ec2..5a3650b8 100644
--- a/site/src/content/docs/getting-started/seo.mdx
+++ b/site/src/content/docs/getting-started/seo.mdx
@@ -52,7 +52,7 @@ Place one `Seo` per page, in the route or layout that knows the page's data.
 />
 ```
 
-<Props rows={[
+<Props for="Seo" rows={[
   { name: "title", type: "string", default: "required", description: "Page title, also used for og:title." },
   { name: "titleTemplate", type: "string", default: "'%s'", description: "Wrapper for the title; %s is replaced." },
   { name: "description", type: "string", default: "-", description: "Meta description and og:description." },
@@ -60,14 +60,14 @@ Place one `Seo` per page, in the route or layout that knows the page's data.
   { name: "robots", type: "string", default: "'index,follow'", description: "Content of the robots meta." },
   { name: "noindex", type: "boolean", default: "false", description: "Shorthand for 'noindex,nofollow'. Use on admin, auth and app pages." },
   { name: "alternates", type: "{ hreflang: string; href: string }[]", default: "-", description: "Translations, including the page itself and an x-default entry." },
-  { name: "og", type: "{ type?, image?, imageAlt?, imageWidth?, imageHeight?, locale?, localeAlternates?, siteName? }", default: "-", description: "Open Graph. Image size defaults to 1200x630." },
-  { name: "twitter", type: "{ card?, site? }", default: "-", description: "Card is summary_large_image when an og image is set." },
+  { name: "og", type: "{ type?, image?, imageAlt?, imageType?, imageWidth?, imageHeight?, locale?, localeAlternates?, siteName? }", default: "-", description: "Open Graph. `type` defaults to 'website', image size to 1200x630 and `imageType` to 'image/png' (set it to 'image/jpeg' for `ogImageRoute`, which renders JPEG by default)." },
+  { name: "twitter", type: "{ card?, site? }", default: "-", description: "`card` is summary_large_image when an og image is set, otherwise summary. `site` is the @handle." },
   { name: "jsonLd", type: "object | object[]", default: "-", description: "Structured data. Serialized with '<' escaped, so values cannot close the script tag." },
   { name: "manifest", type: "string", default: "-", description: "URL of the web app manifest." },
 ]} />
 
 <Callout type="info" title="Where the dev warnings come from">
-  In development `Seo` warns when an indexable page has no `canonical`, and `caThemeHandle` warns once when the final HTML has no `viewport-fit=cover` or no `lang` on `<html>`. Production builds stay silent.
+  In development `Seo` warns when an indexable page has no `canonical`, and `caThemeHandle` warns once per problem when the final HTML has no `viewport-fit=cover`, a viewport meta that blocks zoom (`user-scalable=no`, `maximum-scale=1`) or no `lang` on `<html>`. Production builds stay silent.
 </Callout>
 
 ## Structured data
@@ -219,7 +219,9 @@ Register the plugin next to `caThemePlugin`, with the same theme object:
 
 ```ts
 // vite.config.ts
+import { sveltekit } from "@sveltejs/kit/vite";
 import { caBrandPlugin, caThemePlugin } from "@codeatlasdev/ui/vite";
+import { defineConfig } from "vite";
 import { theme } from "./src/lib/theme.ts";
 
 export default defineConfig({
@@ -231,7 +233,16 @@ export default defineConfig({
 });
 ```
 
-At build start it writes `favicon.<hash>.svg` (follows `prefers-color-scheme`), `favicon.<hash>.ico` (16, 32, 48), `favicon-32`, `apple-touch-icon` (180, opaque), `icon-192`, `icon-512`, `maskable-512` and `manifest.<hash>.webmanifest`, then `src/generated/brand.ts` with their URLs. Colors are `--ca-text-primary`, `--ca-brand-main` and `--ca-surface-base` of the theme's default preset, converted to `#rrggbb`. Add `static/brand/` and `src/generated/` to `.gitignore`: nothing it writes is meant to be committed.
+At build start it writes `favicon.<hash>.svg` (follows `prefers-color-scheme`), `favicon.<hash>.ico` (16, 32, 48), `favicon-32`, `apple-touch-icon` (180, opaque), `icon-192`, `icon-512`, `maskable-512` and `manifest.<hash>.webmanifest`, then `src/generated/brand.ts` with their URLs. `outDir` is emptied first. Colors are `--ca-text-primary`, `--ca-brand-main` and `--ca-surface-base` of the theme's default preset, converted to `#rrggbb`. Add `static/brand/` and `src/generated/` to `.gitignore`: nothing it writes is meant to be committed.
+
+| `caBrandPlugin` option | Default | Description |
+|---|---|---|
+| `mark` | `"src/brand/mark.svg"` | Path of the mark SVG, relative to the project root. The plugin warns and does nothing when it is missing. |
+| `theme` | `{}` | The same `ThemeOptions` you pass to `caThemePlugin`. |
+| `outDir` | `"static/brand"` | Directory served as `/brand`. Use `"public/brand"` with plain Vite and Astro. |
+| `base` | `"/brand"` | URL prefix of `outDir`. |
+| `manifestFile` | `"src/generated/brand.ts"` | Where the asset URLs are written, as a module exporting `brand`. |
+| `name`, `shortName` | none | Fields of the generated web app manifest. |
 
 `@resvg/resvg-js` and `png-to-ico` are optional peer dependencies. Install them where you register the plugin:
 
diff --git a/site/src/content/docs/getting-started/theming.mdx b/site/src/content/docs/getting-started/theming.mdx
index 7210cb93..5b2fc7a9 100644
--- a/site/src/content/docs/getting-started/theming.mdx
+++ b/site/src/content/docs/getting-started/theming.mdx
@@ -10,7 +10,7 @@ A theme is a plain object. The library compiles it to CSS once at build time (th
 
 ```ts
 // src/lib/theme.ts
-import type { ThemeOptions } from "@codeatlasdev/ui";
+import type { ThemeOptions } from "@codeatlasdev/ui/vite";
 
 export const theme: ThemeOptions = {
   presets: [{ id: "acme", color: "#2563eb" }],
@@ -33,13 +33,18 @@ Pass the same object to `caThemeHandle` and `caThemePlugin` (SvelteKit), `caUI`
 | `presets` | `[]` | Brand presets generated from a hex color. Built-in presets are always available. |
 | `defaultPreset` | `"amber"` | Preset used until the user picks one. Must be a built-in or one of `presets`. |
 | `defaultScheme` | `"dark"` | `"light"`, `"dark"` or `"system"`. `bunx @codeatlasdev/ui init` scaffolds `"system"`. |
-| `defaultStyle` | `"solid"` | `"solid"`, `"flat"`, `"frosted"` or `"glass"`. Solid is the sober default; glass is the opt-in [`liquid`](#the-liquid-recipe) look. |
+| `defaultStyle` | `"solid"` | Surface material: `"solid"`, `"flat"`, `"frosted"`, `"glass"`, `"outlined"`, `"neumorphic"`, `"clay"`, `"tonal"` or `"chrome"`. Solid is the sober default; glass is the opt-in [`liquid`](#the-liquid-recipe) look. |
 | `fonts` | `{}` | `body`, `mono` and `display`. Each is a font stack string or a self-hosted font descriptor (`@font-face`, preload, metric-matched fallback), see [Performance](/docs/getting-started/performance/#fonts). They set `--ca-font-sans`, `--ca-font-mono` and `--ca-font-display`. |
 | `radius` | `0.8` | Multiplier applied to the `--ca-radius-xs` to `--ca-radius-xl` scale (`0.8` makes `--ca-radius-md` 8px). |
-| `density` | `"comfortable"` | `"compact"` tightens card padding and page gaps. |
+| `density` | `"comfortable"` | `"compact"` (0.75), `"comfortable"` (1), `"airy"` (1.25) or a number. Scales the `--ca-space-*` tokens, so padding, gaps and page spacing follow. |
 | `paper` | `"plain"` | Page background: `"plain"`, `"mesh"` (brand glow, drawn by the `glass` and `frosted` styles), `"grid"`, `"dots"` or `"lines"`. Flat patterns are drawn in `--ca-outline-subtle`, so they follow the preset and scheme. |
 | `iconStroke` | `1.75` | Lucide stroke width. |
-| `typography.weights.heading` | `600` | Heading weight. |
+| `controlRadius` | `"md"` | Corner role of buttons, fields and chips: `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"` or `"pill"`. |
+| `border` | `{ width: 1, strong: 2 }` | Border weights in px (`--ca-border-width`, `--ca-border-width-strong`). |
+| `elevation` | `"soft"` | How shadows are drawn: `"soft"`, `"none"`, `"hard"` (offset, no blur) or `"glow"`. |
+| `typography` | `{}` | `scale`, `weights` (`heading` defaults to `600`), `headingTracking`, `headingCase`, `labelTracking`, `labelCase`, `lineHeight` and `measure`. |
+| `motion` | `{}` | `scale` (multiplier on every duration) and `easing`: `"standard"`, `"emphasized"`, `"spring"`, `"linear"` or `"steps"`. |
+| `noise` | `0` | Film-grain over the page background, from `0` to `0.12`. |
 | `overrides` | `{}` | Raw `--ca-*` token overrides, per scheme (`light`, `dark`). Prefer preset role colors (below) for palettes. |
 
 `defineTheme(options)` resolves the options (defaults, validation) and `themeCSS(resolved)` returns the CSS string. You rarely call them yourself; the integrations do. Invalid input fails the build: a preset `id` that clashes with a built-in, a color that is not `#rrggbb`, or a `defaultPreset` that does not exist.
@@ -130,6 +135,11 @@ colorScheme.toggle();   // flips resolved light and dark
 | `flat` | No blur, no mesh, no glow, no drop shadows: separation comes from borders. |
 | `frosted` | Less blur, calmer mesh background. |
 | `glass` | Liquid Glass: strong blur and saturation, translucent tints, brand mesh, glow and rim light. Opt-in. |
+| `outlined` | Border-defined opaque surfaces with no elevation. Used by the `swiss`, `brutalism`, `terminal` and `sketchbook` recipes. |
+| `neumorphic` | One base color extruded by paired light and dark shadows. Low contrast: use it for showcases, not dense data UIs. |
+| `clay` | Soft, inflated opaque surfaces. |
+| `tonal` | Surfaces tinted with the brand hue and soft elevation (Material 3 style). |
+| `chrome` | Glossy gradient with a metallic rim and brand glow. Blur stays on. |
 
 ```ts
 colorScheme.setStyle("glass");
@@ -140,7 +150,8 @@ colorScheme.setStyle("glass");
 Earlier versions looked like Liquid Glass: glass surfaces over a three-hue mesh, glow on selected states, round corners (10px controls), 2px icons, bold headings and hue-tinted shadows. That look is now the opt-in `liquid` recipe:
 
 ```ts
-import { designStyle, type ThemeOptions } from "@codeatlasdev/ui";
+import { designStyle } from "@codeatlasdev/ui/astro";
+import type { ThemeOptions } from "@codeatlasdev/ui/vite";
 
 export const theme: ThemeOptions = designStyle("liquid", {
   presets: [{ id: "acme", color: "#2563eb" }],
@@ -149,7 +160,11 @@ export const theme: ThemeOptions = designStyle("liquid", {
 });
 ```
 
-Migrating an app that relied on the old defaults: use `designStyle("liquid", { ... })`, or set `defaultStyle: "glass"` yourself. `designStyle("default")` now means the sober default.
+`designStyle("default")` is the sober default. `designStyle` is plain data, so `theme.ts` can import it in Node from `@codeatlasdev/ui/astro` (it is also exported from the root and from `@codeatlasdev/ui/kit`, which pull in Svelte files that `vite.config` cannot load). To migrate an app that relied on the old defaults, use `designStyle("liquid", { ... })`, or set `defaultStyle: "glass"` yourself.
+
+### Other design styles
+
+`DESIGN_STYLES` maps each id to `{ id, label, description, taxonomy, theme }`. `designStyle(id, overrides)` returns that recipe's `theme` with your overrides merged on top, and `mergeTheme(a, b)` merges two partial themes (`b` wins). The ids are `default`, `liquid`, `swiss`, `brutalism`, `neumorphism`, `glassmorphism`, `material`, `fluent`, `apple`, `bento`, `claymorphism`, `y2k`, `editorial`, `terminal` and `sketchbook`. Each recipe only sets the design knobs from the options table (material, radius, border, elevation, typography, motion, icon stroke, paper).
 
 Users on `prefers-reduced-transparency: reduce` get opaque surfaces regardless of the style.
 
diff --git a/site/src/content/docs/index.mdx b/site/src/content/docs/index.mdx
index 5e712c0b..5a9a74f2 100644
--- a/site/src/content/docs/index.mdx
+++ b/site/src/content/docs/index.mdx
@@ -21,17 +21,17 @@ CodeAtlas UI gives Svelte 5 apps full screens, not just bricks: page templates,
 </AppList>
 ```
 
-That is a whole users page: header, search, pagination, empty state and glass surface, with no CSS written.
+That is a whole users page: header, search, pagination and empty state, with no CSS written.
 
 ## What you get
 
-- **Pages, not primitives.** `AppList`, `AppForm`, `AppSettings`, `PageShell` and `AppShellLayout` bring layout, spacing and empty states.
-- **Liquid Glass.** Five material tiers with real `backdrop-filter`, tuned for light and dark, with opaque fallbacks for reduced transparency.
-- **Theme engine.** Eight OKLCH presets, brand presets from one hex color, four surface styles, and no flash on load.
-- **Native on mobile.** Safe areas, keyboard handling, 44px touch targets, bottom sheets with swipe to dismiss, and browser chrome color that follows the page.
-- **Accessible.** WAI-ARIA keyboard and focus behavior, axe-tested components, reduced motion and reduced transparency support.
-- **Light.** Charts, DataTable and CodeSnippet are separate entry points with optional peers, so they stay out of your bundle unless imported.
-- **Built for AI agents.** Closed prop vocabularies, typed props, `llms.txt` and installable skills.
+- Page templates instead of primitives: `AppList`, `AppForm`, `AppSettings`, `PageShell` and `AppShellLayout` bring layout, spacing and empty states.
+- Sober by default, glass on request: surfaces are solid and opaque out of the box. The `liquid` recipe (or `defaultStyle: "glass"`) brings back Liquid Glass, with five material tiers over a real `backdrop-filter` and opaque fallbacks for reduced transparency.
+- A theme engine with eight OKLCH presets, brand presets from one hex color, nine surface styles, fifteen design-style recipes and no flash on load.
+- Native feel on mobile: safe areas, keyboard handling, 44px touch targets, bottom sheets with swipe to dismiss and a browser chrome color that follows the page.
+- Accessibility: WAI-ARIA keyboard and focus behavior, axe-tested components, reduced motion and reduced transparency support.
+- Small bundles: Charts, DataTable and CodeSnippet are separate entry points with optional peers, so they stay out of your bundle unless imported.
+- Agent-ready: closed prop vocabularies, typed props, an MCP server, `llms.txt` and installable skills.
 
 ## Install
 
@@ -45,7 +45,7 @@ That is a whole users page: header, search, pagination, empty state and glass su
 
 <CardGrid>
   <LinkCard title="Installation" href="/docs/getting-started/installation/" description="SvelteKit, Astro and plain Vite setup." />
-  <LinkCard title="Theming" href="/docs/getting-started/theming/" description="defineTheme, presets, schemes and token overrides." />
+  <LinkCard title="Theming" href="/docs/getting-started/theming/" description="Theme options, presets, schemes, surface styles and token overrides." />
   <LinkCard title="Mobile" href="/docs/getting-started/mobile/" description="Safe areas, keyboard, browser chrome and layout components." />
   <LinkCard title="Accessibility" href="/docs/getting-started/accessibility/" description="What is handled for you and what is not." />
   <LinkCard title="Internationalization" href="/docs/getting-started/i18n/" description="English by default, pt-BR built in, overridable." />
diff --git a/site/src/content/docs/inputs/button.mdx b/site/src/content/docs/inputs/button.mdx
index f0f81650..2575c38d 100644
--- a/site/src/content/docs/inputs/button.mdx
+++ b/site/src/content/docs/inputs/button.mdx
@@ -39,11 +39,12 @@ On touch devices every size grows to a 44px target and presses scale down slight
   { name: "variant", type: "'filled' | 'glass' | 'outlined' | 'ghost' | 'destructive'", default: "'filled'", description: "Visual style." },
   { name: "size", type: "'sm' | 'md' | 'lg'", default: "'md'", description: "Height, padding and font size." },
   { name: "disabled", type: "boolean", default: "false", description: "Prevents interaction." },
-  { name: "loading", type: "boolean", default: "false", description: "Shows a spinner, sets aria-busy and disables the button. Adds ca-btn--loading." },
+  { name: "loading", type: "boolean", default: "false", description: "Shows a spinner in place of leading, sets aria-busy, blocks interaction and keeps the label. Adds ca-btn--loading. Screen readers hear \"Finished loading\" when it ends." },
   { name: "type", type: "'button' | 'submit' | 'reset'", default: "'button'", description: "HTML button type." },
   { name: "fullWidth", type: "boolean", default: "false", description: "Stretches the button to the width of its container." },
   { name: "href", type: "string", description: "Renders an anchor styled as a button." },
   { name: "target", type: "string", description: "Anchor target, used with href." },
+  { name: "children", type: "Snippet", description: "Button label." },
   { name: "leading", type: "Snippet", description: "Content before the label. Replaced by a spinner while loading." },
   { name: "trailing", type: "Snippet", description: "Content after the label." },
   { name: "onclick", type: "(e: MouseEvent) => void", description: "Click handler. Not called while disabled or loading." },
diff --git a/site/src/content/docs/inputs/combobox.mdx b/site/src/content/docs/inputs/combobox.mdx
index 1e1c3241..d9625ef3 100644
--- a/site/src/content/docs/inputs/combobox.mdx
+++ b/site/src/content/docs/inputs/combobox.mdx
@@ -1,6 +1,6 @@
 ---
 title: Combobox
-description: Select with built-in search, built for long option lists.
+description: Select with built-in search for long option lists.
 group: Inputs
 ---
 import Demo from "~/components/docs/Demo.astro";
@@ -19,7 +19,7 @@ import StatesSrc from "~/demos/inputs/combobox/States.svelte?raw";
 <Combobox label="Framework" options={[{ value: "svelte", label: "Svelte" }]} bind:value />
 ```
 
-Typing in the popup filters options by label, and opening the list moves focus to the search input. Pass a `label` (or at least a `placeholder`) so the listbox has an accessible name.
+Typing in the popup filters options by label, and opening the list moves focus to the search input. Pass a `label` (or `ariaLabel`) so the trigger and listbox have an accessible name. Like `Select`, it has no `name` prop and does not submit with a native form: read `value` instead.
 
 <Demo title="Basic" description="Search a list of options and bind the selected value." src={BasicSrc}><Basic client:visible /></Demo>
 <Demo title="States" description="Description, custom search placeholder and empty text, disabled option, error and disabled." src={StatesSrc}><States client:visible /></Demo>
diff --git a/site/src/content/docs/inputs/date-picker.mdx b/site/src/content/docs/inputs/date-picker.mdx
index e5db57e7..3e20d276 100644
--- a/site/src/content/docs/inputs/date-picker.mdx
+++ b/site/src/content/docs/inputs/date-picker.mdx
@@ -27,7 +27,7 @@ Values are `@internationalized/date` objects. `CalendarDate`, `Time`, `today`, `
 
 The default `locale` is `pt-BR` with Monday-first weeks. The demos below pass `locale="en-US"` and `weekStartsOn={0}` to show the English format.
 
-**Keyboard.** In field segments, type digits or use the up and down arrows to change a value, and the left and right arrows or Tab to move between segments. In a calendar, the arrows move by day, PageUp and PageDown by month, Shift with PageUp or PageDown by year, Home and End to the week edges, Enter or Space selects, and Escape closes the popover.
+**Keyboard.** In field segments, type digits or use the up and down arrows to change a value, and the left and right arrows or Tab to move between segments. In a calendar, left and right move by day, up and down by week, PageUp and PageDown by month, Shift with PageUp or PageDown by year, Home and End to the week edges, Enter or Space selects, and Escape closes the popover.
 
 An `error` is rendered with `role="alert"` and sets `aria-invalid` and `aria-describedby`. Clicking a field `label` focuses its first segment.
 
@@ -36,7 +36,7 @@ An `error` is rendered with `role="alert"` and sets `aria-invalid` and `aria-des
 <Demo title="Calendar and RangeCalendar" description="Inline calendars. Click a start date, then an end date for the range." src={CalendarsSrc}><Calendars client:visible /></Demo>
 <Demo title="Min, max, error and disabled" description="Only the next 30 days are selectable. Out-of-range days are disabled and typed values become invalid." src={ConstraintsSrc}><Constraints client:visible /></Demo>
 
-<Props title="Shared props" rows={[
+<Props for="DatePicker, DateRangePicker, DateField, TimeField, Calendar, RangeCalendar" title="Shared props" rows={[
   { name: "label", type: "string", description: "Field label. On Calendar and RangeCalendar it is the screen-reader label." },
   { name: "description", type: "string", description: "Hint below the field (aria-describedby). Pickers and fields only." },
   { name: "error", type: "string", description: "Error message (role=\"alert\"). Sets aria-invalid and the error style. Pickers and fields only." },
diff --git a/site/src/content/docs/inputs/export-menu.mdx b/site/src/content/docs/inputs/export-menu.mdx
index af2ea9b2..c516d5ee 100644
--- a/site/src/content/docs/inputs/export-menu.mdx
+++ b/site/src/content/docs/inputs/export-menu.mdx
@@ -17,7 +17,7 @@ import DefaultSrc from "~/demos/inputs/export-menu/Default.svelte?raw";
 <ExportMenu data={rows} filename="domains" />
 ```
 
-`ExportMenu` is a `DropdownMenu` with CSV and JSON items. Choosing one builds the file from `data`, downloads it and announces "Exported 3 rows as CSV" politely. It is disabled while `data` is empty. Pass **all** rows, not only the visible page.
+`ExportMenu` is a `DropdownMenu` with CSV and JSON items. Choosing one builds the file from `data`, downloads it and announces "Exported 3 rows as CSV" politely. It is disabled while `data` is empty. Pass all rows, not only the visible page.
 
 CSV is RFC 4180 (CRLF, quoted fields) with a UTF-8 BOM in the downloaded file so Excel reads accents correctly. Text cells that start with `=`, `+`, `-` or `@` get a leading `'` so a spreadsheet never runs them as a formula (CSV injection). Numbers are left as they are.
 
@@ -36,9 +36,9 @@ downloadFile("domains.csv", toCsv(rows, columns), "text/csv;charset=utf-8");
 <Props rows={[
   { name: "data", type: "readonly T[]", description: "Rows to export." },
   { name: "filename", type: "string", default: "'export'", description: "File name without extension." },
-  { name: "columns", type: "ExportColumn<T>[]", description: "`{ key, header?, value? }` per column. Defaults to the keys of the first row." },
+  { name: "columns", type: "ExportColumn<T>[]", description: "`{ key, header?, value? }` per column: header defaults to key, value overrides row[key]. Defaults to the keys of the first row." },
   { name: "formats", type: "('csv' | 'json')[]", default: "['csv', 'json']", description: "Formats offered, in menu order." },
-  { name: "label", type: "string", description: "Button label. Defaults to the localised “Export”." },
+  { name: "label", type: "string", default: "'Export' (localized)", description: "Button label." },
   { name: "variant", type: "'filled' | 'glass' | 'outlined' | 'ghost'", default: "'outlined'", description: "Button variant." },
   { name: "size", type: "'sm' | 'md' | 'lg'", default: "'md'", description: "Button size." },
   { name: "disabled", type: "boolean", default: "false", description: "Disables the button." },
diff --git a/site/src/content/docs/inputs/filter-group.mdx b/site/src/content/docs/inputs/filter-group.mdx
new file mode 100644
index 00000000..2fe431bf
--- /dev/null
+++ b/site/src/content/docs/inputs/filter-group.mdx
@@ -0,0 +1,36 @@
+---
+title: FilterGroup
+description: Inline filter chips for list toolbars, with an automatic "All" option.
+group: Inputs
+order: 22
+---
+import Demo from "~/components/docs/Demo.astro";
+import Props from "~/components/docs/Props.astro";
+import Basic from "~/demos/inputs/filter-group/Basic.svelte";
+import BasicSrc from "~/demos/inputs/filter-group/Basic.svelte?raw";
+
+```svelte
+<script>
+  import { FilterGroup } from "@codeatlasdev/ui";
+
+  let role = $state("all");
+</script>
+
+<FilterGroup
+  label="Role"
+  options={[{ value: "admin", label: "Admin" }, { value: "editor", label: "Editor" }]}
+  bind:value={role}
+/>
+```
+
+An "All" option is added in front of `options` and the value is `'all'` when nothing is filtered. Clicking the active option clears the filter and goes back to `'all'`. Inside [AppList](/docs/layout/list-page/), render it in the `filters` snippet and connect it to `list.setFilter`.
+
+<Demo title="Role filter" src={BasicSrc}><Basic client:visible /></Demo>
+
+<Props rows={[
+  { name: "options", type: "{ value: string; label: string }[]", description: "Filter choices. Required." },
+  { name: "value", type: "string", default: "'all'", description: "Bindable selected value." },
+  { name: "label", type: "string", description: "Text shown before the chips." },
+  { name: "onchange", type: "(value: string) => void", description: "Called when the selection changes." },
+  { name: "class", type: "string", default: "''", description: "Extra classes on the root." },
+]} />
diff --git a/site/src/content/docs/inputs/masked-field.mdx b/site/src/content/docs/inputs/masked-field.mdx
index 9153e5f3..be64a4b8 100644
--- a/site/src/content/docs/inputs/masked-field.mdx
+++ b/site/src/content/docs/inputs/masked-field.mdx
@@ -36,7 +36,7 @@ Documents try these values: CPF `123.456.789-09` is valid and `111.111.111-11` i
 <Demo title="Phone and CEP" description="PhoneField binds E.164 (+55...) while showing the masked form. CepField resolves an address through onlookup. Try 01310-100." src={PhoneCepSrc}><PhoneCep client:visible /></Demo>
 <Demo title="use:mask action" description="Apply any pure mask to a plain input. The caret stays on the same digit." src={MaskActionSrc}><MaskAction client:visible /></Demo>
 
-<Props title="MaskedField props" rows={[
+<Props for="MaskedField" title="MaskedField props" rows={[
   { name: "mask", type: "(raw: string) => string", description: "Required. Pure formatter applied while typing, for example maskCPF." },
   { name: "validate", type: "(value: string) => string | undefined", description: "Returns an error message on blur for non-empty values, or undefined when valid." },
   { name: "inputmode", type: "HTMLInputAttributes['inputmode']", default: "auto", description: "Defaults to 'numeric' for digit-only masks and 'text' otherwise." },
@@ -56,7 +56,7 @@ Documents try these values: CPF `123.456.789-09` is valid and `111.111.111-11` i
   { name: "onblur", type: "(e: FocusEvent) => void", description: "Called when the input loses focus." },
 ]} />
 
-<Props title="PhoneField and CepField props" rows={[
+<Props for="PhoneField, CepField" title="PhoneField and CepField props" rows={[
   { name: "PhoneField.value", type: "string", default: "''", description: "Bindable E.164 value (+5511987654321). Empty while the number is incomplete or empty." },
   { name: "PhoneField.country", type: "'BR'", default: "'BR'", description: "Only BR is supported today." },
   { name: "PhoneField.placeholder", type: "string", default: "'(11) 98765-4321'", description: "Input placeholder." },
@@ -67,7 +67,7 @@ Documents try these values: CPF `123.456.789-09` is valid and `111.111.111-11` i
   { name: "CepField.placeholder", type: "string", default: "'00000-000'", description: "Input placeholder." },
 ]} />
 
-<Props title="Exports" rows={[
+<Props for="none" title="Exports" rows={[
   { name: "maskCPF / maskCNPJ / maskCPFCNPJ", type: "(raw: string) => string", description: "Document masks. maskCPFCNPJ switches after 11 digits." },
   { name: "maskDateBR / maskRG / maskCEP / maskPhoneBR", type: "(raw: string) => string", description: "Date (dd/mm/yyyy), RG, CEP and Brazilian phone masks." },
   { name: "isValidCPF / isValidCNPJ / isValidDateBR", type: "(value: string) => boolean", description: "Validators for use in validate." },
diff --git a/site/src/content/docs/inputs/radio.mdx b/site/src/content/docs/inputs/radio.mdx
index f5de4ba3..3609cf26 100644
--- a/site/src/content/docs/inputs/radio.mdx
+++ b/site/src/content/docs/inputs/radio.mdx
@@ -1,6 +1,6 @@
 ---
 title: RadioGroup
-description: Single-selection radio group with roving focus and arrow-key navigation.
+description: Single-selection radio group as a list of rows or a grid of selectable cards.
 group: Inputs
 ---
 import Demo from "~/components/docs/Demo.astro";
@@ -9,6 +9,8 @@ import Vertical from "~/demos/inputs/radio/Vertical.svelte";
 import VerticalSrc from "~/demos/inputs/radio/Vertical.svelte?raw";
 import Horizontal from "~/demos/inputs/radio/Horizontal.svelte";
 import HorizontalSrc from "~/demos/inputs/radio/Horizontal.svelte?raw";
+import Cards from "~/demos/inputs/radio/Cards.svelte";
+import CardsSrc from "~/demos/inputs/radio/Cards.svelte?raw";
 import Disabled from "~/demos/inputs/radio/Disabled.svelte";
 import DisabledSrc from "~/demos/inputs/radio/Disabled.svelte?raw";
 
@@ -21,17 +23,20 @@ import DisabledSrc from "~/demos/inputs/radio/Disabled.svelte?raw";
 <RadioGroup items={[{ value: "free", label: "Free" }, { value: "pro", label: "Pro" }]} bind:value={plan} />
 ```
 
-Arrow keys move focus and selection inside the group, Tab leaves it. The group has no visible title of its own, so wrap it in a `fieldset` with a `legend` when the choice needs a heading.
+The options are native radio inputs that share one `name`, so arrow keys move focus and selection inside the group and Tab leaves it. The group has no visible title of its own: pass `aria-label`, or wrap it in a `fieldset` with a `legend` when the choice needs a visible heading.
 
 <Demo title="Vertical" description="The default layout." src={VerticalSrc}><Vertical client:visible /></Demo>
 <Demo title="Horizontal" description="orientation=&quot;horizontal&quot; lays the options out in a row." src={HorizontalSrc}><Horizontal client:visible /></Demo>
+<Demo title="Cards" description="variant=&quot;cards&quot; renders each option as a selectable card with an optional description." src={CardsSrc}><Cards client:visible /></Demo>
 <Demo title="Disabled" description="Disable a single item, or the whole group." src={DisabledSrc}><Disabled client:visible /></Demo>
 
-<Props rows={[
+<Props for="RadioGroup" rows={[
   { name: "value", type: "string", default: "''", description: "Bindable selected value." },
-  { name: "items", type: "RadioItem[]", description: "Options: { value, label, disabled? }." },
+  { name: "items", type: "RadioItem[]", description: "Options: { value, label, description?, disabled? }. description is shown in the cards variant." },
+  { name: "variant", type: "'list' | 'cards'", default: "'list'", description: "list renders radio and label rows. cards renders each option as a card in a responsive grid, and the whole card is the hit area." },
   { name: "orientation", type: "'vertical' | 'horizontal'", default: "'vertical'", description: "Layout direction and arrow-key axis." },
   { name: "disabled", type: "boolean", default: "false", description: "Disables the entire group." },
+  { name: "aria-label", type: "string", description: "Accessible name of the group." },
   { name: "class", type: "string", description: "Extra classes on the group." },
   { name: "onchange", type: "(value: string) => void", description: "Called when the selection changes." },
 ]} />
diff --git a/site/src/content/docs/inputs/select.mdx b/site/src/content/docs/inputs/select.mdx
index 4913524e..54c2a9b4 100644
--- a/site/src/content/docs/inputs/select.mdx
+++ b/site/src/content/docs/inputs/select.mdx
@@ -1,6 +1,6 @@
 ---
 title: Select
-description: Dropdown selector with keyboard navigation and a glass content panel.
+description: Dropdown selector with keyboard navigation, a label, hint and error state.
 group: Inputs
 ---
 import Demo from "~/components/docs/Demo.astro";
@@ -23,7 +23,7 @@ import StatesSrc from "~/demos/inputs/select/States.svelte?raw";
 <Select label="Country" options={[{ value: "br", label: "Brazil" }]} bind:value />
 ```
 
-For long lists that need filtering, use [Combobox](/docs/inputs/combobox/). Without a `label` the trigger is named by its `placeholder`. Text inside inputs stays at 16px or more on touch screens, so iOS Safari never zooms on focus.
+For long lists that need filtering, use [Combobox](/docs/inputs/combobox/). Without a `label` the trigger is named by its `placeholder`. Arrow keys, Enter and Space open the list from the trigger, and Escape closes it. There is no `name` prop, so a `Select` does not submit with a native form: read `value` instead. `required` blocks native form submission while nothing is selected. Text inside inputs stays at 16px or more on touch screens, so iOS Safari never zooms on focus.
 
 <Demo title="Basic" description="Controlled select with a pre-selected value." src={BasicSrc}><Basic client:visible /></Demo>
 <Demo title="Placeholder" description="No initial value: the placeholder shows until the user picks an option." src={PlaceholderSrc}><Placeholder client:visible /></Demo>
diff --git a/site/src/content/docs/inputs/setting-item.mdx b/site/src/content/docs/inputs/setting-item.mdx
new file mode 100644
index 00000000..98722cc8
--- /dev/null
+++ b/site/src/content/docs/inputs/setting-item.mdx
@@ -0,0 +1,33 @@
+---
+title: SettingItem
+description: A settings row with a label, a description and one control on the right.
+group: Inputs
+order: 23
+---
+import Demo from "~/components/docs/Demo.astro";
+import Props from "~/components/docs/Props.astro";
+import Basic from "~/demos/inputs/setting-item/Basic.svelte";
+import BasicSrc from "~/demos/inputs/setting-item/Basic.svelte?raw";
+
+```svelte
+<script>
+  import { SettingItem, Switch } from "@codeatlasdev/ui";
+
+  let email = $state(true);
+</script>
+
+<SettingItem label="Email notifications" description="Receive an email for every mention.">
+  <Switch bind:checked={email} />
+</SettingItem>
+```
+
+The row is a `<label>`, so clicking the text activates the first control inside it (a `Switch`, an input, a select or a button) and names it for assistive technology. Use it inside [AppSettings](/docs/layout/list-page/) tabs.
+
+<Demo title="Switch rows" src={BasicSrc}><Basic client:visible /></Demo>
+
+<Props rows={[
+  { name: "label", type: "string", description: "Setting name. Required." },
+  { name: "description", type: "string", description: "Help text under the label." },
+  { name: "children", type: "Snippet", description: "The control, placed on the right." },
+  { name: "class", type: "string", default: "''", description: "Extra classes on the root." },
+]} />
diff --git a/site/src/content/docs/inputs/swatch-group.mdx b/site/src/content/docs/inputs/swatch-group.mdx
new file mode 100644
index 00000000..335ad8bc
--- /dev/null
+++ b/site/src/content/docs/inputs/swatch-group.mdx
@@ -0,0 +1,43 @@
+---
+title: SwatchGroup
+description: Single-choice color picker made of round swatches. Preset swatches follow the theme; custom ones take any CSS color.
+group: Inputs
+---
+import Demo from "~/components/docs/Demo.astro";
+import Props from "~/components/docs/Props.astro";
+import Presets from "~/demos/inputs/swatch-group/Presets.svelte";
+import PresetsSrc from "~/demos/inputs/swatch-group/Presets.svelte?raw";
+import Custom from "~/demos/inputs/swatch-group/Custom.svelte";
+import CustomSrc from "~/demos/inputs/swatch-group/Custom.svelte?raw";
+
+```svelte
+<script>
+  import { SwatchGroup } from "@codeatlasdev/ui";
+  let preset = $state("ocean");
+</script>
+
+<SwatchGroup
+  aria-label="Accent"
+  bind:value={preset}
+  items={[{ value: "ocean" }, { value: "violet" }, { value: "emerald" }]}
+/>
+```
+
+Each item paints from the theme preset named by its `value`, so the swatch always matches the palette. Give an item a `color` to paint it with any CSS color instead; its `value` is then free-form. Leave `value` empty for "none selected", for example while a custom color is active. The selected swatch shows a check mark.
+
+On touch screens (`pointer: coarse`) each swatch grows to the 44px touch target, so neighbouring hit areas never overlap.
+
+**Accessibility.** The group is a `radiogroup` and every swatch a `radio` with `aria-checked`. The group has no visible heading, so pass `aria-label`; each swatch is named by its `label`, falling back to `value`, so give custom colors a readable `label` ("Blue", not "#2563eb"). Arrow keys move focus between enabled swatches and Tab leaves the group. The selected state does not rely on color alone: it adds a check mark and a ring, and both survive forced-colors mode.
+
+<Demo title="Theme presets" description="Swatches without a color paint from the preset named by their value." src={PresetsSrc}><Presets client:visible /></Demo>
+<Demo title="Custom colors" description="Any CSS color, a small size and a disabled swatch." src={CustomSrc}><Custom client:visible /></Demo>
+
+<Props for="SwatchGroup" rows={[
+  { name: "value", type: "string", default: "''", description: "Bindable selected item value. Empty means none selected." },
+  { name: "items", type: "SwatchItem[]", description: "{ value, label?, color?, disabled? }. Without `color` the swatch paints from the theme preset named by `value`; `label` is the accessible name and falls back to `value`." },
+  { name: "size", type: "'sm' | 'md'", default: "'md'", description: "Swatch diameter." },
+  { name: "disabled", type: "boolean", default: "false", description: "Disables every swatch." },
+  { name: "aria-label", type: "string", description: "Accessible name of the group." },
+  { name: "class", type: "string", description: "Extra classes on the root." },
+  { name: "onchange", type: "(value: string) => void", description: "Called when the user picks a different swatch." },
+]} />
diff --git a/site/src/content/docs/inputs/text-area.mdx b/site/src/content/docs/inputs/text-area.mdx
index 52a4708c..ff017a50 100644
--- a/site/src/content/docs/inputs/text-area.mdx
+++ b/site/src/content/docs/inputs/text-area.mdx
@@ -1,6 +1,6 @@
 ---
 title: TextArea
-description: Multi-line text input with label, glass styling and configurable resize behavior.
+description: Multi-line text input with label, helper text, error state and configurable resize behavior.
 group: Inputs
 ---
 import Demo from "~/components/docs/Demo.astro";
@@ -19,7 +19,7 @@ import StatesSrc from "~/demos/inputs/text-area/States.svelte?raw";
 <TextArea label="Message" bind:value={message} rows={4} />
 ```
 
-The label floats when the field has a value or a placeholder. `description` is hidden while an `error` is shown. Text stays at 16px or more on touch devices so iOS Safari does not zoom on focus.
+The label sits above the field. `description` is hidden while an `error` is shown, and the error is announced with `role="alert"`. Text stays at 16px or more on touch devices so iOS Safari does not zoom on focus.
 
 <Demo title="Basic" description="Empty, with a placeholder, and pre-filled." src={BasicSrc}><Basic client:visible /></Demo>
 <Demo title="States" description="Helper text, error, required, read-only, disabled and resize=&quot;none&quot;." src={StatesSrc}><States client:visible /></Demo>
@@ -27,19 +27,19 @@ The label floats when the field has a value or a placeholder. `description` is h
 <Props rows={[
   { name: "value", type: "string", default: "''", description: "Bindable text value." },
   { name: "label", type: "string", description: "Label text." },
-  { name: "placeholder", type: "string", default: "''", description: "Native placeholder. Also floats the label." },
-  { name: "rows", type: "number", default: "4", description: "Initial visible row count." },
-  { name: "minRows", type: "number", description: "Minimum rows for the min-height. Defaults to rows." },
+  { name: "placeholder", type: "string", default: "''", description: "Native placeholder." },
+  { name: "rows", type: "number", default: "4", description: "Visible row count." },
+  { name: "minRows", type: "number", description: "Row count used for the minimum height. Defaults to rows." },
   { name: "resize", type: "'none' | 'vertical' | 'horizontal' | 'both'", default: "'vertical'", description: "CSS resize behavior." },
   { name: "error", type: "string", description: "Error message. Sets the error styling." },
   { name: "description", type: "string", description: "Helper text shown below. Hidden when error is set." },
-  { name: "helperText", type: "string", description: "Deprecated alias of description." },
+  { name: "helperText", type: "string", description: "Deprecated alias of description. Use description." },
   { name: "disabled", type: "boolean", default: "false", description: "Disables the textarea." },
   { name: "required", type: "boolean", default: "false", description: "Marks the field as required, with a visual asterisk." },
   { name: "readonly", type: "boolean", default: "false", description: "Makes the textarea read-only." },
   { name: "name", type: "string", description: "Native name, for form submission." },
   { name: "class", type: "string", description: "Extra classes on the root." },
   { name: "oninput", type: "(value: string) => void", description: "Called on every keystroke with the new value." },
-  { name: "onchange", type: "(value: string) => void", description: "Called when the value is committed (blur)." },
+  { name: "onchange", type: "(value: string) => void", description: "Called when the value is committed (on blur, after an edit)." },
   { name: "onblur", type: "(e: FocusEvent) => void", description: "Called when the textarea loses focus." },
 ]} />
diff --git a/site/src/content/docs/inputs/toggle-group.mdx b/site/src/content/docs/inputs/toggle-group.mdx
index 25ab30f1..86e0a1df 100644
--- a/site/src/content/docs/inputs/toggle-group.mdx
+++ b/site/src/content/docs/inputs/toggle-group.mdx
@@ -1,6 +1,6 @@
 ---
 title: ToggleGroup
-description: A set of toggle buttons with single or multiple selection, roving focus and arrow-key navigation.
+description: A set of toggle buttons with single or multiple selection. Single groups use arrow-key navigation.
 group: Inputs
 ---
 import Demo from "~/components/docs/Demo.astro";
@@ -14,12 +14,16 @@ import VariantsSrc from "~/demos/inputs/toggle-group/Variants.svelte?raw";
 <script>
   import { ToggleGroup } from "@codeatlasdev/ui";
   let format = $state(["bold"]);
+  const items = [
+    { value: "bold", label: "Bold" },
+    { value: "italic", label: "Italic" },
+  ];
 </script>
 
-<ToggleGroup type="multiple" aria-label="Text formatting" bind:value={format} items={items} />
+<ToggleGroup type="multiple" aria-label="Text formatting" bind:value={format} {items} />
 ```
 
-In `single` mode the user can press the active item again to clear the selection, so `value` can be an empty string. Use [SegmentedControl](/docs/inputs/segmented-control/) when a choice is required. Icon-only items need an `aria-label`.
+In `single` mode the user can press the active item again to clear the selection, so `value` can be an empty string. Use [SegmentedControl](/docs/inputs/segmented-control/) when a choice is required. In `single` mode the group is one tab stop and arrow keys move focus (Home and End jump to the ends); in `multiple` mode each item stays in the tab order. Icon-only items need an `aria-label`.
 
 <Demo title="Single and multiple" description="type=&quot;single&quot; binds a string. type=&quot;multiple&quot; binds a string array." src={SelectionSrc}><Selection client:visible /></Demo>
 <Demo title="Variants and orientation" description="outlined and ghost variants, sizes, a disabled item and a vertical layout." src={VariantsSrc}><Variants client:visible /></Demo>
diff --git a/site/src/content/docs/inputs/use-form.mdx b/site/src/content/docs/inputs/use-form.mdx
index a4df46d5..0d6e6371 100644
--- a/site/src/content/docs/inputs/use-form.mdx
+++ b/site/src/content/docs/inputs/use-form.mdx
@@ -39,13 +39,13 @@ Pass `arrays` for repeatable row groups, for example `useForm({ name: "" }, { ar
 <Demo title="With schema" description="A plain-function schema runs on every keystroke once a field is touched." src={WithSchemaSrc}><WithSchema client:visible /></Demo>
 <Demo title="Submit state" description="validate() gates submission, submitting drives the button loading state, and reset() clears everything after success." src={SubmitSrc}><Submit client:visible /></Demo>
 
-<Props title="useForm(initialValues, options?)" rows={[
+<Props for="none" title="useForm(initialValues, options?)" rows={[
   { name: "initialValues", type: "Record<K, string>", description: "Field names and their initial string values." },
   { name: "options.schema", type: "ValidationSchema<K>", description: "A function (data) => Partial<Record<K, string>>, or a Zod or Valibot schema." },
   { name: "options.arrays", type: "{ [name]: Item[] }", description: "Initial rows for repeatable field groups, exposed as form.arrays." },
 ]} />
 
-<Props title="Returned form state" rows={[
+<Props for="none" title="Returned form state" rows={[
   { name: "fields", type: "Record<K, { value: string; error: string | undefined; touched: boolean }>", description: "Reactive state of every field." },
   { name: "arrays", type: "{ [name]: { items; add(item); remove(index); move(from, to) } }", description: "Repeatable row groups declared with options.arrays." },
   { name: "dirty", type: "boolean", description: "True when any value differs from its initial value." },
diff --git a/site/src/content/docs/layout/app-shell.mdx b/site/src/content/docs/layout/app-shell.mdx
index 992aea22..ed2216a1 100644
--- a/site/src/content/docs/layout/app-shell.mdx
+++ b/site/src/content/docs/layout/app-shell.mdx
@@ -12,11 +12,13 @@ import Shell from "~/demos/layout/app-shell/Shell.svelte";
 import ShellSrc from "~/demos/layout/app-shell/Shell.svelte?raw";
 
 ```svelte
-<script>
-  import { AppShellLayout, type NavModule } from "@codeatlasdev/ui";
+<script lang="ts">
+  import { AppShellLayout, SiteHeader, type NavModule } from "@codeatlasdev/ui";
   import { goto } from "$app/navigation"; // or any router
   import { page } from "$app/state";
 
+  let { children } = $props();
+
   const modules: NavModule[] = [/* id, label, icon, basePath, items */];
 </script>
 
@@ -26,16 +28,16 @@ import ShellSrc from "~/demos/layout/app-shell/Shell.svelte?raw";
 </AppShellLayout>
 ```
 
-The shell never imports a router. You pass the current `pathname` and handle `onNavigate`, so it works with SvelteKit, Astro, or plain state. `onNavigate` fires when the user switches module from the rail or the bottom navigation. Panel items are plain `<a href>` links, so a client-side router takes them over like any other link. Put it only on application routes, never on marketing pages. Below 900px the rail and panel disappear and the mobile header plus bottom navigation take over. See the [templates](/templates/) for complete applications built on it.
+The shell never imports a router. You pass the current `pathname` and handle `onNavigate`, so it works with SvelteKit, Astro, or plain state. `onNavigate` fires when the user switches module from the rail or the bottom navigation. Panel items are plain `<a href>` links, so a client-side router takes them over like any other link. Put it only on application routes, never on marketing pages. The panel is skipped for a module with fewer than two destinations, since it would only repeat the rail icon and the page title. Below 900px the rail and panel disappear and the mobile header plus bottom navigation take over. See the [templates](/templates/) for complete applications built on it.
 
 <Demo title="Anatomy" description="Rail (52px), panel (200px) and the main content area." src={AnatomySrc}><Anatomy /></Demo>
 <Demo title="Live shell" description="The real component inside a fixed-height frame. The pathname lives in local state; click the rail and panel to navigate." src={ShellSrc} stage><Shell client:visible /></Demo>
 
-<Props rows={[
+<Props for="AppShellLayout" rows={[
   { name: "modules", type: "NavModule[]", description: "Navigation modules. Each has id, label, icon, basePath, optional pathPrefixes and items (NavItem or NavSection)." },
   { name: "pathname", type: "string", description: "Current location. Decides the active module and item." },
-  { name: "onNavigate", type: "(path: string) => void", description: "Called with the destination path when the rail, panel or bottom navigation is used." },
-  { name: "defaultModule", type: "number", default: "0", description: "Module index used before any navigation matches." },
+  { name: "onNavigate", type: "(path: string) => void", description: "Called with the first path of the module when the rail or the bottom navigation switches module. Panel items are links and do not call it." },
+  { name: "defaultModule", type: "number", default: "0", description: "Module index used when the URL matches no module and none was stored." },
   { name: "persistPanel", type: "boolean", default: "true", description: "Keeps the shell across page loads: panel open or closed, selected module and expanded sections (localStorage), panel scroll (sessionStorage). Restored before the first paint. Turn it off for demos and embeds that must always start from the defaults." },
   { name: "header", type: "Snippet", description: "Desktop header rendered above the page content. Hidden below 900px." },
   { name: "brand", type: "Snippet", description: "Logo shown at the top of the rail and in the mobile header." },
@@ -59,3 +61,33 @@ On a multi-page site (Astro, a full reload) every link loads a new document, so
 An inline script emitted right after the sidebar reads those keys and sets `data-ca-panel="open|closed"` and `data-ca-module="<id>"` on `<html>` before anything paints, so a panel the user closed is laid out closed from the first frame instead of flashing open. Stored values are validated and discarded when malformed. A section's last open or closed choice wins over `defaultOpen`, but the section that holds the current page always opens. The module comes from the URL when `modules` matches it, and from the stored choice otherwise.
 
 Render the shell on the server so the first paint is not blank: the inline script and the markup travel together. A client-only mount gets the same restore on hydration, and a page whose CSP blocks inline scripts too. Keep `id` stable on each `NavModule` (it is the stored module key) and each section `label` unique within a module (it is the stored section key).
+
+## Building blocks for a custom panel
+
+`AppShellLayout` renders the panel for you. `Rail`, `Panel`, `BottomNav` and `MobileHeader` are exported too, and two of them are the pieces to reuse when you lay out your own navigation: `PanelNavItem` is the row the panel draws for one `NavItem` (icon, label, unread badge, new dot and the active pip), and `SectionGroup` is a titled group of items that collapses.
+
+```svelte
+<script lang="ts">
+  import { PanelNavItem, SectionGroup, type NavSection } from "@codeatlasdev/ui";
+
+  const section: NavSection = { label: "Reports", collapsible: true, items };
+</script>
+
+<SectionGroup {section} {pathname} />
+<PanelNavItem item={items[0]} isActive={pathname === items[0].path} href={items[0].path} />
+```
+
+`PanelNavItem` renders a plain `<a>` with `aria-current="page"` when active. `SectionGroup` opens itself when it holds the current page, and inside an `AppShellLayout` with `persistPanel` it stores its open state under the section `label`; a bare `SectionGroup` keeps nothing.
+
+<Props for="PanelNavItem" title="PanelNavItem props" rows={[
+  { name: "item", type: "NavItem", description: "The destination: `id`, `label`, `icon`, `path`, and optional `badge`, `isNew`, `shortcut`, `description`. Required." },
+  { name: "isActive", type: "boolean", description: "Marks the row as the current page (`aria-current=\"page\"`, active pip). Required." },
+  { name: "href", type: "string", description: "Link target. Required." },
+  { name: "class", type: "string", default: "''", description: "Extra class names." },
+]} />
+
+<Props for="SectionGroup" title="SectionGroup props" rows={[
+  { name: "section", type: "NavSection", description: "`label`, `items`, and optional `collapsible` (default `true`) and `defaultOpen` (default `true`). Required." },
+  { name: "pathname", type: "string", description: "Current location, used to mark the active item and to keep the group holding it open. Required." },
+  { name: "class", type: "string", default: "''", description: "Extra class names." },
+]} />
diff --git a/site/src/content/docs/layout/auth-layout.mdx b/site/src/content/docs/layout/auth-layout.mdx
new file mode 100644
index 00000000..997b4c06
--- /dev/null
+++ b/site/src/content/docs/layout/auth-layout.mdx
@@ -0,0 +1,50 @@
+---
+title: AuthLayout
+description: A two-column page for sign in, sign up and password reset, with AuthCard for the form.
+group: Layout
+order: 100
+---
+import Props from "~/components/docs/Props.astro";
+
+```svelte
+<script>
+  import { AuthLayout, AuthCard, TextField, Button, Stack } from "@codeatlasdev/ui";
+</script>
+
+<AuthLayout logoName="Acme">
+  {#snippet panel()}
+    <blockquote>Ship the boring parts in a day.</blockquote>
+  {/snippet}
+
+  <AuthCard title="Welcome back" subtitle="Sign in to continue">
+    <form>
+      <Stack gap="3">
+        <TextField label="Email" type="email" />
+        <Button type="submit" fullWidth>Sign in</Button>
+      </Stack>
+    </form>
+    {#snippet footer()}
+      <a href="/sign-up">Create an account</a>
+    {/snippet}
+  </AuthCard>
+</AuthLayout>
+```
+
+`AuthLayout` renders the page `<main id="main">`, so a route that uses it must not add another one. The `panel` snippet fills the side column; below 768px it is hidden and `mobileBrand` shows a compact brand strip above the form. The full pages live in the [sign in, sign up and forgot password templates](/templates/).
+
+<Props for="AuthLayout" title="AuthLayout props" rows={[
+  { name: "logoMark", type: "string", default: "'CA'", description: "Text inside the logo square." },
+  { name: "logoName", type: "string", default: "'CodeAtlas UI'", description: "Product name next to the mark." },
+  { name: "logoHref", type: "string", default: "'/'", description: "Where the logo links to." },
+  { name: "mobileBrand", type: "boolean", default: "true", description: "Shows the compact brand strip below 768px, where the side panel is hidden." },
+  { name: "brand", type: "Snippet", description: "Replaces the default logo." },
+  { name: "panel", type: "Snippet", description: "Content of the side column." },
+  { name: "children", type: "Snippet", description: "The form column, usually an AuthCard." },
+]} />
+
+<Props for="AuthCard" title="AuthCard props" rows={[
+  { name: "title", type: "string", description: "Heading of the card." },
+  { name: "subtitle", type: "string", description: "Text under the heading." },
+  { name: "footer", type: "Snippet", description: "Links under the form, such as sign up." },
+  { name: "children", type: "Snippet", description: "The form." },
+]} />
diff --git a/site/src/content/docs/layout/error-page.mdx b/site/src/content/docs/layout/error-page.mdx
new file mode 100644
index 00000000..961efb9c
--- /dev/null
+++ b/site/src/content/docs/layout/error-page.mdx
@@ -0,0 +1,32 @@
+---
+title: ErrorPage
+description: A full-page error state for 404, 403, 500 and 503 with localized copy and home and back actions.
+group: Layout
+order: 90
+---
+import Demo from "~/components/docs/Demo.astro";
+import Props from "~/components/docs/Props.astro";
+import Statuses from "~/demos/layout/error-page/Statuses.svelte";
+import StatusesSrc from "~/demos/layout/error-page/Statuses.svelte?raw";
+
+```svelte
+<!-- src/routes/+error.svelte -->
+<script>
+  import { page } from "$app/state";
+  import { ErrorPage } from "@codeatlasdev/ui";
+</script>
+
+<ErrorPage status={page.status} message={page.error?.message} />
+```
+
+Known statuses (404, 403, 500, 503) get an icon, a title and a hint in the active locale. Any other status falls back to a generic title. An explicit `message` replaces the hint and `title` replaces the title. The actions go back in history and to `/`. `caErrorPlugin({ scaffold: true })` writes a `+error.svelte` like this one for you (see [Installation](/docs/getting-started/installation/)).
+
+<Demo title="404 without actions" description="hideActions removes the back and home buttons." src={StatusesSrc}><Statuses client:visible /></Demo>
+
+<Props rows={[
+  { name: "status", type: "number", default: "500", description: "HTTP status shown as the large number. Picks the icon, title and hint for 404, 403, 500 and 503." },
+  { name: "message", type: "string", description: "Replaces the preset hint under the title." },
+  { name: "title", type: "string", description: "Replaces the preset title." },
+  { name: "hideActions", type: "boolean", default: "false", description: "Hides the back and home buttons." },
+  { name: "class", type: "string", default: "''", description: "Extra classes on the root." },
+]} />
diff --git a/site/src/content/docs/layout/form-page.mdx b/site/src/content/docs/layout/form-page.mdx
index e825fc45..ce4806c9 100644
--- a/site/src/content/docs/layout/form-page.mdx
+++ b/site/src/content/docs/layout/form-page.mdx
@@ -32,7 +32,7 @@ AppForm fills its parent, so give the parent a height. It replaces the removed F
 <Demo title="Basic form" description="Header with a back button, a grid of fields, a list of switches and a sticky footer." src={BasicSrc}><Basic client:visible /></Demo>
 <Demo title="Without header" description="Omit title, description, leading, trailing and backHref to drop the header." src={NoHeaderSrc}><NoHeader client:visible /></Demo>
 
-<Props rows={[
+<Props for="AppForm" rows={[
   { name: "title", type: "string", description: "Page title in the header." },
   { name: "description", type: "string", description: "Subtitle under the title." },
   { name: "backHref", type: "string", description: "Renders a back-arrow button linking here. Ignored when leading is provided." },
diff --git a/site/src/content/docs/layout/layout-primitives.mdx b/site/src/content/docs/layout/layout-primitives.mdx
index 4959b389..3a5656fe 100644
--- a/site/src/content/docs/layout/layout-primitives.mdx
+++ b/site/src/content/docs/layout/layout-primitives.mdx
@@ -49,7 +49,7 @@ Pass an object instead of a value. `base` applies everywhere, and each breakpoin
 <Demo title="Responsive Grid" description={"Resize the window: 1, 2, then 4 columns, and the gap grows at `md`."} src={ResponsiveSrc}><Responsive /></Demo>
 <Demo title="Container and Section" src={PageSrc}><Page /></Demo>
 
-<Props title="Shared props" rows={[
+<Props for="Box, Flex, Stack, Grid, Container, Section" title="Shared props" rows={[
   { name: "as", type: "string", default: "per component", description: "Element to render (`div`, `section`, `ul`, `nav`...)." },
   { name: "gap", type: "Space | responsive", default: "undefined", description: "Gap between children." },
   { name: "p, px, py", type: "Space | responsive", default: "undefined", description: "Padding on every side, horizontal, vertical." },
diff --git a/site/src/content/docs/layout/page-shell.mdx b/site/src/content/docs/layout/page-shell.mdx
index fd45f4b7..14cf3017 100644
--- a/site/src/content/docs/layout/page-shell.mdx
+++ b/site/src/content/docs/layout/page-shell.mdx
@@ -22,15 +22,15 @@ import DashboardSrc from "~/demos/layout/page-shell/Dashboard.svelte?raw";
 
 Below 900px the header stacks: the description leads and `actions` wrap onto their own row. Labeled buttons share that row full-width (large tap targets); icon-only controls (`IconButton`, `ThemeToggle`) keep their natural size and stay at the end of the row.
 
-Inside a `PageShell`, `EmptyState` titles default to `<h2>` (under the page `<h1>`). Pass `headingLevel` to `EmptyState` or `Card` to pick the level explicitly.
+The shell renders `title` as the page `<h1>`; below 900px inside an `AppShellLayout` it is hidden visually because the mobile header already shows it. Inside a `PageShell`, `EmptyState` titles default to `<h2>` (under the page `<h1>`). Pass `headingLevel` to `EmptyState` or `Card` to pick the level explicitly.
 
 <Demo title="Dashboard page" description="KPI cards and a content card inside a PageShell." src={DashboardSrc}><Dashboard /></Demo>
 
 <Props rows={[
   { name: "title", type: "string", description: "Page title." },
   { name: "description", type: "string", description: "Supporting text under the title." },
-  { name: "gap", type: "number", default: "28", description: "Vertical gap between the header and the content, in px." },
-  { name: "maxWidth", type: "string", default: "'1280px'", description: "Maximum width of the content column." },
+  { name: "gap", type: "number", default: "undefined", description: "Vertical gap between the header and the content, in px. Omit for `--ca-space-7` (28px at the default density)." },
+  { name: "maxWidth", type: "string", default: "undefined", description: "Maximum width of the content column, any CSS length. Omit for 80rem (1280px at the default 4px spacing unit)." },
   { name: "actions", type: "Snippet", description: "Right side of the page header." },
   { name: "children", type: "Snippet", description: "Page content." },
   { name: "class", type: "string", default: "''", description: "Extra class names." },
diff --git a/site/src/content/docs/layout/sticky-actions.mdx b/site/src/content/docs/layout/sticky-actions.mdx
index 38e93aab..a9e6a4f7 100644
--- a/site/src/content/docs/layout/sticky-actions.mdx
+++ b/site/src/content/docs/layout/sticky-actions.mdx
@@ -1,6 +1,6 @@
 ---
 title: StickyActions
-description: A form action bar pinned to the bottom of a scrolling container, with glass, safe-area and virtual keyboard support.
+description: A form action bar pinned to the bottom of a scrolling container, with safe-area and virtual keyboard support.
 group: Layout
 order: 10
 ---
@@ -22,7 +22,7 @@ import StretchSrc from "~/demos/layout/sticky-actions/Stretch.svelte?raw";
 </StickyActions>
 ```
 
-Place it as the last child of the element that scrolls. On screens narrower than 900px it sticks to the bottom edge with a glass background, respects the home-indicator inset (`--ca-safe-bottom`) and rises with the virtual keyboard. From 900px up it becomes a plain inline row without chrome.
+Place it as the last child of the element that scrolls. On screens narrower than 900px it sticks to the bottom edge with the `--ca-glass-bg` fill (blurred only under the `glass` and `frosted` styles), respects the home-indicator inset (`--ca-safe-bottom`) and rises with the virtual keyboard. From 900px up it becomes a plain inline row without chrome.
 
 <Demo title="End aligned" description="Buttons sit on the right. The bar only renders while the form is dirty (show)." src={DirtySrc}><Dirty client:visible /></Demo>
 <Demo title="Stretch" description="On touch screens the primary button fills the width and the ghost button stays compact." src={StretchSrc}><Stretch client:visible /></Demo>
diff --git a/site/src/content/docs/navigation/actions.mdx b/site/src/content/docs/navigation/actions.mdx
index 4550a43a..e4506e63 100644
--- a/site/src/content/docs/navigation/actions.mdx
+++ b/site/src/content/docs/navigation/actions.mdx
@@ -19,26 +19,27 @@ import LongpressSrc from "~/demos/navigation/actions/Longpress.svelte?raw";
 
 ```svelte
 <script>
-  import { clickOutside, focusTrap, autofocus, clipboard, longpress, keyboardAware, primeKeyboard } from "@codeatlasdev/ui/actions";
+  import { clickOutside, focusTrap, autofocus, clipboard, longpress, scrollFocusable, keyboardAware, primeKeyboard, focusTextField } from "@codeatlasdev/ui/actions";
 </script>
 
 <div use:clickOutside={() => (open = false)}>...</div>
 ```
 
-Actions attach behavior to a plain element with `use:`. They are exported from `@codeatlasdev/ui/actions`, which keeps them out of the main bundle.
+Actions attach behavior to a plain element with `use:`. They are exported from `@codeatlasdev/ui/actions`, which keeps them out of the main bundle. Dialog, Sheet, Drawer and Popover already handle focus, Escape and outside presses through the layer engine, so reach for these actions on your own elements.
 
-<Demo title="clickOutside" description="Calls the handler for every click that lands outside the element." src={ClickOutsideSrc}><ClickOutside client:visible /></Demo>
+<Demo title="clickOutside" description="Calls the handler for every click that lands outside the element. It listens on the capture phase of `document`." src={ClickOutsideSrc}><ClickOutside client:visible /></Demo>
 <Demo title="focusTrap" description="Keeps Tab and Shift+Tab inside the element while enabled." src={FocusTrapSrc}><FocusTrap client:visible /></Demo>
 <Demo title="autofocus" description="Focuses the element when it mounts." src={AutofocusSrc}><Autofocus client:visible /></Demo>
-<Demo title="clipboard" description="Copies the given text on click and dispatches a copy event." src={ClipboardSrc}><Clipboard client:visible /></Demo>
-<Demo title="longpress" description="Dispatches a longpress event after the pointer is held for the given duration." src={LongpressSrc}><Longpress client:visible /></Demo>
+<Demo title="clipboard" description="Copies the given text on click and dispatches a copy event (listen with `oncopy`) once the copy succeeded." src={ClipboardSrc}><Clipboard client:visible /></Demo>
+<Demo title="longpress" description="Dispatches a longpress event (listen with `onlongpress`) after the pointer is held for the given duration." src={LongpressSrc}><Longpress client:visible /></Demo>
 
-<Props title="Actions" rows={[
+<Props for="none" title="Actions" rows={[
   { name: "clickOutside", type: "Action<HTMLElement, () => void>", description: "Calls the handler when a click lands outside the element." },
   { name: "focusTrap", type: "Action<HTMLElement, boolean>", description: "Traps Tab focus inside the element while the parameter is true." },
   { name: "autofocus", type: "Action<HTMLElement, { touch?: boolean } | undefined>", description: "Focuses the element on mount without scrolling. On touch devices it only focuses when primeKeyboard() ran in the opening gesture; pass { touch: true } to focus anyway." },
-  { name: "clipboard", type: "Action<HTMLElement, string>", description: "Copies the text to the clipboard on click and dispatches a copy CustomEvent with the text as detail." },
-  { name: "longpress", type: "Action<HTMLElement, number>", description: "Dispatches a longpress CustomEvent after the pointer is held for the given milliseconds (default 500)." },
+  { name: "clipboard", type: "Action<HTMLElement, string>", description: "Copies the text to the clipboard on click and, once the copy succeeded, dispatches a copy CustomEvent with the text as detail. Nothing is dispatched when the Clipboard API is unavailable, for example on a non-HTTPS page." },
+  { name: "longpress", type: "Action<HTMLElement, number>", description: "Dispatches a longpress CustomEvent after the pointer is held for the given milliseconds (default 500). Releasing or leaving the element cancels it." },
+  { name: "scrollFocusable", type: "Action<HTMLElement>", description: "Makes a scroll container keyboard-reachable only while it overflows: sets tabindex=\"0\" when the content is wider or taller than the box and removes it otherwise. SimpleTable and ScrollArea use it." },
   { name: "keyboardAware", type: "Action<HTMLElement>", description: "Pads the element's bottom by --ca-kb-inset and scrolls the focused field into view when the on-screen keyboard opens. Use on composers and sticky action bars." },
   { name: "primeKeyboard", type: "() => void", description: "Helper, not an action. Call synchronously in the tap handler that opens a view with an autofocused field so iOS and Android open the on-screen keyboard. No-op with a fine pointer." },
   { name: "focusTextField", type: "(el: HTMLElement | null | undefined, force?: boolean) => boolean", description: "Helper used by autofocus. Focuses the element with a fine pointer, or on touch only after primeKeyboard(). Returns whether it focused." },
diff --git a/site/src/content/docs/navigation/app-bar.mdx b/site/src/content/docs/navigation/app-bar.mdx
index eb1175fb..37282f0b 100644
--- a/site/src/content/docs/navigation/app-bar.mdx
+++ b/site/src/content/docs/navigation/app-bar.mdx
@@ -27,7 +27,7 @@ Renders a `<header>`. Icon-only buttons inside it need an `aria-label`. Inside [
 <Demo title="Default" description="Content in the middle and actions in the trailing slot." src={DefaultSrc}><Default /></Demo>
 <Demo title="With leading icon" description="A menu button in the leading slot." src={WithLeadingSrc}><WithLeading /></Demo>
 
-<Props rows={[
+<Props for="GlassAppBar" rows={[
   { name: "children", type: "Snippet", description: "Main content, for example the title." },
   { name: "leading", type: "Snippet", description: "Content at the start, usually a menu button." },
   { name: "trailing", type: "Snippet", description: "Content at the end, usually actions and an avatar." },
diff --git a/site/src/content/docs/navigation/breadcrumb.mdx b/site/src/content/docs/navigation/breadcrumb.mdx
index f7a2d287..4fdd4ade 100644
--- a/site/src/content/docs/navigation/breadcrumb.mdx
+++ b/site/src/content/docs/navigation/breadcrumb.mdx
@@ -19,12 +19,12 @@ import SeparatorSrc from "~/demos/navigation/breadcrumb/Separator.svelte?raw";
 <Breadcrumb items={[{ label: "Home", href: "/" }, { label: "Components" }]} />
 ```
 
-Rendered as a `nav` landmark with an ordered list. The last item is the current page and is not a link.
+Rendered as a `nav` landmark with an ordered list. The last item is the current page: it has `aria-current="page"` and is never a link. Items without `href` render as plain text.
 
 <Demo title="Levels" description="Two, three and five levels, and a single root item." src={LevelsSrc}><Levels /></Demo>
 <Demo title="Custom separator" description="Using › instead of /." src={SeparatorSrc}><Separator /></Demo>
 
-<Props rows={[
+<Props for="Breadcrumb" rows={[
   { name: "items", type: "BreadcrumbItem[]", description: "Array of { label, href? }. The last item is always rendered as the current page, without a link." },
   { name: "separator", type: "string", default: "'/'", description: "Character rendered between crumbs." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
diff --git a/site/src/content/docs/navigation/command-palette.mdx b/site/src/content/docs/navigation/command-palette.mdx
index 714ec5c9..ef182f60 100644
--- a/site/src/content/docs/navigation/command-palette.mdx
+++ b/site/src/content/docs/navigation/command-palette.mdx
@@ -21,12 +21,12 @@ import KeysSrc from "~/demos/navigation/command-palette/Keys.svelte?raw";
 <CommandPalette modules={NAV} onNavigate={(path) => goto(path)} bind:open />
 ```
 
-The palette searches the same `NavModule[]` you pass to [AppShellLayout](/docs/layout/app-shell/). It registers `Cmd+K` and `Ctrl+K` itself, so mount it once near the root. Results are a listbox: arrow keys move the selection, Enter confirms and Escape closes.
+The palette searches the same `NavModule[]` you pass to [AppShellLayout](/docs/layout/app-shell/), matching on item label and module label. It registers `Cmd+K` and `Ctrl+K` itself on `window`, so mount it once near the root. It opens as a modal dialog layer. Arrow keys move the selection, Enter navigates and Escape closes.
 
 <Demo title="Open the palette" description="Click the button or press Cmd+K / Ctrl+K while this page is focused. Picking an item shows its path instead of navigating." src={PaletteSrc}><Palette client:visible /></Demo>
 <Demo title="Keyboard" description="Type to filter across every module. Queries shorter than minQueryLength keep the full grouped list." src={KeysSrc}><Keys /></Demo>
 
-<Props rows={[
+<Props for="CommandPalette" rows={[
   { name: "modules", type: "NavModule[]", description: "Navigation tree to search. Same format as AppShellLayout." },
   { name: "onNavigate", type: "(path: string) => void", description: "Called with the selected item's path. Use goto() in SvelteKit or location in static sites." },
   { name: "open", type: "boolean", default: "false", description: "Bindable. Controls visibility. Cmd+K and Ctrl+K also toggle it." },
diff --git a/site/src/content/docs/navigation/drawer.mdx b/site/src/content/docs/navigation/drawer.mdx
index dded93e8..18ee640d 100644
--- a/site/src/content/docs/navigation/drawer.mdx
+++ b/site/src/content/docs/navigation/drawer.mdx
@@ -1,6 +1,6 @@
 ---
 title: Drawer (navigation)
-description: A sliding panel anchored to the left or right edge, used for navigation and settings.
+description: The Drawer used for navigation and settings panels that slide in from the left or right edge.
 group: Navigation
 order: 8
 ---
@@ -17,6 +17,6 @@ import SidesSrc from "~/demos/navigation/drawer/Sides.svelte?raw";
 <Drawer bind:open side="left" title="Navigation">...</Drawer>
 ```
 
-This is the same component as the [Drawer in Feedback](/docs/feedback/drawer/), shown here with the two navigation patterns: a left menu and a right settings panel. See that page for the full props table, the bottom side and the footer `actions` snippet.
+This is the same component as the [Drawer in Feedback](/docs/feedback/drawer/), shown here with the two navigation patterns: a left menu and a right settings panel. It is a native modal `<dialog>` in the top layer: focus is trapped, Escape and a press on the overlay close it, and focus returns to the trigger. See that page for the full props table, the bottom side and the footer `actions` snippet.
 
 <Demo title="Left and right" description="Left for navigation, right for settings or details." src={SidesSrc}><Sides client:visible /></Demo>
diff --git a/site/src/content/docs/navigation/menu.mdx b/site/src/content/docs/navigation/menu.mdx
index f009b306..07f0b56e 100644
--- a/site/src/content/docs/navigation/menu.mdx
+++ b/site/src/content/docs/navigation/menu.mdx
@@ -13,23 +13,30 @@ import IconTriggerSrc from "~/demos/navigation/menu/IconTrigger.svelte?raw";
 
 ```svelte
 <script>
-  import { DropdownMenu, DropdownMenuItem, DropdownMenuSeparator, Button } from "@codeatlasdev/ui";
+  import {
+    DropdownMenu,
+    DropdownMenuItem,
+    DropdownMenuLabel,
+    DropdownMenuSeparator,
+    Button,
+  } from "@codeatlasdev/ui";
 </script>
 
 <DropdownMenu>
   {#snippet triggerChild(props)}<Button {...props}>Open menu</Button>{/snippet}
+  <DropdownMenuLabel>File actions</DropdownMenuLabel>
   <DropdownMenuItem onclick={edit}>{#snippet children()}Edit{/snippet}</DropdownMenuItem>
   <DropdownMenuSeparator />
   <DropdownMenuItem variant="destructive" onclick={remove}>{#snippet children()}Delete{/snippet}</DropdownMenuItem>
 </DropdownMenu>
 ```
 
-Keyboard support follows the WAI-ARIA menu pattern: Enter or Space opens the menu, arrows move, Escape closes and focus returns to the trigger. Pass an interactive trigger (`Button`, `IconButton`) through `triggerChild` and spread the received `props` on it. Use `trigger` only for non-interactive content such as text or an icon.
+Keyboard support follows the WAI-ARIA menu pattern: Enter, Space or ArrowDown opens the menu on the first item, ArrowUp opens it on the last, arrows then move, Enter or Space selects, Escape closes and focus returns to the trigger. Tab closes the menu. Selecting an item closes it. The menu is a popover layer in the browser top layer, positioned with CSS anchor positioning where supported, so it stays on top of a dialog it is opened from. Pass an interactive trigger (`Button`, `IconButton`) through `triggerChild` and spread the received `props` on it. Use `trigger` only for non-interactive content such as text or an icon. Use `DropdownMenuLabel` for a non-interactive group heading and `DropdownMenuSeparator` for a divider.
 
 <Demo title="Default" description="A button trigger with a label, items, a separator and a destructive item." src={DefaultSrc}><Default client:visible /></Demo>
 <Demo title="Icon trigger" description="An IconButton trigger. IconButton needs an aria-label." src={IconTriggerSrc}><IconTrigger client:visible /></Demo>
 
-<Props title="DropdownMenu" rows={[
+<Props for="DropdownMenu" title="DropdownMenu" rows={[
   { name: "triggerChild", type: "Snippet<[Record<string, unknown>]>", description: "Interactive trigger. Receives the trigger props to spread onto your Button or IconButton." },
   { name: "trigger", type: "Snippet", description: "Non-interactive trigger content (text, icon), wrapped in the menu's own button." },
   { name: "children", type: "Snippet", description: "Menu content: items, labels and separators." },
@@ -39,10 +46,17 @@ Keyboard support follows the WAI-ARIA menu pattern: Enter or Space opens the men
   { name: "class", type: "string", default: "''", description: "Extra CSS classes on the content." },
 ]} />
 
-<Props title="DropdownMenuItem" rows={[
+<Props for="DropdownMenuItem" title="DropdownMenuItem" rows={[
   { name: "onclick", type: "() => void", description: "Called when the item is selected." },
   { name: "variant", type: "'default' | 'destructive'", default: "'default'", description: "destructive colors the item with the error token." },
   { name: "disabled", type: "boolean", default: "false", description: "Prevents selection." },
   { name: "children", type: "Snippet", description: "Item content, usually an icon and a label." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
 ]} />
+
+<Props for="DropdownMenuLabel" title="DropdownMenuLabel" rows={[
+  { name: "children", type: "Snippet", description: "Heading text." },
+  { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
+]} />
+
+`DropdownMenuSeparator` takes no props.
diff --git a/site/src/content/docs/navigation/popover.mdx b/site/src/content/docs/navigation/popover.mdx
index 3db8508e..075e69d2 100644
--- a/site/src/content/docs/navigation/popover.mdx
+++ b/site/src/content/docs/navigation/popover.mdx
@@ -22,12 +22,12 @@ import FormSrc from "~/demos/navigation/popover/Form.svelte?raw";
 </Popover>
 ```
 
-Escape closes the popover, a click outside dismisses it and focus returns to the trigger. Pass an interactive trigger through `triggerChild` and spread the received `props` on it; use `trigger` only for non-interactive content. For a hint that appears on hover, use [Tooltip](/docs/display/tooltip/) instead.
+Escape closes the popover and returns focus to the trigger, and a press outside dismisses it. It is a popover layer in the browser top layer, positioned with CSS anchor positioning where supported, so it stays above a dialog it opens from. Pass an interactive trigger through `triggerChild` and spread the received `props` on it; use `trigger` only for non-interactive content. For a hint that appears on hover, use [Tooltip](/docs/display/tooltip/) instead.
 
 <Demo title="Basic" description="Text and an action inside the popover." src={BasicSrc}><Basic client:visible /></Demo>
 <Demo title="Form" description="A small form anchored to its trigger, aligned to the start." src={FormSrc}><Form client:visible /></Demo>
 
-<Props rows={[
+<Props for="Popover" rows={[
   { name: "triggerChild", type: "Snippet<[Record<string, unknown>]>", description: "Interactive trigger. Receives the trigger props to spread onto your Button or IconButton." },
   { name: "trigger", type: "Snippet", description: "Non-interactive trigger content (text, icon), wrapped in the popover's own button." },
   { name: "children", type: "Snippet", description: "Popover content." },
diff --git a/site/src/content/docs/navigation/stepper.mdx b/site/src/content/docs/navigation/stepper.mdx
index e82bcf36..1783da11 100644
--- a/site/src/content/docs/navigation/stepper.mdx
+++ b/site/src/content/docs/navigation/stepper.mdx
@@ -19,11 +19,11 @@ import HorizontalSrc from "~/demos/navigation/stepper/Horizontal.svelte?raw";
 <Stepper {steps} bind:current={step} />
 ```
 
-The Stepper shows progress; it does not render the step content or the Back and Next buttons. Drive `current` from your own form state, as in the demo.
+The Stepper shows progress and each step bubble is a button that sets `current` when clicked. It does not render the step content or the Back and Next buttons. Drive `current` from your own form state, as in the demo.
 
 <Demo title="Horizontal stepper" description="Four steps with Back and Next controls." src={HorizontalSrc}><Horizontal client:visible /></Demo>
 
-<Props rows={[
+<Props for="Stepper" rows={[
   { name: "steps", type: "StepItem[]", description: "Array of { label, description? }." },
   { name: "current", type: "number", default: "0", description: "Bindable, zero-indexed active step. Earlier steps render as completed." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
diff --git a/site/src/content/docs/navigation/tabs.mdx b/site/src/content/docs/navigation/tabs.mdx
index 08777075..22cca075 100644
--- a/site/src/content/docs/navigation/tabs.mdx
+++ b/site/src/content/docs/navigation/tabs.mdx
@@ -26,27 +26,32 @@ import ControlledSrc from "~/demos/navigation/tabs/Controlled.svelte?raw";
 </Tabs>
 ```
 
-Arrow keys move between tabs, Home and End jump to the first and last, and the panels use the `tabpanel` role. Each `TabsTrigger` and `TabsContent` pair must share a `value`.
+Arrow keys move between tabs, Home and End jump to the first and last, and focusing a tab selects it (automatic activation). Disabled tabs are skipped. The panels use the `tabpanel` role and are focusable. Each `TabsTrigger` and `TabsContent` pair must share a `value`. `Tabs` is horizontal only.
 
 <Demo title="Default" description="Three tabs with content panels." src={DefaultSrc}><Default client:visible /></Demo>
 <Demo title="Controlled" description="The parent owns the active tab with bind:value." src={ControlledSrc}><Controlled client:visible /></Demo>
 
-<Props title="Tabs" rows={[
+<Props for="Tabs" title="Tabs" rows={[
   { name: "value", type: "string", description: "Bindable active tab value." },
-  { name: "onchange", type: "(v: string) => void", description: "Fires when the active tab changes." },
-  { name: "children", type: "Snippet", description: "TabsList and TabsContent children." },
+  { name: "onchange", type: "(v: string) => void", description: "Fires when the active tab changes by click or keyboard." },
+  { name: "children", type: "Snippet", description: "`TabsList` and `TabsContent` children." },
   { name: "class", type: "string", default: "''", description: "Extra classes on the root." },
 ]} />
 
-<Props title="TabsTrigger" rows={[
+<Props for="TabsTrigger" title="TabsTrigger" rows={[
   { name: "value", type: "string", description: "Required. Links the trigger to its TabsContent." },
   { name: "disabled", type: "boolean", default: "false", description: "Prevents selecting the tab." },
   { name: "children", type: "Snippet", description: "Trigger label." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
 ]} />
 
-<Props title="TabsContent" rows={[
+<Props for="TabsContent" title="TabsContent" rows={[
   { name: "value", type: "string", description: "Required. Shown while the matching trigger is active." },
   { name: "children", type: "Snippet", description: "Panel content." },
   { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
 ]} />
+
+<Props for="TabsList" title="TabsList" rows={[
+  { name: "children", type: "Snippet", description: "The `TabsTrigger` elements." },
+  { name: "class", type: "string", default: "''", description: "Extra CSS classes." },
+]} />
diff --git a/site/src/content/docs/surfaces/accordion.mdx b/site/src/content/docs/surfaces/accordion.mdx
index 14c05aaa..bd585b37 100644
--- a/site/src/content/docs/surfaces/accordion.mdx
+++ b/site/src/content/docs/surfaces/accordion.mdx
@@ -23,7 +23,7 @@ import ControlledSrc from "~/demos/surfaces/accordion/Controlled.svelte?raw";
 </Accordion>
 ```
 
-Triggers are buttons with `aria-expanded`, and Arrow, Home and End keys move between them. With `type="single"` the bound `value` is a string, with `type="multiple"` it is a string array.
+Triggers are buttons with `aria-expanded`. Arrow Up, Arrow Down, Home and End move focus between the enabled triggers, and every trigger stays in the tab order. With `type="single"` the bound `value` is a string, with `type="multiple"` it is a string array.
 
 <Demo title="Single" description={"Only one item is open at a time. Clicking the open item collapses it."} src={SingleSrc}><Single client:visible /></Demo>
 <Demo title="Multiple" description={"Several items can be open at once."} src={MultipleSrc}><Multiple client:visible /></Demo>
@@ -32,7 +32,7 @@ Triggers are buttons with `aria-expanded`, and Arrow, Home and End keys move bet
 
 <Props title="Accordion props" rows={[
   { name: "type", type: "'single' | 'multiple'", default: "'single'", description: "Whether one or many items can be open." },
-  { name: "value", type: "string | string[]", default: "undefined", description: "Open item value(s). Bindable." },
+  { name: "value", type: "string | string[]", default: "undefined", description: "Open item value(s): a string for `single` (`''` when none is open), an array for `multiple`. Bindable." },
   { name: "onValueChange", type: "(value: string | string[]) => void", default: "undefined", description: "Called when the open items change." },
   { name: "class", type: "string", default: "''", description: "Extra class names on the root." },
   { name: "children", type: "Snippet", default: "undefined", description: "`AccordionItem` children." },
diff --git a/site/src/content/docs/surfaces/card.mdx b/site/src/content/docs/surfaces/card.mdx
index 4ff0d186..7116dd42 100644
--- a/site/src/content/docs/surfaces/card.mdx
+++ b/site/src/content/docs/surfaces/card.mdx
@@ -25,7 +25,7 @@ import LinkSrc from "~/demos/surfaces/card/Link.svelte?raw";
 <Card title="Team" headingLevel={2} tone="brand">…</Card>
 ```
 
-Card is a [Surface](/docs/surfaces/surface/) with a header (`title`, `headerActions`), padding from `--ca-card-padding` and an optional link. Every Surface prop passes through (`elevation`, `material`, `tone`, `variant`, `radius`, `glow`), and `material="auto"` follows the theme. Use `flush` for content that touches the edges, such as tables, images and code.
+Card is a [Surface](/docs/surfaces/surface/) with a header (`title`, `headerActions`), padding from `--ca-card-padding` and an optional link. Every Surface prop passes through (`elevation`, `material`, `tone`, `variant`, `radius`, `glow`, `interactive`), and `material="auto"` follows the theme: opaque under the default solid style, glass under `liquid`. The demos below set `material="glass"` so they look the same under any style. Use `flush` for content that touches the edges, such as tables, images and code.
 
 `title` is a paragraph unless you pass `headingLevel`, so adding a Card never changes a page outline by accident. Pass `headingLevel` to make the card a section under the page heading (a `PageShell` title is the `<h1>`, so cards start at `2`). Only the tag changes, never the look.
 
@@ -33,7 +33,7 @@ With `href` the card is a single `<a>` and is interactive. The link name comes f
 
 <Demo title="Content card" description={"Text-heavy card with eyebrow, title, body and a link."} src={ContentCardSrc}><ContentCard /></Demo>
 <Demo title="Stat cards" description={"Compact metric display."} src={StatsSrc}><Stats /></Demo>
-<Demo title="Tone and glow" description={"Accent treatments."} src={AccentsSrc}><Accents /></Demo>
+<Demo title="Tone and glow" description={"`tone=\"brand\"` tints the fill. `glow` adds a halo that only shows under styles that keep one, such as `glass`."} src={AccentsSrc}><Accents /></Demo>
 <Demo title="Header and actions" description={"`title` and `headerActions` render a built-in header row."} src={HeaderActionsSrc}><HeaderActions /></Demo>
 <Demo title="Link card" description={"`href` renders the whole card as a link."} src={LinkSrc}><Link /></Demo>
 
diff --git a/site/src/content/docs/surfaces/glass-card.mdx b/site/src/content/docs/surfaces/glass-card.mdx
index 07bdc7f5..79f899bc 100644
--- a/site/src/content/docs/surfaces/glass-card.mdx
+++ b/site/src/content/docs/surfaces/glass-card.mdx
@@ -16,6 +16,14 @@ bunx @codeatlasdev/ui migrate --write src
 
 The codemod rewrites each static usage and leaves dynamic ones (`thickness={t}`) for you. `GlassCard` followed the theme (`<html data-style>`), so the replacement for an unchanged look is `<Card>` with `material="auto"`, which is the default; the codemod writes `material="glass"` so the result is glass in every theme, as the name promised.
 
+```svelte
+<!-- before -->
+<GlassCard thickness="thick" tinted glowing padding="24px" title="Team">…</GlassCard>
+
+<!-- after -->
+<Card material="glass" elevation={4} tone="brand" glow p="6" title="Team">…</Card>
+```
+
 | GlassCard | Card |
 |---|---|
 | `thickness="ultra-thin"` `"thin"` `"regular"` `"thick"` `"chrome"` | `elevation={1}` `{2}` `{3}` (default) `{4}` `{5}` |
diff --git a/site/src/content/docs/surfaces/glass-surface.mdx b/site/src/content/docs/surfaces/glass-surface.mdx
index 6d69037b..065a31c3 100644
--- a/site/src/content/docs/surfaces/glass-surface.mdx
+++ b/site/src/content/docs/surfaces/glass-surface.mdx
@@ -14,6 +14,14 @@ import { Callout } from "@codeatlasdev/ui";
 bunx @codeatlasdev/ui migrate --write src
 ```
 
+```svelte
+<!-- before -->
+<GlassSurface thickness="thick" tinted glowing>…</GlassSurface>
+
+<!-- after -->
+<Surface material="liquid" elevation={4} tone="brand" glow>…</Surface>
+```
+
 | GlassSurface | Surface |
 |---|---|
 | `thickness="ultra-thin"` `"thin"` `"regular"` `"thick"` `"chrome"` | `elevation={1}` `{2}` `{3}` (default) `{4}` `{5}` |
@@ -22,4 +30,6 @@ bunx @codeatlasdev/ui migrate --write src
 | `refraction` (default `true`) | `material="liquid"`; `refraction={false}` is `material="glass"` |
 | `class`, `style`, other attributes | unchanged (use `p` / `as` instead of a padding style) |
 
+`GlassSurface` followed the theme (`<html data-style>`) through its `glass*` classes, and drew the refraction layer when `refraction` was on. The codemod writes `material="liquid"` (or `"glass"`), so the result is glass in every theme, as the name promised.
+
 Dynamic props (`thickness={t}`) are not rewritten by the codemod: map them by hand with the table above.
diff --git a/site/src/content/docs/surfaces/liquid-glass.mdx b/site/src/content/docs/surfaces/liquid-glass.mdx
new file mode 100644
index 00000000..13b20c10
--- /dev/null
+++ b/site/src/content/docs/surfaces/liquid-glass.mdx
@@ -0,0 +1,32 @@
+---
+title: LiquidGlass
+description: The SVG refraction layer that Surface paints when material is "liquid". Use it directly only for a custom glass container.
+group: Surfaces
+order: 7
+---
+import Demo from "~/components/docs/Demo.astro";
+import Props from "~/components/docs/Props.astro";
+import Basic from "~/demos/surfaces/liquid-glass/Basic.svelte";
+import BasicSrc from "~/demos/surfaces/liquid-glass/Basic.svelte?raw";
+
+```svelte
+<script>
+  import { LiquidGlass, GLASS_OPTICS } from "@codeatlasdev/ui";
+</script>
+
+<div class="my-glass">
+  <LiquidGlass optics={GLASS_OPTICS.regular} />
+  <slot />
+</div>
+```
+
+You rarely need this. [Surface](/docs/surfaces/surface/) with `material="liquid"` renders `LiquidGlass` for you and picks the optics from its `elevation`. The component is an absolutely positioned, `aria-hidden` SVG that fills its parent and inherits the parent's border radius, so the parent needs `position: relative` and `overflow: hidden`. It only adds the refraction; the blur, tint and border come from the glass material classes on the parent.
+
+`GLASS_OPTICS` maps each material thickness (`ultra-thin`, `thin`, `regular`, `thick`, `chrome`) to a ready-made `optics` object.
+
+<Demo title="Refraction layer" src={BasicSrc}><Basic /></Demo>
+
+<Props rows={[
+  { name: "optics", type: "{ frost, bend, depth, curvature, sheen, dispersion: number }", description: "Optical parameters of the refraction filter. Required. Take one from `GLASS_OPTICS`." },
+  { name: "style", type: "string", default: "''", description: "Extra inline style for the SVG." },
+]} />
diff --git a/site/src/content/docs/surfaces/surface.mdx b/site/src/content/docs/surfaces/surface.mdx
index f3dd9d06..d94e30c8 100644
--- a/site/src/content/docs/surfaces/surface.mdx
+++ b/site/src/content/docs/surfaces/surface.mdx
@@ -26,12 +26,12 @@ import InteractiveSrc from "~/demos/surfaces/surface/Interactive.svelte?raw";
 
 A Surface is one element painted by one CSS rule (`.ca-surface`). Each prop is a `data-*` attribute, and each attribute writes different `--ca-surface-*` variables, so the axes never fight: `elevation` is depth (shadow and the blur/fill tier), `material` is what the surface is made of, `tone` tints it, `variant` removes the fill or draws an outline, `radius` rounds it. Nothing is written to `style`.
 
-`material="auto"` follows the theme: it reads the tokens that `<html data-style>` already rewrites, so an app on the solid style gets opaque surfaces and one on the `liquid` recipe gets glass, with no change to the component. The explicit materials ignore `data-style`: use `glass` for one blurred surface in a solid app, or `solid` to keep one opaque in a glass app. Glass needs something behind it to blur, which is why the demos sit on a gradient.
+`material="auto"` follows the theme: it reads the tokens that `<html data-style>` already rewrites, so an app on the default solid style gets opaque surfaces and one on the [`liquid` recipe](/docs/getting-started/theming/#surface-styles) gets glass, with no change to the component. The explicit materials ignore `data-style`: use `glass` for one blurred surface in a solid app, or `solid` to keep one opaque in a glass app. `liquid` is `glass` plus the SVG refraction layer, see [LiquidGlass](/docs/surfaces/liquid-glass/). Glass needs something behind it to blur, which is why the demos sit on a gradient.
 
-Rules the CSS follows, and you should too when you wrap a Surface: never `will-change: transform` on it or an ancestor, and never `isolation: isolate` on a parent of a glass or frosted surface. Both silently remove the backdrop blur. Under `prefers-reduced-transparency` translucent fills become opaque, and under `forced-colors` every surface gets a real `CanvasText` border.
+Rules the CSS follows, and you should too when you wrap a Surface: never `will-change: transform` on it or an ancestor, and never `isolation: isolate` on a parent of a glass or frosted surface. Both silently remove the backdrop blur. Under `prefers-reduced-transparency` translucent fills become opaque, and under `forced-colors` every surface gets a real `CanvasText` border, except `variant="ghost"`.
 
 <Demo title="Materials" description={"`auto` follows the theme; the others look the same under every style."} src={MaterialsSrc}><Materials /></Demo>
-<Demo title="Elevation" description={"Steps 0 to 5: shadow and, for `auto`, `glass` and `frosted`, the blur tier (0 flat, 3 regular, 5 chrome)."} src={ElevationSrc}><Elevation /></Demo>
+<Demo title="Elevation" description={"Steps 0 to 5: shadow and, for every material but `solid`, the blur and fill tier (0 flat, 3 regular, 5 chrome)."} src={ElevationSrc}><Elevation /></Demo>
 <Demo title="Tone and variant" description={"Tone tints the fill, or colors the outline of `variant=\"outlined\"`."} src={ToneVariantSrc}><ToneVariant /></Demo>
 <Demo title="Interactive" description={"`interactive` adds hover, press and a focus-visible ring. Render a real `button` or `a` (`as`), so it is focusable and named."} src={InteractiveSrc}><Interactive client:visible /></Demo>
 
@@ -41,9 +41,9 @@ Rules the CSS follows, and you should too when you wrap a Surface: never `will-c
   { name: "material", type: "'auto' | 'solid' | 'frosted' | 'glass' | 'liquid'", default: "'auto'", description: "`auto` follows `<html data-style>`; the others are absolute. `liquid` adds the SVG refraction layer." },
   { name: "tone", type: "'neutral' | 'brand' | 'success' | 'warning' | 'error' | 'info'", default: "'neutral'", description: "Semantic tint over the fill; the outline color of `variant=\"outlined\"`." },
   { name: "variant", type: "'filled' | 'outlined' | 'ghost'", default: "'filled'", description: "`outlined` has an edge and no fill, `ghost` neither." },
-  { name: "radius", type: "'none' | 'sm' | 'md' | 'lg' | 'xl' | 'pill'", default: "'lg'", description: "Corner radius from the radius scale." },
-  { name: "interactive", type: "boolean", default: "false", description: "Hover, press and focus-visible states and a pointer cursor." },
-  { name: "glow", type: "boolean", default: "false", description: "Brand halo behind the surface (a shadow, so it needs no isolation)." },
+  { name: "radius", type: "'none' | 'sm' | 'md' | 'lg' | 'xl' | 'pill'", default: "undefined", description: "Corner radius from the radius scale. Omit for the large radius (`--ca-radius-lg`)." },
+  { name: "interactive", type: "boolean", default: "false", description: "Hover, press and focus-visible states and a pointer cursor. Render a link or button, or give it a role and a name." },
+  { name: "glow", type: "boolean", default: "false", description: "Brand halo behind the surface (a shadow, so it needs no isolation). It uses `--ca-glow-primary`, which is transparent under the `solid` and `flat` styles, so it only shows under styles that keep a glow, such as `glass`." },
   { name: "p, px, py", type: "Space | responsive", default: "undefined", description: "Padding as a spacing step (`\"4\"` = 16px). See [Layout primitives](/docs/layout/layout-primitives/)." },
   { name: "class", type: "string", default: "''", description: "Extra class names. Other attributes are forwarded to the element." },
   { name: "children", type: "Snippet", default: "undefined", description: "Content." },
diff --git a/site/src/demos/display/kbd/Basic.svelte b/site/src/demos/display/kbd/Basic.svelte
new file mode 100644
index 00000000..a01d4ae5
--- /dev/null
+++ b/site/src/demos/display/kbd/Basic.svelte
@@ -0,0 +1,5 @@
+<script lang="ts">
+  import { Kbd } from '@codeatlasdev/ui';
+</script>
+
+<p>Press <Kbd>Ctrl</Kbd> + <Kbd>K</Kbd> to open the command palette, or <Kbd>Esc</Kbd> to close it.</p>
diff --git a/site/src/demos/feedback/dialog/Info.svelte b/site/src/demos/feedback/dialog/Info.svelte
index 34539b01..60792ecd 100644
--- a/site/src/demos/feedback/dialog/Info.svelte
+++ b/site/src/demos/feedback/dialog/Info.svelte
@@ -13,7 +13,7 @@
 <Dialog bind:open title="About this component">
   <p class="body">
     <strong>Dialog</strong> renders a native modal <code>&lt;dialog&gt;</code>. It traps focus
-    (Tab cycles inside), closes on Escape and exposes correct <code>aria-modal</code> semantics.
+    (Tab cycles inside), closes on Escape and makes the page behind inert.
   </p>
   <p class="body">
     The overlay blurs the page while the panel uses a solid <code>--ca-surface-overlay</code>,
diff --git a/site/src/demos/feedback/lightbox/Basic.svelte b/site/src/demos/feedback/lightbox/Basic.svelte
new file mode 100644
index 00000000..1b49abcd
--- /dev/null
+++ b/site/src/demos/feedback/lightbox/Basic.svelte
@@ -0,0 +1,13 @@
+<script lang="ts">
+  import { Button, Lightbox } from '@codeatlasdev/ui';
+
+  const photo =
+    "data:image/svg+xml;utf8," +
+    encodeURIComponent(
+      '<svg xmlns="http://www.w3.org/2000/svg" width="640" height="400"><rect width="640" height="400" fill="#334155"/><circle cx="320" cy="200" r="90" fill="#94a3b8"/></svg>'
+    );
+  let open = $state(false);
+</script>
+
+<Button variant="outlined" onclick={() => (open = true)}>View photo</Button>
+<Lightbox bind:open src={photo} alt="Gray circle on a dark background" />
diff --git a/site/src/demos/foundation/materials/Tiers.svelte b/site/src/demos/foundation/materials/Tiers.svelte
index 25f0ae5f..f17ffeec 100644
--- a/site/src/demos/foundation/materials/Tiers.svelte
+++ b/site/src/demos/foundation/materials/Tiers.svelte
@@ -4,9 +4,9 @@
 	const tiers: { elevation: 1 | 2 | 3 | 4 | 5; label: string; desc: string }[] = [
 		{ elevation: 1, label: "Ultra thin", desc: "Subtle background hint" },
 		{ elevation: 2, label: "Thin", desc: "Light translucency" },
-		{ elevation: 3, label: "Regular", desc: "Standard glass surface" },
-		{ elevation: 4, label: "Thick", desc: "Strong frosted effect" },
-		{ elevation: 5, label: "Chrome", desc: "Opaque chrome bar" },
+		{ elevation: 3, label: "Regular", desc: "Default blur" },
+		{ elevation: 4, label: "Thick", desc: "Strong blur" },
+		{ elevation: 5, label: "Chrome", desc: "Heaviest blur and fill" },
 	];
 </script>
 
diff --git a/site/src/demos/foundation/typography/Families.svelte b/site/src/demos/foundation/typography/Families.svelte
index 324b8386..ac8999c8 100644
--- a/site/src/demos/foundation/typography/Families.svelte
+++ b/site/src/demos/foundation/typography/Families.svelte
@@ -3,6 +3,10 @@
 		<p class="label">--ca-font-sans</p>
 		<p class="sample sample--sans">The quick brown fox jumps over the lazy dog</p>
 	</div>
+	<div>
+		<p class="label">--ca-font-display</p>
+		<p class="sample sample--display">Headings use the display family</p>
+	</div>
 	<div>
 		<p class="label">--ca-font-mono</p>
 		<p class="sample sample--mono">const answer = 42;</p>
@@ -28,5 +32,6 @@
 		color: var(--ca-text-primary);
 	}
 	.sample--sans { font-family: var(--ca-font-sans); }
+	.sample--display { font-family: var(--ca-font-display); }
 	.sample--mono { font-family: var(--ca-font-mono); }
 </style>
diff --git a/site/src/demos/inputs/filter-group/Basic.svelte b/site/src/demos/inputs/filter-group/Basic.svelte
new file mode 100644
index 00000000..600a42b4
--- /dev/null
+++ b/site/src/demos/inputs/filter-group/Basic.svelte
@@ -0,0 +1,13 @@
+<script lang="ts">
+  import { FilterGroup } from '@codeatlasdev/ui';
+
+  const roles = [
+    { value: 'admin', label: 'Admin' },
+    { value: 'editor', label: 'Editor' },
+    { value: 'viewer', label: 'Viewer' },
+  ];
+  let role = $state('all');
+</script>
+
+<FilterGroup label="Role" options={roles} bind:value={role} />
+<p>Selected: {role}</p>
diff --git a/site/src/demos/inputs/radio/Cards.svelte b/site/src/demos/inputs/radio/Cards.svelte
new file mode 100644
index 00000000..015565a9
--- /dev/null
+++ b/site/src/demos/inputs/radio/Cards.svelte
@@ -0,0 +1,13 @@
+<script lang="ts">
+  import { RadioGroup } from '@codeatlasdev/ui';
+
+  let plan = $state('pro');
+
+  const plans = [
+    { value: 'free', label: 'Free', description: 'For side projects.' },
+    { value: 'pro', label: 'Pro', description: 'For teams that ship weekly.' },
+    { value: 'team', label: 'Team', description: 'Shared billing and audit log.', disabled: true },
+  ];
+</script>
+
+<RadioGroup variant="cards" aria-label="Plan" items={plans} bind:value={plan} />
diff --git a/site/src/demos/inputs/setting-item/Basic.svelte b/site/src/demos/inputs/setting-item/Basic.svelte
new file mode 100644
index 00000000..ceccbc9d
--- /dev/null
+++ b/site/src/demos/inputs/setting-item/Basic.svelte
@@ -0,0 +1,13 @@
+<script lang="ts">
+  import { SettingItem, Switch } from '@codeatlasdev/ui';
+
+  let email = $state(true);
+  let digest = $state(false);
+</script>
+
+<SettingItem label="Email notifications" description="Receive an email for every mention.">
+  <Switch bind:checked={email} />
+</SettingItem>
+<SettingItem label="Weekly digest" description="One summary every Monday.">
+  <Switch bind:checked={digest} />
+</SettingItem>
diff --git a/site/src/demos/inputs/swatch-group/Custom.svelte b/site/src/demos/inputs/swatch-group/Custom.svelte
new file mode 100644
index 00000000..ba00d4c5
--- /dev/null
+++ b/site/src/demos/inputs/swatch-group/Custom.svelte
@@ -0,0 +1,34 @@
+<script lang="ts">
+  import { SwatchGroup } from '@codeatlasdev/ui';
+
+  let color = $state('#2563eb');
+</script>
+
+<div class="col">
+  <SwatchGroup
+    size="sm"
+    aria-label="Label color"
+    bind:value={color}
+    items={[
+      { value: '#2563eb', label: 'Blue', color: '#2563eb' },
+      { value: '#16a34a', label: 'Green', color: '#16a34a' },
+      { value: '#dc2626', label: 'Red', color: '#dc2626' },
+      { value: '#9333ea', label: 'Purple', color: '#9333ea', disabled: true },
+    ]}
+  />
+  <p class="out">value: {color}</p>
+</div>
+
+<style>
+  .col {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ca-space-3);
+  }
+
+  .out {
+    margin: 0;
+    font-size: var(--ca-font-size-caption);
+    color: var(--ca-text-secondary);
+  }
+</style>
diff --git a/site/src/demos/inputs/swatch-group/Presets.svelte b/site/src/demos/inputs/swatch-group/Presets.svelte
new file mode 100644
index 00000000..be77e28e
--- /dev/null
+++ b/site/src/demos/inputs/swatch-group/Presets.svelte
@@ -0,0 +1,34 @@
+<script lang="ts">
+  import { SwatchGroup } from '@codeatlasdev/ui';
+
+  let preset = $state('ocean');
+</script>
+
+<div class="col">
+  <SwatchGroup
+    aria-label="Accent"
+    bind:value={preset}
+    items={[
+      { value: 'ocean' },
+      { value: 'violet' },
+      { value: 'emerald' },
+      { value: 'rose' },
+      { value: 'amber' },
+    ]}
+  />
+  <p class="out">value: {preset}</p>
+</div>
+
+<style>
+  .col {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ca-space-3);
+  }
+
+  .out {
+    margin: 0;
+    font-size: var(--ca-font-size-caption);
+    color: var(--ca-text-secondary);
+  }
+</style>
diff --git a/site/src/demos/layout/error-page/Statuses.svelte b/site/src/demos/layout/error-page/Statuses.svelte
new file mode 100644
index 00000000..e3aaebbc
--- /dev/null
+++ b/site/src/demos/layout/error-page/Statuses.svelte
@@ -0,0 +1,5 @@
+<script lang="ts">
+  import { ErrorPage } from '@codeatlasdev/ui';
+</script>
+
+<ErrorPage status={404} hideActions />
diff --git a/site/src/demos/surfaces/accordion/Single.svelte b/site/src/demos/surfaces/accordion/Single.svelte
index 54d12c0c..57a6a68a 100644
--- a/site/src/demos/surfaces/accordion/Single.svelte
+++ b/site/src/demos/surfaces/accordion/Single.svelte
@@ -5,14 +5,14 @@
 <div class="wrap">
   <Accordion type="single">
     <AccordionItem value="a1" title="What is Liquid Glass?">
-      Liquid Glass is a design language that applies real-time backdrop blur, refraction and
-      tinting to UI surfaces, creating depth without heavy visual weight.
+      Liquid Glass is the opt-in look of the kit: backdrop blur, refraction and tinting on
+      surfaces. The default theme is solid.
     </AccordionItem>
     <AccordionItem value="a2" title="Which browsers support backdrop-filter?">
       All modern evergreen browsers. Older environments receive a fallback without the blur effect.
     </AccordionItem>
-    <AccordionItem value="a3" title="Can I nest GlassSurface inside GlassCard?">
-      Yes. Both components use isolation: isolate to keep stacking contexts correct.
+    <AccordionItem value="a3" title="Can I nest a Surface inside a Card?">
+      Yes. A Card is a Surface, so any Surface can sit inside it.
     </AccordionItem>
   </Accordion>
 </div>
diff --git a/site/src/demos/surfaces/card/Accents.svelte b/site/src/demos/surfaces/card/Accents.svelte
index 62f6a929..8074bd10 100644
--- a/site/src/demos/surfaces/card/Accents.svelte
+++ b/site/src/demos/surfaces/card/Accents.svelte
@@ -5,11 +5,11 @@
 <div class="row">
   <Card material="glass" tone="brand" class="accent">
     <p class="title">Tinted</p>
-    <p class="text">Brand gradient overlay on the surface.</p>
+    <p class="text">Brand tint over the fill.</p>
   </Card>
   <Card material="glass" glow class="accent">
     <p class="title">Glowing</p>
-    <p class="text">Backlit halo behind the surface.</p>
+    <p class="text">Brand halo behind the surface.</p>
   </Card>
 </div>
 
diff --git a/site/src/demos/surfaces/liquid-glass/Basic.svelte b/site/src/demos/surfaces/liquid-glass/Basic.svelte
new file mode 100644
index 00000000..2c0ccabb
--- /dev/null
+++ b/site/src/demos/surfaces/liquid-glass/Basic.svelte
@@ -0,0 +1,17 @@
+<script lang="ts">
+  import { LiquidGlass, GLASS_OPTICS } from '@codeatlasdev/ui';
+</script>
+
+<div class="frame">
+  <LiquidGlass optics={GLASS_OPTICS.regular} />
+  <p>Refraction layer behind this text.</p>
+</div>
+
+<style>
+  .frame {
+    position: relative;
+    padding: var(--ca-space-6);
+    border-radius: var(--ca-radius-lg);
+    overflow: hidden;
+  }
+</style>