@sableui/react 0.17.0 → 0.18.0

package/llms/components/pill.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-A chip someone clicks: a filter, a tag choice, an option in a row. Always a button with aria-pressed. appearance="solid" (filters; selected lifts onto the primary surface) or "outline" (quiet chips that annotate content, like reactions); size md or sm. A static label is a Badge.
+A chip someone clicks: a filter, a tag choice, an option in a row. Always a button with aria-pressed. appearance="solid" (filters; selected lifts onto the primary surface) or "outline" (quiet chips that annotate content, like reactions); size lg, md or sm. A static label is a Badge.
 
 **Keywords:** pill, chip, filter, tag, toggle chip, category
 
@@ -14,9 +14,10 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 
 - Do: Use short text that names the filter or choice.
 - Do: Reflect the current choice with selected, so the active filter reads at a glance.
+- Do: In a toolbar where filter chips share a row with a search field ("All 8 · Products 5 · Open source 2 … [Find a project]"), pair Pill size="lg" with SearchInput size="sm", and Button size="sm" for any action beside them. All three stand on --control-sm (32px, 28 compact), the rung the spacing doctrine gives toolbar controls, so the row is one height in either density. Pill md (28px) has no text field of its height in the page register, so md beside a field always reads as a mismatch.
 - Don't: Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row — that is a Badge. → use **Badge**
 - Don't: Do not use Pill for primary actions or important system status.
-- Don't: Do not restyle a Pill with border or background classes to get a quieter chip. That is appearance="outline" (and size="sm" for a small one); an override is a look that exists nowhere else in the system.
+- Don't: Do not restyle a Pill with border or background classes to get a quieter chip. That is appearance="outline" (and size="sm" for a small one); an override is a look that exists nowhere else in the system. Likewise never set h-* on a Pill to match a neighbour: pick the size that shares its rung.
 
 ## Props
 
@@ -24,14 +25,14 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 | --- | --- | --- | --- |
 | selected | boolean | false | Marks the pill as chosen. Solid lifts onto the primary surface; outline takes a primary tint and soft primary edge. Sets aria-pressed. |
 | appearance | "solid" \| "outline" | "solid" | solid for a filter row; outline for quiet chips that annotate other content (a reaction under a message, a tag on a card), where a filled chip would compete with what it annotates. |
-| size | "md" \| "sm" | "md" | md sits on the density ladder's xs control height (28px); sm is 24px, for chips under or inside other content. |
+| size | "lg" \| "md" \| "sm" | "md" | lg sits on --control-sm (32px, 28 compact), the toolbar rung it shares with SearchInput sm and Button sm, for a filter row beside a search field. md sits on --control-xs (28px, 24 compact), the chip in a row of its own or among content. sm is a fixed 24px (the target floor, which density does not shrink), for chips under or inside other content. |
 | tone | "neutral" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" | "neutral" | neutral is the chip as described. A palette family colours it as a category, like the choices in a tag picker: a wash at rest, the solid family colour when selected. Painted from the theme's generated palette. |
 | icon | ReactNode | — | Optional leading glyph (e.g. <Icon name="lock" />), rendered before the children with the base gap. |
 
 ## Variants
 
 - **appearance**: solid, outline
-- **size**: md, sm
+- **size**: lg, md, sm
 - **selected**: true, false
 - **tone**: neutral, red, orange, yellow, green, teal, blue, purple, pink
 
@@ -54,7 +55,7 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 
 ## Related
 
-- Components: Badge, ToggleGroup
+- Components: Badge, ToggleGroup, SearchInput
 
 ## Examples
 
