@sableui/react 0.4.0 → 0.6.0

package/llms/components/card.md

@@ -39,7 +39,7 @@ Use Card for a discrete thing with its own boundary, such as one product, one no
 | CardAction | ComponentPropsWithRef<"div"> | Header-aligned top-right action slot (e.g. an overflow menu, switch, or close button). Place inside CardHeader, which becomes a 2-column grid when present and collapses to a single column otherwise. |
 | CardContent | ComponentPropsWithRef<"div"> & { flush?: boolean } | The body region. Padding follows the density knob on all sides — does not assume a preceding CardHeader, so it is safe to use standalone (e.g. no CardHeader in the card). When paired with CardHeader, the seam stays tight because CardHeader zeroes its own bottom padding. `flush` runs it edge to edge for a table: the Table insets its first and last columns by exactly the card padding, so it lines up with the header — never hand-set pl-6/pr-6 on columns. |
 | CardList | ComponentPropsWithRef<"div"> | Rows that run edge to edge in the card (Entity rows, most often), divided by hairlines. Insets each row to the card's own padding, so a list card lines up with every other card at any density — no hand-tuned px-* on the rows. Under a CardHeader it opens with a hairline and a gap; alone it fills the card. |
-| CardFooter | ComponentPropsWithRef<"div"> | Bottom row for actions/meta. Padding follows the density knob. |
+| CardFooter | ComponentPropsWithRef<"div"> & { actions?: boolean } | Bottom row for actions/meta. Padding follows the density knob. `actions` marks it as the card's action row (buttons only): in a sheet (IosSheet, a bottom SheetContent) it becomes a full-width stack pinned to the bottom, primary on top; on a page nothing changes. |
 
 ## Props
 

package/llms/components/gradient-art.md

