@tonycodes-ui/mortar 0.0.0-stage → 0.12.0

package/dist/workspace.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { KitLink } from "./navigation.js";
+import { Fragment, useId } from "react";
+import { Combobox, ComboboxInput, ComboboxOption, ComboboxOptions, Description, DialogPanel, DialogTitle, } from "@headlessui/react";
+import { Button } from "./primitives.js";
+import { Kbd } from "./display.js";
+import { ChevronRight, Close } from "./icons.js";
+import { childLevel, headingTag } from "./heading.js";
+import { DialogFrame, componentRoot, cx, useComponentName, } from "./internal.js";
+export function SlideOver({ open, onClose, title, description, children, actions, size = "md", className, }) {
+    return (_jsx(DialogFrame, { open: open, onClose: onClose, component: "SlideOver", children: _jsxs(DialogPanel, { className: cx("m-slide-over", className), "data-size": size === "md" ? undefined : size, children: [_jsxs("header", { children: [_jsxs("div", { children: [_jsx(DialogTitle, { children: title }), description && _jsx(Description, { children: description })] }), _jsx(Button, { variant: "ghost", onClick: onClose, "aria-label": "Close panel", children: _jsx(Close, {}) })] }), _jsx("div", { className: "m-slide-over-body", children: children }), actions && _jsx("footer", { className: "m-actions", children: actions })] }) }));
+}
+function Highlight({ label, match, }) {
+    if (!match)
+        return _jsx(_Fragment, { children: label });
+    const [a, b] = match;
+    return (_jsxs(_Fragment, { children: [label.slice(0, a), _jsx("mark", { children: label.slice(a, b) }), label.slice(b)] }));
+}
+/** Controlled ⌘K palette. Filtering and ranking stay with the consumer. */
+export function CommandPalette({ open, onClose, query, onQueryChange, groups, label = "Command menu", placeholder = "Type a command or search", empty, footer, className, }) {
+    const total = groups.reduce((n, g) => n + g.items.length, 0);
+    const component = useComponentName("CommandPalette");
+    return (_jsx(DialogFrame, { open: open, onClose: onClose, component: component, children: _jsx("div", { className: "m-dialog-position m-palette-position", children: _jsxs(DialogPanel, { className: cx("m-palette", className), children: [_jsx(DialogTitle, { className: "m-sr-only", children: label }), _jsxs(Combobox, { value: null, onChange: (item) => {
+                            if (!item)
+                                return;
+                            item.onSelect();
+                            onClose();
+                        }, children: [_jsxs("div", { className: "m-palette-input", children: [_jsx(ComboboxInput, { autoFocus: true, "aria-label": label, placeholder: placeholder, value: query, onChange: (e) => onQueryChange(e.target.value), onKeyDownCapture: (e) => {
+                                            if (e.key === "Escape") {
+                                                e.preventDefault();
+                                                e.stopPropagation();
+                                                onClose();
+                                            }
+                                        } }), _jsx(Kbd, { keys: ["esc"] })] }), _jsx(ComboboxOptions, { static: true, modal: false, className: "m-palette-results", children: groups
+                                    .filter((g) => g.items.length)
+                                    .map((group) => (_jsxs("div", { role: "group", "aria-label": group.label, children: [_jsx("div", { className: "m-palette-group", "aria-hidden": "true", children: group.label }), group.items.map((item) => (_jsx(ComboboxOption, { value: item, as: Fragment, children: _jsxs("div", { className: "m-palette-item", children: [item.icon && (_jsx("span", { className: "m-palette-icon", "aria-hidden": "true", children: item.icon })), _jsxs("span", { children: [_jsx("span", { className: "m-palette-label", children: _jsx(Highlight, { label: item.label, match: item.match }) }), item.description && (_jsx("small", { children: item.description }))] }), item.shortcut ? (_jsx(Kbd, { keys: item.shortcut })) : (item.meta && (_jsx("span", { className: "m-palette-meta", children: item.meta })))] }) }, item.id)))] }, group.label))) })] }), _jsx("p", { className: total ? "m-sr-only" : "m-palette-empty", role: "status", children: total ? ("") : empty ? (_jsxs(_Fragment, { children: [empty.title, empty.description && _jsxs("span", { children: [" ", empty.description] })] })) : (`No results for “${query}”.`) }), footer && _jsx("div", { className: "m-palette-footer", children: footer })] }) }) }));
+}
+export function StackedList({ label, title, headingLevel = 2, action, items = [], groups = [], chevrons = false, id, className, }) {
+    const base = useId();
+    const hasTitle = title !== undefined && title !== null && title !== "";
+    const Title = headingTag(headingLevel);
+    const GroupHeading = headingTag(hasTitle ? childLevel(headingLevel) : headingLevel);
+    const row = (item) => {
+        const body = (_jsxs(_Fragment, { children: [item.leading, _jsxs("span", { className: "m-stacked-text", children: [_jsx("strong", { children: item.title }), item.description && _jsx("span", { children: item.description })] }), item.meta && _jsx("span", { className: "m-stacked-meta", children: item.meta }), chevrons && item.href && (_jsx("span", { className: "m-stacked-chevron", "aria-hidden": "true", children: _jsx(ChevronRight, {}) }))] }));
+        return (_jsxs("li", { children: [item.href ? (_jsx(KitLink, { href: item.href, children: body })) : (_jsx("div", { children: body })), item.trailing && (_jsx("div", { className: "m-stacked-trailing", children: item.trailing }))] }, item.id));
+    };
+    return (_jsxs("section", { id: id, ...componentRoot("StackedList"), className: cx("m-stacked-list", className), "aria-label": label, "aria-labelledby": label || !hasTitle ? undefined : `${base}-title`, children: [(hasTitle || action) && (_jsxs("header", { children: [hasTitle && (_jsx(Title, { id: `${base}-title`, className: "m-stacked-title", children: title })), action && _jsx("div", { className: "m-stacked-action", children: action })] })), (items.length > 0 || !groups.length) && _jsx("ul", { children: items.map(row) }), groups.map((group, index) => (_jsxs("div", { className: "m-stacked-group", children: [_jsx(GroupHeading, { id: `${base}-${index}`, className: "m-stacked-group-heading", children: group.label }), _jsx("ul", { "aria-labelledby": `${base}-${index}`, children: group.items.map(row) })] }, group.label)))] }));
+}