@@ -74,6 +75,24 @@ import { Pill, Row } from "@sableui/react"
 <Row gap={1}><Pill selected onClick={() => {}}>All</Pill><Pill onClick={() => {}}>Projects</Pill><Pill onClick={() => {}}>Reports</Pill></Row>
 ```
 
+### Filters with search
+
+```tsx
+import { Pill, Row, SearchInput } from "@sableui/react"
+
+const [filter, setFilter] = useState("all")
+const [q, setQ] = useState("")
+
+<Row gap={2} align="center" justify="between" wrap>
+	<Row gap={1}>
+		<Pill size="lg" selected={filter === "all"} onClick={() => setFilter("all")}>All 8</Pill>
+		<Pill size="lg" selected={filter === "products"} onClick={() => setFilter("products")}>Products 5</Pill>
+		<Pill size="lg" selected={filter === "oss"} onClick={() => setFilter("oss")}>Open source 2</Pill>
+	</Row>
+	<SearchInput size="sm" value={q} onValueChange={setQ} placeholder="Find a project…" aria-label="Find a project" className="max-w-64" />
+</Row>
+```
+
 ### Outline, small (reactions)
 
 ```tsx

package/llms/components/search-input.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value.
+Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value. size md (form), sm (toolbar, matching Pill lg and Button sm) or xs (inset tool-panel field).
 
 **Keywords:** search, input, filter, query
 
@@ -16,6 +16,8 @@ Use SearchInput for text queries that filter or search a known content set.
 - Do: Provide a visible clear affordance when query state persists.
 - Do: When a button stands in for search (a header trigger that opens CommandMenu with ⌘K), use CommandMenuTrigger. It wears this field's shell from the same source, so the two cannot drift; a hand-styled button already did once, into a borderless chip that matched neither the field nor a button.
 - Do: Light the query in the results it filters with `useMatchHighlight(query)` — a callback ref for the results container, with `selector` to keep it to titles. It paints on the `highlight` pair without wrapping matches in `<mark>`, the same paint Combobox and CommandMenu use for their rows.
+- Do: In a toolbar beside filter chips, use size="sm" with Pill size="lg" (and Button size="sm" for actions). All three stand on --control-sm (32px, 28 compact), the rung the spacing doctrine gives toolbar controls, so the row is one height in either density. Keep md for a search field in a form or a page header beside md buttons, and xs for a filter inside a workspace panel, where it matches Input xs's inset surface.
+- Don't: Do not match a neighbour's height with h-* on className or inputClassName. The magnifier, padding and clear button would stay sized for the old rung; pick the size that shares the neighbour's rung.
 - Don't: Do not use SearchInput as a command palette; use CommandMenu for global commands, opened from the header by CommandMenuTrigger. A SearchInput that opens a dialog on focus is a text box you cannot type in.
 - Don't: Do not search on every keystroke against an expensive backend without debouncing. The user sees results flicker and reorder under them, and you send a request per character.
 
@@ -23,6 +25,7 @@ Use SearchInput for text queries that filter or search a known content set.
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
+| size | "md" \| "sm" \| "xs" | "md" | The rung of the control ladder, named as on Input, Select and Combobox. md is the form field (--control-md, 40px / 32 compact). sm is the toolbar field (--control-sm, 32px / 28 compact), the rung Pill lg and Button sm share, so filters + search + actions in one row are one height. xs is the tool-panel field (--control-xs, 28px / 24 compact) on Input xs's inset panel-field surface. The magnifier, inline padding and clear button scale with the rung and stay vertically centred. |
 | value | string | — | Controlled value of the search field. |
 | defaultValue | string | — | Uncontrolled initial value. The field tracks its own text, so the clear button still appears and empties it. |
 | className | string | — | Sizes and places the whole field — magnifier, input and clear button together (e.g. max-w-80). A width cap here keeps the clear button inside the field. |
@@ -31,11 +34,11 @@ Use SearchInput for text queries that filter or search a known content set.
 | onClear | () => void | — | Called when the clear button is pressed. The component also fires onValueChange('') so a controlled value resets. |
 | placeholder | string | "Search" | Placeholder text shown when the field is empty. |
 | disabled | boolean | false | Dims the control and blocks pointer interaction. |
-| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (name, autoFocus, ref, aria-invalid, …) pass through to the <input> except value/onChange, which are owned by value/onValueChange, and className, which sizes the whole field. |
+| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (name, autoFocus, ref, aria-invalid, …) pass through to the <input> except value/onChange, which are owned by value/onValueChange, className, which sizes the whole field, and the native numeric size attribute, which the size prop replaces. |
 
 ## Tokens used
 
-`field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`
+`field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`, `panel-field`, `panel-field-hover`
 
 ## Motion
 
@@ -54,7 +57,7 @@ Use SearchInput for text queries that filter or search a known content set.
 
 ## Related
 
-- Components: Input, CommandMenu, Combobox
+- Components: Input, CommandMenu, Combobox, Pill
 
 ## Examples
 
@@ -100,6 +103,36 @@ const shown = posts.filter((post) => post.title.toLowerCase().includes(q.trim().
 </ul>
 ```
 
+### Filters with search
+
+```tsx
+import { Pill, Row, SearchInput } from "@sableui/react"
+
+const [filter, setFilter] = useState("all")
+const [q, setQ] = useState("")
+
+<Row gap={2} align="center" justify="between" wrap>
+	<Row gap={1}>
+		<Pill size="lg" selected={filter === "all"} onClick={() => setFilter("all")}>All 8</Pill>
+		<Pill size="lg" selected={filter === "products"} onClick={() => setFilter("products")}>Products 5</Pill>
+		<Pill size="lg" selected={filter === "oss"} onClick={() => setFilter("oss")}>Open source 2</Pill>
+	</Row>
+	<SearchInput size="sm" value={q} onValueChange={setQ} placeholder="Find a project…" aria-label="Find a project" className="max-w-64" />
+</Row>
+```
+
+### Sizes
+
+```tsx
+import { SearchInput, Stack } from "@sableui/react"
+
+<Stack gap={1}>
+	<SearchInput size="md" placeholder="Search posts" aria-label="Search posts" />
+	<SearchInput size="sm" placeholder="Find a project…" aria-label="Find a project" />
+	<SearchInput size="xs" placeholder="Filter layers" aria-label="Filter layers" />
+</Stack>
+```
+
 ### Disabled
 
 ```tsx

package/llms/components/section-header.md

@@ -4,7 +4,7 @@
 
 The heading block for one section of a page: a title (h2 by default), an optional line of description, and actions on the title row — a "View all" link or a couple of buttons — that drop beneath the title only when the row runs out of room.
 
-**Keywords:** section header, section heading, section title, shelf, view all, see all, show all, h2, subsection, optical alignment, bleed
+**Keywords:** section header, section heading, section title, shelf, view all, see all, show all, h2, subsection, optical alignment, bleed, editorial section, large section title
 
 ## Usage
 
@@ -13,7 +13,7 @@ Use SectionHeader to head each section below the page title — a home-page shel
 ### Best practices
 
 - Do: Wrap the header and its content in a `<section aria-labelledby={titleId}>` (a flex column with a gap, or a Stack inside it) so the section is a named region and the header's title is its name.
-- Do: Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: md for a page's sections and shelves, sm for denser groups like settings.
+- Do: Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: lg for an editorial page's sections under a PageHeader size="lg", md for a page's sections and shelves, sm for denser groups like settings.
 - Do: Keep actions to one or two `size="sm"` buttons — the title is centred on that height. A shelf's "View all" is a ghost Button rendered as a link (`render={<a href=… />}`), named for what it opens when the label alone is ambiguous (aria-label="View all new releases").
 - Do: Pass a ghost or link action as a plain Button and let the header align it: the last direct child bleeds by its own padding at the end, so "View all" sits on the edge of the grid below, and the first bleeds at the start, which is the edge once the actions wrap beneath the title. Filled buttons keep their edge on the line. Set bleed="none" on the Button to opt one out.
 - Don't: Nudge a View all onto the edge with -me-3, or wrap the actions in your own div: the header aligns direct children only, and only by each button's real padding. If you must wrap them, set bleed on the Button inside instead.
@@ -38,11 +38,11 @@ Use SectionHeader to head each section below the page title — a home-page shel
 | actions | ReactNode | — | Trailing actions on the title row — a View all link or a couple of buttons, size="sm". They stay on the title's row and drop beneath it only when the row runs out of room; the title wraps rather than truncating. A ghost or link Button that ends the group bleeds by its padding at the end (and one that starts it, at the start — the edge once wrapped), so its label lines up with the content below; Button bleed="none" opts out. Direct children only. |
 | titleAs | "h2" \| "h3" \| "h4" | "h2" | The heading element, chosen by the document outline: h2 for a section under the page's h1, h3 for a subsection inside one. |
 | titleId | string | — | The title's id, so the section it heads can point at it: <section aria-labelledby={titleId}>. Generated when omitted. |
-| size | "md" \| "sm" | "md" | Visual weight, independent of the heading level: md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets — settings groups, subsections. |
+| size | "lg" \| "md" \| "sm" | "md" | Visual weight, independent of the heading level: lg (text-heading-2 over a text-body-md description) for an editorial page's sections, under a PageHeader size="lg"; md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets — settings groups, subsections. lg stops at heading-2: heading-1 is the page title's, one per route. The actions stay centred on the title's first line at every size. |
 
 ## Variants
 
-- **size**: md, sm
+- **size**: lg, md, sm
 
 ## Tokens used
 
@@ -135,6 +135,30 @@ import { Button, Entity, Icon, SectionHeader, Stack } from "@sableui/react"
 </section>
 ```
 
+### An editorial section (size lg)
+
+```tsx
+import { Button, Card, CardDescription, CardHeader, CardTitle, Grid, SectionHeader } from "@sableui/react"
+
+<section aria-labelledby="selected-work" className="flex flex-col gap-6">
+	<SectionHeader
+		titleId="selected-work"
+		size="lg"
+		title="Selected work"
+		description="Five projects from the last two years."
+		actions={
+			<Button variant="ghost" size="sm" render={<a href="/work" />} aria-label="View all work">
+				View all
+			</Button>
+		}
+	/>
+	<Grid minItemWidth="16rem" gap={3}>
+		<Card><CardHeader><CardTitle>Tidewater</CardTitle><CardDescription>Brand identity</CardDescription></CardHeader></Card>
+		<Card><CardHeader><CardTitle>Northlight</CardTitle><CardDescription>Product design</CardDescription></CardHeader></Card>
+	</Grid>
+</section>
+```
+
 ### A subsection inside a section
 
 ```tsx

package/llms/components/sheet.md

@@ -48,7 +48,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. |
+| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. Records the element focused when the sheet opens, trigger or not, and returns focus there on close. |
 | snapPoints | (number \| string)[] | — | Stops a bottom sheet rests at, smallest first: a fraction of the viewport (0.4), pixels (320), or a px/rem string ("20rem"). The panel is the full stop's height and opens at the first stop; a swipe moves between stops and a swipe below the first closes it. side="bottom" only: other sides ignore them, with a development warning. |
 | snapPoint | number \| string \| null | — | The active stop, controlled. Pair with onSnapPointChange; use defaultSnapPoint to open at a different stop uncontrolled. |
 | onSnapPointChange | (snapPoint: number \| string \| null, eventDetails) => void | — | Fires when a swipe (or your code) moves the sheet to another stop. |
@@ -68,7 +68,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 - The panel scrolls its own content (thin scrollbar, contained overscroll) when it outgrows its bound — the full height on left/right, 80vh on top/bottom.
 - Esc and click-outside dismiss by default; on touch, a swipe toward the sheet's own edge dismisses too. A short or slow drag springs back.
 - Swipe is an extra path, never the only one: Esc, click-outside and SheetClose all still work.
-- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down); focus returns to the trigger on close.
+- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down). On close, focus returns to the element that held it when the sheet opened: the SheetTrigger, or your own button when it drives a controlled open. It is captured before the content mounts, so an autoFocus field inside cannot displace it; an explicit finalFocus on SheetContent wins.
 - Render a SheetClose inside SheetContent so screen-reader users can escape the popup.
 - Slide animation runs via data-[starting-style]/data-[ending-style] attributes on the motion-duration token; while swiping the panel tracks the finger directly, and a released swipe finishes on the same token (scaled by flick speed), so reduced motion makes it instant.
 - A mouse drag that starts on sheet content selects text rather than dragging the panel; mouse dragging only starts from the padding edge.