@@ -0,0 +1,80 @@
+# GradientArt
+
+**Status:** beta
+
+Placeholder artwork painted by a static WebGL shader from the preset's own art direction (the --art-* tokens: palette, ground, warp, softness, grain) — Ember burns, Prism airbrushes, Meridian is grainy monochrome — with a CSS gradient underneath for prerendered pages and browsers without WebGL2.
+
+**Keywords:** gradient, mesh gradient, grain, shader, artwork, placeholder image, cover, banner, avatar fallback, generative
+
+## Usage
+
+Use GradientArt where a real image belongs but none exists yet, or where the image is decoration: a product cover before upload, a profile banner, an album tile, an avatar with no photo. It reads the theme's own tokens, so it follows every preset, mode and live edit; `seed` fixes each item's composition so a list of covers or avatars stays individually recognisable.
+
+### Best practices
+
+- Do: Pass a stable `seed` per item — the name for an avatar, the title for a cover. Each item then keeps the same art across renders, reloads and themes, which is what lets someone recognise it.
+- Do: Size it with layout classes (`aspect-[4/3]`, `h-20`, `size-10 rounded-full`) and put any glyph or initials inside as children; they render above the art.
+- Do: Keep the default `mesh` for covers, tiles and avatars. Reach for `grain` where a printed, tactile surface suits — a banner, a hero card — and keep one variant per surface type so art reads as a system.
+- Don't: Do not put body text over it. The art spans the palette's lightest and most saturated tones, so no single ink is guaranteed to clear contrast across it; reserve overlays for a short label on a scrim or an avatar's initials.
+- Don't: Do not pass colours, and reach for `tones` rarely. The art follows the preset's --art-* tokens on purpose; to change how a product's art looks, set the --theme-art-* hooks in its theme or preset, so every cover, banner and avatar changes together.
+- Don't: Do not use it as a page or hero background. It paints at the element's pixel size, so a full-viewport instance costs a large frame on every theme change; it is sized for covers, banners and tiles.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| variant | "mesh" \| "grain" | "mesh" | mesh: soft spots of colour pulled together by gentle waves. grain: glowing light over deep corners with a printed texture. |
+| tones | ("info" \| "standard" \| "collectible" \| "edition" \| "warning")[] | — | Paint these `--tone-*` colours instead of the preset's art palette. Leave unset to follow the preset's art direction. |
+| seed | string \| number | — | Fixes the composition: the same seed paints the same art in every theme. Pass a stable id. |
+| children | ReactNode | — | Rendered above the art — initials, a glyph, a short label. |
+| className | string | — | Size and shape: aspect, height, rounding. |
+
+## Variants
+
+- **variant**: mesh, grain
+
+## Tokens used
+
+`art-1`, `art-2`, `art-3`, `art-4`, `art-5`, `art-6`, `art-ground`, `art-warp`, `art-softness`, `art-grain`, `primary`, `tone-info`, `tone-standard`, `tone-collectible`, `tone-edition`, `tone-warning`
+
+## Motion
+
+- **arrival** · canvas · `motion-interactive` — The shader frame fades in over the CSS gradient it replaces, so the swap from fallback to shader reads as the art settling rather than a flash.
+- **response** · root · _no motion_ — Artwork, not a control: it does not react to the pointer.
+- **transition** · canvas · _custom (outside the recipe layer)_ — A theme change repaints the frame in place on the next animation frame; there are no states to move between.
+- **activity** · root · _no motion_ — Static by design: nothing animates between paints, so it costs nothing while idle and respects reduced motion without a branch.
+
+## Accessibility
+
+- Decorative by default: the canvas is aria-hidden. When the art stands for something (an avatar), label the element that contains it, not the art.
+- Children render above the art in the normal reading order, so initials or a label are announced as usual.
+
+## Related
+
+- Components: Avatar, Card, AspectBox
+
+## Examples
+
+### Product cover
+
+```tsx
+import { GradientArt } from "@sableui/react"
+
+<GradientArt seed="Untitled (gold rush)" className="aspect-[4/3] rounded-lg" />
+```
+
+### Grain banner
+
+```tsx
+import { GradientArt } from "@sableui/react"
+
+<GradientArt variant="grain" seed="juno" tones={["info", "edition"]} className="h-20 rounded-md" />
+```
+
+### Avatar with initials
+
+```tsx
+import { GradientArt } from "@sableui/react"
+
+<GradientArt seed="Mara Okafor" className="grid size-10 place-items-center rounded-full text-label-md text-overlay-foreground">MO</GradientArt>
+```

package/llms/components/sheet.md

@@ -39,7 +39,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 | SheetHeader | ComponentProps<"div"> | Top section holding SheetTitle/SheetDescription. |
 | SheetTitle | Base UI Drawer.Title props + className | The sheet's accessible name — wires aria-labelledby on the popup. |
 | SheetDescription | Base UI Drawer.Description props + className | Muted supporting line; wires aria-describedby. |
-| SheetFooter | ComponentProps<"div"> | Bottom row for actions, pinned after the scrollable body. |
+| SheetFooter | ComponentProps<"div"> | Bottom row for actions, pinned after the scrollable body. In a bottom sheet it stacks: full width, the primary on top, every button at the cta height. |
 
 ## Props
 

package/llms/components/tabs.md

@@ -31,7 +31,7 @@ Use Tabs to switch between related panels within the same page context.
 
 | Name | Type | Description |
 | --- | --- | --- |
-| TabsList | Base UI Tabs.List props (activateOnFocus, loopFocus) + variant?: "underline" \| "pill" + className | The tablist row. variant="underline" (default) draws a divider rule beneath the triggers; variant="pill" drops the rule and fills the active trigger. Triggers inherit the variant. |
+| TabsList | Base UI Tabs.List props (activateOnFocus, loopFocus) + variant?: "underline" \| "pill" + className | The tablist row. variant="underline" (default) draws a divider rule beneath the triggers; variant="pill" drops the rule and fills the active trigger, which takes the theme's button shape (--button-radius). Triggers inherit the variant. |
 | TabsTrigger | Base UI Tabs.Tab props (value, disabled) + className | A single tab button. value pairs it with the panel of the same value. |
 | TabsPanel | Base UI Tabs.Panel props (value, keepMounted) + className | The content shown when the matching trigger is active. |
 | TabsContent | Alias of TabsPanel | Re-export of TabsPanel for consumers that prefer this name. |

