@sableui/react 0.0.0-stage → 0.1.1

package/llms/foundations/shape.md

@@ -0,0 +1,73 @@
+# Shape
+
+Radius signals what something is: tight on containers, full on actions. Nested corners stay concentric, and one edge treatment marks a boundary.
+
+**7 radius steps · concentric nesting · 1 edge treatment per boundary**
+
+## The radius ladder
+
+Each step is 4px apart, so common insets land on a real step. Themes and the customizer retune every step together.
+
+| Name | Value | Use |
+|---|---|---|
+| `rounded-none` | 0 | Full-bleed media. |
+| `rounded-xs` | 4px | Tags, kbd, small inline marks. |
+| `rounded-sm` | 8px | Inputs, menu items, list rows. |
+| `rounded-md` | 12px | Popovers, menus, toasts. |
+| `rounded-lg` | 16px | Cards, dialogs, sheets. |
+| `rounded-xl` | 20px | Hero surfaces. |
+| `rounded-full` | pill | Buttons (via --button-radius), avatars, pills, dots. |
+
+## Edges
+
+| Name | Value | Use |
+|---|---|---|
+| `border-border` | hairline | The default edge: inputs, cards, badges. |
+| `border-border-strong` | hairline, higher contrast | Structural rules: table grids, section separators. |
+| `border-border-floating` | faint, alpha | Every floating surface: popovers, menus, selects, tooltips, dialogs, sheets, toasts. Lighter than border; the shadow carries the elevation. |
+| `ring-2 ring-ring` | 2px focus ring | Focus only. Never a thick border. |
+
+## Rules
+
+1. **Nested corners are concentric: inner radius = outer radius − inset. Write it as rounded-concentric-<outer>/<inset>, not a hardcoded step.** A 12px popover with 4px padding takes 8px items. The utility computes the subtraction from the live tokens, so the pair stays concentric when a theme or the customizer rescales the radius ladder; a hardcoded rounded-sm drifts.
+2. **A list of rows inside a rounded popup uses popup-inset on the popup, rounded-popup-item on the rows and popup-bleed on a separator.** All three derive from the popup's radius: the inset grows to a third of it (never below --spacing(1), so density moves it too), the rows take what is left, and a separator bleeds by exactly the inset. A rounder look gets more room instead of rows that round into pills, and the default ladder still lands on the familiar 4px inset and 8px rows. *Enforced by sable-lint: popup-separator-bleed.*
+3. **A Button, Pill or Badge gets its look from a variant, never from override classes.** border, bg, rounded, ring and shadow classes on a component fight the variant's own hover, selected and focus states, and give one call site a look no other site can ask for. Use the variant that exists (Button variant="floating" over content, "on-color" on a fill; Pill appearance="outline"; Badge appearance and tone) or add one to the component. *Enforced by sable-lint: component-restyle.*
+4. **The outer radius is always at least the inner radius.** If the inset is larger than the outer radius, square the inner element or step the container up.
+5. **Never mix radii within one component.** A component reads as one object when its corners agree.
+6. **Actions are full; containers are tight.** The contrast itself says 'this is a control'. A theme flattens buttons through --button-radius, not by editing each one.
+7. **High-contrast outlines (selection, emphasis) are inset rings; hairline chrome is a border.** Rings anti-alias on rounded corners at any display scale; a 1px light border on dark snaps to the pixel grid and looks jagged.
+8. **One edge treatment per boundary: a border, a ring or a shadow.** Stacking all three makes an edge heavier than the content it holds.
+9. **Prefer a tonal step or space over a divider line.** The flattest thing that reads is best.
+
+## Never
+
+- **Never:** rounded-[10px] or any off-ladder radius. **Instead:** The ladder step for the role. Off-ladder radii cannot follow a theme or the customizer's radius control.
+- **Never:** A card inside a card with the same radius. **Instead:** Flatten the inner one, or use rounded-concentric-*. Nested surfaces with equal corners look misaligned at every corner.
+- **Never:** <Button className="rounded-full">, <Pill className="border bg-card">, a -mx-1 separator in a popup. **Instead:** The component's variant (add one if it is missing); popup-bleed for the separator. An override fights the component's own states and does not follow the radius ladder, the density or a theme. *Enforced by sable-lint: component-restyle, popup-separator-bleed.*
+- **Never:** border-2 for emphasis or focus. **Instead:** ring-2 ring-ring for focus; a tonal fill for emphasis. A thick border shifts layout and competes with the focus ring.
+
+## Details
+
+### Crisp selected outlines on dark surfaces
+
+```tsx
+// before
+<button className="rounded-lg border border-foreground">
+// after
+<button className="rounded-lg ring-[1.5px] ring-foreground ring-inset">
+```
+
+A 1px high-contrast border on a rounded corner snaps unevenly at fractional device-pixel ratios (Windows 125%/150%) and reads as jagged, worst light-on-dark. A box-shadow ring is anti-aliased instead, and inset keeps it from changing the element's size. Keep hairline borders for low-contrast chrome, where the snapping is invisible.
+
+### Concentric menu items
+
+```tsx
+// before
+<div className="rounded-md p-1"><div className="rounded-md">Item</div></div>
+// after
+<div className="rounded-md popup-inset"><div className="rounded-popup-item">Item</div></div>
+```
+
+12px outer − 4px inset = 8px inner at the default ladder, and the utilities keep the subtraction right when a preset or the customizer rescales the radius or the density.
+
+**Related:** `sable docs surfaces` · `sable docs spacing` · `sable token radii`