package/llms/layout/aspect-box.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds.
+Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds. The ratio is a class reading a CSS variable, so className reshapes it at a breakpoint (md:aspect-video).
 
 **Keywords:** aspect box, aspect ratio, media, layout shift
 

package/llms/layout/bleed.md

@@ -2,7 +2,7 @@
 
 **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.
+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. Width and margins are classes, so a breakpoint can turn the bleed off (lg:mx-0 lg:w-auto).
 
 **Keywords:** bleed, full bleed, media band, layout
 

package/llms/layout/center.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout).
+Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout). Centering and cap are classes, so className overrides them at a breakpoint.
 
 **Keywords:** center, measure, reading width, layout
 

package/llms/layout/columns.md

@@ -2,7 +2,7 @@
 
 **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.
+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. display is the grid class, so hidden md:grid works; a gap-* utility replaces both gaps and the column-gap cap.
 
 **Keywords:** columns, 12 column, span, layout
 

package/llms/layout/grid.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row.
+CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row. display is the grid class and the gap a CSS variable, so className utilities win at any breakpoint (hidden md:grid, md:gap-6, lg:grid-cols-3).
 
 **Keywords:** grid, card grid, auto fit, layout
 

package/llms/layout/region.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route.
+The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route. The inset and cap are classes (px-(--page-inset), max-w-…), so className overrides them at a breakpoint (max-sm:px-0); only safeArea padding is inline.
 
 **Keywords:** region, page width, container, layout
 

