@sableui/react 0.1.1 → 0.3.0

package/llms/patterns/settings-page.md

@@ -1,36 +1,83 @@
 # SettingsPage
 
-Stacked settings sections inside the app shell: a content-width region, one Fieldset card per concern (each with its own save), auto-wired Form/Field rows, and a destructive zone last.
+Account settings inside the app shell: a sticky SideNav section rail beside a column of section Cards — a Profile form with the page's one explicit save, Card + CardList + Entity rows with Switches that apply instantly, a read-only payouts summary, account rows, and a delete card confirmed through DestructiveActionModal.
 
 **Intent:** Reach for this for account/profile/workspace settings and any 'edit a handful of grouped preferences' route. Not for a single short form (use AuthPage's centered form shape) or bulk record editing (use DashboardPage + DataTable).
 
 ## Notes
 
-- Region cap is `content` (896px): settings panes hold labeled rows and the occasional 2-up field, never a full grid.
-- One Fieldset per concern, each with its own footer save — per-section saves beat one page-wide submit for settings.
-- Field wires label/description/error a11y automatically; never hand-roll <label> + <input> pairs here.
-- The destructive section is visually last, isolated in its own Fieldset with a destructive-variant action.
-- Toggles use orientation="horizontal" Fields so the label sits beside the Switch.
+- Region cap is `wide`, split on a 12-column track: a 3-column SideNav rail and a 9-column section column. The rail fills the space a lone content-width column would leave empty and gives the page its table of contents.
+- The rail is `SideNav` (the documented settings sub-nav), sticky, with in-page anchor items; it hides below lg, where the sections simply stack and the shell's BottomNav carries app navigation.
+- One save model, stated in the copy: drafted text (the Profile form) commits through its single footer save; toggles apply the moment they change, and the Notifications description says so. Never pair a Switch with a Save button.
+- Settings rows are Card + CardList + Entity with the Switch in `action` — the row owns its title and one-line description; keep descriptions short, because Entity truncates its subtitle.
+- Each section is a Card whose CardTitle holds an h2, so the page has a real heading outline under PageHeader's h1; Cards carry the anchor id and `scroll-mt-*` so anchor jumps clear the top edge.
+- Field wires label/description/error a11y automatically; never hand-roll <label> + <input> pairs. Pair fields side by side with Grid cols={{ base: 1, sm: 2 }}.
+- The destructive action is last and isolated in its own Card, and it never acts directly: it opens DestructiveActionModal with type-to-confirm on the handle.
 - Lives in the same AppShell as DashboardPage: Sidebar from lg up, AppHeader + BottomNav below it, with Settings marked active in both.
 
 ## Accessibility
 
 - AppShell provides the skip link and <main id="main-content"> landmark; the active SidebarItem and BottomNavItem carry aria-current.
-- Each section is a real <fieldset> with a <legend> (FieldsetLegend).
+- The section rail is a labelled <nav> ("Settings sections") distinct from the primary navigation; its active item carries aria-current.
+- Every section has an h2, so screen-reader heading navigation mirrors the rail.
+- Each Switch takes its row title as aria-label, since the Entity title is not a <label>.
 - Field auto-wires htmlFor/id, aria-describedby (description + error), aria-invalid, and required.
-- The danger action is a real button labeled by its visible text — no icon-only destructive controls.
+- DestructiveActionModal is an alertdialog: focus opens on Cancel, the backdrop does not dismiss, and the confirm stays disabled until the handle is typed.
 
 ## Source
 
 ```tsx
-import { AppHeader, AppShell, BottomNav, BottomNavItem, Button, Field, Fieldset, FieldsetContent, FieldsetDescription, FieldsetFooter, FieldsetLegend, Form, Icon, Input, Page, PageHeader, Select, SelectContent, SelectItem, SelectTrigger, Sidebar, SidebarHeader, SidebarItem, SidebarNav, Switch, Textarea } from "@sableui/react"
+import { useState } from "react"
+import { AppHeader, AppShell, Avatar, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, Col, Columns, DestructiveActionModal, Entity, Field, Form, Grid, Icon, Input, MenuItem, MenuSeparator, NotificationBadge, OverflowMenu, Page, PageHeader, Row, Select, SelectContent, SelectItem, SelectTrigger, Sidebar, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, SideNav, SideNavItem, Stack, Switch, Textarea } from "@sableui/react"
+
+const sections = [
+	{ id: "profile", label: "Profile" },
+	{ id: "notifications", label: "Notifications" },
+	{ id: "payouts", label: "Payouts" },
+	{ id: "account", label: "Account" },
+]
+
+const timezones = [
+	{ value: "europe-london", label: "London (GMT+1)" },
+	{ value: "europe-paris", label: "Paris (GMT+2)" },
+	{ value: "america-new-york", label: "New York (GMT−4)" },
+	{ value: "america-los-angeles", label: "Los Angeles (GMT−7)" },
+	{ value: "asia-tokyo", label: "Tokyo (GMT+9)" },
+]
+
+const notifications = [
+	{ name: "notifyCollects", title: "New collects", description: "When someone collects your work", on: true },
+	{ name: "notifySoldOut", title: "Sold out", description: "When an edition sells its last copy", on: true },
+	{ name: "notifyFollowers", title: "New followers", description: "When a collector follows you", on: false },
+	{ name: "notifyDigest", title: "Weekly digest", description: "Sales and collectors, every Monday", on: true },
+	{ name: "notifyProduct", title: "Product updates", description: "New Atelier features", on: false },
+]
+
+const payouts = [
+	{ label: "Next payout", value: "$1,284.60", note: "Friday, Oct 16" },
+	{ label: "Pending", value: "$412.00", note: "Clears in 7 days" },
+	{ label: "Paid this year", value: "$18,920.00", note: "Across 214 collects" },
+]
 
 export function SettingsPage() {
+	const [activeSection, setActiveSection] = useState("profile")
+	const [deleteOpen, setDeleteOpen] = useState(false)
+
 	return (
 		<AppShell
 			// Sidebar hides below lg, so the same destinations ride in the shell's
 			// mobile slots — without them the route has no navigation under 1024px.
-			header={<AppHeader title={<span className="text-title-sm">Atelier</span>} />}
+			header={
+				<AppHeader
+					title={
+						<Row gap={1} align="center">
+							<Icon name="gem" variant="solid" className="text-xl" />
+							<span className="text-title-sm">Atelier</span>
+						</Row>
+					}
+					actions={<Avatar size="sm" fallback="AL" alt="Ada Lovelace" />}
+				/>
+			}
 			bottomNav={
 				<BottomNav aria-label="Primary">
 					<BottomNavItem icon={<Icon name="grid" />} label="Overview" showLabel render={<a href="/" />} />
@@ -43,78 +90,232 @@ export function SettingsPage() {
 			sidebar={
 				<Sidebar>
 					<SidebarHeader>
-						<span className="text-title-sm">Atelier</span>
+						<Row gap={1} align="center" className="px-3">
+							<Icon name="gem" variant="solid" className="text-xl" />
+							<span className="text-title-sm">Atelier</span>
+						</Row>
 					</SidebarHeader>
 					<SidebarNav>
 						<SidebarItem icon={<Icon name="grid" />} label="Overview" render={<a href="/" />} />
 						<SidebarItem icon={<Icon name="image-stack" />} label="Editions" render={<a href="/editions" />} />
 						<SidebarItem icon={<Icon name="user" />} label="Collectors" render={<a href="/collectors" />} />
-						<SidebarItem icon={<Icon name="bell" />} label="Activity" render={<a href="/activity" />} />
+						<SidebarItem
+							icon={<Icon name="bell" />}
+							label="Activity"
+							badge={<NotificationBadge count={4} tone="neutral" />}
+							render={<a href="/activity" />}
+						/>
 						<SidebarItem icon={<Icon name="gear" />} label="Settings" active render={<a href="/settings" />} />
 					</SidebarNav>
+					<SidebarFooter>
+						<Entity
+							className="[--entity-py:0]"
+							leading={<Avatar size="sm" fallback="AL" alt="" />}
+							title="Ada Lovelace"
+							subtitle="@ada"
+							action={
+								<OverflowMenu label="Account" size="icon-sm">
+									<MenuItem render={<a href="/@ada" />}>View profile</MenuItem>
+									<MenuItem render={<a href="/settings" />}>Settings</MenuItem>
+									<MenuSeparator />
+									<MenuItem>Sign out</MenuItem>
+								</OverflowMenu>
+							}
+						/>
+					</SidebarFooter>
 				</Sidebar>
 			}
 		>
 			{/* No `as="main"`: AppShell already renders <main id="main-content">. */}
-			<Page max="content" gap={4} className="py-6">
+			<Page max="wide" gap={4} className="py-6">
 				<PageHeader
 					title="Settings"
-					description="Your profile, notifications, and account controls."
+					description="Manage your profile, notifications, and payouts."
 				/>
-				<Form onSubmit={(event) => event.preventDefault()}>
-					<Fieldset>
-						<FieldsetLegend>Profile</FieldsetLegend>
-						<FieldsetDescription>How you appear across the app.</FieldsetDescription>
-						<FieldsetContent>
-							<Field label="Display name" required>
-								<Input name="displayName" defaultValue="ada" />
-							</Field>
-							<Field label="Bio" description="Shown on your public profile.">
-								<Textarea name="bio" rows={3} placeholder="Tell collectors who you are" />
-							</Field>
-							<Field label="Timezone">
-								<Select defaultValue="utc" name="timezone">
-									<SelectTrigger />
-									<SelectContent>
-										<SelectItem value="utc">UTC</SelectItem>
-										<SelectItem value="est">Eastern (UTC−5)</SelectItem>
-										<SelectItem value="pst">Pacific (UTC−8)</SelectItem>
-									</SelectContent>
-								</Select>
-							</Field>
-						</FieldsetContent>
-						<FieldsetFooter>
-							<Button type="submit">Save profile</Button>
-						</FieldsetFooter>
-					</Fieldset>
-				</Form>
-				<Form onSubmit={(event) => event.preventDefault()}>
-					<Fieldset>
-						<FieldsetLegend>Notifications</FieldsetLegend>
-						<FieldsetDescription>What we email you about.</FieldsetDescription>
-						<FieldsetContent>
-							<Field label="New collector alerts" orientation="horizontal">
-								<Switch name="collectorAlerts" defaultChecked />
-							</Field>
-							<Field label="Weekly digest" orientation="horizontal">
-								<Switch name="weeklyDigest" />
-							</Field>
-						</FieldsetContent>
-						<FieldsetFooter>
-							<Button type="submit">Save notifications</Button>
-						</FieldsetFooter>
-					</Fieldset>
-				</Form>
-				<Fieldset>
-					<FieldsetLegend>Danger zone</FieldsetLegend>
-					<FieldsetDescription>
-						Deleting your account removes your posts and collections permanently.
-					</FieldsetDescription>
-					<FieldsetFooter>
-						<Button variant="destructive">Delete account</Button>
-					</FieldsetFooter>
-				</Fieldset>
+				<Columns gap={4}>
+					{/* The section rail is a desktop aid; on mobile the sections simply stack. */}
+					<Col span={{ base: 12, lg: 3 }} className="hidden lg:block">
+						<SideNav aria-label="Settings sections" className="sticky top-6">
+							{sections.map((section) => (
+								<SideNavItem
+									key={section.id}
+									label={section.label}
+									active={activeSection === section.id}
+									onClick={() => setActiveSection(section.id)}
+									render={<a href={`#${section.id}`} />}
+								/>
+							))}
+						</SideNav>
+					</Col>
+					<Col span={{ base: 12, lg: 9 }}>
+						<Stack gap={3}>
+							<Card id="profile" className="scroll-mt-6">
+								<CardHeader>
+									<CardTitle render={<h2 />}>Profile</CardTitle>
+									<CardDescription>How collectors see you on Atelier.</CardDescription>
+								</CardHeader>
+								{/* The one explicit save on the page: profile text is drafted, then
+								    committed. Toggles below apply the moment they change. */}
+								<Form onSubmit={(event) => event.preventDefault()} className="gap-0">
+									<CardContent>
+										<Stack gap={3}>
+											<Row gap={2}>
+												<Avatar size="lg" fallback="AL" alt="Ada Lovelace" />
+												<Stack gap={0.5} align="start">
+													<Row gap={1}>
+														<Button type="button" variant="outline" size="sm">
+															Upload photo
+														</Button>
+														<Button type="button" variant="ghost" size="sm">
+															Remove
+														</Button>
+													</Row>
+													<p className="text-caption text-muted-foreground">
+														Square PNG or JPG, at least 400 px.
+													</p>
+												</Stack>
+											</Row>
+											<Grid cols={{ base: 1, sm: 2 }} gap={3}>
+												<Field label="Display name" name="displayName" required>
+													<Input defaultValue="Ada Lovelace" autoComplete="name" />
+												</Field>
+												<Field label="Handle" name="handle" description="atelier.com/@ada" required>
+													<Input defaultValue="ada" autoComplete="username" spellCheck={false} />
+												</Field>
+											</Grid>
+											<Field label="Bio" name="bio" description="Shown on your profile and edition pages.">
+												<Textarea
+													rows={3}
+													defaultValue="Generative artist working in plotted ink and code. New editions of 25 to 100 every month."
+												/>
+											</Field>
+											<Grid cols={{ base: 1, sm: 2 }} gap={3}>
+												<Field label="Timezone" name="timezone" description="Release times use this zone.">
+													<Select defaultValue="europe-london" items={timezones}>
+														<SelectTrigger />
+														<SelectContent>
+															{timezones.map((zone) => (
+																<SelectItem key={zone.value} value={zone.value}>
+																	{zone.label}
+																</SelectItem>
+															))}
+														</SelectContent>
+													</Select>
+												</Field>
+											</Grid>
+										</Stack>
+									</CardContent>
+									<CardFooter className="justify-end">
+										<Button type="submit">Save profile</Button>
+									</CardFooter>
+								</Form>
+							</Card>
+
+							<Card id="notifications" className="scroll-mt-6">
+								<CardHeader>
+									<CardTitle render={<h2 />}>Notifications</CardTitle>
+									<CardDescription>
+										Email updates about your editions. Changes save automatically.
+									</CardDescription>
+								</CardHeader>
+								<CardList>
+									{notifications.map((item) => (
+										<Entity
+											key={item.name}
+											title={item.title}
+											subtitle={item.description}
+											action={
+												<Switch
+													name={item.name}
+													defaultChecked={item.on}
+													aria-label={item.title}
+												/>
+											}
+										/>
+									))}
+								</CardList>
+							</Card>
+
+							<Card id="payouts" className="scroll-mt-6">
+								<CardHeader>
+									<CardTitle render={<h2 />}>Payouts</CardTitle>
+									<CardDescription>Paid in USD every Friday to Chase checking ••4821.</CardDescription>
+									<CardAction>
+										<Button variant="outline" size="sm" render={<a href="/settings/payouts" />}>
+											Manage payouts
+										</Button>
+									</CardAction>
+								</CardHeader>
+								<CardContent>
+									<Grid cols={{ base: 1, sm: 3 }} gap={3}>
+										{payouts.map((stat) => (
+											<Stack key={stat.label} gap={0.5}>
+												<p className="text-body-sm text-muted-foreground">{stat.label}</p>
+												<p className="text-mono-lg text-foreground">{stat.value}</p>
+												<p className="text-caption text-muted-foreground">{stat.note}</p>
+											</Stack>
+										))}
+									</Grid>
+								</CardContent>
+							</Card>
+
+							<Card id="account" className="scroll-mt-6">
+								<CardHeader>
+									<CardTitle render={<h2 />}>Account</CardTitle>
+									<CardDescription>Sign-in details and your data.</CardDescription>
+								</CardHeader>
+								<CardList>
+									<Entity
+										leading={<Icon name="mail" className="text-lg text-muted-foreground" />}
+										title="Email"
+										subtitle="ada@atelier.art"
+										action={
+											<Button variant="outline" size="sm">
+												Change
+											</Button>
+										}
+									/>
+									<Entity
+										leading={<Icon name="download" className="text-lg text-muted-foreground" />}
+										title="Export data"
+										subtitle="Editions, sales, and collectors"
+										action={
+											<Button variant="outline" size="sm">
+												Export
+											</Button>
+										}
+									/>
+								</CardList>
+							</Card>
+
+							<Card>
+								<CardHeader>
+									<CardTitle render={<h2 />}>Delete account</CardTitle>
+									<CardDescription>
+										Permanently remove your profile, editions, and sales history. Collectors keep
+										the editions they own.
+									</CardDescription>
+								</CardHeader>
+								<CardFooter className="justify-end">
+									<Button variant="destructive" onClick={() => setDeleteOpen(true)}>
+										Delete account
+									</Button>
+								</CardFooter>
+							</Card>
+						</Stack>
+					</Col>
+				</Columns>
 			</Page>