package/llms/foundations/spacing.md

@@ -0,0 +1,82 @@
+# Spacing & sizing
+
+One 4px scale governs every gap, inset and size, and space is assigned by role. Controls read a height ladder that a density scope can retune all at once.
+
+**4px base · 8px rhythm · 3 roles · 1 control ladder**
+
+## Spacing by role
+
+Steps below 2 (8px) are optical correction only.
+
+| Name | Value | Use |
+|---|---|---|
+| `Inset  p-4` | 16px | Padding inside a surface. p-3 for a dense card, px-3 py-2 for a row. |
+| `Stack, within a group  gap-1.5 – gap-2` | 6–8px | Label to field, title to description. |
+| `Stack, between groups  gap-4 – gap-6` | 16–24px | Field to field, card to card. |
+| `Stack, between sections  gap-12+` | 48px+ | Major regions of a page. |
+| `Inline  gap-2 – gap-3` | 8–12px | Icon to label, control to control. |
+
+## The control ladder
+
+Comfortable values; data-density="compact" (or <Density>) redefines every step for a region.
+
+| Name | Value | Use |
+|---|---|---|
+| `h-(--control-xs)` | 28px · compact 24 | Inline chips, tree rows. |
+| `h-(--control-sm)` | 32px · compact 28 | Compact buttons, toolbar controls. |
+| `h-(--control-md)` | 40px · compact 32 | The default: inputs, buttons, selects, menu triggers. |
+| `h-(--control-cta)` | 44px · compact 36 | The primary call to action; clears the touch floor on its own. |
+| `h-(--control-lg)` | 48px · compact 40 | Prominent or touch-first actions. |
+
+## Icons and touch
+
+| Name | Value | Use |
+|---|---|---|
+| `text-base (16px)` | sm | Inline with label-md / body-sm. |
+| `text-xl (20px)` | md · default | The default UI glyph beside label-lg. |
+| `hit-target` | 44×44px | Keeps a visually small control's hit area at the WCAG floor without moving layout. |
+
+## Rules
+
+1. **Every margin, padding and gap is a step on the 4px scale.** Off-scale values break the rhythm that lets adjacent components line up without coordination.
+2. **Padding, gaps and insets in a component sit on the spacing scale: a step (p-4, gap-2) or --spacing(n) inside an arbitrary value (p-[var(--card-p,--spacing(6))]).** The density (Character) control works by retuning --spacing, so anything on the scale moves with it. A literal p-[1.5rem] or padding: "12px" stays put while everything around it tightens. Keep fixed rem/px for what must not scale: a 1px hairline, a ring width. *Enforced by design-lint: fixed-spacing (library source).*
+3. **Related things sit closer than unrelated things.** Proximity groups content without a divider line. Use space first; reach for a border only when space is not enough.
+4. **Space lives on the container (gap), not on children (margins).** gap survives reordering, conditional children and RTL; per-child margins do not.
+5. **Control heights read the --control-* ladder.** A density scope retunes every control at once. A hardcoded height has to be found and overridden by hand. *Enforced by sable-lint: raw-control-height.*
+6. **Single-column content inside a card stacks with flex flex-col and a gap, not CSS grid.** A grid track sizes to its widest min-content child, so one long unbreakable string (a URL, a code line, a table) blows the column out past the card. A flex column lets children shrink to the card.
+7. **A compact surface drops one whole step; a spacious one adds one.** Moving in whole steps keeps density changes proportional.
+8. **Every interactive element clears a 44×44px hit area.** WCAG 2.5.5. Use padding or hit-target to grow the hit area; never a bigger glyph.
+9. **Borderless controls get roughly twice the gap of bordered ones.** A border declares where a control ends. Two ghost buttons 12px apart read as one target.
+
+## Never
+
+- **Never:** Arbitrary values: p-[15px], gap-[7px], mt-[13px]. **Instead:** The nearest scale step. Arbitrary values cannot follow density or a customized scale.
+- **Never:** h-[40px] on a control. **Instead:** h-(--control-md). It will not follow <Density>. *Enforced by sable-lint: raw-control-height.*
+- **Never:** Icons sized with type utilities (text-body-md on an <Icon>). **Instead:** text-{size} scale classes. Type utilities carry line-height and tracking that misalign glyphs.
+- **Never:** A fixed width sized to an English label. **Instead:** padding-inline and max-width with wrapping. German and Finnish run 30–50% longer.
+
+## Details
+
+### A dense region in one attribute
+
+```tsx
+// before
+<div className="[&_button]:h-8 [&_input]:h-8">…</div>
+// after
+<Density value="compact">…</Density>
+```
+
+Every control, menu and popup inside retunes, including portaled overlays.
+
+### Grouping by space
+
+```tsx
+// before
+<Separator /> between every field
+// after
+<Stack gap={3}> between groups (24px), <Stack gap={1}> inside a group (8px)
+```
+
+Two spacing steps do the work of every divider, with less ink. Stack's numeric gap counts --rhythm-unit — two spacing steps — so it follows the density control like every other spacing value.
+
+**Related:** `sable docs shape` · `sable docs typography` · `sable docs building-a-tool` · `sable token layout`