package/llms/components/toast.md

@@ -34,6 +34,7 @@ Use Toast for transient feedback caused by a user action: saved, failed, copied,
 | Name | Type | Description |
 | --- | --- | --- |
 | ToastRoot | Base UI Toast.Root props + className (requires the `toast` object) | A single toast surface. Animates enter/leave via data-[starting-style]/data-[ending-style]; swipe-to-dismiss is wired by Base UI. |
+| ToastContent | Base UI Toast.Content props + className | The toast's contents as one row. In a stacked viewport it fades on the cards behind the front one and returns when the stack fans out. Wrap a hand-composed toast's parts in it so a stacked viewport can hide them. |
 | ToastTitle | Base UI Toast.Title props + className | The toast headline (text-title-sm). Auto-associated as the toast's accessible name. |
 | ToastDescription | Base UI Toast.Description props + className | Supporting body copy beneath the title (text-body-sm, muted). Auto-associated as the toast's accessible description. |
 | ToastClose | Base UI Toast.Close props + className | Dismiss button. Base UI handles the close and leave animation; labelled "Dismiss" by default. |
@@ -43,8 +44,9 @@ Use Toast for transient feedback caused by a user action: saved, failed, copied,
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| ToastProvider | { children, timeout?, limit?, closeIcon?, position?, viewportClassName? } | — | Wraps Base UI Toast.Provider and renders the themed Viewport + toast list. Mount once near the app root, above any caller of useToast(). |
+| ToastProvider | { children, timeout?, limit?, closeIcon?, position?, stacked?, viewportClassName? } | — | Wraps Base UI Toast.Provider and renders the themed Viewport + toast list. Mount once near the app root, above any caller of useToast(). |
 | position | "top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right" | "top-right" | Screen anchor for the toast stack. |
+| stacked | boolean | false | Stack the toasts like a deck of cards, the newest in front and the older ones peeking out behind it, a step smaller, instead of listing them one under another. Hovering or focusing the stack fans it out into the list. Use it when an app can raise several toasts in a row, so they don't take over the corner of the page. |
 | viewportClassName | string | — | Extra classes merged LAST onto the fixed viewport region — for safe-area insets or an offset (e.g. clearing a sidebar). |
 | timeout | number | 5000 | Default auto-dismiss time in ms for toasts. 0 keeps a toast until it is dismissed. Error toasts, loading toasts, and any toast carrying actionProps default to 0 regardless of this value; a per-toast timeout overrides both. |
 | limit | number | 3 | Maximum toasts shown at once; older toasts are pushed out when the limit is exceeded. |
@@ -62,6 +64,7 @@ Use Toast for transient feedback caused by a user action: saved, failed, copied,
 - **arrival** · ToastRoot · `motion-slide-left` — A toast interrupts without being asked, so where it came from is the reader's first question. Sliding in from the viewport edge answers it and marks the toast as belonging to the edge rather than to whatever it happens to cover.
 - **response** · ToastAction · `motion-interactive` — Toasts are on a timer, so the action has to look actionable at a glance — there is no time to hunt for the hit target.
 - **transition** · ToastRoot · `motion-slide-left` — Leaving the same way it entered keeps the stack legible when several dismiss at once; toasts that fade in place leave the remaining ones jumping to fill gaps with no visible cause.
+- **transition** · ToastRoot (stacked) · _custom (outside the recipe layer)_ — A stacked toast arrives from the anchored edge in front of the others, which step back and shrink to make room; hovering fans the deck out into the list. Moving every card, rather than snapping them, shows that the new one went on top and the old ones are still there.
 - **activity** · ToastRoot · _no motion_ — A toast reports a result that has already happened. Anything still in flight belongs in the surface that started it, where the reader is still looking.
 
 ## Accessibility
