@sableui/react 0.0.0-stage → 0.1.0

package/llms/components/tree.md

@@ -0,0 +1,227 @@
+# Tree
+
+**Status:** stable
+
+The object list a tool is built around — layers, scene graph, outline — on one shared grid, so every left edge in the panel resolves to the rail or an exact multiple of the indent step.
+
+**Keywords:** tree, layers, outline, scene graph, hierarchy, nesting, indent, disclosure, workspace, panel, file tree, files, folders, explorer, treeview
+
+## Usage
+
+Use Tree for the hierarchy panel in a workspace: layers, objects, an inspector outline. It owns the geometry that makes nesting legible — the rail, the disclosure and type columns, and the indent step — via the density ladder (scope the panel with data-density, e.g. data-density="compact"), so nothing in the panel computes its own inset. It is also the file tree: nest rows with `subtree`, let folders manage their own open state with `defaultExpanded`, and mark kind with the `icon` convention (folder for a row with a subtree, file for a leaf). Reach for Accordion when the content is prose sections rather than nodes in a hierarchy.
+
+### Best practices
+
+- Do: Give Tree an aria-label naming the hierarchy ("Layers", "Files"). It is a role="tree", and an unnamed tree is announced as just "tree".
+- Do: For a file tree, nest with `subtree` and use the icon convention: `icon={<Icon name="folder" />}` on a row with a subtree, `icon={<Icon name="file" />}` on a leaf. There are no folder/file presets — they would only bind those two props.
+- Do: Give TreeAddRow the same depth as the rows it adds to, so its mark lands in their type column: one deeper than the parent for a child list, the parent's own depth for a sibling list.
+- Do: Put mutable per-row state (visibility, solo, a row menu) in `actions`, on the right rail. Show it on hover, and at rest only when its value is the non-default one.
+- Do: Let section headers sit on the rail at the same height as a depth-0 row. Space and a hairline separate sections; TreeSection handles both, including dropping the divider on the first.
+- Don't: Hardcode a left inset anywhere in the panel. Use treeIndent(depth) or var(--tree-rail); a hand-written px value is how a tree ends up with four different left edges.
+- Don't: Redefine --tree-indent to anything other than --tree-column. A step smaller than the column puts a child's content left of its parent's and the nesting reads inverted.
+- Don't: Put the visibility toggle before the name. A leading toggle makes each row's visual start depend on its depth, so no two rows share an edge.
+- Don't: Hand-copy icon paths into a tree row. Use Icon and the shared semantic set, or provide an app-specific icon through the supported slot.
+- Don't: Use EmptyState inside a panel. It is page-register furniture (px-6 py-12 around a size-12 disc) and in 240px it spends 24px of inset and ~96px of height on nothing. Use TreeEmpty.
+- Don't: Show explanatory prose AND an add row in an empty section. That is two things to read where one carries the affordance; give TreeEmpty a one-line message and pass the add row as its action.
+- Don't: Leave a section actionable when its action cannot do anything yet — a document-level effect list with no content to apply to, for instance. Hide the section or its affordance until the thing it operates on exists.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Tree | yes | The container. Does not scroll itself — put it in a scrolling Panel, or make it the scrolling region with className. |
+| TreeSection | no | A titled group. Header on the rail, hairline above, divider suppressed on the first section. |
+| TreeRow | yes | One node: rail, disclosure column, type column, name, right-rail actions. |
+| TreeAddRow | no | The affordance that ends a branch. Mark in the type column, label in the name column. |
+| TreeEmpty | no | A section's empty state at panel scale: one line, one action, optionally a dashed drop region. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| TreeSection | { title: ReactNode; hint?: string; action?: ReactNode } | A titled group of rows, with the header on the rail. |
+| TreeRow | { depth?: number; selected?: boolean; accent?: boolean; dimmed?: boolean; expandable?: boolean; expanded?: boolean; defaultExpanded?: boolean; onExpandedChange?: (expanded: boolean) => void; subtree?: ReactNode; toggleLabel?: string; disclosureIcon?: ReactNode; icon?: ReactNode; actions?: ReactNode } | One node in the hierarchy (role=treeitem inside a Tree). Controlled via expanded/onExpandedChange or uncontrolled via defaultExpanded; nest children with subtree. Always reserves both leading columns (disclosure and type), so a leaf's name lines up with its expandable siblings. |
+| TreeAddRow | { depth?: number; label: ReactNode; icon?: ReactNode } | The add affordance, shaped as a row and aligned to the branch it adds to. Its mark sits in the type column (level with the siblings' kind markers), not the name column. `icon` replaces the built-in add mark. |
+| TreeEmpty | { message: ReactNode; action?: ReactNode; dropTarget?: boolean; depth?: number } | A section's or a branch's empty state, at panel scale rather than page scale. One-line message, one action slot; dropTarget renders it as a dashed drop region and sets data-drop-target for styling. `depth` (inherited inside a subtree) starts the line on the edge of the rows that branch would hold. |
+| treeIndent | (depth: number) => string | The left inset for a depth, as a calc() expression reading the density ladder. Use this rather than computing pixels. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| depth | number | 0 | Nesting level, on TreeRow and TreeAddRow. 0 sits on the rail; each level adds one --tree-indent. |
+| expandable | boolean | true with subtree, else false | Whether TreeRow renders a disclosure control. The column is reserved either way, so leaf and parent names stay aligned. |
+| expanded | boolean | — | Controlled open state for a TreeRow. Pair with onExpandedChange; omit both for an uncontrolled row. |
+| defaultExpanded | boolean | true | Uncontrolled initial open state, used when `expanded` is not passed. Pass false for a file tree's closed folders. |
+| onExpandedChange | (expanded: boolean) => void | — | Called when a TreeRow opens or closes — from the disclosure, ArrowRight/ArrowLeft, or activating a row that has no onClick. Fires in both controlled and uncontrolled use. |
+| subtree | ReactNode | — | The rows nested under a TreeRow, rendered after it while it is expanded. Nested rows inherit depth + 1 unless they pass their own `depth`, so a file tree never computes depth by hand. |
+| selected | boolean | false | Selection fill and accent bar on a TreeRow. Inside a Tree it is exposed as aria-selected on the treeitem; a row rendered outside a Tree is a plain div and exposes aria-current instead. |
+| toggleLabel | string | — | Names the thing being disclosed, for the toggle's accessible label — "Expand Background" rather than "Expand group". Every example passes it; a screen-reader user hearing twenty identical "Expand group" buttons has no way to tell them apart. |
+| icon | ReactNode | — | The kind marker for a TreeRow, rendered in the type column at 1em. Use a semantic Icon so it follows the app icon set. |
+| disclosureIcon | ReactNode | — | Replaces TreeRow's semantic chevron-down icon. Omit to use the current IconProvider set or Reicon by default. |
+| actions | ReactNode | — | Right-rail controls for a TreeRow: visibility, solo, a row menu. |
+| label | ReactNode | — | TreeAddRow's visible label. Name what gets added — 'Add effect', not 'Add'. |
+
+## Tokens used
+
+`panel-raised`, `hairline`, `foreground`, `muted-foreground`, `primary`, `ring`
+
+## Accessibility
+
+- Tree implements the ARIA tree view pattern: Tree is role="tree", each TreeRow and TreeAddRow is role="treeitem" with aria-level, expandable rows carry aria-expanded, and a TreeSection is a role="group" labelled by its heading. Rows stay flat in the DOM — hierarchy is aria-level — so the fills span the panel's full width.
+- Keyboard: exactly one row is in the tab order (roving tabindex, seeded on the selected row, else the first). ArrowUp/Down move between visible rows; ArrowRight expands a collapsed row, then steps to its first child; ArrowLeft collapses an expanded row, else steps to its parent; Home/End jump to the ends; Enter/Space activate the row — its onClick, or toggling it when it has none. Keys pressed inside a row's own controls (an action button, a rename field) are left to that control.
+- Selection has one mapping: inside a Tree, `selected` is aria-selected on the treeitem; outside a Tree the row is a plain div, where aria-selected is invalid, so it falls back to aria-current. A navigation tree that wants aria-current="page" passes it through props.
+- Each treeitem is named by its own label (aria-labelledby the name), never by the text of its icon or action buttons.
+- The disclosure is a real button with aria-expanded and a label naming what it discloses, and it stops propagation so collapsing a group never changes the selection. Inside a Tree the treeitem carries aria-expanded and the arrow keys, so the button becomes a pointer target only: aria-hidden, out of the tab order, and it leaves focus where it was when clicked.
+- The disclosure's POINTER TARGET is bigger than the mark it draws. `--tree-column` is 20px comfortable and 18px compact, both under WCAG 2.5.8's 24x24 floor, so a centred pseudo-element takes the hit at `--control-xs` (28/24) instead. The drawn box stays on the column, because that column is also the indent step — growing the button would push every name in the tree one column right.
+- Right-rail actions stay in the tab order, so a row with actions costs extra Tab stops. Keep actions few and show them on hover and focus-visible.
+- `dimmed` is presentation only. A row switched off must also say so in its actions' aria-pressed or its accessible name; opacity alone is invisible to a screen reader and fails contrast.
+- Right-rail controls that appear on hover must also appear on focus-visible, or they are unreachable by keyboard.
+
+## Related
+
+- Components: Panel, PanelSection, Workspace, Accordion, SideNav
+
+## Examples
+
+### File tree
+
+```tsx
+import { Icon, Tree, TreeRow } from "@sableui/react"
+
+// Nest with subtree; folders own their open state via defaultExpanded.
+// A row with no onClick toggles when clicked or activated, like a folder in
+// a file explorer. Depth is inherited — never computed by hand.
+<Tree aria-label="Files" className="max-w-xs">
+  <TreeRow
+    icon={<Icon name="folder" />}
+    toggleLabel="src"
+    subtree={
+      <>
+        <TreeRow icon={<Icon name="file" />} onClick={() => open("index.ts")}>index.ts</TreeRow>
+        <TreeRow
+          icon={<Icon name="folder" />}
+          toggleLabel="components"
+          defaultExpanded={false}
+          subtree={
+            <TreeRow icon={<Icon name="file" />} selected onClick={() => open("button.tsx")}>
+              button.tsx
+            </TreeRow>
+          }
+        >
+          components
+        </TreeRow>
+      </>
+    }
+  >
+    src
+  </TreeRow>
+  <TreeRow icon={<Icon name="file" />} onClick={() => open("README.md")}>README.md</TreeRow>
+</Tree>
+```
+
+### Layer tree with per-node effects
+
+```tsx
+import { Button, Icon, Tree, TreeAddRow, TreeRow, TreeSection } from "@sableui/react"
+
+<Tree aria-label="Layers" className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">
+  <TreeSection title="Document effects" hint="Applied to the flattened composite">
+    <TreeRow depth={0} icon={<Icon name="sparkles" />}>Channel shift</TreeRow>
+    <TreeAddRow depth={0} label="Add effect" />
+  </TreeSection>
+
+  <TreeSection title="Layers" action={<span className="text-ui-num text-muted-foreground">2</span>}>
+    <TreeRow
+      depth={0}
+      expandable
+      expanded
+      toggleLabel="Backdrop"
+      icon={<Icon name="image-stack" />}
+      actions={<Button size="icon-xs" variant="ghost" aria-label="Hide Backdrop"><Icon name="eye" /></Button>}
+    >
+      Backdrop
+    </TreeRow>
+    <TreeRow depth={1} icon={<Icon name="sparkles" />}>Block displacement</TreeRow>
+    <TreeAddRow depth={1} label="Add effect" />
+
+    <TreeRow depth={0} icon={<Icon name="image-stack" />} dimmed>Overlay</TreeRow>
+    <TreeAddRow depth={0} label="Add image" />
+  </TreeSection>
+</Tree>
+```
+
+### Empty state — one line, one action
+
+```tsx
+import { TreeAddRow, TreeEmpty, TreeSection } from "@sableui/react"
+
+// A section with nothing in it offers exactly ONE way forward. Not EmptyState:
+// that is page-register (px-6 py-12 around a size-12 disc) and in a 240px panel
+// it spends 24px of inset and ~96px of height on nothing.
+<TreeSection title="Layers">
+  <TreeEmpty message="No images yet" action={<TreeAddRow depth={0} label="Add image" />} />
+</TreeSection>
+
+// As a drop region — the app owns the drag handlers; TreeEmpty owns the frame
+// and sets data-drop-target so a data-[drop-active] style can respond.
+<TreeEmpty
+  dropTarget
+  message="Drop an image"
+  data-drop-active={dragging || undefined}
+  onDragOver={(e) => { e.preventDefault(); setDragging(true) }}
+  onDragLeave={() => setDragging(false)}
+  onDrop={handleDrop}
+  className="data-[drop-active]:border-primary"
+/>
+```
+
+### Selection and disclosure
+
+```tsx
+import { Icon, Tree, TreeRow } from "@sableui/react"
+
+<Tree aria-label="Layers">
+  <TreeRow
+    depth={0}
+    expandable
+    expanded={open}
+    onExpandedChange={setOpen}
+    toggleLabel="Group 1"
+    icon={<Icon name="folder" />}
+    selected
+    onClick={() => select("group-1")}
+  >
+    Group 1
+  </TreeRow>
+  {open ? <TreeRow depth={1} icon={<Icon name="file" />}>Child</TreeRow> : null}
+</Tree>
+```
+
+### An empty branch
+
+```tsx
+import { Icon, TreeAddRow, TreeEmpty, TreeRow } from "@sableui/react"
+
+// A layer with no effects: TreeEmpty at the branch's depth lands on the
+// same edge its effect rows would — no hand-computed inset.
+<TreeRow depth={0} icon={<Icon name="image-stack" />} toggleLabel="Overlay" subtree={
+  <>
+    <TreeEmpty message="No effects yet" />
+    <TreeAddRow label="Add effect" />
+  </>
+}>
+  Overlay
+</TreeRow>
+```
+
+### Aligning a custom affordance
+
+```tsx
+import { treeIndent } from "@sableui/react"
+
+// Anything else that needs a tree inset reads it from the same place the rows do.
+<div style={{ paddingInlineStart: treeIndent(1) }} className="flex h-(--control-xs) items-center">
+  <span className="text-ui-body text-muted-foreground">Drag a layer here</span>
+</div>
+```

package/llms/components/video.md

@@ -0,0 +1,66 @@
+# Video
+
+**Status:** stable
+
+Styled 16:9 video player frame. Mounts a native <video> when given a src, or shows a poster/placeholder with a centered play overlay.
+
+**Keywords:** video, media, player, demo
+
+## Usage
+
+Use Video to embed playable or previewable video media inside a page.
+
+### Best practices
+
+- Do: Use captions, poster imagery, and controls when the video carries information.
+- Do: Keep the surrounding layout stable while media loads.
+- Don't: Do not autoplay important audio or make video the only way to access required information.
+- Don't: Do not ship it without captions or a transcript. Captions are what make video usable for deaf users and searchable for everyone; a video with neither is inaccessible content you also cannot index.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| onRequestPlay | () => void | — | Placeholder only (no src): renders the play mark as a real button labelled "Play video" that calls this — e.g. to load the source. Without it the mark is decorative. |
+| src | string | — | Video source URL. When omitted, a poster/placeholder with a play overlay renders. |
+| poster | string | — | Poster image shown before playback (and as the placeholder backdrop). |
+| controls | boolean | true | Show native playback controls. |
+
+## Tokens used
+
+`border`, `overlay`, `overlay-foreground`, `ring`
+
+## Accessibility
+
+- Mounts a native <video> element, preserving built-in keyboard controls when controls is enabled.
+- Without onRequestPlay the placeholder play mark is decorative (aria-hidden) — nothing on the frame pretends to be pressable. With it, the mark is a native button named "Play video".
+
+## Related
+
+- Components: Carousel, Dialog, Badge
+
+## Examples
+
+### With a poster
+
+```tsx
+import { Video } from "@sableui/react"
+
+<Video poster="/cover.jpg" src="/clip.mp4" />
+```
+
+### Placeholder (no src)
+
+```tsx
+import { Video } from "@sableui/react"
+
+<Video poster="/cover.jpg" />
+```
+
+### Placeholder that loads on play
+
+```tsx
+import { Video } from "@sableui/react"
+
+<Video poster="/cover.jpg" src={src} onRequestPlay={() => setSrc("/clip.mp4")} />
+```

package/llms/components/workspace.md

@@ -0,0 +1,138 @@
+# Workspace
+
+**Status:** stable
+
+The shell for a tool: a fixed viewport partitioned into independently scrolling regions, with a compact density scope, a skip link, and a canvas landmark.
+
+**Keywords:** workspace, tool, editor, shell, frame, canvas, chrome, panels, density, viewport
+
+## Usage
+
+Use Workspace as the outer frame for a tool — an editor, a console, a canvas app. It owns the viewport, scopes the compact control density, and guarantees a skip link plus a main landmark on the canvas. Reach for AppShell instead for page-register products: it is built around a scrolling document, where a workspace is built around a fixed one. Workspace fills the viewport (h-dvh) by design; to embed one in a page (a docs preview, a modal-sized demo), wrap it in a bounded container and pass className="h-full".
+
+### Best practices
+
+- Do: Put a PanelGroup in the body and a WorkspaceCanvas inside it, so panels are aside chrome and the work surface is the main landmark.
+- Do: Let each panel own its scrolling. The shell never scrolls, and the canvas clips rather than scrolls — panning is the viewport's job.
+- Do: Keep the density scope at compact unless you have a specific reason; the workspace register's measured control ladder is what makes tool chrome read as tool chrome.
+- Don't: Nest a Region or Page inside it to set a width. Region caps are a page-register idea; a workspace is edge-to-edge and its panels are fixed-width chrome outside the content grid.
+- Don't: Hardcode a control height (h-[32px]). CI rejects it (raw-control-height); read the ladder instead, e.g. h-(--control-sm), so the density scope can size it.
+- Don't: Put a Card in the chrome. Use PanelSection — a card inside a narrow panel spends its border and inset on nothing.
+- Don't: Use it for a dashboard that scrolls. If the primary interaction is reading down a page, that's AppShell plus a Region, not a workspace.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| WorkspaceBar | no | Top chrome at --chrome-bar-height with a hairline beneath: toolbar, document tabs, menubar row. |
+| Body | yes | The flexible middle row, normally a PanelGroup. Constrained so its children can shrink and scroll. |
+| WorkspaceCanvas | no | The work surface and the main#main-content landmark the skip link targets. Clips rather than scrolls. |
+| StatusBar | no | Bottom chrome for ambient document facts. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| WorkspaceBar | ComponentProps<'header'> | The top chrome strip, sized to --chrome-bar-height with a hairline beneath. |
+| WorkspaceCanvas | ComponentProps<'main'> | The work surface: renders main#main-content, fills the body, clips its overflow. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| toolbar | ReactNode | — | Top chrome, normally a WorkspaceBar. |
+| statusBar | ReactNode | — | Bottom chrome, normally a StatusBar. |
+| density | "compact" \| "comfortable" | "compact" | Density scope for everything inside. Sets the --control-* ladder via data-density; compact is the workspace register. Nothing hardcodes a height, so the same size="md" Button is 40px on a page and 32px inside a compact Workspace. A Dialog opened from inside resets to comfortable, because a modal is a page-register surface even when a tool launched it. |
+| skipLinkLabel | string | "Skip to canvas" | Text for the skip link that targets the canvas landmark. |
+
+## Tokens used
+
+`canvas`, `canvas-foreground`, `panel`, `hairline`, `popover`, `popover-foreground`, `ring`
+
+## Accessibility
+
+- Renders a skip link to #main-content as the first focusable element, even though there is no scrolling document.
+- WorkspaceCanvas is the <main id="main-content"> landmark; Panels are <aside> chrome with their own names.
+- Density only changes control sizes, never hit-target rules — an icon button at the 24px floor still needs a padded 44px hit area.
+
+## Related
+
+- Components: PanelGroup, PanelSection, StatusBar, ScrubField, AppShell
+
+## Examples
+
+### Editor shell
+
+```tsx
+import { Button, Panel, PanelGroup, PanelSection, PropertyPair, PropertyRow, ScrubField, Separator, StatusBar, StatusBarGroup, StatusBarSeparator, Switch, Workspace, WorkspaceBar, WorkspaceCanvas } from "@sableui/react"
+
+<Workspace
+  toolbar={
+    <WorkspaceBar>
+      <span className="px-1 text-ui-md text-foreground">Studio</span>
+      <Separator orientation="vertical" className="mx-1 h-4" />
+      <Button size="xs" variant="ghost">Open</Button>
+    </WorkspaceBar>
+  }
+  statusBar={
+    <StatusBar>
+      <span className="text-ui-num">1024 × 768</span>
+      <StatusBarSeparator />
+      <span>3 layers</span>
+      <StatusBarGroup align="end"><span>Saved</span></StatusBarGroup>
+    </StatusBar>
+  }
+>
+  <PanelGroup>
+    <Panel label="Layers" width={240}>
+      <PanelSection title="Layers">
+        <PropertyRow label="Background"><Switch defaultChecked /></PropertyRow>
+      </PanelSection>
+    </Panel>
+    <WorkspaceCanvas>
+      <div className="grid h-full place-items-center text-ui-body text-muted-foreground">Canvas</div>
+    </WorkspaceCanvas>
+    <Panel label="Properties" width={256}>
+      <PanelSection title="Blending">
+        <PropertyPair>
+          <ScrubField label="Opacity" icon="grid" suffix="%" value={100} min={0} max={100} />
+          <ScrubField label="Blur" value={0} min={0} max={64} suffix="px" />
+        </PropertyPair>
+      </PanelSection>
+    </Panel>
+  </PanelGroup>
+</Workspace>
+```
+
+### Console shell (no canvas)
+
+```tsx
+import { Input, Panel, PanelGroup, PanelSection, PropertyRow, StatusBar, Workspace, WorkspaceCanvas } from "@sableui/react"
+
+<Workspace statusBar={<StatusBar><span>Connected</span></StatusBar>}>
+  <PanelGroup>
+    <Panel label="Sources" width={240}>
+      <PanelSection title="Sources">
+        <PropertyRow label="Filter"><Input placeholder="Search" /></PropertyRow>
+      </PanelSection>
+    </Panel>
+    <WorkspaceCanvas className="overflow-y-auto scrollbar-quiet">
+      <div className="p-3 text-ui-num text-muted-foreground">log output…</div>
+    </WorkspaceCanvas>
+  </PanelGroup>
+</Workspace>
+```
+
+### Comfortable density
+
+```tsx
+import { PanelGroup, Workspace, WorkspaceBar, WorkspaceCanvas } from "@sableui/react"
+
+<Workspace density="comfortable" toolbar={<WorkspaceBar><span className="text-ui-md">Review</span></WorkspaceBar>}>
+  <PanelGroup>
+    <WorkspaceCanvas>
+      <div className="grid h-full place-items-center text-body-md text-muted-foreground">Touch-friendly review mode</div>
+    </WorkspaceCanvas>
+  </PanelGroup>
+</Workspace>
+```

package/llms/foundations/accessibility.md

@@ -0,0 +1,60 @@
+# Accessibility
+
+Sable's components ship accessible behavior from Base UI. These rules cover what an app composing them still has to get right.
+
+**WCAG AA · 44px targets · visible focus · reduced motion · logical properties**
+
+## Floors
+
+| Name | Value | Use |
+|---|---|---|
+| `Contrast` | 4.5:1 text · 3:1 UI and large text | Every semantic text/surface pair is checked per theme by contrast.test.ts. |
+| `Hit area` | 44×44px | hit-target keeps a small control at the floor without moving layout. |
+| `Focus` | ring-2 ring-ring, full opacity | Visible on every interactive element, in light, dark and forced-colors. |
+| `Mobile input text` | ≥ 16px | iOS Safari zooms the page on focus below it. |
+| `Reduced motion` | --motion-scale: 0 | Transitions resolve instantly; loaders hold their first frame. |
+
+## Rules
+
+1. **Use the component, not a div with a click handler.** Base UI supplies roles, keyboard handling and focus management. A clickable div has none of them.
+2. **Every control has an accessible name.** Icon-only buttons take aria-label. Fields take a <Label> through <Field>, which also wires aria-describedby and aria-invalid.
+3. **A live region exists before it has anything to say.** Render role="status" empty from the start and swap its text. A region inserted together with its content is announced inconsistently.
+4. **On client-side navigation, update document.title and move focus to the new view's h1.** Route changes are silent to assistive technology unless the app announces them. AppShell supplies the skip link and landmarks; the app does the rest.
+5. **Keep submit enabled; validate on submit and focus the first invalid field.** A disabled submit hides why it is disabled. Focus is the only way a screen-reader user finds the error.
+6. **Use logical properties: ms-/me-/ps-/pe-/text-start/inset-inline-*.** Flex and grid mirror for free under dir="rtl"; hand-positioned elements do not. *Enforced by design-lint: physical-direction (ratchet).*
+7. **Decorative layers over content take pointer-events-none and aria-hidden.** Scrims, glows and fades otherwise swallow clicks on the controls beneath.
+8. **Check focus and disabled states under forced-colors: active.** Windows High Contrast overrides ring colors and erases opacity-based disabled styling.
+
+## Never
+
+- **Never:** Color as the only signal (a red border with no message). **Instead:** Color plus text or an icon. Roughly 1 in 12 men cannot tell red from green.
+- **Never:** Opacity on the focus ring. **Instead:** ring-ring at full opacity; tune the token in the theme. A faded ring loses the contrast the theme tested. *Enforced by sable-lint: faded-focus-ring.*
+- **Never:** Blocking paste, or type="number" for codes and card numbers. **Instead:** type="text" inputMode="numeric" with the right autocomplete. Blocking paste breaks password managers; number inputs scroll-change identifiers.
+- **Never:** forced-color-adjust: none to 'fix' high-contrast mode. **Instead:** Let the system colors apply; verify the result. It removes the user's chosen colors exactly where they need them.
+- **Never:** outline: none without a replacement. **Instead:** focus-visible:ring-2 ring-ring. Keyboard users lose their place.
+
+## Details
+
+### An icon-only button
+
+```tsx
+// before
+<Button size="icon"><Icon name="xmark" /></Button>
+// after
+<Button size="icon" aria-label="Close"><Icon name="xmark" /></Button>
+```
+
+Without a name, a screen reader announces only 'button'.
+
+### A status that announces
+
+```tsx
+// before
+{saved && <p role="status">Saved</p>}
+// after
+<p role="status">{saved ? "Saved" : ""}</p>
+```
+
+The region is in the accessibility tree before its text changes, so the change is announced.
+
+**Related:** `sable docs typography` · `sable docs motion` · `sable component <Name> --a11y`

package/llms/foundations/motion.md

@@ -0,0 +1,96 @@
+# Motion
+
+Motion explains a change: where something came from, what responded, and that work is happening. It is subtle by default, built from named recipes, and one switch turns it off.
+
+**4 slots · 3 speeds · enter-only overshoot · 1 kill switch**
+
+## Three speeds
+
+Match duration to the distance and size of what moves. Each value is multiplied by --motion-scale. Two edge steps sit outside the three: --motion-duration-instant (75ms) for a checkbox tick or tab swap, and --motion-duration-slower (500ms) for progress and value changes.
+
+| Name | Value | Use |
+|---|---|---|
+| `fast  --motion-duration-fast` | 150ms | Hover, press, focus, tooltips, small toggles. Also every exit. |
+| `base  --motion-duration-base` | 200ms | Menus, popovers, tabs, disclosure. The default enter. |
+| `slow  --motion-duration-slow` | 300ms | Dialogs, sheets, page-level transitions. |
+
+## Recipes
+
+Reach for one named class before writing a transition.
+
+| Name | Value | Use |
+|---|---|---|
+| `motion-interactive` | fast · standard | Hover/focus/press chrome on anything clickable. Replaces transition-colors. |
+| `motion-press` | fast · scale settle | Tactile press. Always paired with motion-interactive. |
+| `motion-fade` | enter base / exit fast | Scrims and backdrops. |
+| `motion-pop` | enter base · spring | Anchored or centred surfaces: popovers, menus, dialogs. |
+| `motion-slide-{up,down,left,right}` | enter base / exit fast | Directional surfaces: sheets, toasts. |
+| `motion-disclosure` | base · standard | Height changes: accordion, collapsible. |
+| `motion-icon-swap` | enter · emphasized cross-fade | Two icons of one control trading places: play/pause, outline/fill. |
+| `motion-draw` | slower · decelerate | SVG line art drawing on when a <Reveal> scrolls in. The path needs pathLength="1"; stagger siblings with --motion-draw-delay. |
+| `motion-spin · pulse · shimmer · dot-bounce · ping` | loops | Activity. Scale-aware, so reduced motion freezes them. |
+
+## Easings
+
+| Name | Value | Use |
+|---|---|---|
+| `ease-standard` | cubic-bezier(0.4, 0, 0.2, 1) | The default for state changes. |
+| `ease-decelerate` | cubic-bezier(0, 0, 0.2, 1) | Entrances: arrive fast, settle slowly. |
+| `ease-emphasized` | cubic-bezier(0.2, 0, 0, 1) | Large surfaces covering a lot of distance. |
+| `ease-spring` | ~4% overshoot | A gentle pop on enter. Never on exit. |
+| `ease-bounce` | ~10% overshoot | A playful pop, opt-in only. Enter only, never on exit. |
+
+## The four slots
+
+Every interactive component answers all four, by filling the slot or declining it with a reason in meta.motion.
+
+| Name | Value | Use |
+|---|---|---|
+| `arrival` | fade · slide · pop · Reveal | How does it enter? |
+| `response` | motion-interactive · motion-press | What happens under the pointer? |
+| `transition` | motion-disclosure · eased transform | How does it move between its own states? |
+| `activity` | spin · pulse · shimmer | How do you tell working from frozen? |
+
+## Rules
+
+1. **Every motion has a reason: orientation, feedback, continuity or activity.** Motion with no reason is latency. If you cannot say which of the four it serves, remove it.
+2. **Reach for a recipe first; drop to tokens only when none fits.** Recipes are reviewed once and respect the kill switch. A bespoke transition string is reviewed never. *Enforced by sable-lint: transition-colors, transition-all.*
+3. **Exits are one step faster than entrances, and never overshoot.** Something leaving should get out of the way. A bounce on exit draws the eye to what the user just dismissed.
+4. **Animate opacity and transform only.** They run on the compositor. Width, height, top and left cause layout on every frame. motion-disclosure is the one sanctioned exception.
+5. **Durations come from tokens, so --motion-scale can stop them.** prefers-reduced-motion and <MotionProvider> off both set --motion-scale to 0. A raw duration ignores that. *Enforced by sable-lint: raw-duration, builtin-animate.*
+6. **Interactive elements always respond. Something styled for hover with no motion recipe snaps.** A snap between states reads as broken. The four prohibitive rules could not catch missing motion, so this one does. *Enforced by sable-lint: static-interactive.*
+7. **JS motion reads useMotion().enabled and does nothing when it is false.** Reduced motion is an accessibility setting, not a style preference.
+
+## Never
+
+- **Never:** Tailwind's animate-spin / animate-pulse / animate-ping / animate-bounce. **Instead:** motion-spin, motion-pulse, motion-ping, motion-dot-bounce. The built-ins ignore --motion-scale, so reduced motion cannot freeze them. *Enforced by sable-lint: builtin-animate.*
+- **Never:** duration-150, duration-300, or any raw duration utility. **Instead:** duration-(--motion-duration-fast) and siblings. Raw durations bypass the kill switch. *Enforced by sable-lint: raw-duration.*
+- **Never:** transition-all, or transition-colors on its own. **Instead:** motion-interactive, or name the properties you animate. transition-all animates unrelated layout changes and defeats the browser's pre-computation. *Enforced by sable-lint: transition-all, transition-colors.*
+- **Never:** Motion on first paint of static content, or staggered entrances on every list. **Instead:** Reveal for one deliberate moment per view. Entrance choreography repeated everywhere becomes a loading delay.
+- **Never:** The motion library in the core package. **Instead:** src/motion (WAAPI, IntersectionObserver, View Transitions). Sable's motion layer is zero-dependency; drag, FLIP and velocity springs belong in an optional adapter.
+
+## Details
+
+### Hover that respects the kill switch
+
+```tsx
+// before
+<button className="transition-colors duration-150 sable-surface-interactive">
+// after
+<button className="motion-interactive sable-surface-interactive">
+```
+
+Same feel, but reduced motion now resolves it instantly.
+
+### Faster exits
+
+```tsx
+// before
+transition: opacity 200ms ease-in-out;  /* in and out */
+// after
+data-[starting-style]: enter 200ms decelerate · data-[ending-style]: exit 150ms standard
+```
+
+motion-pop and motion-slide-* already do this; dismissing feels responsive instead of sluggish.
+
+**Related:** `sable docs accessibility` · `sable docs reviewing-motion` · `sable token motion`

package/llms/foundations/scrolling.md

@@ -0,0 +1,41 @@
+# Scrolling
+
+Every scroll container declares a policy. Vertical regions get a quiet bar that appears only while you are in them; horizontal strips get edge fades instead of a rail.
+
+**2 policies · vertical gets a bar · horizontal gets a fade**
+
+## Policies
+
+| Name | Value | Use |
+|---|---|---|
+| `scrollbar-quiet` | 4px thumb · hidden at rest → 12% active → 16% hovered → 20% dragging | The default for vertical scrolling. Grows to 6px under the pointer. |
+| `scrollbar-hidden` | no bar | Only when something else carries the affordance — and you can name it (an edge fade, paging controls). |
+| `<Scroller>` | edge fades + wheel mapping | Horizontal strips: media rows, chip rows, tab overflow. |
+| `useScrollActivity` | data-scrolling for ~600ms | Lets the bar respond to touch drags and programmatic scrolls, which hover cannot see. |
+
+## Rules
+
+1. **Every overflow-*-auto|scroll declares scrollbar-quiet or scrollbar-hidden.** Left bare, the platform draws its own: on Windows, stepper arrows hard against the padding edge that poke out of rounded corners. *Enforced by sable-lint: unmanaged-overflow (also checked over every registry example).*
+2. **Vertical regions get a bar; horizontal regions get an edge fade.** A vertical list needs position feedback. A horizontal strip needs 'there is more this way', which a fade says better than a 4px rail.
+3. **A horizontal region must work without a horizontal input.** Most mice have no horizontal wheel. Scroller maps the vertical wheel sideways and handles arrow keys, Home and End.
+4. **Reveal on scrolling, not only on hover.** Touch drags and programmatic scrolls (a chat following a reply) hover nothing, and those are the moments a reader needs to see where they are.
+
+## Never
+
+- **Never:** scrollbar-hidden on a vertical list with no fade or paging. **Instead:** scrollbar-quiet. It leaves the reader with no sense of position and nothing to discover.
+- **Never:** A styled ::-webkit-scrollbar written per component. **Instead:** The scrollbar-quiet utility. Chromium ignores ::-webkit-scrollbar once scrollbar-width is set; the utility handles both engines.
+
+## Details
+
+### A scrolling panel
+
+```tsx
+// before
+<div className="overflow-y-auto">
+// after
+<div className="overflow-y-auto scrollbar-quiet" ref={useScrollActivity()}>
+```
+
+No bar at rest; it appears while scrolling, hovered or focused, and fades a beat after. Content cut off at the edge is what says the region scrolls.
+
+**Related:** `sable docs surfaces` · `sable docs accessibility` · `sable component Scroller`