package/llms/foundations/surfaces.md

@@ -0,0 +1,69 @@
+# Surfaces & elevation
+
+Depth is a step up the surface ladder, chosen by how transient a surface is. Dark mode lifts with lighter tones and edge light; light mode adds soft shadows.
+
+**4 surface tokens · 5 elevation roles · 1 shadow per surface · 1 layer scale**
+
+## The surface ladder
+
+| Name | Value | Use |
+|---|---|---|
+| `bg-background` | the page | The document body; the furthest-back surface. |
+| `bg-card` | +1 step | Resting containers: cards, panels, dialogs. |
+| `bg-muted` | +1 step, quieter | Wells, code blocks, inactive fills inside a card. |
+| `bg-popover` | +2 steps | Anything that floats: menus, popovers, selects, tooltips. Always distinct from card, so a menu in a dialog never melts into it. |
+| `bg-overlay` | scrim | Behind modals, and pills over imagery. |
+
+## Elevation by role
+
+Raise by transience — how much a surface floats over content — not by importance.
+
+| Name | Value | Use |
+|---|---|---|
+| `Resting` | no shadow | Page content and flat cards. A hairline border if it needs an edge. |
+| `Raised  shadow-sm` | subtle | A draggable card, a sticky header over scrolled content. |
+| `Floating  shadow-md` | anchored | Menus, popovers, selects, dropdowns. |
+| `Modal  shadow-lg` | with scrim | Dialogs, sheets, the command menu. |
+| `Top  shadow-xl` | rare | The toast stack. |
+
+## Layers
+
+| Name | Value | Use |
+|---|---|---|
+| `z-(--z-sticky)` | 30 | Sticky in-content chrome: table headers. |
+| `z-(--z-nav)` | 40 | App chrome: header, sidebar, bottom nav. |
+| `z-(--z-overlay)` | 50 | Every portaled transient surface. |
+| `z-(--z-toast)` | 60 | Toasts, above modals. |
+| `z-(--z-skip-link)` | 100 | The skip link, above everything. |
+
+## Rules
+
+1. **Pick the elevation role, not a shadow value.** Elevation is a five-step system. A custom box-shadow cannot follow a theme or the light/dark split.
+2. **Floating surfaces use bg-popover, resting ones bg-card. Anything with shadow-md or above floats: menus, popovers, selects, tooltips, dialogs, sheets, toasts, a floating panel.** In dark mode popover is guaranteed lighter than card, so a menu opened inside a dialog always reads as on top of it. In light mode several presets make background, card and popover the same colour, so the fill alone never carries elevation. *Enforced by themes.test.ts + sable-lint: floating-surface.*
+3. **A floating surface's edge is border-border-floating (or ring-border-floating), never the full border-border. The shadow carries the elevation.** A full hairline plus a shadow stacks into a heavy dark outline. border-floating is a faint alpha edge: it defines the shape against a same-coloured page in light mode and reads as a lit edge in dark mode, where shadows barely show. *Enforced by sable-lint: floating-surface.*
+4. **A recessed area inside a surface (a segmented-control track, a pad, a preview well) is sable-well, and it takes no outline. Whatever sits on the well takes the surface's own colour back (bg-popover inside a popover).** sable-well mixes a fixed amount of ink into the surface it sits in, so it is the same visible step on the page, in a card or in a floating panel, in every theme and mode. A fixed bg-muted can nearly vanish inside a popover in dark mode, and adding an outline to every well to compensate stacks a panel into boxes.
+5. **One shadow per surface; never a heavy shadow with a heavy border.** Stacked depth cues read as decoration rather than position.
+6. **Do not elevate a static section to make it stand out.** Elevation means 'this floats'. Use a tonal step or space for emphasis.
+7. **For modals, the scrim is the primary depth cue.** The scrim is what tells the user the page behind is inert; the shadow is secondary.
+8. **Stack with the named layer scale.** Overlays portal to the end of body and order themselves by open order; the layer only has to clear in-flow chrome.
+
+## Never
+
+- **Never:** z-[9999] or any raw z-index. **Instead:** z-(--z-overlay) and the other named layers. Raw z-indexes become a bidding war that a future overlay always loses. *Enforced by sable-lint: raw-z-index.*
+- **Never:** shadow-[0_8px_30px_rgba(0,0,0,.2)] or any custom shadow. **Instead:** shadow-sm … shadow-xl by role. Custom shadows ignore the theme's light/dark elevation recipes.
+- **Never:** bg-card on a popover, or bg-popover on a resting card. **Instead:** Match the token to the role. Swapping them is how floating surfaces melt into the surface beneath.
+
+## Details
+
+### A menu inside a dialog
+
+```tsx
+// before
+Dialog bg-card · Menu bg-card — identical in dark mode
+// after
+Dialog bg-card · Menu bg-popover — one step lighter, plus edge light
+```
+
+The menu reads as above the dialog without any prop.
+
+**Related:** `sable docs shape` · `sable docs token-intent`

