@tanishqkancharla/maui 0.0.21 → 0.0.23

package/dist/components/Button.d.ts

@@ -4,6 +4,7 @@ export type ButtonVariant = "default" | "quiet" | "primary";
 /** Opaque hex or `rgb()`. Palette names stay ColorName (`"blue"` is Radix, not CSS `blue`). */
 export type ButtonCssColor = `#${string}` | `rgb(${string}`;
 export type ButtonVariantColor = ColorName | ButtonCssColor;
+export declare function isCssColor(value: string): value is ButtonCssColor;
 type ButtonAttributes = React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>;
 type ButtonData = {
     id: string;

package/dist/components/Button.js

@@ -86,7 +86,7 @@ const darkTextOnSolid = new Set([
     "sky",
     "yellow",
 ]);
-function isCssColor(value) {
+export function isCssColor(value) {
     return value.startsWith("#") || value.startsWith("rgb");
 }
 function paletteFill(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tanishqkancharla/maui",
-	"version": "0.0.21",
+	"version": "0.0.23",
 	"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`.