@tanishqkancharla/maui 0.0.21 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tanishqkancharla/maui",
-	"version": "0.0.21",
+	"version": "0.0.22",
 	"description": "Maui design system",
 	"type": "module",
 	"main": "./dist/maui.js",

package/skills/maui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maui
-description: Conventions and design constraints for consuming the Maui design system. Use when building UI with Maui tokens, components, or purse-styles in an app that depends on Maui. Before designing or implementing new UI, read the closest example under src/apps/ or src/patterns/.
+description: Conventions and design constraints for consuming the Maui design system. Use when building UI with Maui tokens, components, patterns, or purse-styles. Prefer this skill and its references for composition knowledge.
 ---
 
 # Maui
@@ -34,14 +34,32 @@ The published package exposes:
 - `"maui/src"` — TypeScript source barrel
 - `"maui/src/*"` — TypeScript source for deep imports
 - `"maui/skills/maui"` — this skill file
+- `"maui/skills/maui/*"` — reference files next to this skill
 
 `MauiProvider` sets up theme (`data-theme` / `color-scheme`), `PurseProvider`, design-system globals, and the focus UI database used by Button/Dialog.
 
+## How to learn Maui
+
+Prefer this skill for composition knowledge — how to assemble tokens, components, patterns, and apps. Reach for package source (`"maui/src/patterns"`, `"maui/src/apps"`, or an install under `node_modules`) when you need a detail the skill does not cover.
+
+Before designing or implementing new UI:
+
+1. Read the constraints in this file.
+2. Open the matching reference (same grouping as the [gallery nav](https://maui.tanishqkancharla.dev)) and reuse its structure, tokens, and interactions.
+
+| Need | Read |
+| --- | --- |
+| Tokens, `purse-styles`, motion, layout, theme | [references/tokens.md](references/tokens.md) |
+| A component | [Components](#components) |
+| A pattern | [Patterns](#patterns) |
+| An app | [Apps](#apps) |
+
+Patterns, demo apps, and the gallery `Panel` preview surface are **not** part of the `"maui"` package barrel. Prefer the recipes in those references and rebuild with barrel exports (`Button`, `Flex`, `text(...)`, …).
+
 ## Design constraints
 
-- Before designing or implementing new UI with Maui components, read the closest example under `src/apps/` or `src/patterns/`. Reuse its structure, components, tokens, and interactions.
 - Hover backgrounds have no transitions. Hover fills (`backgroundColor.elementHover`, quiet-button washes, list/row highlights) snap instantly. Do not animate `background` / `background-color` on hover with `motion.standard(...)` or a CSS `transition`. Other motion (tooltips, transforms) is fine.
-- Simple apps default to a `proseMaxWidth` column (`72ch`) centered in their container: `width: "100%"`, `maxWidth: proseMaxWidth`, `marginInline: "auto"`. `sizingTokens.contentWidth` is the same measure. Use this for single-column tools, settings, forms, and reading layouts. Multi-pane or full-bleed apps (inbox, calendar, IDE) are the exception.
+- Simple apps default to a `proseMaxWidth` column (`72ch`) centered in their container: `width: "100%"`, `maxWidth: proseMaxWidth`, `marginInline: "auto"`. `sizing.contentWidth` is the same measure. Use this for single-column tools, settings, forms, and reading layouts. Multi-pane or full-bleed apps (inbox, calendar, IDE) are the exception.
 - Always design empty states. Every list, inbox, search result, or collection needs an intentional empty composition (copy and an optional action), never a blank panel.
 
 ## Theme FOUC
@@ -84,65 +102,54 @@ import { Text as TextIcon } from "maui/icons"
 <TextIcon size="md" />
 ```
 
-`size` uses the same t-shirt scale as `text(...)` (`2xs`–`xl`, default `sm`). Stroke and fill use `currentColor`. Icons that share a root export name (`Text`, `Badge`, `Switch`, …) are `TextIcon` / `BadgeIcon` / `SwitchIcon` from `"maui"`, or the original name from `"maui/icons"` / `Icons.Text`.
+`size` uses the same t-shirt scale as `text(...)` (`2xs`–`xl`, default `sm`). Stroke and fill use `currentColor`. Icons that share a root export name (`Text`, `Badge`, `Switch`, `H1`, `H2`, `H3`, `Link`, `Menu`, `Code`, `Blockquote`, `Padding`, `SearchField`) are `TextIcon` / `BadgeIcon` / … from `"maui"`, or the original name from `"maui/icons"` / `Icons.Text`.
 
 ## Components
 
-### Typography and reading
-
-- `Text` — size / weight / color / `monospace` span
-- `H1`–`H4`, `P`, `Label`, `Blockquote`, `Ul`, `Ol`, `Li`, `Link`
-- `Prose` — long-form rhythm; headings switch to the prose scale inside it
-- `Editor` — TipTap markdown surface (CommonMark shortcuts, `proseHtml` type) with no chrome; wrap it for padding, elevation, and actions
-
-### Form controls
-
-- `Button` — `variant` is `"default"` | `"quiet"` | `"primary"`; `variantColor` is a palette name, or an opaque hex / `rgb()` string (`#${string}` or `rgb(`). Primary palettes fill step 9 (hover 10) with light text (`onAccent`, or step 12 on amber/lime/mint/sky/yellow). A CSS color is used as the fill (alpha is dropped; hover is `l - 0.04`; text is white or near-black from lightness). The edge is `tintedSubtle`. Quiet + color uses a 3.5% wash of the fill (hover 7%). Disable with React Aria’s `isDisabled` (maps to the native `disabled` attribute; no parallel `disabled` React prop).
-- `TextField`, `SearchField`, `NumberField`, `QuietTextField`
-- `Checkbox`, `Switch`, `Slider`
-- `RadioOptionGroup` / `RadioOption`
-- `Select` / `SelectItem`
-
-### Collections and overlays
-
-- `ListBox` / `ListBoxItem`
-- `MenuTrigger` / `Menu` / `MenuItem`
-- `Tooltip`
-- `CollectionPopover` — shared popover used by Select and Menu
-- `Overlay`, `Dialog`
-
-### Display
-
-- `Avatar`
-- `Badge`
-- `Code`, `Kbd`, `CodeBlock`
-- `Table` — React Aria table. `TableHeader` contains `TableHead` columns directly (no `TableRow`). Mark the identifying column with `isRowHeader` (required; usually the name/id column, not a leading checkbox or drag handle). When `selectionMode` is `"multiple"`, `TableHeader` and `TableRow` insert a leading checkbox column (`Checkbox slot="selection"`). `align` on `TableHead` / `TableCell` is `"start"` | `"center"` | `"end"`. `TableFooter` fills with `colors.gray[2]`. Place `TableCaption` after `Table`. `TableBody` renders “No results.” when empty; pass `renderEmptyState` to replace it.
-- `FuzzyString` — highlight segments; takes a match result, not a plain string
-- `Thinking` — 3×3 Game of Life indicator; reseeds when the board dies or loops
-- `Crossfade` — when `contentKey` changes, the previous view exits in `direction` (`up` | `down` | `left` | `right`) and the next view enters from the opposite side. `contentKey` is required. Do not put `key` on `Crossfade` itself or the exit is skipped.
-- `LoadingScreen` — fills available width and height. Optional `progressLabel`. Label at start fades Thinking (accent, small / `0.8em`) and the label (accent, weight 500, trailing `...`) in together; later label changes Crossfade up. With no label at start, Thinking waits 2s before fading in; a label before 2s fades both in immediately; a label after 2s animates in and shifts Thinking so the pair stays centered.
-
-## Reference: patterns and apps
-
-Patterns, demo apps, and the gallery `Panel` preview surface are not part of the `"maui"` package barrel. Read the closest example before designing or implementing new UI, and reuse its structure, components, tokens, and interactions (also available via `"maui/src/..."`):
-
-### Patterns — `src/patterns/`
-
-| Path | Role |
-| --- | --- |
-| `src/patterns/AssistantMessage.tsx` | Streaming markdown reply (Streamdown + Maui prose) |
-| `src/patterns/Sidebar.tsx` | App sidebar chrome |
-| `src/patterns/Inbox.tsx` | Mail inbox layout |
-| `src/patterns/MessageList.tsx` | Message list rows |
-
-### Apps — `src/apps/`
+Gallery order. Props and composition live in the linked file.
 
-| Path | Role |
+| Page | Reference |
 | --- | --- |
-| `src/apps/AiChat/` | Mock streaming AI chat (Editor + AssistantMessage) |
-| `src/apps/EmailClient/` | Email client demo composing inbox patterns |
-| `src/apps/Calendar/` | Three-pane schedule (mini month, week grid, event details) |
-| `src/apps/JsxEditor/` | Live JSX playground (CodeMirror + Maui catalog) |
+| Avatar | [avatar.md](references/components/avatar.md) |
+| Badge | [badge.md](references/components/badge.md) |
+| Buttons | [buttons.md](references/components/buttons.md) (`Button`, `Overlay`, `Dialog`) |
+| Prose | [prose.md](references/components/prose.md) (`Prose`, `H1`–`H4`, `P`, lists, `Label`, `Link`) |
+| Editor | [editor.md](references/components/editor.md) |
+| Thinking | [thinking.md](references/components/thinking.md) |
+| Crossfade | [crossfade.md](references/components/crossfade.md) |
+| Loading screen | [loading-screen.md](references/components/loading-screen.md) |
+| Text | [text.md](references/components/text.md) |
+| Form controls | [form-controls.md](references/components/form-controls.md) |
+| Select | [select.md](references/components/select.md) |
+| List box | [list-box.md](references/components/list-box.md) |
+| Table | [table.md](references/components/table.md) |
+| Menu | [menu.md](references/components/menu.md) |
+| Tooltip | [tooltip.md](references/components/tooltip.md) |
+| Layout utilities | [layout-utilities.md](references/components/layout-utilities.md) |
+| FuzzyString | [fuzzy-string.md](references/components/fuzzy-string.md) |
+| Icons | [icons.md](references/components/icons.md) |
+| Code | [code.md](references/components/code.md) |
+
+## Patterns
+
+Not on the `"maui"` barrel. Prefer the recipes; rebuild with barrel exports in consuming apps. Hover fills snap; empty collections get copy.
+
+| Page | Role | Reference |
+| --- | --- | --- |
+| Inbox | Mail thread list with unread dot, hover actions, selection | [inbox.md](references/patterns/inbox.md) |
+| Message list | Thread of raised message cards (avatar + Prose body) | [message-list.md](references/patterns/message-list.md) |
+| Assistant message | Streaming markdown reply (Streamdown + Maui prose + CodeBlock) | [assistant-message.md](references/patterns/assistant-message.md) |
+| Sidebar | 240px nav: sections, active item, optional icon and trailing badge | [sidebar.md](references/patterns/sidebar.md) |
+
+## Apps
+
+Not on the `"maui"` barrel. Prefer these layouts; rebuild with barrel exports.
+
+| Page | Role | Reference |
+| --- | --- | --- |
+| Email client | Two-pane inbox + reading pane | [email-client.md](references/apps/email-client.md) |
+| AI chat | Mock streaming chat (Editor + AssistantMessage + Thinking) | [ai-chat.md](references/apps/ai-chat.md) |
+| Calendar | Three-pane schedule (mini month, week grid, event details) | [calendar.md](references/apps/calendar.md) |
 
 ## License
 

package/skills/maui/references/apps/ai-chat.md

@@ -0,0 +1,32 @@
+# AI chat
+
+Gallery: `/apps/ai-chat`. Not on the `"maui"` barrel. Prefer this layout; rebuild with barrel components. Package source: `"maui/src/apps/AiChat/"` if you need a detail this file does not cover.
+
+Uses [Editor](../components/editor.md), [Assistant message](../patterns/assistant-message.md), [Thinking](../components/thinking.md).
+
+Column shell: outline border, `radius.lg`, `minHeight` ~560px / `maxHeight` ~720px, `overflow: hidden`.
+
+```
+[ scrollable feed: user bubbles + assistant rows ]
+[ composer: Editor in a raised shell + send ]
+```
+
+**Feed** (`role="log"` `aria-label="Conversation"` `aria-relevant="additions"`)
+
+- Padding `x: 8, y: 6`, column `gap` 6, `flex: 1`, `overflowY: auto`. Scroll to bottom when messages change.
+- **User**: `justify: end`, bubble `maxWidth: 80%`, `prose("sm")` paragraph, `radius.md`, `shadow.subtle`, `background.element`, `pre-wrap`.
+- **Assistant**: full-width column.
+  1. Optional tool-call lines (lowContrast, ellipsis): `Read path`, `Wrote path`, `$ command` (command in `monospace`).
+  2. AssistantMessage `size="sm"` `isAnimating={streaming}` — override `maxWidth: none` so it fills the pane.
+  3. While streaming, a muted `Thinking` + “Thinking” (`xs` / lowContrast, row `gap` 4).
+
+**Composer**
+
+- Outer padding `x: 6, top: 4, bottom: 6`.
+- Inner shell: `radius.lg`, `shadow.subtle`, `background.element`, padding `x: 4, y: 3`, column.
+- `<Editor size="sm" onSubmit={send} editable={!streaming} placeholder="Message the assistant…" />`
+- Send: circular quiet-ish `Button` (`radius.circle`, no box-shadow, `gray[3]` fill so it reads on `element`), icon `ArrowUp`, `aria-label="Send"`, disabled while streaming or empty. ⌘/Ctrl+Enter also sends (`Editor onSubmit`).
+
+Mock streaming (no model required for a demo): wait ~3s (Thinking), optionally emit tool-call rows, then append markdown in small chunks. Keep `animated` on Streamdown the whole time; only `isAnimating` flips off when the last chunk lands.
+
+Empty conversation: still show a welcome **assistant** markdown message, not a blank feed.

package/skills/maui/references/apps/calendar.md

@@ -0,0 +1,46 @@
+# Calendar
+
+Gallery: `/apps/calendar`. Not on the `"maui"` barrel. Prefer this layout; rebuild with barrel components. Package source: `"maui/src/apps/Calendar/"` if you need a detail this file does not cover.
+
+**Three panes** (sidebar can collapse):
+
+```
+[ 196px sidebar ] [ flexible week grid ] [ ~200–220px details ]
+```
+
+Shell: `radius.lg`, `shadow.subtle`, `minHeight` ~640px, `backgroundColor.app`, `overflow: hidden`. Without sidebar: `minmax(0, 1fr) minmax(200px, 220px)`.
+
+This is a **full-bleed schedule**, not a prose column.
+
+## Sidebar
+
+Raised `background.element` + `shadow.subtle`, column `gap` 6, padding 4.
+
+- Toolbar: quiet icon buttons — hide sidebar (`Sidebar` icon), new event (`Plus`). Wrap in `Tooltip`.
+- **Mini month**: 7-column weekday initials (`2xs`), 24px circular day buttons. Today = `accent[9]` + `onAccent` text. Selected (not today) = `grayAlpha[4]`. Outside-month = `gray[8]`. Hover = `elementHover` (no background transition on the chrome; day buttons may use `motion.standard` on color only). Prev/next month chevrons.
+- `TextField` placeholder “Meet with...”.
+- Account groups: xs/500/lowContrast email, then source rows (10px color swatch + name + hover-revealed quiet `Eye` to hide the calendar). Hidden sources drop to 45% opacity.
+- Footer: quiet “Add calendar account” / “Add Notion database”.
+
+Event colors: `accent` | `green` | `orange` | `pink` — fill step 3, text 11, selected fill 9 + `onAccent`.
+
+## Week grid
+
+- Header: month title (`xl`/700) + `Avatar` + `Select` for 1/3/5/7-day view + `Today` + prev/next quiet chevrons (`Tooltip`).
+- Sticky **all-day** row, then a vertically scrolling 24h grid (`HOUR_HEIGHT` 52px).
+- Timed events: absolutely positioned blocks (`radius.sm`, padding 3/1, title + time range `2xs` lowContrast). Click a block to select; click empty grid to **create** a 30-minute event (snap 15 minutes).
+- Today column: `accentAlpha[2]` wash. Now line: 2px `accent[9]` + circle on the today column.
+- Time gutter ~36px, `2xs` mono labels.
+
+## Details pane
+
+Raised column, padding 8.
+
+- `SearchField` “Search events”. Matches render as a list of title (`FuzzyString`) + meta; click jumps to that event and date.
+- Selected event: title `lg`/600, time range or “All day”, duration, calendar swatch + name, `Button` “Add meeting note”.
+- None selected: “Select an event to see details, or click the grid to create one.”
+- Footer: “Useful shortcuts” with `Kbd` (`T` today, `←`/`→` range, `` ` `` sidebar). Ignore shortcuts when focus is in an input.
+
+Hotkeys (no modifiers): `t` today, arrows shift the visible range by `viewDays`, backtick toggles sidebar.
+
+Empty search: show nothing extra (the selected-event block and shortcuts remain). Empty calendar: still show the grid + the details empty copy.

package/skills/maui/references/apps/email-client.md

@@ -0,0 +1,27 @@
+# Email client
+
+Gallery: `/apps/email-client`. Not on the `"maui"` barrel. Prefer this layout; rebuild with barrel components. Package source: `"maui/src/apps/EmailClient/"` if you need a detail this file does not cover.
+
+Patterns: [Inbox](../patterns/inbox.md), [Message list](../patterns/message-list.md).
+
+**Two panes**, full-bleed (not a 72ch column).
+
+```
+[ 240px inbox ] [ flexible reading pane ]
+```
+
+Shell: `radius.lg`, `shadow.subtle`, `minHeight` ~640px, `overflow: hidden`, `backgroundColor.app`, grid `240px minmax(0, 1fr)`.
+
+**Inbox pane**
+
+- Column, padding step 2, `minHeight: 0`, list `overflowY: auto`.
+- Header: `H3` “Inbox” (or mailbox name), padded to match multi-line row text (`pt` 6, `px` 4).
+- Body: InboxMultiLine with `threads`, `selectedId`, `onSelectThread`. Reset the pattern’s default `marginTop` so it sits flush under the header.
+
+**Reading pane**
+
+- Padding `x: 16, y: 8`, column `gap` 6, `overflowY: auto`.
+- Selected: `H2` subject, then MessageList of that thread’s messages (`sender`, `timestamp`, optional `edited`, `P` children).
+- None selected: lowContrast “Select a thread to read messages.”
+
+State: one `selectedThreadId`. Threads carry `id / senders / subject / snippet / time / unread?` plus a `messages[]` array. Unread dots and hover toolbars come from the inbox pattern.

package/skills/maui/references/components/avatar.md

@@ -0,0 +1,9 @@
+# Avatar
+
+Gallery: `/components/avatar`. Import from `"maui"`. Tokens: [tokens.md](../tokens.md).
+
+Initials from `name` (first letters of up to two words). `size` matches `TextSize` (default `sm` = 18px). Color is hashed from the name (accent / green / orange / pink). `aria-hidden`.
+
+```tsx
+<Avatar name="Maya Chen" size="lg" />
+```

package/skills/maui/references/components/badge.md

@@ -0,0 +1,9 @@
+# Badge
+
+Gallery: `/components/badge`. Import from `"maui"`.
+
+Compact pill count/status (`grayAlpha[3]`, 18px tall, tabular nums). Children are the label.
+
+```tsx
+<Badge>12</Badge>
+```

package/skills/maui/references/components/buttons.md

@@ -0,0 +1,57 @@
+# Buttons
+
+Gallery: `/components/buttons`. Import from `"maui"`. Overlay and Dialog live on this page too.
+
+## `Button`
+
+Native `<button>` (default `type="button"`). Height 28px, `shadow.subtle`, `radius` 4px.
+
+```tsx
+<Button>Save</Button>
+<Button variant="quiet">Cancel</Button>
+<Button variant="primary" variantColor="blue">Create</Button>
+<Button variant="primary" variantColor="#6366f1">Indigo</Button>
+<Button isDisabled>Wait</Button>
+<Button aria-label="Search"><Search size="sm" /></Button>
+<Button>
+  <Plus size="sm" />
+  Create
+</Button>
+```
+
+| Prop | Notes |
+| --- | --- |
+| `variant` | `"default"` (raised element) \| `"quiet"` (no shadow, transparent) \| `"primary"` (solid fill) |
+| `variantColor` | Palette name or opaque `#hex` / `rgb(...)`. Primary default is `"accent"`. Quiet ignores color unless set |
+| `isDisabled` | React Aria name. Maps to native `disabled`. **No `disabled` React prop** |
+| `children` | Text is wrapped for cap-height trim; SVG icons sit beside text. Icon-only needs `aria-label` |
+
+Primary: fill step 9, hover 10, light text (`onAccent`, or step 12 on amber/lime/mint/sky/yellow). Custom CSS fill drops alpha; hover is `l - 0.04`; text is white or near-black from lightness. Edge is `tintedSubtle`. Quiet + color: 3.5% wash (hover 7%).
+
+`useButton(props)` is exported for custom focus-tracked buttons; prefer `Button`.
+
+## `Overlay`
+
+Full-viewport portal. `onClickOutside` fires when the backdrop itself is the mousedown target.
+
+```tsx
+{open && (
+  <Overlay onClickOutside={() => setOpen(false)}>
+    {/* centered panel */}
+  </Overlay>
+)}
+```
+
+## `Dialog`
+
+`Overlay` + focus lock + scale/fade in. Children are the dialog body (padding 32px, `background.element`, 4px radius). Not React Aria Dialog — you own title and close.
+
+```tsx
+{open && (
+  <Dialog onClickOutside={() => setOpen(false)}>
+    <H3>Confirm</H3>
+    <P>This cannot be undone.</P>
+    <Button onClick={() => setOpen(false)}>Close</Button>
+  </Dialog>
+)}
+```

package/skills/maui/references/components/code.md

@@ -0,0 +1,11 @@
+# Code
+
+Gallery: `/components/code`. Import from `"maui"`.
+
+```tsx
+<Code>proseMaxWidth</Code>
+<Kbd>⌘</Kbd><Kbd>K</Kbd>
+<CodeBlock lang="ts">{`const n = 1`}</CodeBlock>
+```
+
+`CodeBlock` highlights with Shiki using the resolved theme. `lang` is required. Unsupported langs / pending highlight render a plain `<pre>`.

package/skills/maui/references/components/crossfade.md

@@ -0,0 +1,16 @@
+# Crossfade
+
+Gallery: `/components/crossfade`. Import from `"maui"`.
+
+When `contentKey` changes, the previous view exits in `direction` while the next view enters from the opposite side. Views overlap (`AnimatePresence` `mode="sync"`). Offset is spacing step 6. The root clips overflow.
+
+```tsx
+<Crossfade direction="left" contentKey={slide.id}>
+  <Text size="lg">{slide.title}</Text>
+</Crossfade>
+```
+
+- `direction` is required: `"up" | "down" | "left" | "right"`. Gallery playground starts on `"left"`.
+- `contentKey` is required. **Do not** put `key` on `Crossfade` itself or the exit is skipped.
+- Timing is internal: enter is a spring (`visualDuration` 0.3, `bounce` 0.2); exit uses `motionDurationMs` (80ms) and ease-in-out. There are no public motion props.
+- Reduced motion: opacity only.

package/skills/maui/references/components/editor.md

@@ -0,0 +1,22 @@
+# Editor
+
+Gallery: `/components/editor`. Import from `"maui"`. Composer chrome: [AI chat](../apps/ai-chat.md).
+
+Unchromed TipTap markdown surface. Wrap it for padding, elevation, and actions.
+
+```tsx
+<Editor
+  content={draft}
+  onChange={setDraft}
+  onSubmit={send}          // ⌘/Ctrl+Enter
+  placeholder="Write…"
+  size="sm"                // ProseSize: sm | md | lg
+  editable={!streaming}
+  aria-label="Compose message"
+/>
+```
+
+- `content` is markdown; updates apply when the string changes.
+- `onChange` receives markdown.
+- CommonMark shortcuts (`#`, `**`, `-`, `>`).
+- No chrome, no submit button — parent owns those.

package/skills/maui/references/components/form-controls.md

@@ -0,0 +1,49 @@
+# Form controls
+
+Gallery: `/components/form-controls`. Import from `"maui"`. [Select](select.md) has its own page.
+
+All fields are 28px tall, full width of the parent, `shadow.subtle` except `QuietTextField`. They take React Aria field props (`value`, `onChange`, `placeholder`, `isDisabled`, `isInvalid`, `aria-label`, `id`, …).
+
+```tsx
+<TextField aria-label="Title" placeholder="Title" value={v} onChange={setV} />
+<SearchField aria-label="Search" value={q} onChange={setQ} />   // clear button when non-empty
+<NumberField aria-label="Count" value={n} onChange={setN} minValue={0} maxValue={10} />
+<QuietTextField aria-label="Filter" placeholder="Filter" value={f} onChange={setF} />
+```
+
+Invalid (unfocused) adds a red 1px ring on top of `shadow.subtle`. Placeholders are italic `gray[8]`. Cap width in the parent (`maxWidth: 240px` is the gallery default).
+
+## `Checkbox`
+
+Controlled only: `checked` + `setChecked`. Optional `label`.
+
+```tsx
+<Checkbox label="Subscribe" checked={on} setChecked={setOn} />
+```
+
+## `Switch`
+
+Controlled: `selected` + `onChange`. **`label` is required.**
+
+```tsx
+<Switch label="Enable notifications" selected={on} onChange={setOn} />
+```
+
+## `Slider`
+
+`label` required. React Aria slider props: `value`, `onChange`, `minValue`, `maxValue`, `step`. Default width 240px. Shows the formatted value as `<output>`.
+
+```tsx
+<Slider label="Volume" value={v} onChange={setV} minValue={0} maxValue={100} />
+```
+
+## `RadioOptionGroup` / `RadioOption`
+
+```tsx
+<RadioOptionGroup label="Plan" value={plan} onChange={setPlan}>
+  <RadioOption value="free">Free</RadioOption>
+  <RadioOption value="pro">Pro</RadioOption>
+</RadioOptionGroup>
+```
+
+`RadioOption` must be nested. Group also accepts React Aria radio-group props (`isDisabled`, …).

package/skills/maui/references/components/fuzzy-string.md

@@ -0,0 +1,13 @@
+# FuzzyString
+
+Gallery: `/components/fuzzy-string`. Import from `"maui"`. Search UI example: [Calendar](../apps/calendar.md).
+
+Renders highlight segments. **Not a plain string.**
+
+```tsx
+type FuzzyMatch = Array<{ match: string } | { skip: string }>
+
+<FuzzyString match={[{ skip: "Em" }, { match: "ail" }, { skip: " client" }]} />
+```
+
+Matched spans use `accent[11]`. The matcher is **not** on the package barrel — build `{ match | skip }[]` in the app (first matching subsequence is enough). Drop items that do not match; sort by a score if you have one.

package/skills/maui/references/components/icons.md

@@ -0,0 +1,16 @@
+# Icons
+
+Gallery: `/components/icons`. Import named icons from `"maui"` or `"maui/icons"`.
+
+```ts
+import { Search, Plus, ChevronLeft } from "maui"
+import { Text as TextIcon, Badge as BadgeIcon } from "maui/icons"
+```
+
+Root-export collisions (use the `*Icon` alias from `"maui"`, or the original name from `"maui/icons"`):
+
+`BadgeIcon`, `BlockquoteIcon`, `CodeIcon`, `H1Icon`, `H2Icon`, `H3Icon`, `LinkIcon`, `MenuIcon`, `PaddingIcon`, `SearchFieldIcon`, `SwitchIcon`, `TextIcon`.
+
+Avoid `import { Icons } from "maui"` in app code — it pulls the full set. The JSX editor catalog uses `Icons.*` because every icon is in scope.
+
+`IconProps`: SVG props + `size?: TextSize` (default `sm`). Size matches the text t-shirt scale (`2xs`–`xl`). Stroke and fill use `currentColor`.

package/skills/maui/references/components/layout-utilities.md

@@ -0,0 +1,50 @@
+# Layout utilities
+
+Gallery: `/components/layout-utilities`. Import from `"maui"`. Layout tokens: [tokens.md](../tokens.md).
+
+Gallery-only: `Panel` is a preview frame in the docs site. It is **not** exported. Use `Flex` + `shadow` + `radius` instead.
+
+## `Flex`
+
+Row **or** column (exactly one of `row` / `column` is required).
+
+```tsx
+<Flex row gap={4} alignItems="center">
+  <Avatar name="Ada Lovelace" size="md" />
+  <Text size="lg" fontWeight={600}>Ada Lovelace</Text>
+  <Spacer />
+  <Badge>Active</Badge>
+</Flex>
+```
+
+| Prop | Notes |
+| --- | --- |
+| `row` / `column` | Required, mutually exclusive |
+| `gap` | Spacing step |
+| `p` / `padding` | All-side padding step |
+| `px` `py` `pt` `pb` | Axis / side padding |
+| `alignItems` | CSS `align-items` |
+| `border` | `true` (outline) or `"border" \| "outline" \| "accent"`. **Skipped when `shadow` is set** |
+| `shadow` | `"subtle" \| "medium" \| "strong"` — includes a ring; do not also set `border` |
+| `radius` | Token key (`sm`, `lg`, `pill`, …) |
+| `style` | React style object |
+
+## `Padding`
+
+`xy` (all), `x` / `y`, or `top` `right` `bottom` `left`. Spacing steps.
+
+## `Gap`
+
+Fixed spacer: `{ width: Space }` **or** `{ height: Space }`. Does not grow.
+
+## `Spacer`
+
+`flex: 1 1 auto` — fills leftover space in a `Flex`.
+
+## `Divider`
+
+Full-width `<hr>` (`gray[5]`, 1.5px). Has vertical margin (~1.5rem). For tight lists, prefer `gap: 1px` between rows instead.
+
+## `navigationItem`
+
+Style object (not a component) for current-page nav rows: sm text, `radius.sm`, hover `elementHover`, `[aria-current="page"]` accent + weight 500. Used by the [Sidebar](../patterns/sidebar.md) recipe.

package/skills/maui/references/components/list-box.md

@@ -0,0 +1,22 @@
+# List box
+
+Gallery: `/components/list-box`. Import from `"maui"`.
+
+Persistent selectable list (not a popup). Wrap in a raised, padded panel.
+
+```tsx
+<ListBox
+  aria-label="Inboxes"
+  selectionMode="single"
+  selectedKeys={keys}
+  onSelectionChange={setKeys}
+  disallowEmptySelection
+>
+  <ListBoxItem id="inbox">Inbox</ListBoxItem>
+  <ListBoxItem id="sent">Sent</ListBoxItem>
+</ListBox>
+```
+
+Hover/focus uses `elementHover` with **no** background transition. Selected: accent text + trailing ✓.
+
+`textValue` is inferred from string children; pass it when children are not a string.

package/skills/maui/references/components/loading-screen.md

@@ -0,0 +1,17 @@
+# Loading screen
+
+Gallery: `/components/loading-screen`. Import from `"maui"`. Uses [Thinking](thinking.md) and [Crossfade](crossfade.md).
+
+Fills available width and height (`flex: 1`, `width/height: 100%`). Centered `Thinking` (accent, `0.8em`).
+
+```tsx
+<LoadingScreen />
+<LoadingScreen progressLabel="Indexing files" />
+```
+
+| First paint | Later `progressLabel` |
+| --- | --- |
+| Label present | Thinking + label fade in together. Later labels Crossfade `up`. Missing `...` / `…` is appended |
+| No label | Thinking waits **2s**, then fades in. A label before 2s fades both in immediately. A label after 2s animates in and shifts Thinking so the pair stays centered |
+
+`role="status"` `aria-busy` `aria-live="polite"`.

package/skills/maui/references/components/menu.md

@@ -0,0 +1,17 @@
+# Menu
+
+Gallery: `/components/menu`. Import from `"maui"`. Related: [select.md](select.md).
+
+Exactly two children on `MenuTrigger`: **trigger**, then **menu**. The trigger should be focusable.
+
+```tsx
+<MenuTrigger placement="bottom start">
+  <Button>Actions</Button>
+  <Menu onAction={(key) => doAction(String(key))}>
+    <MenuItem id="rename">Rename</MenuItem>
+    <MenuItem id="delete">Delete</MenuItem>
+  </Menu>
+</MenuTrigger>
+```
+
+`placement` defaults to `"bottom start"`. Popover uses `shadow.strong` via `CollectionPopover`.

package/skills/maui/references/components/prose.md

@@ -0,0 +1,39 @@
+# Prose
+
+Gallery: `/components/prose`. Import from `"maui"`. Type tokens: [tokens.md](../tokens.md).
+
+Typography components have **no margin and no max-width**. Spacing belongs to the parent (`Flex` gap or `Prose`).
+
+## `Prose`
+
+Long-form column: `maxWidth: 72ch` (`proseMaxWidth`) plus vertical rhythm. `size?: "sm" | "md" | "lg"` (default `md`) is inherited via `useProseSize()`.
+
+```tsx
+<Prose size="md">
+  <H2>Shipping notes</H2>
+  <P>Body copy with <Link href="/docs">a link</Link>.</P>
+  <Ul>
+    <Li>First</Li>
+    <Li>Second</Li>
+  </Ul>
+</Prose>
+```
+
+Do not wrap app chrome (sidebars, toolbars, forms) in `Prose`.
+
+## `H1` `H2` `H3` `H4` `Blockquote` `Link`
+
+**Children must be a `string`.** `Link` also needs `href`.
+
+Outside `Prose` they use the app `text` scale (`H1` xl/700, `H2` lg/600, `H3`/`H4` md/600). Inside `Prose` they switch to the prose scale.
+
+## `P` `Ul` `Ol` `Li` `Label`
+
+`P` / lists / `Li` take `ReactNode`. `Label` forwards `<label>` attributes (`htmlFor`, …) and uses xs/500/lowContrast, non-selectable (`labelText`).
+
+```tsx
+<Flex column gap={3}>
+  <Label htmlFor="name">Name</Label>
+  <TextField id="name" aria-label="Name" />
+</Flex>
+```

package/skills/maui/references/components/select.md

@@ -0,0 +1,23 @@
+# Select
+
+Gallery: `/components/select`. Import from `"maui"`. Related: [list-box.md](list-box.md), [menu.md](menu.md).
+
+Trigger + `CollectionPopover` + `ListBox`. Width 100% of parent.
+
+```tsx
+<Select
+  label="Favorite fruit"
+  placeholder="Choose a fruit"
+  selectedKey={key}
+  onSelectionChange={(k) => setKey(String(k))}
+>
+  <SelectItem id="apple">Apple</SelectItem>
+  <SelectItem id="banana">Banana</SelectItem>
+</Select>
+```
+
+React Aria also accepts `value` / `onChange` on some versions; `selectedKey` / `onSelectionChange` is the usual collection API. Optional `description`, `errorMessage`, `items` + child render function.
+
+Selected items show an accent checkmark on the right (`ListBoxItem`).
+
+`CollectionPopover` is the shared RAC `Popover` for Select and Menu. Default `placement="bottom start"`, `offset={6}`, min-width = trigger width, max-height 280px, `shadow.strong`. Use it for a custom collection overlay.

package/skills/maui/references/components/table.md

@@ -0,0 +1,41 @@
+# Table
+
+Gallery: `/components/table`. Import from `"maui"`.
+
+React Aria table. Columns live **directly** in `TableHeader` (no header `TableRow`).
+
+```tsx
+<Table aria-label="Invoices">
+  <TableHeader>
+    <TableHead isRowHeader>Invoice</TableHead>
+    <TableHead>Status</TableHead>
+    <TableHead align="end">Amount</TableHead>
+  </TableHeader>
+  <TableBody>
+    {rows.map((row) => (
+      <TableRow key={row.id} id={row.id}>
+        <TableCell>{row.id}</TableCell>
+        <TableCell>{row.status}</TableCell>
+        <TableCell align="end">{row.amount}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+  <TableFooter>
+    <TableRow id="total">
+      <TableCell colSpan={2}>Total</TableCell>
+      <TableCell align="end">$2,500.00</TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+<TableCaption>Recent invoices.</TableCaption>
+```
+
+Rules:
+
+- Mark the identifying column with `isRowHeader` (name/id, not a checkbox).
+- `align` on `TableHead` / `TableCell`: `"start"` | `"center"` | `"end"`.
+- Selection is **opt-in**. Without `selectionMode`, rows do not highlight on hover.
+- `selectionMode="multiple"` inserts a leading checkbox column (select-all in the header). Hover/selected washes follow `data-selection-mode`.
+- `TableBody` default empty state is “No results.” Pass `renderEmptyState`.
+- Put `TableCaption` **after** `Table` (often inside a `<figure>`).
+- `TableFooter` uses `gray[2]`.

package/skills/maui/references/components/text.md

@@ -0,0 +1,14 @@
+# Text
+
+Gallery: `/components/text`. Import from `"maui"`. Type tokens: [tokens.md](../tokens.md). Headings and `Prose`: [prose.md](prose.md).
+
+Inline `<span>`. Defaults: `size="md"`, `fontWeight={400}`, `color="highContrast"`.
+
+```tsx
+<Text size="sm" color="lowContrast">Secondary</Text>
+<Text size="lg" fontWeight={600} monospace>src/maui.ts</Text>
+```
+
+Also accepts native span props except `color` (that axis is the token).
+
+`size`: `2xs` | `xs` | `sm` | `md` | `lg` | `xl`. `fontWeight`: `400` | `500` | `600` | `700`. `color`: `lowContrast` | `highContrast` | `accent` | `onAccent`.

package/skills/maui/references/components/thinking.md

@@ -0,0 +1,12 @@
+# Thinking
+
+Gallery: `/components/thinking`. Import from `"maui"`.
+
+3×3 Game of Life, text-sized. `size` is a CSS length (default `1em`). `variant`: `"primary"` (currentColor) | `"accent"` | `"muted"`.
+
+```tsx
+<Flex row alignItems="center" gap={4}>
+  <Thinking size="0.75em" variant="muted" />
+  <Text size="xs" color="lowContrast">Thinking</Text>
+</Flex>
+```

package/skills/maui/references/components/tooltip.md

@@ -0,0 +1,15 @@
+# Tooltip
+
+Gallery: `/components/tooltip`. Import from `"maui"`.
+
+Wraps the trigger in an inline-block `<span>`. Child should contain something focusable.
+
+```tsx
+<Tooltip content="Previous" placement="top" delay={500}>
+  <Button variant="quiet" aria-label="Previous">
+    <ChevronLeft size="sm" />
+  </Button>
+</Tooltip>
+```
+
+`placement`: `top` | `bottom` | `left` | `right`. Adjacent tooltips skip enter animation (warm group); only the first/last animate.

package/skills/maui/references/patterns/assistant-message.md

@@ -0,0 +1,23 @@
+# Assistant message
+
+Gallery: `/patterns/assistant-message`. Not on the `"maui"` barrel. Prefer this recipe; rebuild with barrel components. Package source: `"maui/src/patterns/AssistantMessage.tsx"` if you need a detail this file does not cover.
+
+`AssistantMessage`: streaming **markdown reply**. Same reading scale as `Prose` (`proseHtml(size)`), max width `proseMaxWidth`.
+
+```tsx
+<AssistantMessage size="sm" isAnimating={streaming}>
+  {markdown}
+</AssistantMessage>
+```
+
+Rebuild with Streamdown + Maui tokens (Streamdown is a Maui dependency):
+
+1. Root: `maxWidth: proseMaxWidth`, `minWidth: 0`. `aria-live="polite"` and `aria-busy` while `isAnimating`.
+2. `<Streamdown>` with `proseHtml(size)` on the root (flex column, Maui type, **drop Streamdown’s Tailwind classNames** on `h1`/`p`/`ul`/… so markers and gaps stay under Maui).
+3. Fenced code: while the fence is incomplete, render a plain `<pre>` (`radius.md`, `shadow.subtle`, `backgroundColor.app`, padding 12px) so the highlighter does not remount every chunk. When complete, `<CodeBlock lang={lang}>{text}</CodeBlock>`.
+4. Animation: keep Streamdown `animated` **stably on**; toggle `isAnimating` only. Flipping `animated` resets stagger and makes new blocks pop. Word fade: `duration: motionStreamDurationMs`, `easing: motionEasing`, `stagger: 16`. While animating, also apply `proseStreamingMarkers` so list bullets fade with words.
+5. `controls={false}`, `lineNumbers={false}`, `mode="streaming"`.
+
+Do not wrap AssistantMessage in `Prose` — `proseHtml` already owns rhythm.
+
+User turns in a chat are **not** this pattern: they are a right-aligned bubble (`prose("sm").paragraph`, `radius.md`, `shadow.subtle`, `background.element`, max-width ~80%). See [AI chat](../apps/ai-chat.md).

package/skills/maui/references/patterns/inbox.md

@@ -0,0 +1,36 @@
+# Inbox
+
+Gallery: `/patterns/inbox`. Not on the `"maui"` barrel. Prefer this recipe; rebuild with barrel components. Package source: `"maui/src/patterns/Inbox.tsx"` if you need a detail this file does not cover.
+
+`Inbox` / `InboxMultiLine`: mail **thread list**, not a table. Two densities:
+
+| | `Inbox` (single line) | `InboxMultiLine` |
+| --- | --- | --- |
+| Grid | `minmax(180px, 24%) minmax(0, 1fr) 92px` — sender · subject+snippet · time | Column: sender+time row, subject, 2-line snippet |
+| Height | ~40px | Padded `y: 6, x: 4` |
+| Unread | 6px accent dot before sender | Same, aligned to the first line |
+
+Row model:
+
+```ts
+type EmailThread = {
+	id: string
+	senders: string
+	subject: string
+	snippet: string
+	time: string
+	unread?: boolean
+}
+```
+
+Behavior:
+
+- `selectedId` + `onSelectThread(id)`. Selected row uses `backgroundColor.elementActive`. Hover uses `elementHover` (instant).
+- `radius.md`, `userSelect: none`, list `gap: 1px`.
+- Subject: highContrast, ellipsis. Snippet: lowContrast, ellipsis (multi-line clamps to 2).
+- Time sits on the right. **On hover**, time fades out and a quiet icon toolbar (`Star`, `Archive`, `Trash`, `Envelope`, `Clock`) fades in at the right — `shadow.subtle` chip, `Button variant="quiet"` with `aria-label`, `stopPropagation` on click.
+- Always include an empty state when `threads.length === 0` (“No messages” + optional compose action).
+
+Single-line sender column is highContrast with the unread dot. Multi-line puts the dot in a leading column (`align: start`).
+
+[Email client](../apps/email-client.md) uses **InboxMultiLine** in a 240px pane.

package/skills/maui/references/patterns/message-list.md

@@ -0,0 +1,23 @@
+# Message list
+
+Gallery: `/patterns/message-list`. Not on the `"maui"` barrel. Prefer this recipe; rebuild with barrel components. Package source: `"maui/src/patterns/MessageList.tsx"` if you need a detail this file does not cover.
+
+`MessageList` + `Message`: raised **cards** in a column (`gap` 6, max width ~760px), `role="feed"`.
+
+Each `Message`:
+
+```tsx
+<article> {/* radius.lg, shadow.subtle, padding 8, column gap 4, background.element */}
+  <header> {/* row, wrap, gap 2 */}
+    <Avatar name={sender} size="sm" />
+    <Text size="sm" fontWeight={500}>{sender}</Text>
+    <time><Text size="xs" color="lowContrast">{timestamp}</Text></time>
+    {edited ? <Text size="xs" color="lowContrast">(edited)</Text> : null}
+  </header>
+  <Prose>{/* body: P / lists, not a raw string */}</Prose>
+</article>
+```
+
+- `sender` + `timestamp` required; `edited?` appends “(edited)”.
+- Body is React children inside `Prose` (so headings/paragraphs get reading rhythm). For email, keep the inner `Prose` unconstrained (`minWidth: 0`) so it fills the card.
+- Empty thread: “Select a thread to read messages.” See [Email client](../apps/email-client.md).

package/skills/maui/references/patterns/sidebar.md

@@ -0,0 +1,38 @@
+# Sidebar
+
+Gallery: `/patterns/sidebar`. Not on the `"maui"` barrel. Prefer this recipe; rebuild with barrel components. Package source: `"maui/src/patterns/Sidebar.tsx"` if you need a detail this file does not cover.
+
+`Sidebar` / `SidebarSection` / `SidebarItem`: fixed **240px** nav: raised `background.element` + `shadow.subtle` + `radius.lg`, column `gap={8}`, padding step 2.
+
+Uses `navigationItem` from [layout utilities](../components/layout-utilities.md).
+
+Composition:
+
+1. Optional brand block (not a special component).
+2. One or more sections: xs/500/lowContrast label, then a list of items.
+3. Each item is a full-width quiet row: 16px icon column, label, optional trailing (`Badge`).
+
+```tsx
+import { Flex, Text } from "maui"
+
+<nav aria-label="Workspace">
+  {/* 240px column, padding step 2, radius.lg, shadow.subtle, background.element, gap 8 */}
+  <Flex column gap={2} px={4} pt={4}>
+    <Text size="sm" fontWeight={600}>Maui Cloud</Text>
+    <Text size="xs" color="lowContrast">Production</Text>
+  </Flex>
+  {/* sections + items — see layout rules below */}
+</nav>
+```
+
+Item layout (rebuild, do not invent a different nav row):
+
+- Grid: `16px minmax(0, 1fr) auto`, column gap spacing 3.
+- Style from `navigationItem` + `focusRing("&:focus-visible")`.
+- `aria-current="page"` when `active` — accent color + weight 500, **no** filled background.
+- Icon wrap is 16×16, `gray[11]`; active icon uses `accent[9]`.
+- Label: 13/20, ellipsis. Section label is padded to align with the text column (padding-start = item padding 4 + 16px icon + gap 3).
+- Native `<button type="button">` inside `<li>`, not `Button` — so the row can be a grid without the 28px control chrome.
+- List: no bullets, `gap: 1px`.
+
+Hover: `backgroundColor.elementHover`, instant.

package/skills/maui/references/tokens.md

@@ -0,0 +1,229 @@
+# Tokens, theme, and styling
+
+Use this file when choosing color, type, space, motion, or elevation, or when writing custom `purse-styles` around Maui components.
+
+Import tokens from `"maui"`. Import `style` / `useStyles` from `"purse-styles"`. Prefer semantic tokens over one-off CSS variables.
+
+## Theme
+
+`MauiProvider` wraps `ThemeProvider` + `PurseProvider` + global CSS + the focus UI database.
+
+```tsx
+import { MauiProvider, themeFoucScript, useTheme } from "maui"
+
+// In <head>, before React:
+// <script>{themeFoucScript}</script>
+
+const { preference, resolvedTheme, setPreference } = useTheme()
+// preference: "system" | "light" | "dark"
+// resolvedTheme: "light" | "dark"
+```
+
+- Storage key: `themeStorageKey` (`"maui-theme"`).
+- Dark CSS: `DARK_THEME` is `:root[data-theme="dark"]`. `defineVars` dark values use that selector.
+- FOUC: inline `themeFoucScript` in a classic `<script>` in `<head>` so `data-theme` and `color-scheme` exist before first paint.
+
+`MauiProvider` also sets `box-sizing: border-box`, zeros `html`/`body` margin, paints `backgroundColor.app`, applies `baseTextStyle` (md / 400 / highContrast) on `html, body`, and resets heading/paragraph margins.
+
+## purse-styles
+
+Maui styles are `purse-styles` objects. `useStyles(...)` turns one or more of them into a class name.
+
+```tsx
+import { style, useStyles } from "purse-styles"
+import { flex, spacing, text, backgroundColor, radius, shadow } from "maui"
+
+function Row({ children }: { children: React.ReactNode }) {
+	const className = useStyles(
+		flex({ direction: "row", align: "center", gap: 4 }),
+		radius.sm,
+		shadow.subtle,
+		style({
+			minWidth: 0,
+			backgroundColor: backgroundColor.element,
+		}),
+	)
+	return <div className={className}>{children}</div>
+}
+```
+
+- `text({...})`, `shadow.subtle`, `background.element`, `radius.md`, `flex({...})`, `spacing.padding({...})` are already style objects — pass them to `useStyles`.
+- `style({ ... })` is for leftover CSS that tokens do not cover (`minWidth`, grid templates, absolute positioning).
+- Compose several objects in one `useStyles` call. Falsy entries are skipped.
+- For one-off layout, prefer the `Flex` / `Padding` components (see [layout-utilities.md](components/layout-utilities.md)). For repeated custom chrome, prefer tokens + `useStyles`.
+
+## Color
+
+`colors` is Radix Scales with a brand `accent` (teal in light, violet in dark). Each scale has steps **1–12**. Alpha scales are `colors.grayAlpha`, `colors.accentAlpha`, `colors.blueAlpha`, …
+
+| Steps | Use |
+| --- | --- |
+| 1–2 | App / subtle surfaces |
+| 3–5 | Interactive washes |
+| 6–8 | Borders / strong lines |
+| 9–10 | Solid fills (9 rest, 10 hover) |
+| 11–12 | Text (11 secondary, 12 primary) |
+
+```ts
+import { colors, colorNames, paletteNames } from "maui"
+
+colors.accent[9]   // solid brand fill
+colors.gray[12]    // high-contrast text
+colors.blueAlpha[8]
+```
+
+`colorNames` is `"accent"` plus every Radix palette name. `paletteNames` omits `"accent"`. `"blue"` as a `variantColor` is the Radix blue scale, not CSS `blue`.
+
+Prefer semantic surfaces over raw scale steps for chrome:
+
+```ts
+import { background, backgroundColor } from "maui"
+
+backgroundColor.app            // page
+backgroundColor.element        // raised control / card
+backgroundColor.elementHover   // 3.5% gray-12 wash over element
+backgroundColor.elementActive  // 7% wash
+background.app                 // style objects of the same values
+background.element
+background.accent              // accent[9]
+```
+
+Hover/active washes use `color-mix` in oklch. **Do not transition `background` / `background-color` on hover.**
+
+## Text
+
+```ts
+import { text, monospace, fontFamily, monoFontFamily } from "maui"
+
+text({
+	size: "sm",          // 2xs | xs | sm | md | lg | xl  (default md)
+	fontWeight: 500,     // 400 | 500 | 600 | 700          (default 400)
+	color: "lowContrast", // lowContrast | highContrast | accent | onAccent
+	monospace: true,
+})
+```
+
+| Size | Font | Line |
+| --- | --- | --- |
+| `2xs` | 10px | 14px |
+| `xs` | 12px | 18px |
+| `sm` | 13px | 20px |
+| `md` | 14px | 22px |
+| `lg` | 16px | 24px |
+| `xl` | 22px | 30px |
+
+- `lowContrast` → `gray[11]`, `highContrast` → `gray[12]`, `accent` → `accent[11]`, `onAccent` → white.
+- UI sans: `fontFamily` (system ui-sans-serif stack). Mono: Commit Mono with `ss05` smart kerning (`monoFontStyle` / `monospace`).
+- `baseTextStyle` is md / 400 / highContrast — already on `html, body`.
+- Inside `Prose`, `H1`–`H4` / `P` / lists switch to the **prose** scale (`sm` 14px, `md` 16px, `lg` 18px), which is larger and has reading rhythm. Do not put app chrome inside `Prose`.
+
+`proseMaxWidth` is `"72ch"`. `sizing.contentWidth` is `maxWidth: 72ch`. `sizing.fullWidth` is `width: 100%`.
+
+## Spacing
+
+Scale steps are **not pixels**:
+
+| Step | px |
+| --- | --- |
+| 1 | 2 |
+| 2 | 4 |
+| 3 | 6 |
+| 4 | 9 |
+| 6 | 12 |
+| 8 | 16 |
+| 12 | 24 |
+| 16 | 32 |
+
+```ts
+spacing.padding({ all: 4, x: 6, y: 2, top: 8 })
+spacing.gap[4]           // style { gap: 9px }
+spacing.value(4)         // "9px" — only when gap/padding tokens cannot apply
+```
+
+`Flex` / `Padding` / `Gap` / `flex({ gap })` all take these steps.
+
+## Layout tokens
+
+```ts
+flex({ direction: "row" | "column", align, justify, gap, wrap })
+flexItem({ size: "hug" | "fill" | "auto", align, order })
+grid({ columns: "one" | "two" | "three" | "autoFit" | "sidebarContent", align, justify, gap })
+gridItem({ area: "sidebar" | "content", span: "full" | 1 | 2 | 3, align, justify })
+```
+
+- `align`: `start` | `center` | `end` | `stretch` | `baseline`
+- `justify`: `start` | `center` | `end` | `between` | `around` | `evenly`
+- `gap` on these token helpers also accepts `0`.
+- `sidebarContent` is `180px minmax(0, 1fr)` with areas `"sidebar content"`.
+
+Prefer `<Flex row gap={4}>` for one-off JSX. Use `flex()` / `grid()` when composing with other tokens.
+
+## Radius
+
+`radius.none` | `2xs` (2px) | `xs` (3) | `sm` (4) | `md` (6) | `lg` (8) | `xl` (12) | `pill` | `circle`.
+
+Controls typically use `sm`. Cards / sidebars use `lg`. Avatars use `circle`.
+
+## Shadows and rings
+
+```ts
+shadow.subtle | shadow.medium | shadow.strong   // style objects
+shadowVars.subtle | .medium | .strong           // raw box-shadow strings
+tintedSubtle(color)                             // subtle ring+blur tinted from a fill
+```
+
+Every elevation already includes a 1px ring. **Do not also `border()` the same element.**
+
+`border(sides, color)`:
+
+- `sides`: `[]` for all sides, or `"top" | "right" | "bottom" | "left"`
+- `color`: `"border"` (gray-12 @ 5%) | `"outline"` (10%) | `"accent"` (`accent[8]`)
+
+`borderColor.border` / `borderColor.outline` are the raw color strings (hairlines, `borderBottom`).
+
+`focusRing(selector = "&:focus-visible", existingShadow?)` — Radix blue ring. Pass `shadowVars.subtle` as the second argument so a raised control keeps its elevation while focused.
+
+`visuallyHidden` — clip an input and keep the styled sibling visible (Checkbox / Switch / Radio).
+
+## Motion
+
+```ts
+motionDurationMs          // 80
+motionStreamDurationMs    // 80 — Streamdown word fade
+motionEasing              // "ease-in-out"
+motion.standard("opacity", "transform")  // 80ms ease-in-out on those properties
+```
+
+Use `motion.standard` for opacity, transform, box-shadow, color. **Never** for hover `background` / `background-color`.
+
+Tooltips use a snappy spring (not `motion.standard`). Crossfade enter is a 0.3s spring (`bounce` 0.2); exit uses `motionDurationMs` / ease-in-out. Streaming markdown uses `motionStreamDurationMs`.
+
+## Sizing and icons
+
+`iconSizeValues` pairs t-shirt sizes to icon boxes (slightly above the matching font-size):
+
+| Size | Box |
+| --- | --- |
+| `2xs` | 12px |
+| `xs` | 14px |
+| `sm` | 16px (default) |
+| `md` | 18px |
+| `lg` | 20px |
+| `xl` | 24px (intrinsic SVG) |
+
+Stroke/fill is `currentColor`. Pass `size` on the icon component; optional `width` / `height` override the box.
+
+## Avatar tokens
+
+`avatar.green` / `avatar.orange` / `avatar.pink` each have `background` and `foreground`. The `Avatar` component also uses `accent[4]`/`[11]`. You rarely need these tokens directly.
+
+## Prose tokens
+
+For HTML that is **not** React typography (`Editor` ProseMirror tree, Streamdown output):
+
+- `prose(size)` — style objects for paragraph, h1–h4, link, blockquote, list (`size`: `sm` | `md` | `lg`)
+- `proseRhythm(size)` — margin-top-only rhythm for `Prose` children
+- `proseHtml(size)` — flex-column + gap styles for a markdown HTML tree
+- `proseStreamingMarkers` — fade list markers with Streamdown’s word animation
+
+Prefer `<Prose>` + `H1`/`P`/… for React trees. Use `proseHtml` only when rendering markdown HTML.