+			<DestructiveActionModal
+				open={deleteOpen}
+				onOpenChange={setDeleteOpen}
+				title="Delete your account?"
+				description="This permanently removes your profile, 12 editions, and sales history. Pending payouts are still sent. This can't be undone."
+				confirmLabel="Delete account"
+				confirmingLabel="Deleting…"
+				confirmText="ada"
+				onConfirm={() => setDeleteOpen(false)}
+			/>
 		</AppShell>
 	)
 }

package/llms/reference/token-intent.md

@@ -2,7 +2,7 @@
 
 Which token to reach for, and what it is most often confused with. Generated from `src/themes/token-docs.ts`; the full data is `registry.json → tokens`.
 
-### semantic (44)
+### semantic (45)
 
 - **`background`** — The page. The furthest-back surface in the page register. *Use for:* The document body, and any surface meant to read as 'the page itself'. Never anything that floats: background is the BOTTOM of the surface stack (background < card < popover in every dark mode), so a floating panel painted with it reads as a hole beneath the cards it hovers over.
     - **Not** `popover` for anything floating, `card` for a bounded block on the page. `canvas`. `canvas` is the *work* surface in a tool — the artboard being edited — which is not the page behind the UI. Using `background` for an artboard makes the thing being edited indistinguishable from the chrome around it.