package/llms/layout/row.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap.
+Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap. Layout lives in classes (flex flex-row items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (hidden md:flex, max-md:flex-col, md:gap-6).
 
 **Keywords:** row, toolbar, horizontal, layout
 
@@ -38,3 +38,11 @@ import { Button, Row } from "@sableui/react"
 
 <Row gap={2} justify="end"><Button variant="ghost">Cancel</Button><Button>Save changes</Button></Row>
 ```
+
+### Responsive through className
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row justify="between"><span className="text-title-sm">Acme</span><Row gap={1} className="max-md:hidden"><Button variant="ghost" size="sm">Docs</Button><Button variant="ghost" size="sm">Pricing</Button></Row></Row>
+```

package/llms/layout/spacer.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row).
+Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row). The size is a class reading a CSS variable, so className resizes or hides it at a breakpoint.
 
 **Keywords:** spacer, spacing, grow, layout
 

package/llms/layout/split-pane.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata.
+Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata. display is the grid class and the breakpoint rules are layered, so className utilities (hidden lg:grid, gap-8) win.
 
 **Keywords:** split pane, two pane, list detail, responsive
 

package/llms/layout/stack.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+).
+Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+). Layout lives in classes (flex flex-col items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (max-lg:hidden, md:flex-row, md:gap-8).
 
 **Keywords:** stack, vertical rhythm, layout, spacing
 

package/llms/tasks/auditing-an-app.md

@@ -58,6 +58,37 @@ names the nearest pair that reads. Report it with that pair as a recommendation.
 A reasoned `design-lint-disable-next-line label-contrast` is the app's recorded
 choice: list it as intentional, not as a defect.
 
+## Adoption: an app wired for Sable that barely uses it
+
+The commonest drift is not a wrong prop. It is an app where an agent never
+loaded this skill: the stylesheet and tokens are wired, and every control is the
+app's own (a `Modal`, a `PrimaryButton`, a `Tabs` written from scratch). Wiring
+checks pass, and lint only sees the raw elements. `sable check` (and `sable
+grade --json` → `adoption`) measures it: how many UI files compose Sable, which
+app-defined components are named for something Sable ships and do the behaviour
+by hand, and what the app's foundation is. `sable doctor` warns when adoption is
+`none` or `low`. It is never a failure: whether working screens move is the
+user's call.
+
+Put the choice to the user before changing anything. Ask, don't migrate silently
+and don't leave it unmentioned. Show the swaps, behaviour first (overlays,
+controls, tabs, menus, anything with focus or keyboard handling), with what each
+one gains ("your Modal has no focus trap or Esc; Sable's Dialog has both").
+Layout and look stay the app's. How strongly to recommend it depends on the
+`foundation` the report names:
+
+| Foundation | What to say |
+|---|---|
+| `ad-hoc`: no system besides Sable | Recommend the move plainly. There is nothing to preserve but one-off components, and every one is a behaviour bug waiting. Offer to do it a screen at a time. |
+| `own`: a folder of the app's own primitives | Offer the swaps and say what each gains. Keep the app's own where the user prefers them; suggest building them on Sable's behaviour (a `Button` wrapper around Sable's `Button`) instead. |
+| `library`: another component library (MUI, Radix, shadcn-style `components/ui`) | Ask whether Sable should replace it or only cover new work. Don't mix two control libraries on one screen. |
+| `sable`: Sable already carries the UI | Mention the few swaps listed when those screens are next touched. |
+
+Use the question tool the host offers when there is one. Record the answer in
+the project's instructions, so the next task doesn't ask again. On a yes, move
+one screen or component at a time with `fix`/`polish`, running `sable check` and
+looking at the rendered states after each.
+
 ## Deliver evidence-backed findings
 
 Save the audit under `design/<surface>/audit/` or the existing review location.