package/docs/agents.md

@@ -0,0 +1,127 @@
+# Mortar for coding agents
+
+Mortar ships its own agent tooling: an MCP server and a `mortar` command-line tool inside the `@tonycodes-ui/mortar` package. Both read the installed package's catalogue (`catalog.json`), contracts, examples and guides. They run locally and work offline. They need no account, token or hosted service, and they never send anything anywhere. Everything is MIT licensed, like the kit.
+
+The tooling needs Node 22 or newer. It adds no runtime dependencies to your app.
+
+## Install
+
+In the application:
+
+```sh
+npm install @tonycodes-ui/mortar react react-dom tailwindcss
+```
+
+In the app's Tailwind CSS entry, after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "@tonycodes-ui/mortar/styles.css";
+```
+
+Render one `ThemeProvider` at the root:
+
+```tsx
+import { ThemeProvider } from "@tonycodes-ui/mortar";
+
+<ThemeProvider brand="neutral" density="comfortable" initialAppearance="system">
+  <App />
+</ThemeProvider>;
+```
+
+## Connect the MCP server
+
+The server speaks the Model Context Protocol over stdio. Inside an app that has Mortar installed, `npx` runs the installed version, so the tools always describe the components you actually import.
+
+**Claude Code:**
+
+```sh
+claude mcp add mortar -- npx -y @tonycodes-ui/mortar mcp
+```
+
+Add `--scope project` to share it with the repository through `.mcp.json`.
+
+**Cursor, Windsurf, VS Code and other clients** that read an `mcpServers` JSON file (for example `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mortar": {
+      "command": "npx",
+      "args": ["-y", "@tonycodes-ui/mortar", "mcp"]
+    }
+  }
+}
+```
+
+In a project without Mortar installed, `npx -y @tonycodes-ui/mortar mcp` downloads the latest release first. To run a checkout of this repository instead, use `node /path/to/mortar/bin/mortar.mjs mcp` after `npm run build`.
+
+## Tools
+
+| Tool                | Arguments                                    | Returns                                                                                                                                                                                                                                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search_components` | `query`, optional `kit`, `category`, `limit` | Ranked components: name, kit, category, description, capabilities.                                                                                                                                                                                       |
+| `get_component`     | `name`                                       | The full contract: props with types, required flags and defaults; usage, avoid and accessibility notes; the components it renders; its `data-m-component` marker; tested states; page templates; a JSX example; the import line.                         |
+| `get_build_packet`  | `components` and/or `brief`                  | The chosen components (for a brief, with the reason for each, starting from the purpose shell), their dependency closure, install, CSS and ThemeProvider setup, the import line, the design principles and API conventions, and matching page templates. |
+| `get_guide`         | `topic`                                      | A guide as markdown: `design`, `conventions`, `theming`, `auth-flows`, `migrating-0.6`, `contributing`, `testing` or `agents`.                                                                                                                           |
+| `list_kits`         | none                                         | Kits → categories → components, and the page templates.                                                                                                                                                                                                  |
+| `audit_app`         | `path`                                       | A read-only audit of an application: findings with file, line, rule, message and a suggested fix.                                                                                                                                                        |
+
+## Command line
+
+The same data is available without an MCP client:
+
+```sh
+npx mortar search "sign in"
+npx mortar component DataTable
+npx mortar packet AppShell DataTable
+npx mortar packet --brief "an admin screen listing invoices with filters"
+npx mortar audit .
+npx mortar guide theming
+```
+
+Add `--json` for machine-readable output. `mortar audit` exits with status 1 when it finds errors, so it can run in CI. `mortar --help` lists every command.
+
+## Workflow
+
+1. **Search.** Before writing UI, find what the kit already has: `search_components`, or `list_kits` to browse. Start from the purpose shell: `AppShell` for application screens, `MarketingHeader` (with `Footer`) for public pages, `DocsShell` for documentation and `AuthLayout` for sign-in and registration.
+2. **Packet.** Call `get_build_packet` with the components you picked, or with the brief. Compose from it: the contracts list every prop, and the page templates show complete page patterns to follow.
+3. **Compose.** Use named imports from `@tonycodes-ui/mortar` and the exact props and values in each contract. Keep product names, data, routes, permissions and actions in props and slots. Theme with `ThemeProvider` and tokens (`get_guide theming`). Never copy a component's source, wrap it repeatedly, or override `.m-*` classes or `[data-m-component]` in your CSS.
+4. **Audit.** Run `audit_app` (or `npx mortar audit`) and fix what it finds, then run the app's own typecheck and build. Verify in a browser: mobile and desktop, light and dark, keyboard and focus, and loading, empty and error states.
+5. **Contribute.** If a shared pattern is missing or a component is wrong, fix it in the kit, not in the app. Open a pull request at [github.com/tonycodes/mortar](https://github.com/tonycodes/mortar) following [CONTRIBUTING.md](../CONTRIBUTING.md) and [AGENTS.md](../AGENTS.md) (`get_guide contributing`). Maintainer review and CI decide what merges; agents never approve, merge or publish their own changes.
+
+## The audit
+
+`audit_app` reads the application's files and never changes them. It checks against the contracts of the Mortar version installed in the app (or, for releases older than this tooling, against the tool's own catalogue, and says so).
+
+| Rule                     | Severity | Finds                                                                                                                                                                                                                                                       |
+| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `not-declared`           | error    | Mortar imported but missing from package.json                                                                                                                                                                                                               |
+| `not-installed`          | error    | Mortar imported but not in node_modules                                                                                                                                                                                                                     |
+| `version-mismatch`       | error    | The installed version does not satisfy the package.json range                                                                                                                                                                                               |
+| `unknown-export`         | error    | A named import the installed version does not export, with the replacement for names removed in 0.6                                                                                                                                                         |
+| `deep-import`            | error    | Imports or aliases into the package's `src` or `dist`                                                                                                                                                                                                       |
+| `unknown-prop`           | error    | A prop the component's contract does not declare, with the 0.6 rename where there is one                                                                                                                                                                    |
+| `invalid-value`          | error    | A literal outside the prop's declared union, such as `layout="centered"` (now `center`)                                                                                                                                                                     |
+| `css-override`           | error    | Consumer CSS selecting Mortar's `.m-*` classes or `[data-m-component]`                                                                                                                                                                                      |
+| `class-override`         | error    | A Tailwind arbitrary variant that targets `.m-*` classes, such as `[&_.m-button]:rounded-none`                                                                                                                                                              |
+| `local-copy`             | error    | A copy of a Mortar source file, or code rendering Mortar's component marker                                                                                                                                                                                 |
+| `missing-styles`         | error    | No import of `@tonycodes-ui/mortar/styles.css`                                                                                                                                                                                                              |
+| `styles-order`           | warning  | Mortar's styles imported before Tailwind                                                                                                                                                                                                                    |
+| `missing-theme-provider` | warning  | Mortar components rendered without a `ThemeProvider`                                                                                                                                                                                                        |
+| `kit-class`              | warning  | Mortar-internal class names on the app's own markup                                                                                                                                                                                                         |
+| `raw-colour`             | warning  | Hex, `rgb()`/`oklch()` colours or Tailwind palette classes in files that render Mortar components, except where they define a brand (`brandTokens`, `brandToCss`/`brandToStyle`/`registerBrand` arguments, `BrandDefinition` objects, `--m-brand-*` values) |
+| `limited-data`           | info     | The installed release has no agent data, so a newer catalogue was used                                                                                                                                                                                      |
+
+The audit is a fast scanner, not a type checker. It does not see props passed through a spread (`{...props}`), components re-exported or wrapped under another name, class names built at runtime, or markup in `.vue`, `.svelte`, `.astro` or `.html` files. Run the app's typecheck and build as well.
+
+## Agent skill
+
+[`skills/mortar/SKILL.md`](../skills/mortar/SKILL.md) is a ready-made skill with these workflow defaults. For Claude Code, install it once:
+
+```sh
+mkdir -p ~/.claude/skills/mortar
+npx mortar skill > ~/.claude/skills/mortar/SKILL.md
+```
+
+Or put it in a project's `.claude/skills/mortar/` to share it with everyone working there.