package/llms/foundations/typography.md

@@ -0,0 +1,120 @@
+# Typography
+
+Type is a closed vocabulary of paired utilities. Each one bundles size, weight, line-height and tracking, and is picked by role rather than by size.
+
+**6 families · 8 everyday tiers · 2 text colors · 1 utility per text node**
+
+## The everyday set
+
+Product UI is built almost entirely from these eight. Reach outside them on purpose.
+
+| Name | Value | Use |
+|---|---|---|
+| `text-heading-1` | 36px · 600 | The page title. Exactly one per route. |
+| `text-heading-2` | 28px · 600 | A major section of the page. |
+| `text-title-lg` | 16px · 600 | Names a component: card, dialog, sheet, list row. |
+| `text-title-sm` | 14px · 600 | Names a dense component: compact card, table section. |
+| `text-body-md` | 15px · 400 | The default paragraph, description and help text. |
+| `text-body-sm` | 13px · 400 | Secondary copy and table cells. |
+| `text-label-lg` | 14px · 600 | Buttons, field labels, tabs. |
+| `text-caption` | 12px · 400 | Timestamps, footnotes, meta rows. |
+
+## The six families
+
+Every tier belongs to one family, and the family is the decision. Size follows from it.
+
+| Name | Value | Use |
+|---|---|---|
+| `Display  display-lg…4xl` | 48–120px · 700–800 | Type as image: landing heroes, campaign numbers. Never in product chrome; never two per view. |
+| `Heading  heading-1…4` | 36 / 28 / 22 / 18px · 600 | The document outline (h1–h4). Keep the order; never skip a level to get a size. |
+| `Title  title-lg · title-sm` | 16 / 14px · 600 | Names a UI part without claiming a document heading. |
+| `Body  body-lg/md/sm/xs` | 17 / 15 / 13 / 12px · 400 | Reading text. -lg is the lede (carries text-wrap: pretty); -xs is a dense-UI floor, not a prose size. |
+| `Label  label-lg/md/sm · caption` | 14 / 12 / 11px · 600; caption 12 · 400 | Functional, scannable text of one to three words. Caption is also the group-label tier: nav sections, menu groups. |
+| `Mono  mono-xl/lg/md/caption/sm` | 28 / 20 / 13 / 12 / 11px · tabular | Numbers that are the content, IDs, hashes, code, aligned figures. |
+
+## Text color
+
+| Name | Value | Use |
+|---|---|---|
+| `text-foreground` | full contrast | Primary text: headings, body, values. |
+| `text-muted-foreground` | secondary contrast (AA on every surface) | Supporting text: descriptions, captions, meta, placeholders. |
+
+## Rules
+
+1. **One paired utility per text node. Compose it with a color and margin only.** Each utility is a tuned set of size, weight, leading and tracking. Splitting it into text-* + font-* + tracking-* breaks the tuning and every theme override of it. *Enforced by sable-lint: decomposed-type.*
+2. **Pick the tier by role, not by the size it renders at.** A card title is title-lg even when body-lg is the same size: role fixes the weight (600 vs 400) and the rhythm around it.
+3. **Two text colors: foreground and muted-foreground.** Both are contrast-tested against every surface in every theme. A third grey, or an opacity step, is untested contrast.
+4. **One heading-1 per route; headings descend without skipping levels.** The heading outline is how screen-reader users navigate a page. Restyle with a tier rather than jumping a level for its size.
+5. **Hierarchy comes from a clear jump (heading → title → body), then weight and space, before size.** Two sizes one step apart read as the same level. Space and weight separate levels more cheaply than another size.
+6. **Cap reading text at --measure-prose (65ch).** Past roughly 75 characters the eye loses the line return. A wide region can still hold a 65ch column.
+7. **Numbers that must align use a mono tier (tabular figures).** Proportional digits change width as values update, so totals and columns shimmy.
+8. **text-wrap: balance on headings, pretty on ledes, neither on long prose.** balance evens short headlines; pretty only refuses a one-word last line. Both cost layout work that long prose does not repay.
+9. **A mark attached to a line of type (a dot, a bullet, a timeline marker, a leading icon) sits in a box one line tall (h-[1lh] items-center) and is sized in em.** 1lh is the line-height of the text beside it, so the mark centres on that line in every tier, density and theme. A px size with a mt-[3px] nudge is right for one font at one size and wrong everywhere else.
+
+## Never
+
+- **Never:** Opacity on text (text-foreground/60, opacity-70 on a paragraph). **Instead:** text-muted-foreground. An alpha step over an unknown surface has unknown contrast, and it shifts per theme. *Enforced by sable-lint: text-opacity.*
+- **Never:** A hand-picked size, weight or tracking (text-[15px], font-medium, tracking-wide). **Instead:** The paired utility for the role. Off-vocabulary type cannot be retuned by a theme or the customizer, so it drifts the moment either changes. *Enforced by sable-lint: decomposed-type.*
+- **Never:** Uppercase in product chrome: nav and menu group labels, page eyebrows, table headers, section titles. **Instead:** Sentence-case text-caption or text-label-md in muted-foreground; hierarchy from size, weight and space. Tracked capitals spread across a UI read as shouting and slow word recognition. The eyebrow tier (label-xs / overline) is an editorial accent: at most one per marketing view.
+- **Never:** Display tiers inside product UI, or two display sizes in one view. **Instead:** heading-1 for a page title; mono-xl for a metric. Display is type as image. In chrome it competes with the content it is supposed to frame.
+- **Never:** Justified text, or reading copy below body-sm. **Instead:** Ragged-right at body-md; body-xs only for dense data. Justification opens rivers on the web, which has no hyphenation control; 12px prose fails people with low vision.
+- **Never:** A new font family, or raw font-feature-settings / font-variation-settings. **Instead:** The theme's sans, mono and optional display; font-variant-numeric and font-weight. Raw axis tags silently do nothing on a fallback font, and every theme declares a fallback stack.
+
+## Details
+
+### Steady numbers
+
+```tsx
+// before
+<span className="text-body-md">{price}</span>
+// after
+<span className="text-mono-md">{price}</span>
+```
+
+Mono tiers set tabular-nums, so a ticking value stops nudging its neighbors sideways.
+
+### Optically centred labels
+
+```tsx
+// before
+<button className="h-(--control-md) px-4 items-center">Save</button>
+// after
+<Button>Save</Button>  {/* label wrapped in .sable-label-trim */}
+```
+
+text-box: trim-both cap alphabetic centres the cap-height band the eye reads, not the line box. Measured: Helvetica otherwise sits a full 1px high on a 40px control.
+
+### A marker centred on its line
+
+```tsx
+// before
+<span className="mt-[5px] size-2 rounded-full bg-primary" />
+// after
+<span className="flex h-[1lh] items-center"><span className="size-[0.5em] rounded-full bg-primary" /></span>
+```
+
+The wrapper is exactly one line of the adjacent text tall, so the dot centres on the first line whatever the tier; em sizing keeps it in proportion when the type scales. Stepper indicator="dot" is built this way.
+
+### Balanced headings
+
+```tsx
+// before
+<h2 className="text-heading-2">Ship faster with fewer review rounds</h2>
+// after
+<h2 className="text-heading-2 text-balance">Ship faster with fewer review rounds</h2>
+```
+
+Evens line lengths so a two-line heading does not end on a single orphaned word.
+
+### Secondary text without opacity
+
+```tsx
+// before
+<p className="text-foreground/60">Updated 2m ago</p>
+// after
+<p className="text-caption text-muted-foreground">Updated 2m ago</p>
+```
+
+muted-foreground is contrast-tested on every surface; a 60% alpha is not.
+
+**Related:** `sable docs spacing` · `sable docs accessibility` · `sable token typography` · `sable token typographyOverrides`