package/llms/tasks/getting-started.md

@@ -79,15 +79,22 @@ In a monorepo where Sable belongs to one workspace package, run setup in that
 package with `--root` naming the repository root (for example
 `pnpm --filter web exec sable setup --agent --root ../..`); the entries go
 there and resolve Sable through the package.
+Setup also adds a short managed block to the project's `AGENTS.md` and
+`CLAUDE.md`, the instructions an agent reads on every task, so a UI request
+goes through the skill even when it doesn't mention Sable. Only the text between
+its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is Sable's;
+`--no-instructions` skips it.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or
 `polish <target>` in Codex; use `/sable` with the same modes in Claude Code or
 Cursor. `create` is a build alias. These are agent modes, not shell commands.
 
-Upgrade with `pnpm update @sableui/react --latest`, then
-`pnpm exec sable setup --agent --update`. Setup only replaces managed files
-that have not been locally edited; `--dry-run` checks without writing. Keep
+Upgrade with `pnpm exec sable upgrade`: it updates the package, then runs the
+new version's `init`, which refreshes the skill entries and the instructions
+block and checks the wiring. From 0.17 or earlier, which has no `upgrade`, run
+`pnpm update @sableui/react --latest` and then `pnpm exec sable init` once.
+Setup only replaces managed files that have not been locally edited; `--dry-run` checks without writing. Keep
 project preferences in project instructions. Package installation alone does not
 change agent settings. See [building-with-sable.md](./building-with-sable.md),
 [creating-a-preset.md](./creating-a-preset.md), and

package/llms/tasks/using-presets.md

@@ -102,8 +102,7 @@ saved file. Replace, don't add beside:
 ## Upgrade the package and skill
 
 ```bash
-pnpm update @sableui/react --latest
-pnpm exec sable setup --agent --update
+pnpm exec sable upgrade
 pnpm exec sable preset --check .sable/presets/clay.json --json
 pnpm exec sable doctor
 ```