@@ -24,8 +24,10 @@ Which token to reach for, and what it is most often confused with. Generated fro
     - **Not** `border-strong`. Reach for `border-strong` when the line carries *structure* (a grid rule, a table divider, a section separator) and for `border` when it merely bounds a control.
 - **`border-strong`** — A structural divider. Visibly stronger than `border`. *Use for:* Grid lines, table rules, separators between major sections.
     - **Not** `border`. If removing the line would make the layout ambiguous, it is structural and belongs here.
-- **`input`** — The outline of a form control specifically. *Use for:* Text inputs, textareas, selects, and the resting edge of a checkbox or radio.
+- **`input`** — The outline of a form control specifically. *Use for:* Text inputs, textareas and selects. Not the edge of a checkbox, radio or switch — that is `control-border`.
     - **Not** `border`. They are often the same value, but a theme is entitled to make form controls read differently from other chrome, and only this token gives it the hook.
+- **`control-border`** — The resting edge of a control whose outline is the whole control. Held to 3:1 (WCAG 1.4.11) on every surface. *Use for:* An unchecked checkbox, an unselected radio, an off switch track, a selection card's check or radio mark — anywhere removing the edge would make the control disappear.
+    - **Not** `input`. A text field is also found by its fill, caret and placeholder, so its outline may stay quiet; a checkbox has nothing else, and at `input`'s strength it measures about 1.4:1.
 - **`ring`** — The focus indicator colour. *Use for:* Only for `focus-visible`. Nothing else.
     - **Not** `primary`. Focus must remain distinguishable from selection; if the ring is the same colour as a selected state, a keyboard user cannot tell where focus is.
 - **`primary`** — The one high-emphasis action colour. *Use for:* The single most important action on a surface — one per view. A submit button, the primary CTA.