@@ -121,6 +124,14 @@ import { toast } from "@sableui/react"
 toast.message("Post archived", { actionProps: { children: "Undo", onClick: () => restorePost() } })
 ```
 
+### Stacked
+
+```tsx
+import { ToastProvider } from "@sableui/react"
+
+<ToastProvider stacked position="bottom-right">{children}</ToastProvider>
+```
+
 ### Provider with app chrome
 
 ```tsx

package/llms/foundations/accessibility.md

@@ -29,6 +29,7 @@ Sable's components ship accessible behavior from Base UI. These rules cover what
 
 - **Never:** Color as the only signal (a red border with no message). **Instead:** Color plus text or an icon. Roughly 1 in 12 men cannot tell red from green.
 - **Never:** Opacity on the focus ring. **Instead:** ring-ring at full opacity; tune the token in the theme. A faded ring loses the contrast the theme tested. *Enforced by sable-lint: faded-focus-ring.*
+- **Never:** A brand or status fill retuned under its old label — dark ink on a bright red that passes 4.5:1 at APCA Lc 42. **Instead:** A label that clears 4.5:1 and APCA Lc 60 in both modes. Move the fill's lightness, not its hue, keeping the ink its colour takes. A status colour on a surface is its own token (`--destructive-text`), so the fill can move freely. The ratio alone passes labels that read muddy. A deliberate brand pair is allowed with a recorded reason (lint disable or preset exceptions). *Enforced by sable-lint: label-contrast.*
 - **Never:** Blocking paste, or type="number" for codes and card numbers. **Instead:** type="text" inputMode="numeric" with the right autocomplete. Blocking paste breaks password managers; number inputs scroll-change identifiers.
 - **Never:** forced-color-adjust: none to 'fix' high-contrast mode. **Instead:** Let the system colors apply; verify the result. It removes the user's chosen colors exactly where they need them.
 - **Never:** outline: none without a replacement. **Instead:** focus-visible:ring-2 ring-ring. Keyboard users lose their place.

package/llms/patterns/auth-page.md