package/llms/layout/aspect-box.md

@@ -0,0 +1,37 @@
+# AspectBox
+
+**Status:** stable
+
+Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds.
+
+**Keywords:** aspect box, aspect ratio, media, layout shift
+
+## Usage
+
+Use AspectBox to reserve stable aspect-ratio space for async media, embeds, and responsive previews.
+
+### Best practices
+
+- Do: Use it around images, video, and embeds that should not shift layout while loading.
+- Do: Match the ratio to the expected media or design slot.
+- Don't: Do not use AspectBox for content whose height should grow with text or controls.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ratio | number | 16/9 | Width / height ratio (e.g. 1 for square, 4/5 for portrait). |
+
+## Related
+
+- Components: Video, Dialog, Browser
+
+## Examples
+
+### Cover image slot
+
+```tsx
+import { AspectBox } from "@sableui/react"
+
+<AspectBox ratio={16 / 9}><img src={post.coverUrl} alt={post.title} className="size-full object-cover" /></AspectBox>
+```

package/llms/layout/bleed.md

@@ -0,0 +1,31 @@
+# Bleed
+
+**Status:** stable
+
+Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page.
+
+**Keywords:** bleed, full bleed, media band, layout
+
+## Usage
+
+Use Bleed to let a band or media element escape an inset or width-capped ancestor while staying within the content area.
+
+### Best practices
+
+- Do: Use it for hero bands, profile covers, or media that should align beyond a capped page column.
+- Do: Keep surrounding content inside Region or Page so the bleed remains intentional.
+- Don't: Do not use Bleed to place content under fixed app chrome or sidebars.
+
+## Related
+
+- Components: Page, Region, AspectBox
+
+## Examples
+
+### Full-bleed hero inside a capped page
+
+```tsx
+import { AspectBox, Bleed, Page, PageHeader } from "@sableui/react"
+
+<Page max="feed"><Bleed><AspectBox ratio={3}><img src="/cover.jpg" alt="" className="size-full object-cover" /></AspectBox></Bleed><PageHeader title="Profile" /></Page>
+```