package/llms/reference/utilities.md

@@ -26,7 +26,7 @@ The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, wh
     - **Instead of** `bg-muted`, which is fixed: inside a popover it can sit within a step of the panel in some dark modes. And never a hand-mixed `color-mix(… var(--foreground) …)` or an outline on every well to compensate — that turns a panel into a stack of boxes. For a segmented control itself, use `ToggleGroup`; the well is for what no component draws.
     - `<div className="sable-well rounded-md p-1">…</div>`
 
-### frame (6)
+### frame (7)
 
 - **`sable-frame`** — A bordered, padded, rounded container that computes the radius its children need: `--sable-frame-inner-radius` = radius − padding − border width, floored at `radius-sm`. *Use for:* A container whose children have their own rounded backgrounds (rows, tiles, a nested preview), so the corners nest concentrically and keep doing so when the radius ladder is rescaled. Defaults: `radius-lg`, `--spacing(4)` padding (1rem at the default scale, and it follows the density control), a 1px edge from the surface (`--sable-surface-edge`, else `border`). Size it with `sable-frame-r-*` / `sable-frame-p-*`; children take `sable-frame-inner`.
     - **Instead of** `rounded-lg p-4 border` on the parent plus a guessed `rounded-sm` on each child — the guess is concentric only at the default ladder. For a one-off nested corner without a frame, `rounded-concentric-*`.