@@ -28,22 +28,7 @@ Split sign-in page: a form column (brand mark, heading, email + password, primar
 
 ```tsx
 import { useState } from "react"
-import { Avatar, Badge, Button, Card, CardContent, Entity, Field, Form, Icon, Input, Region, Separator, Stack } from "@sableui/react"
-
-// A soft mesh of the theme's decorative tones over its brand colour, so the
-// artwork follows every theme and mode. Each tone is lifted from its text
-// strength (dark, restrained) to an art strength.
-const artwork = [
-	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
-	"radial-gradient(in oklab at 18% 22%, oklch(from var(--tone-info) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 58%)",
-	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
-	"radial-gradient(in oklab at 82% 18%, oklch(from var(--tone-collectible) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 55%)",
-	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
-	"radial-gradient(in oklab at 70% 88%, oklch(from var(--tone-edition) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 60%)",
-	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
-	"radial-gradient(in oklab at 12% 92%, oklch(from var(--tone-standard) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 55%)",
-	"var(--primary)",
-].join(", ")
+import { Avatar, Badge, Button, Card, CardContent, Entity, Field, Form, GradientArt, Icon, Input, Region, Separator, Stack } from "@sableui/react"
 
 export function AuthPage() {
 	const [pending, setPending] = useState(false)
@@ -131,7 +116,8 @@ export function AuthPage() {
 
 			{/* The brand panel is decoration: on a phone the form is the whole screen. */}
 			<aside aria-label="Featured release" className="hidden p-3 lg:flex">
-				<div className="flex flex-1 flex-col justify-end rounded-xl p-8" style={{ background: artwork }}>
+				{/* Art painted from the theme's tones over its brand, so it follows every look. */}
+				<GradientArt seed="Untitled (gold rush)" className="flex flex-1 flex-col justify-end rounded-xl p-8">
 					<Card className="max-w-md">
 						<CardContent>
 							<Stack gap={3}>
@@ -143,14 +129,14 @@ export function AuthPage() {
 								</p>
 								<Entity
 									className="p-0"
-									leading={<Avatar fallback="MO" />}
+									leading={<Avatar variant="art" fallback="MO" />}
 									title="Mara Okafor"
 									subtitle="Untitled (gold rush), 2026"
 								/>
 							</Stack>
 						</CardContent>
 					</Card>
-				</div>
+				</GradientArt>
 			</aside>
 		</main>
 	)

package/llms/patterns/brand-landing-page.md

@@ -377,7 +377,7 @@ export function BrandLandingPage() {
 									</blockquote>
 								</Stack>
 								<figcaption className="flex items-center gap-3">
-									<Avatar size="lg" fallback="MO" />
+									<Avatar variant="art" size="lg" fallback="MO" />
 									<div>
 										<p className="text-title-sm">Maya Okafor</p>
 										<p className="text-body-sm text-muted-foreground">Head of operations, Fielddesk</p>

package/llms/patterns/chat-panel.md

@@ -77,7 +77,7 @@ export function ChatPanel() {
 	// at that size reads as a speck); `alt` names it for a screen reader, which
 	// otherwise gets nothing from a fallback-only avatar.
 	const assistant = (
-		<Avatar
+		<Avatar variant="art"
 			size="sm"
 			alt="Assistant"
 			fallback={<Icon name="sparkles" className="text-base" />}

package/llms/patterns/dashboard-page.md

@@ -111,7 +111,7 @@ export function DashboardPage() {
 							<span className="text-title-sm">Atelier</span>
 						</Row>
 					}
-					actions={<Avatar size="sm" fallback="AL" alt="Ada Lovelace" />}
+					actions={<Avatar variant="art" size="sm" fallback="AL" alt="Ada Lovelace" />}
 				/>
 			}
 			bottomNav={
@@ -146,7 +146,7 @@ export function DashboardPage() {
 					<SidebarFooter>
 						<Entity
 							className="[--entity-py:0]"
-							leading={<Avatar size="sm" fallback="AL" alt="" />}
+							leading={<Avatar variant="art" size="sm" fallback="AL" alt="" />}
 							title="Ada Lovelace"
 							subtitle="@ada"
 							action={
@@ -318,7 +318,7 @@ export function DashboardPage() {
 								{collectors.map((person) => (
 									<Entity
 										key={person.id}
-										leading={<Avatar size="sm" fallback={person.initials} alt="" />}
+										leading={<Avatar variant="art" size="sm" fallback={person.initials} alt="" />}
 										title={person.name}
 										subtitle={`${person.handle} · ${person.pieces} pieces`}
 										action={<span className="text-mono-sm">{usd.format(person.spent)}</span>}
@@ -365,7 +365,7 @@ export function DashboardPage() {
 							{activity.map((item) => (
 								<Entity
 									key={item.id}
-									leading={<Avatar size="sm" fallback={item.initials} alt="" />}
+									leading={<Avatar variant="art" size="sm" fallback={item.initials} alt="" />}
 									title={item.who}
 									subtitle={item.what}
 									action={<RelativeTime date={Date.now() - item.when} className="text-caption text-muted-foreground" />}

package/llms/patterns/feed-page.md

@@ -95,7 +95,7 @@ const renderPost = (post: Post) => (
 		<Card>
 			<CardList>
 				<Entity
-					leading={<Avatar fallback={post.initials} alt={post.author} />}
+					leading={<Avatar variant="art" fallback={post.initials} alt={post.author} />}
 					title={post.author}
 					subtitle={`${post.handle} · ${post.time}`}
 					action={
@@ -176,7 +176,7 @@ export function FeedPage() {
 					<Card>
 						<CardContent>
 							<Row gap={1.5} align="start">
-								<Avatar fallback="AL" alt="Ada Lovelace" />
+								<Avatar variant="art" fallback="AL" alt="Ada Lovelace" />
 								<Stack gap={1.5} className="min-w-0 flex-1">
 									<Textarea
 										autoResize
@@ -243,7 +243,7 @@ export function FeedPage() {
 								{suggestions.map((person) => (
 									<Entity
 										key={person.id}
-										leading={<Avatar fallback={person.initials} alt={person.name} />}
+										leading={<Avatar variant="art" fallback={person.initials} alt={person.name} />}
 										title={person.name}
 										subtitle={person.handle}
 										action={
@@ -263,7 +263,7 @@ export function FeedPage() {
 								{upcoming.map((drop) => (
 									<Entity
 										key={drop.id}
-										leading={<Avatar fallback={drop.initials} alt={drop.artist} />}
+										leading={<Avatar variant="art" fallback={drop.initials} alt={drop.artist} />}
 										title={drop.title}
 										subtitle={`${drop.artist} · ${drop.date}`}
 										action={

package/llms/patterns/landing-page.md

@@ -309,7 +309,7 @@ export function LandingPage() {
 											{deploys.map((deploy) => (
 												<Entity
 													key={deploy.meta}
-													leading={<Avatar size="sm" fallback={deploy.initials} alt={deploy.name} />}
+													leading={<Avatar variant="art" size="sm" fallback={deploy.initials} alt={deploy.name} />}
 													title={deploy.title}
 													subtitle={deploy.meta}
 													action={

package/llms/patterns/list-detail-page.md

@@ -212,7 +212,8 @@ export function ListDetailPage() {
 												selected={isSelected}
 												onSelect={() => select(m.id)}
 												leading={
-													<Avatar
+													<Avatar variant="art"
+														seed={m.name}
 														fallback={m.pending ? <Icon name="mail" className="size-5" /> : m.initials}
 														status={m.lastActive === "Online now" ? <StatusDot tone="success" /> : undefined}
 														// The row's title already names it: keep the initials out of the row's name.
@@ -274,7 +275,7 @@ export function ListDetailPage() {
 								<Card>
 									<CardHeader>
 										<Row gap={2}>
-											<Avatar
+											<Avatar variant="art"
 												size="lg"
 												fallback={selected.pending ? <Icon name="mail" className="size-6" /> : selected.initials}
 												status={selected.lastActive === "Online now" ? <StatusDot tone="success" /> : undefined}

package/llms/patterns/settings-page.md

@@ -75,7 +75,7 @@ export function SettingsPage() {
 							<span className="text-title-sm">Atelier</span>
 						</Row>
 					}
-					actions={<Avatar size="sm" fallback="AL" alt="Ada Lovelace" />}
+					actions={<Avatar variant="art" size="sm" fallback="AL" alt="Ada Lovelace" />}
 				/>
 			}
 			bottomNav={
@@ -110,7 +110,7 @@ export function SettingsPage() {
 					<SidebarFooter>
 						<Entity
 							className="[--entity-py:0]"
-							leading={<Avatar size="sm" fallback="AL" alt="" />}
+							leading={<Avatar variant="art" size="sm" fallback="AL" alt="" />}
 							title="Ada Lovelace"
 							subtitle="@ada"
 							action={
@@ -160,7 +160,7 @@ export function SettingsPage() {
 									<CardContent>
 										<Stack gap={3}>
 											<Row gap={2}>
-												<Avatar size="lg" fallback="AL" alt="Ada Lovelace" />
+												<Avatar variant="art" size="lg" fallback="AL" alt="Ada Lovelace" />
 												<Stack gap={0.5} align="start">
 													<Row gap={1}>
 														<Button type="button" variant="outline" size="sm">

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 (45)
+### semantic (49)
 
 - **`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.
@@ -74,6 +74,14 @@ Which token to reach for, and what it is most often confused with. Generated fro
     - **Not** `foreground`. That is the ink for `background` only; on any other surface it is a contrast gamble that happens to pass in the default theme and fails in another.
 - **`highlight-foreground`** — Ink paired with `highlight`. Evaluate the rendered contrast together; never choose it independently. *Use for:* Whenever the background is `highlight`. Use them as a pair — `bg-highlight text-highlight-foreground` — so a theme can retune the surface and the ink together.
     - **Not** `foreground`. That is the ink for `background` only; on any other surface it is a contrast gamble that happens to pass in the default theme and fails in another.
+- **`destructive-text`** — `destructive` drawn on a surface: text, icons, borders and focus rings. *Use for:* Write `text-destructive`, `border-destructive` or `ring-destructive` — they read this token; only `bg-destructive` reads the fill.
+    - **Not** `destructive` itself for marks on a page. The fill is tuned to carry a label (dark mode lowers it under white ink), which can leave it too dark to read on a dark card.
+- **`success-text`** — `success` drawn on a surface: text, icons, borders and focus rings. *Use for:* Write `text-success`, `border-success` or `ring-success` — they read this token; only `bg-success` reads the fill.
+    - **Not** `success` itself for marks on a page. The fill is tuned to carry a label (dark mode lowers it under white ink), which can leave it too dark to read on a dark card.
+- **`tone-warning-text`** — `tone-warning` drawn on a surface: text, icons, borders and focus rings. *Use for:* Write `text-tone-warning`, `border-tone-warning` or `ring-tone-warning` — they read this token; only `bg-tone-warning` reads the fill.
+    - **Not** `tone-warning` itself for marks on a page. The fill is tuned to carry a label (dark mode lowers it under white ink), which can leave it too dark to read on a dark card.
+- **`tone-info-text`** — `tone-info` drawn on a surface: text, icons, borders and focus rings. *Use for:* Write `text-tone-info`, `border-tone-info` or `ring-tone-info` — they read this token; only `bg-tone-info` reads the fill.
+    - **Not** `tone-info` itself for marks on a page. The fill is tuned to carry a label (dark mode lowers it under white ink), which can leave it too dark to read on a dark card.
 - **`overlay`** — A scrim over the page behind a modal, and the wash behind media chrome. *Use for:* Dialog and sheet backdrops, letterboxing, a pill sitting on top of an image.
     - **Not** `bg-black/50`. Pure black is never right — it crushes whatever is behind it, and a theme cannot tune it. This token is the sanctioned answer, which is why `raw-black-white` is a lint rule.
 - **`overlay-foreground`** — Ink paired with `overlay`. Evaluate the rendered contrast together; never choose it independently. *Use for:* Whenever the background is `overlay`. Use them as a pair — `bg-overlay text-overlay-foreground` — so a theme can retune the surface and the ink together.

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

@@ -51,6 +51,12 @@ drift; repeated overrides can indicate a missing system hook rather than app mis
 Run relevant `sable doctor`, `sable lint <paths> --json` and `sable grade <paths>
 --json` checks. Lint is lexical; source grades and pattern similarity do not judge
 taste. Deliberately static motion slots remain valid with appropriate feedback.
+Lint's `label-contrast` measures an app's overrides of the brand fills (`--primary`,
+`--sidebar-primary`, `--highlight`) and status fills (`--destructive`, `--success`,
+`--tone-warning`, `--tone-info`) against their labels on top of the installed theme, and
+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.
 
 ## Deliver evidence-backed findings
 

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

@@ -70,7 +70,9 @@ Entity rows in a Card) or `redesign` (desktop workspace tools).
 3. Compose: `NativeApp` at the root (`mode` sets light or dark, also on
    `<html>` so portaled Sable popups follow); one `NavigationStack` per tab,
    each holding an `IosPage` with an `IosNavbar` and Sable content; an