package/llms/layout/center.md

@@ -0,0 +1,37 @@
+# Center
+
+**Status:** stable
+
+Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout).
+
+**Keywords:** center, measure, reading width, layout
+
+## Usage
+
+Use Center to center a block and optionally cap its width inside a wider layout.
+
+### Best practices
+
+- Do: Use it for reading columns, forms, or compact content inside a broad Region.
+- Do: Choose a named max when the content role matches Sable's measure tokens.
+- Don't: Do not use Center for full page inset or app chrome; use Region or AppShell.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| max | "prose" \| "form" \| "feed" \| "content" \| "wide" \| CSS length | — | Cap width: a named region token or any raw CSS length. |
+
+## Related
+
+- Components: Region, Page, Stack
+
+## Examples
+
+### Reading column in a wide page
+
+```tsx
+import { Center } from "@sableui/react"
+
+<Center max="prose"><p className="text-body-lg">Long-form description text that should hold a comfortable reading measure even inside a wide dashboard region.</p></Center>
+```

package/llms/layout/columns.md

@@ -0,0 +1,51 @@
+# Columns
+
+**Status:** stable
+
+An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth.
+
+**Keywords:** columns, 12 column, span, layout
+
+## Usage
+
+Use Columns and Col for proportioned layouts that need explicit spans, such as list-detail or asymmetric panes.
+
+### Best practices
+
+- Do: Use breakpoint span maps when the same layout needs to collapse cleanly on smaller screens.
+- Do: Use Columns for proportional composition, not for uniform card wrapping.
+- Don't: Do not use column spans as a replacement for Region width or text measure.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Columns | yes | The explicit column track container. |
+| Col | yes | A child cell with span and optional start placement. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| Col | span?: number \| breakpoint map · start?: number \| breakpoint map | A cell in the track: columns to span (default 1) and optional 1-based start column. Both accept breakpoint maps ({ base: 12, lg: 8 }). |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| count | number \| breakpoint map | 12 | Columns in the track; a breakpoint map ({ base: 2, md: 6, lg: 12 }) thins the track on small screens. |
+| gap | number \| string | var(--grid-gutter) | Gap between columns and rows. Number = rhythm units (×8px); string = raw CSS. The column gap is capped so all gaps together never take more than 75% of the track's width — a large gap can't push a narrow screen into horizontal scroll, and at normal desktop widths it renders exactly as given. The row gap is never capped. |
+
+## Related
+
+- Components: Grid, SplitPane, Region
+
+## Examples
+
+### List-detail (8/4)
+
+```tsx
+import { Card, CardHeader, CardTitle, Col, Columns } from "@sableui/react"
+
+<Columns count={12}><Col span={{ base: 12, lg: 8 }}><Card><CardHeader><CardTitle>Posts</CardTitle></CardHeader></Card></Col><Col span={{ base: 12, lg: 4 }}><Card variant="flat"><CardHeader><CardTitle>Filters</CardTitle></CardHeader></Card></Col></Columns>
+```