package/docs/auth-flows.md

@@ -0,0 +1,71 @@
+# Sign-in and registration flows
+
+Every auth screen is a page of its own, built from the same parts:
+
+- **AuthLayout** is the page. It renders the `main` landmark and the page's `h1`, with an optional logo, description and footer link. `layout="center"` sets the form on the page, `layout="cards"` on a raised card, and `layout="split"` beside an `aside` (a quote or image) on wide screens.
+- **ProviderButtons** lists sign-in providers (GitHub, Google, SSO). Separate them from the email form with `<Divider label="or continue with" soft spacing="none" />`.
+- **PasswordInput** is every password field: a show/hide toggle, the right `autocomplete`, an optional requirement checklist and a strength meter.
+- **CodeInput** is every one-time code: one input drawn as a cell per character.
+- **ErrorSummary** lists the problems after a failed submit, above the form, with a link to each field.
+- **Input**, **Checkbox**, **Button** and **Notice** do the rest. Submit buttons use `loading` while the request runs.
+
+AuthLayout is a standalone page: do not put it inside AppShell or MarketingHeader. For a passwordless sign-in section inside another page (an emailed link plus providers), use **SignInPanel** with `headingLevel={2}`.
+
+A `<form>` placed directly in AuthLayout stacks its fields, and its direct Button children fill the width. Give each form an accessible name (`aria-label="Sign in"`), and set `noValidate` when you show your own errors.
+
+## Steps
+
+The playground has a page template for each step (`?recipe=<id>`).
+
+| Step             | Template                   | Components                                                                                                                                                                  | Fields and `autocomplete`                                                                                                                                                      |
+| ---------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Sign in          | `sign-in`, `sign-in-split` | AuthLayout, Input, PasswordInput, Checkbox ("Remember me"), a "Forgot password?" link, Divider, ProviderButtons; footer links to sign-up                                    | Email: `type="email" autoComplete="username"`. Password: `PasswordInput` (default `purpose="current"`, `current-password`)                                                     |
+| Sign up          | `sign-up`                  | AuthLayout, Input, PasswordInput with `requirements` and `strength`, Checkbox (`required`, with `error`) for the terms with links, ProviderButtons; footer links to sign-in | Name: `autoComplete="name"`. Email: `type="email" autoComplete="email"`. Password: `purpose="new"` (`new-password`)                                                            |
+| Forgot password  | `forgot-password`          | AuthLayout, Input, Button, a success Notice                                                                                                                                 | Email: `type="email" autoComplete="email"`                                                                                                                                     |
+| Check your email | `check-email`              | AuthLayout, Text, a resend Button with a cooldown                                                                                                                           | none                                                                                                                                                                           |
+| Reset password   | `reset-password`           | AuthLayout, two PasswordInputs, Button                                                                                                                                      | Both `purpose="new"`. Add a hidden `<input type="email" autoComplete="username" value={email} readOnly hidden>` so password managers save the new password against the account |
+| Verify email     | `verify-email`             | AuthLayout, CodeInput, Button, a resend Button with a countdown, a "Change your email" link                                                                                 | `CodeInput` (`one-time-code`, `inputmode="numeric"`)                                                                                                                           |
+| Two-factor       | `two-factor`               | AuthLayout, CodeInput, Button, a ghost Button that switches to a recovery code                                                                                              | Authenticator: `CodeInput`. Recovery: `CodeInput alphanumeric length={8}`                                                                                                      |
+
+## Validation and errors
+
+- Validate on submit, not while the person is still typing. Clear a field's error as soon as they change it.
+- Show each error under its field (`error` on Input, PasswordInput, CodeInput and Checkbox, and on RadioGroup for a group: the field is marked `aria-invalid` and the message is announced).
+- When a submit fails, also show an `ErrorSummary` above the form: pass the same messages, each with its field's id as `target`, and the count of failed submits as `submitCount`. It is an alert titled "There is a problem" and takes focus after each failed submit, so keyboard and screen reader users start from the list; it does not take focus while a fixed field's error clears. Each link focuses its field (the checked or first radio of a RadioGroup) and scrolls its label into view without changing the URL. The templates show the pattern.
+- Messages say what to do: "Enter your email address", "Enter an email address in the correct format, like name@example.com", "The passwords don't match".
+- Errors from the server (wrong password, expired code) go in the same places: a form-level Notice for credentials, the field's `error` for a code.
+- Confirm success with a Notice whose title changes from empty (`announce`, kept mounted), or by moving to the next step.
+
+## Passwords
+
+- **Show every rule up front.** Pass every rule the server enforces as `requirements`, before the person types. Never reveal a rule only after a failed submit.
+- Requirements update on each keystroke visually, but are announced only when the whole set becomes met (or stops being met), not on every key.
+- Use a real strength estimator (for example zxcvbn) for `strength`; the playground's scoring is a stand-in.
+- **Never block paste**, and never disable autocomplete on password fields. Password managers and pasting from them are the safest way to use long, unique passwords.
+- Do not cap password length below 64 characters, or forbid characters such as spaces.
+- For a confirm field, use a second `PasswordInput purpose="new"` and check that the values match on submit.
+
+## One-time codes
+
+- Use one `CodeInput`, never one input per digit: separate inputs break screen readers, paste and SMS or password-manager autofill.
+- Pasting a formatted code (`123 456`, `123-456`) works: `onChange` receives only the allowed characters.
+- **Do not submit automatically unless you mean to.** `onComplete` is opt-in: pass it only when a full code should submit at once (the two-factor template does, and says so in the hint). Otherwise the person presses the button.
+- Say where the code went ("We sent a 6-digit code to ana@example.com") and how long it lasts. Offer resend, a way to change the address, and a fallback such as a recovery code.
+- **Never log codes, or store them in analytics, URLs or local storage.** Treat a code like a password.
+
+## Security notes
+
+- **Do not reveal whether an account exists.** "If an account exists for that address, you'll get a link" — on forgot-password, sign-up conflicts and resend.
+- **Rate limits come from the server.** Show its message in the page ("You've asked for a lot of emails. Try again in 10 minutes.") with a Notice, a field `error` or the resend status, and keep the action `aria-disabled` while it applies, so focus stays on it. Mortar has no built-in limit: pass whatever your auth service returns.
+- Resend buttons count down before they can be used again (the templates use 30 seconds). Use `aria-disabled` rather than `disabled`, so a focused button keeps focus.
+- After a password reset, sign out other sessions and say so.
+- Provider buttons call your auth SDK through `onSelect`; Mortar renders no redirects and holds no credentials.
+
+## Accessibility checklist
+
+- One `h1` per page (AuthLayout's `title`) and one `main`.
+- Every field has a visible label; hints and errors are linked with `aria-describedby`.
+- The password toggle is a button named "Show password" with `aria-pressed`; it never steals focus from the field.
+- Links in AuthLayout's text are underlined, so they do not rely on colour.
+- Focus moves only in response to the person: to the error summary after a failed submit, to the new field when switching to a recovery code. Do not autofocus on page load.
+- On narrow screens, `layout="split"` puts a text aside after the form and hides an aside that is only an image or video.

package/docs/migrating-to-0.6.md

@@ -0,0 +1,94 @@
+# Migrating to 0.6
+
+Mortar 0.6.0 applies one set of API conventions across every component. The rules are in [DESIGN.md](../DESIGN.md#api-conventions). Old names were removed rather than aliased, so TypeScript reports every call site that needs a change. Work through the compiler errors with the tables below.
+
+## Patterns that apply everywhere
+
+| Before                                                                        | After                                            |
+| ----------------------------------------------------------------------------- | ------------------------------------------------ |
+| Busy props: `saving`, `submitting`, `adding`                                  | `loading`                                        |
+| `emptyTitle`, `emptyDescription`, `emptyAction`, `emptyMessage`, `emptyLabel` | `empty={{ title, description?, action? }}`       |
+| Item or action callbacks: `onClick`                                           | `onSelect`                                       |
+| Column `align: "left" \| "right"`                                             | `align: "start" \| "end"`                        |
+| `headingLevel` that set item headings (GridList, ProductList, Steps, Footer)  | `itemHeadingLevel`                               |
+| Visible heading props named `heading`                                         | `title`                                          |
+| Group shapes `{ title, items }` or `{ title, links }`                         | `{ label, items }` (`ItemGroup`)                 |
+| Single-word values `centered`, `card`                                         | `center`, `cards`                                |
+| Section tone `surface`                                                        | `default`                                        |
+| `className` on an inner control (Input, Select, TextArea, Checkbox, Switch)   | `className` goes on the component's root element |
+
+New everywhere, with no change needed:
+
+- every component accepts `className` on its root;
+- section-level components accept `id`;
+- headings accept `headingLevel` (`1`–`6`).
+
+## By component
+
+### Controls and feedback
+
+| Component            | Before                                            | After                                                                                                                        |
+| -------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Button               | `loading` sets native `disabled`                  | `loading` sets `aria-disabled` and `aria-busy`, and the button keeps focus. Don't rely on `:disabled` styling while loading. |
+| ButtonGroup          | item `onClick`                                    | item `onSelect`                                                                                                              |
+| Toast                | `action` / `secondaryAction` `{ label, onClick }` | `{ label, onSelect }` (`ToastAction`)                                                                                        |
+| SaveBar              | `saving`                                          | `loading`                                                                                                                    |
+| CommentComposer      | `submitting`, `onValueChange`                     | `loading`, `onChange`                                                                                                        |
+| ConfirmDialog        | `destructive` (boolean, default `true`)           | `tone: "default" \| "danger"` (default `"danger"`)                                                                           |
+| Combobox             | `emptyLabel`                                      | `empty={{ title }}`                                                                                                          |
+| Banner               | `tone="neutral"`                                  | `tone="default"`                                                                                                             |
+| PreviewFrame         | `title`                                           | `label`                                                                                                                      |
+| Badge, Notice, Toast | `m-tone-*` classes                                | `data-tone`, omitted for neutral                                                                                             |
+| Modal                | `data-size="md"`                                  | omitted for the default size                                                                                                 |
+
+### Application
+
+| Component            | Before                                                              | After                                                                                                                                                  |
+| -------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| AppShell             | `user`, `secondaryNavigation`                                       | `footer`, `sections`                                                                                                                                   |
+| AppShell             | main element `id="m-content"`                                       | a generated id; use the skip link instead of a hard-coded `#m-content`                                                                                 |
+| AppShell, DocsShell  | Menu button `aria-label="Open navigation"`                          | named by its visible text "Menu", with `aria-haspopup="dialog"` and `aria-expanded`                                                                    |
+| StackedList          | `heading`                                                           | `title`, plus `headingLevel`. Group headings sit one level below the title; without a title they use `headingLevel`. `items` and `groups` both render. |
+| DataTable            | `emptyTitle`, `emptyDescription`; column `align: "left" \| "right"` | `empty`; `align: "start" \| "end"`                                                                                                                     |
+| Table                | column `align: "left" \| "right"`                                   | `align: "start" \| "end"`                                                                                                                              |
+| GridList             | `headingLevel` (item headings)                                      | `itemHeadingLevel`                                                                                                                                     |
+| Card                 | `tone="sunken"`                                                     | `tone="muted"`                                                                                                                                         |
+| Text                 | `tone`                                                              | `color` (`data-color`)                                                                                                                                 |
+| ProgressBar          | `tone: "primary" \| "warning" \| "danger"`                          | `tone: Tone`; omit it for the accent colour                                                                                                            |
+| CommandPalette       | `emptyMessage`                                                      | `empty={{ title, description? }}`                                                                                                                      |
+| Navbar, StackedShell | `NavigationItem[]` (children silently dropped)                      | `LinkItem[]`                                                                                                                                           |
+| Sidebar              | group labels are `<h2>`                                             | `<p class="m-nav-group-title">` in a labelled group; a parent with children lists its own page as the first link                                       |
+
+### Marketing and docs
+
+| Component             | Before                                             | After                                                                                                                                          |
+| --------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Hero                  | `align="center" \| "split"`                        | `layout="center" \| "split"`                                                                                                                   |
+| FAQ                   | `layout="centered"`                                | `layout="center"`                                                                                                                              |
+| CallToAction, Pricing | `tone: MarketingTone` (`surface \| inverse`)       | `tone: SectionTone` (`default \| muted \| inverse`); `MarketingTone` is removed                                                                |
+| BentoGrid             | item `inverse: boolean`                            | item `tone: SectionTone`                                                                                                                       |
+| Footer                | `columns: { title, links }[]`; `headingLevel`      | `columns: { label, items }[]`; `itemHeadingLevel`                                                                                              |
+| Steps                 | `headingLevel`                                     | `itemHeadingLevel`                                                                                                                             |
+| DocsShell             | `navigation: { title, items }[]`                   | `navigation: { label, items }[]`; icons, counts and nested items now render                                                                    |
+| Callout               | `type: "note" \| "tip" \| "warning" \| "breaking"` | `tone: Tone`: `tip` becomes `success`, and `breaking` becomes `tone="danger" title="Breaking"`. It renders `role="note"` instead of `<aside>`. |
+| LinkCards             | item `title`                                       | item `label`                                                                                                                                   |
+| PagerLinks            | landmark named "Pagination"                        | `label`, default "Previous and next page"                                                                                                      |
+| Pricing               | availability text in `role="status"`               | plain text with class `m-pricing-availability`                                                                                                 |
+
+### Ecommerce and calendar
+
+| Component                         | Before                                                | After                                                                               |
+| --------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| ProductList                       | `headingLevel` (item headings); `variant="card"`      | `itemHeadingLevel`; `variant="cards"`                                               |
+| ProductOverview, ProductQuickView | `adding`; the add button was `type="button"`          | `loading`; the add button submits the form, so `onAdd` fires once on submit         |
+| ProductFilters                    | `onChange(facet, values)`                             | `onChange(selected)` with the complete next selection                               |
+| ShoppingCart                      | `emptyTitle`, `emptyDescription`, `emptyAction`       | `empty`, plus `headingLevel`                                                        |
+| OrderHistory                      | `emptyTitle`, `emptyDescription`                      | `empty`                                                                             |
+| Calendar                          | `onDateChange` fired only from the week and day views | it fires from every view, and so does `onMonthChange`; a new controlled `date` prop |
+
+## Markup and styling
+
+Read this section if your own CSS or tests select on Mortar markup.
+
+- **Data attributes follow one rule.** A boolean attribute is present only when true (`data-x="true"`). An enum attribute is omitted for its default value. Selectors such as `[data-divider="false"]` or `[data-variant="compact"]` no longer match. Use `:not([data-divider])` or the component's own props instead.
+- **Section and component titles carry classes** such as `m-section-title`, `m-card-title` and `m-product-name`. Styles no longer depend on the title being an `h2`.

package/docs/theming.md

@@ -0,0 +1,170 @@
+# Theming
+
+Mortar's look comes from tokens in [`src/tokens.css`](../src/tokens.css), in three layers:
+
+1. **Brand contract.** A brand declares `--m-brand-l-*` (light), `--m-brand-d-*` (dark) and the brand fonts (`--m-brand-font`, `--m-brand-font-heading`), and nothing else. Every value is optional.
+2. **Appearance.** Light and dark resolve the contract into the live tokens (`--m-primary`, `--m-link`, …) and into the `--m-inv-*` tokens that inverse sections use. So dark mode and `tone="inverse"` never need brand-specific CSS.
+3. **Scales.** Type, space, radius, sizing, density and stacking. These are appearance-independent.
+
+Components only read the live `--m-*` tokens. Never style components directly; change tokens.
+
+## Choosing a brand, appearance and density
+
+```tsx
+<ThemeProvider brand="green" initialAppearance="system" density="compact">
+  <App />
+</ThemeProvider>
+```
+
+ThemeProvider writes `data-mortar-brand`, `data-mortar-appearance` and `data-mortar-density` on the document root, or on a wrapper with `scope="container"`. Menus, listboxes and dialogs opened inside a container keep its theme.
+
+## Adding a brand
+
+### In CSS
+
+A brand is one rule. This is enough; everything else derives from it:
+
+```css
+[data-mortar-brand="acme"] {
+  --m-brand-l-primary: #1d4ed8;
+  --m-brand-l-on-primary: #ffffff;
+  --m-brand-d-primary: #93c5fd;
+  --m-brand-d-on-primary: #0b1f4d;
+}
+```
+
+```tsx
+<ThemeProvider brand="acme">…</ThemeProvider>
+```
+
+The full contract, for each of `l` (light) and `d` (dark):
+
+| Token                               | Default when omitted                                |
+| ----------------------------------- | --------------------------------------------------- |
+| `--m-brand-*-primary`               | Neutral (black in light, white in dark)             |
+| `--m-brand-*-primary-hover`         | `primary` mixed 85% with ink                        |
+| `--m-brand-*-primary-active`        | `primary` mixed 72% with ink                        |
+| `--m-brand-*-on-primary`            | Neutral (white in light, black in dark)             |
+| `--m-brand-*-accent` / `-on-accent` | `primary` / `on-primary`                            |
+| `--m-brand-*-focus`                 | `primary`                                           |
+| `--m-brand-*-link`                  | `primary` in light, ink in dark                     |
+| `--m-brand-*-selected`              | `primary` tinted into the page (8% light, 10% dark) |
+| `--m-brand-*-paper`                 | `#ffffff` in light, `#000000` in dark               |
+| `--m-brand-*-surface`               | `#ffffff` in light, `#0e0e10` in dark               |
+| `--m-brand-*-sunken`                | `#f5f5f7` in light, `#1c1c1e` in dark               |
+| `--m-brand-*-accent-gradient`       | None: accent fills are the flat `accent`            |
+
+And once for both appearances:
+
+| Token                    | Default when omitted                   |
+| ------------------------ | -------------------------------------- |
+| `--m-brand-font`         | `--m-font` (the system stack)          |
+| `--m-brand-font-heading` | `--m-font-heading`, else the body font |
+
+Hover and active mix towards **ink** (darker in light, lighter in dark), so text on them keeps at least the contrast it has on `primary`. Check `on-primary` against `primary` yourself (4.5:1 or more); Mortar's own brands are tested in `tests/tone-contrast.test.mjs`.
+
+A brand never inherits values from an outer brand: every `[data-mortar-brand]` starts from an empty contract.
+
+### Surfaces
+
+`paper` is the page, `surface` is cards, panels and raised controls, and `sunken` is wells, muted bands and hover fills. Inverse bands use the other appearance's surfaces: a brand with a navy dark page (`--m-brand-d-paper: #0b1f3a`) gets navy inverse bands on light pages too. Without a brand surface, an inverse band on a light page keeps `#000000` / `#1c1c1e` / `#1c1c1e`, and on a dark page `#f5f5f7` / `#ffffff` / `#ffffff`. `selected` is tinted into the brand's page.
+
+Text, line and status colours stay Mortar's, so a tinted surface is the brand's contrast responsibility. Muted text and danger are the lowest text, and strong lines (control borders, 3:1) the lowest overall: on a navy dark page, `#0b1f3a` (paper), `#0d2341` (surface) and `#0f2848` (sunken) keep every text and status colour at 4.5:1 and strong lines at 3:1, but a lighter sunken such as `#143156` drops strong lines to 2.7:1, and `#16365f` drops muted text to 4.2:1. The brand builder's contrast table checks text, muted text, links and strong lines on all three surfaces.
+
+### Accent gradients
+
+`accentGradient` (`--m-brand-*-accent-gradient`) is an optional fill for components that opt in: Button and ActionLink `variant="accent"`, and `tone="accent"` on CallToAction, Hero and Banner. Everything else, including the derived hover, active and selected colours, keeps reading the flat `accent`, which should be a colour close to the gradient.
+
+```css
+[data-mortar-brand="sunset"] {
+  --m-brand-l-accent: #c2410c;
+  --m-brand-l-on-accent: #ffffff;
+  --m-brand-l-accent-gradient: linear-gradient(90deg, #c2410c, #9a3412);
+}
+```
+
+- The value is a `linear-gradient()`, `radial-gradient()` or `conic-gradient()`, or a `repeating-` form, with at least two colour stops. Angles, positions, percentages and keywords such as `to right` are allowed; `url()` and other images are not.
+- The appearance exposes it as `--m-accent-fill`, an image. Without a gradient it is a flat gradient of `--m-accent`, so paint it as `background-image: var(--m-accent-fill)` over `background-color: var(--m-accent)`. It is not a colour and cannot be used where one is expected. Inverse bands use `--m-inv-accent-fill`, from the other appearance.
+- Text on it is `on-accent`, which must reach 4.5:1 against **every** stop. `tests/tone-contrast.test.mjs` checks a sample gradient brand, and the brand builder checks yours stop by stop.
+- In an accent band, copy and links use `on-accent`, primary actions invert (an `on-accent` button with accent text, the same pair) and secondary actions are outlined. Media and Hero previews keep the page's colours.
+
+### Fonts
+
+`fonts: { body, heading }` (`--m-brand-font`, `--m-brand-font-heading`) are font-family lists, the same in light and dark. They apply wherever the brand does, including a container-scoped ThemeProvider. Headings (`h1`–`h6` inside Mortar) and component titles use the heading font; without one they keep the body font. Mortar loads no font files: load them in your app (for example with `@font-face` or your framework's font loader) and name them here. An entry may be a bare `var(--name)`, as framework font loaders such as `next/font` hand out (`var(--font-inter), system-ui, sans-serif`); a `var()` with a fallback, `url()` and `local()` are rejected.
+
+### At runtime, from data
+
+For tenant-specific colours from a database or CMS, pass `brandTokens`:
+
+```tsx
+<ThemeProvider brand={tenant.slug} brandTokens={tenant.theme}>
+```
+
+```ts
+tenant.theme = {
+  light: { primary: "#1d4ed8", onPrimary: "#ffffff" },
+  dark: { primary: "#93c5fd", onPrimary: "#0b1f4d" },
+};
+```
+
+ThemeProvider renders the brand as a `<style>` element beside its content. It is included in server-rendered HTML, so there is no unstyled flash; it updates when the tokens change and is removed with the provider. Overlays opened inside the provider share it, because the rule matches the brand attribute they carry. Brand names may contain only letters, digits and hyphens. Every value is checked, and anything else throws an error that names the key (such as `dark.accent`), so tenant data cannot inject CSS and a value of the wrong kind cannot fail silently:
+
+- **Colours** are hex, a colour name (including `transparent` and `currentcolor`), or `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, `color()`, `color-mix()`, `light-dark()` or `var(--name)`. Arguments may nest those functions and `calc()`, `min()`, `max()` or `clamp()`. A gradient, `url()`, top-level `calc()`, `attr()` or `image-set()` is rejected.
+- **`accentGradient`** is a gradient whose stops follow the colour rules (see [Accent gradients](#accent-gradients)).
+- **Fonts** are family names, quoted names and generic families separated by commas, such as `"Inter", sans-serif`. Functions and `url()` are rejected.
+- `;`, `{`, `}`, `<`, `>`, comments and, outside font names, quotes are always rejected.
+
+`isBrandColour`, `isBrandGradient` and `isBrandFont` from `@tonycodes-ui/mortar/brand` run the same checks, for validating a form before you save a tenant's theme.
+
+Outside ThemeProvider, `@tonycodes-ui/mortar/brand` has the same building blocks:
+
+```ts
+import {
+  brandToCss,
+  brandToStyle,
+  registerBrand,
+} from "@tonycodes-ui/mortar/brand";
+
+brandToCss("acme", theme); // a CSS rule, e.g. for a build step
+const dispose = registerBrand("acme", theme); // adds a <style>; reference-counted
+brandToStyle(theme); // inline custom properties for one element
+```
+
+Inline custom properties apply only to that element's subtree. Menus and dialogs portal outside it, so prefer `brandTokens` or `registerBrand` for anything with overlays.
+
+### With the brand builder
+
+The playground's [brand builder](https://mortar.tony.codes/playground/?page=brand) (`/playground/?page=brand`) designs a brand against this contract. Start from a preset, set the light and dark primary pairs, and open Advanced for the optional tokens, surfaces and accent gradient; empty fields show the value they derive. Set heading and body fonts below. Light and dark previews, each with an inverse band, an accent band, an accent button, a heading sample and overlays, update as you type, and a table checks contrast: 4.5:1 for text on primary, hover, active and accent, for links, text and muted text on page, surface and sunken, and for on-accent text on the accent fill (every gradient stop) at rest, hover and active; 3:1 for strong lines on page, surface and sunken, and for the focus ring. Copy the result as the CSS rule (from `brandToCss`) or as the `brandTokens` object. The brand is kept in the URL, so a link shares it.
+
+## Appearance before JavaScript runs
+
+Until ThemeProvider sets `data-mortar-appearance` (during server rendering, or with JavaScript off), Mortar follows the operating system's colour scheme, so dark-mode users don't see a light flash. To always start light, render `data-mortar-appearance="light"` on `<html>`.
+
+## Scales
+
+Override these on `:root` or on any container to retheme shape and rhythm:
+
+- **Type:** `--m-font`, `--m-font-heading` (headings and component titles; unset by default, so they keep the body font), `--m-mono`, `--m-weight-regular|medium|semibold|bold`, `--m-tracking-display|heading|body|caps`, `--m-leading-display|heading|body`.
+- **Space:** `--m-space-1|2|3|4|6|8|10|12` (4px to 48px).
+- **Radius:** `--m-radius-xs|sm`, `--m-radius`, `--m-radius-lg|xl|full`.
+- **Sizing and density:** `--m-control`, `--m-pad`, `--m-font-size`, `--m-row-pad`, `--m-icon`. `data-mortar-density="compact" | "spacious"` adjusts these.
+- **Stacking:** `--m-z-sticky|overlay|popover|toast|skip`.
+
+What follows the scales, and what does not:
+
+- **Weight:** every component font weight reads `--m-weight-*`.
+- **Radius:** every component corner that is 2, 4, 8, 12, 16 or 999px reads the matching `--m-radius-*` token. Circles (`50%`) and a few in-between sizes (5, 6, 7, 10 and 44px, and `0.5rem` in CodeBlock and PreviewFrame) stay fixed.
+- **Tracking:** display titles and big numbers read `--m-tracking-display`, headings `--m-tracking-heading`, uppercase labels `--m-tracking-caps`, and text that resets to normal reads `--m-tracking-body`. Titles tuned to other values, such as the hero's `-0.045em` or section titles' `-0.035em`, stay fixed.
+- **Leading:** display titles read `--m-leading-display`, testimonial quotes `--m-leading-heading`, and long-form text `--m-leading-body`. Other line heights stay fixed, including compact table and calendar text at 1.3, which does not follow `--m-leading-heading`.
+- **Space:** component padding, gaps and margins do not read `--m-space-*` yet. Use the space scale in your own layouts.
+
+## Tailwind utilities
+
+`@tonycodes-ui/mortar/styles.css` maps tokens into Tailwind's theme, so utilities follow a retheme:
+
+- **Colours:** `paper`, `surface`, `sunken`, `ink`, `secondary`, `muted`, `line`, `primary`, `on-primary`, `accent`, `on-accent`, `focus`, `link`, `selected`, `success`, `warning`, `danger`, `info`. For example `bg-primary` or `text-muted`.
+- **Radius:** `rounded-m-xs`, `rounded-m-sm`, `rounded-m`, `rounded-m-lg`, `rounded-m-xl`, `rounded-m-full`. Tailwind's own `rounded-sm/md/lg` keep their usual sizes.
+- **Shadow:** `shadow-float`.
+- **Tracking:** `tracking-display`, `tracking-heading`, `tracking-caps`.
+- **Fonts:** `font-sans` (a brand's body font, else `--m-font`), `font-heading` (the brand's heading font, else `--m-font-heading`, else the body font) and `font-mono`.
+- **Weights:** `font-medium`, `font-semibold` and `font-bold` follow `--m-weight-*`.