-   `IosTabbar` of `IosTab`s with Sable `Icon`s; `IosSheet` around Sable forms.
+   `IosTabbar` of `IosTab`s with Sable `Icon`s; `IosSheet` around Sable forms
+   (`background="opaque"` for a form at the medium detent, and the block
+   `framed={false}`: the sheet is already its surface).
    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

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

@@ -27,7 +27,7 @@ button and text node takes a minute and settles the argument.
 
 ## 1. Wire the package
 
-Follow **Consuming** in `llms.txt`: `.npmrc`, `pnpm add`, React dedupe, the CSS
+Follow **Consuming** in `llms.txt`: `pnpm add`, React dedupe, the CSS
 import order, `@source`, fonts, providers. React dedupe is the one that fails
 loudest and least clearly ("invalid hook call").
 

package/llms/tasks/creating-a-preset.md

@@ -31,6 +31,30 @@ light and dark modes and test long text, focus, disabled controls, floating
 surfaces, and errors. Token validation checks the contract and safe CSS structure;
 rendered review establishes contrast, coherence, and suitability.
 
+`--check` also measures the label on every filled role against its `-foreground`,
+in both modes: the brand fills `primary`, `sidebar-primary` and `highlight`, and the
+status fills `destructive`, `success`, `tone-warning` and `tone-info`. A label must
+clear 4.5:1 and APCA Lc 60, because a pair can pass the ratio and still read muddy
+(dark ink on a bright red-orange). A failing pair stops the check with
+`ERR_PRESET_CONTRAST` and the nearest pair that reads, with the fill's lightness
+moved and its hue kept. A fill keeps the ink its light-mode colour takes, so a
+colour with a white label keeps white in dark mode and its fill comes down to meet
+it. Offer that pair to the user.
+
+Each status colour has two tokens. The fill (`destructive`) carries its label;
+`destructive-text` is the same colour drawn on a surface, and `text-destructive`,
+`border-destructive` and `ring-destructive` read it. In dark mode the two usually
+differ: a saturated fill low enough for white, and a lighter text value that reads
+on a dark card. Author both; lowering the fill never darkens the page's error text.
+If the user chose the failing pair on purpose (a brand book, a reference to match),
+keep it and record the decision in the preset rather than overriding it:
+
+```json
+"exceptions": [{ "rule": "label-contrast", "mode": "dark", "token": "primary", "reason": "Brand book specifies dark ink on the bright fill." }]
+```
+
+An accepted pair is reported with its reason on every check; it is never silent.
+
 Canvas's Export view downloads this same format with resolved theme values and
 the current customizations. Enter a name and design guidance, save the JSON, and
 place it in the target project. The browser cannot write into that project for