package/llms/layout/grid-overlay.md

@@ -0,0 +1,40 @@
+# GridOverlay
+
+**Status:** stable
+
+Dev/docs structure visualizer — overlays the column grid so the layout skeleton is legible. Place inside a position:relative container; never ships in product UI.
+
+**Keywords:** grid overlay, debug, layout visualizer, docs
+
+## Usage
+
+Use GridOverlay only as a development or documentation visualizer for the column structure.
+
+### Best practices
+
+- Do: Use it inside a position-relative layout while debugging alignment.
+- Do: Keep it gated behind docs, debug, or development-only state.
+- Don't: Do not ship GridOverlay as visible product UI.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| columns | number | 12 | Number of column bands. |
+| gap | string | var(--grid-gutter) | Gap between bands. |
+| inset | boolean | true | Align bands to the fluid page inset. |
+| show | boolean | true | Toggle visibility. |
+
+## Related
+
+- Components: Grid, Columns, Region
+
+## Examples
+
+### Debugging a layout
+
+```tsx
+import { Card, CardContent, Col, Columns, GridOverlay } from "@sableui/react"
+
+<div className="relative"><GridOverlay show={debug} /><Columns count={12}><Col span={8}><Card><CardContent><p className="text-body-md">Main</p></CardContent></Card></Col><Col span={4}><Card><CardContent><p className="text-body-md">Rail</p></CardContent></Card></Col></Columns></div>
+```