@@ -34,6 +34,9 @@ The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, wh
 - **`sable-frame-popover`** — The popup frame recipe: `radius-md`, `--spacing(1)` padding, the `border-floating` edge and `shadow-lg`, applied over `sable-frame`. *Use for:* A hand-composed floating list or panel that must match Sable's menus (with `sable-frame sable-surface sable-surface-popover`); rows inside take `sable-frame-inner`.
     - **Instead of** Copying a Menu's class string. And use `Menu`, `Select`, `Popover` or `Combobox` first — they own focus and dismissal; this is only for floating chrome no component covers.
     - `<div className="sable-frame sable-surface sable-surface-popover sable-frame-popover">…</div>`
+- **`sable-frame-tool`** — The frame for edge-to-edge tool chrome at the theme's radius, with no padding. It publishes concentric geometry for what's inside: `--panel-inset` (row side padding, grown so rows clear the corner), `--panel-field-radius` (compact fields curve parallel to the frame) and `--panel-edge` (the first and last section's extra top and bottom). PanelSection and the xs field shell read them. Applied over `sable-frame`. *Use for:* Framing PanelSections, ScrubFields, a Tree, a StatusBar or a PanelGroup outside a Workspace (a docs demo, a floating inspector). Add `overflow-hidden` to clip to the corners.
+    - **Instead of** `rounded-lg border overflow-hidden` by hand: the panel keeps its square-column 8px inset and small field radius, so a rounded preset crowds the first label and last field into the curve.
+    - `<div className="sable-frame sable-frame-tool overflow-hidden bg-panel" data-density="compact"><PanelSection title="Layer">…</PanelSection></div>`
 - **`sable-frame-borderless`** — Sets a `sable-frame`'s border width to 0 while keeping the inner-radius math correct. *Use for:* A frame that separates by fill or space rather than an edge (a well, a tinted group) but still needs concentric children.
     - **Instead of** `border-0` on a `sable-frame`, which removes the border but leaves 1px in the inner-radius calculation.
     - `<div className="sable-frame sable-frame-borderless sable-well sable-frame-r-md sable-frame-p-1">…</div>`
@@ -49,14 +52,14 @@ The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, wh
 
 ### geometry (4)
 
-- **`rounded-concentric-*`** — A border radius computed as an outer radius minus an inset: `rounded-concentric-<radius>/<spacing>`, clamped at zero. `rounded-concentric-md/1` = `radius-md` − `spacing-1`. *Use for:* A one-off rounded element nested inside another — a tab trigger inside a tab list, a thumb inside a track, a row inside a well — where a `sable-frame` would be overkill. The outer radius and the inset are the parent's.
+- **`rounded-concentric-*`** — A border radius computed as an outer radius minus an inset: `rounded-concentric-<radius>/<spacing>`, floored at `radius-xs` so a deep inset never leaves a 1-2px sliver. `rounded-concentric-md/1` = `radius-md` − `spacing-1`. *Use for:* A one-off rounded element nested inside another — a tab trigger inside a tab list, a thumb inside a track, a row inside a well — where a `sable-frame` would be overkill. The outer radius and the inset are the parent's.
     - **Instead of** Picking the next ladder step down by eye (`rounded-sm` inside `rounded-md p-1`). That is concentric only at the default ladder; the utility recomputes from live tokens. Registered in `cn()` as a radius, so it correctly overrides a component's own `rounded-*`.
     - `<div className="sable-well rounded-md p-1"><button className="rounded-concentric-md/1 px-2 py-1">…</button></div>`
 - **`popup-inset`** — The padding of a popup list, derived from the popup's radius: a third of `radius-md`, at least `--spacing(1)`. A rounder popup gets more room, and the floor is on the spacing scale, so the density control moves it. *Use for:* On a hand-composed rounded-md popup that holds a list of rows. Sable's Menu, Select, Combobox and ContextMenu already use it.
     - **Instead of** `p-1`. A fixed inset at a larger radius preset leaves the rows' corners approaching half their height, so every row turns into a pill.
     - `<div className="rounded-md bg-popover popup-inset shadow-md">…</div>`
 - **`rounded-popup-item`** — The row radius that nests inside a `popup-inset` popup: `radius-md` minus the popup inset, clamped at zero. *Use for:* On every row inside a `popup-inset` container.
-    - **Instead of** `rounded-sm` on menu rows, which matches only the default ladder (12px popup, 4px inset, 8px rows).
+    - **Instead of** `rounded-sm` on menu rows, which matches no ladder exactly (a 12px popup with a 4px inset and 1px border wants 7px rows).
     - `<div role="option" className="rounded-popup-item px-2 py-1.5 sable-highlighted:bg-accent">…</div>`
 - **`popup-bleed`** — A negative inline margin of exactly one `popup-inset`, so a separator inside a padded popup runs edge to edge at every radius and density. *Use for:* On a hand-composed separator (a 1px rule) inside a `popup-inset` popup. Sable's MenuSeparator, ContextMenuSeparator and SelectSeparator already use it.
     - **Instead of** `-mx-1`, which matches the inset only at the default ladder and stops short of both edges once a rounder preset or a roomier density grows it. design-lint flags it (`popup-separator-bleed`).
@@ -89,8 +92,20 @@ The `@utility` and `@custom-variant` layer in `styles.css`: what each one is, wh
     - **Instead of** `scrollbar-quiet` on a vertical list. A vertical region with no bar and no fade tells a reader nothing about how far through they are.
     - `<div className="flex gap-3 overflow-x-auto scrollbar-hidden">…</div>`
 
-### text (8)
-
+### text (12)
+
+- **`sable-list`** — A bulleted list as typography: body type, a hanging muted marker, and item rhythm. Put it on a native `<ul>`. *Use for:* Running content with bullets: release notes, a feature list, steps that are not ordered.
+    - **Instead of** A stack of `<div>`s with a hand-drawn dot, or an unstyled `<ul>` that inherits the reset (no markers, no indent).
+    - `<ul className="sable-list"><li>Faster sync</li><li>Offline drafts</li></ul>`
+- **`sable-list-numbered`** — A numbered list as typography: `sable-list` with decimal markers in tabular figures. Put it on a native `<ol>`. *Use for:* Ordered content in running text: setup steps, a ranked list. For a stepped flow with state, use Stepper.
+    - **Instead of** Numbers typed into the text, which neither renumber nor read as a list to assistive tech.
+    - `<ol className="sable-list-numbered"><li>Install</li><li>Import the styles</li></ol>`
+- **`sable-list-dl`** — Label/value pairs on a native `<dl>`: muted label-tier `<dt>`s and body-tier `<dd>`s on a baseline-aligned two-column grid; long values wrap inside their column. Colour a status value with a `text-*` utility on its `<dd>`. *Use for:* Read-only details: an order summary, a record's metadata, a settings summary, profile stats.
+    - **Instead of** A grid of `<div>`s (screen readers lose the term/value pairing), or Table for a single record. For editable values use Form and Field.
+    - `<dl className="sable-list-dl"><dt>Network</dt><dd>Solana</dd><dt>Status</dt><dd className="text-success">Active</dd></dl>`
+- **`sable-list-dl-2`** — Two label/value pairs a row once the nearest `@container` ancestor is at least 28rem wide. Add to `sable-list-dl`. *Use for:* A compact metadata block in a wide card or panel. Put `@container` on a parent so it measures the room it actually has.
+    - **Instead of** A viewport breakpoint, which gives a narrow card on a wide screen four columns it cannot fit.
+    - `<div className="@container"><dl className="sable-list-dl sable-list-dl-2">…</dl></div>`
 - **`text-overline`** — The eyebrow / overline / kicker tier: small, letter-spaced, uppercase by default (a theme may set sentence case via `--type-overline-transform`). *Use for:* A section eyebrow above a heading, a stat's label, a badge-style category line. Sits ABOVE and categorises.
     - **Instead of** `text-label-xs uppercase tracking-wider` assembled by hand, or `text-caption`, which sits BELOW and explains. In tool chrome, panel headers use `text-ui-section` instead.
     - `<p className="text-overline text-muted-foreground">Latest news</p>`

package/llms/tasks/building-an-ios-prototype.md

@@ -74,7 +74,10 @@ Entity rows in a Card) or `redesign` (desktop workspace tools).
    Keep the app's `IconProvider`.
 4. Frame it on a host page with `PhoneFrame` from `@sableui/react/ios/preview`
    and `@sableui/react/ios/frame.css` (Sable's Phone around an iframe at
-   402×874, scaled as a whole device). To follow a host's live look, call
+   402×874, scaled as a whole device). `fit="contain"` with a height in
+   `className` keeps the whole device on screen. Shown on a real phone with no
+   frame, pass `systemChrome={false}` to `NativeApp`: the device draws its own
+   status bar and home indicator, and the safe areas come from it. To follow a host's live look, call
    `useIosPreviewBridge(frameRef, { mode })` on the host and
    `useIosPreviewTheme()` in the prototype.
 5. Verify light and dark, keyboard focus, reduced motion, back and edge swipe,

package/llms/tasks/choosing-a-component.md

@@ -28,8 +28,8 @@ The question to ask is always **what the user is doing**, not what it looks like
 | The user is… | Use | Not |
 |---|---|---|
 | Choosing one action from a list under a button | `Menu` | `Select` (that picks a *value*) |
-| Reaching secondary actions for a row or card | `DotsMenu` | a bare `Menu` with a hand-made icon trigger |
-| Acting on the thing under the pointer (right-click or long press) | `ContextMenu`, always mirrored in a visible `DotsMenu` | `ContextMenu` alone: it is undiscoverable |
+| Reaching secondary actions for a row or card | `OverflowMenu` | a bare `Menu` with a hand-made icon trigger |
+| Acting on the thing under the pointer (right-click or long press) | `ContextMenu`, always mirrored in a visible `OverflowMenu` | `ContextMenu` alone: it is undiscoverable |
 | Changing a few settings that each show their current value | `SettingsMenu` | a `Menu` of toggles that hides each current state |
 | Running a main action that has close variations | a `Button` beside an icon `Button` that opens a `Menu` | a hand-fused split control |