package/llms/tasks/reviewing-a-design.md

@@ -92,6 +92,15 @@ Use opaque `focus-visible:ring-ring` or `ring-sidebar-ring`; reducing the ring t
 `faded-focus-ring` rule catches those classes. A token contrast report establishes
 the tested pairs, not the entire rendered product's accessibility.
 
+A label on a filled role (a primary or destructive Button, the sidebar's active
+item, a highlight, a success or warning badge) should clear 4.5:1 and APCA Lc 60 in
+both modes. A colour retuned for dark mode often lands where dark ink passes the
+ratio but reads muddy. `label-contrast`
+in `sable lint` and `sable preset --check` find it and suggest the nearest pair
+that reads; offer that pair. Keep a pair the user chose deliberately, recorded with
+its reason (a lint disable or a preset `exceptions` entry), instead of overriding
+it to finish.
+
 Describe a defect as a visible or behavioral consequence: "The heading wraps to
 six lines at 390px and pushes the action below the intended first decision point."
 Then record the repair and before/after artifact IDs in `iterations`. Avoid vague

package/llms/tasks/using-presets.md

@@ -18,7 +18,12 @@ Font stacks are requirements, not downloaded fonts. Declare matching stacks in
 the font metadata and tokens. Resolve internal palette variables before saving;
 portable presets may reference public Sable tokens, not private palette names.
 The validator rejects unknown tokens and CSS that can escape its declaration.
-It does not certify contrast or that a CSS value makes visual sense.
+`sable preset --check` also holds labels on brand and status fills to 4.5:1 and APCA Lc 60
+and suggests a pair that reads; a preset may keep a pair deliberately through
+`exceptions` with a reason (see `sable docs creating-a-preset`). Neither certifies
+the rendered product's contrast or that a CSS value makes visual sense. Do not
+change a supplied preset's colours to clear a finding without asking; report the
+finding and the suggested pair.
 
 Motion durations are nominal times at scale 1. `presetCss()` and the CLI connect
 them to the live `--motion-scale` policy, so reduced motion still stops recipes.