package/llms/layout/grid.md

@@ -0,0 +1,47 @@
+# Grid
+
+**Status:** stable
+
+CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth auto-fit so cells breathe with NO breakpoints (the default choice for card grids).
+
+**Keywords:** grid, card grid, auto fit, layout
+
+## Usage
+
+Use Grid for uniform grid layouts inside a Region, especially card grids that can breathe responsively.
+
+### Best practices
+
+- Do: Prefer minItemWidth for responsive card grids that do not need breakpoint-specific spans.
+- Do: Use explicit columns only when the design truly needs a fixed track count.
+- Don't: Do not use Grid to set a page's reading width; use Region or Center.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| cols | number \| { base?, sm?, md?, lg?, xl?, "2xl"? } | 12 | Fixed column count or a mobile-first breakpoint map ({ base: 2, md: 4 }). Ignored when minItemWidth is set. |
+| minItemWidth | string | — | Auto-fit mode: repeat(auto-fit, minmax(minItemWidth, 1fr)) — the grid grows/wraps responsively without breakpoints. e.g. "16rem". |
+| gap | number \| string | var(--grid-gutter) | Gap between cells. Number = rhythm units (×8px); string = raw CSS. |
+
+## Related
+
+- Components: Region, Columns, Card
+
+## Examples
+
+### Card grid that breathes (no breakpoints)
+
+```tsx
+import { Card, CardHeader, CardTitle, Grid } from "@sableui/react"
+
+<Grid minItemWidth="16rem" gap={3}><Card><CardHeader><CardTitle>Alpha</CardTitle></CardHeader></Card><Card><CardHeader><CardTitle>Beta</CardTitle></CardHeader></Card><Card><CardHeader><CardTitle>Gamma</CardTitle></CardHeader></Card></Grid>
+```
+
+### Responsive fixed columns
+
+```tsx
+import { Badge, Grid } from "@sableui/react"
+
+<Grid cols={{ base: 1, md: 2, lg: 4 }}><Badge appearance="plain" tone="standard" dot /><Badge appearance="plain" tone="warning" dot /><Badge appearance="plain" tone="neutral" dot /><Badge appearance="plain" tone="destructive" dot /></Grid>
+```

package/llms/layout/page.md

@@ -0,0 +1,39 @@
+# Page
+
+**Status:** stable
+
+A route shell: Region (inset + opt-in max cap) whose children flow as a vertically-rhythmic Stack. Use as the top-level wrapper of a route's content — distinct from AppShell (the frame around routes) and PageHeader (the heading block inside).
+
+**Keywords:** page, route shell, region, stack
+
+## Usage
+
+Use Page as a route content shell that combines Region sizing with vertical rhythm.
+
+### Best practices
+
+- Do: Use it as the top-level wrapper for route content after application chrome.
+- Do: Set max by the page's content role rather than by the current viewport.
+- Don't: Do not confuse Page with AppShell; Page is content, AppShell is the frame around routes.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| gap | number \| string | 4 | Vertical gap between stacked page sections. Number = rhythm units (×8px, so 4 = 32px); string = raw CSS. |
+| align | "start" \| "center" \| "end" \| "stretch" | "stretch" | Cross-axis alignment of the stacked sections. |
+| …RegionProps | as, inset, max, bleed, safeArea | — | All Region props pass through (Page IS a Region). |
+
+## Related
+
+- Components: Region, Stack, PageHeader, AppShell
+
+## Examples
+
+### Feed route
+
+```tsx
+import { Card, CardContent, Page, PageHeader } from "@sableui/react"
+
+<Page as="main" max="feed"><PageHeader title="Home" description="Latest posts from artists you follow." /><Card><CardContent><p className="text-body-md">First post.</p></CardContent></Card></Page>
+```