@sableui/react 0.1.1 → 0.2.0

package/dist/themes/meridian/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CYScOdf5.js';
+import { T as ThemeManifest } from '../../_contract-o3tUc8Ig.js';
 
 /**
  * Meridian — a Sable theme. Concrete token values live in

package/dist/themes/meridian/meridian.css

@@ -117,15 +117,19 @@
 	   ---------------------------------------------------------------------- */
 	--background: oklch(94.6% 0.0083 91.48);
 	--foreground: oklch(26.25% 0.0162 102.18);
-	--card: oklch(94.6% 0.0083 91.48);
+	/* A step above the paper page, as in every preset with a tinted page: a card
+	   level with it left fields reading as part of the page, not a box to type in. */
+	--card: oklch(97.6% 0.006 91.48);
 	--card-foreground: oklch(26.25% 0.0162 102.18);
-	--popover: oklch(94.6% 0.0083 91.48);
+	--popover: oklch(97.6% 0.006 91.48);
 	--popover-foreground: oklch(26.25% 0.0162 102.18);
 	--muted: oklch(91.24% 0.0138 92.99);
 	--muted-foreground: oklch(49.93% 0.0412 93.54);
 	--border: oklch(87.54% 0.0194 93.69);
 	--border-strong: oklch(81.94% 0.0252 94.12);
 	--input: oklch(87.54% 0.0194 93.69);
+	/* The resting edge of a control whose outline IS the control (checkbox, radio, an off switch track). Held to WCAG 1.4.11 3:1 on every surface, unlike the quieter --input field outline. */
+	--control-border: oklch(58.9% 0.0346 93.54);
 	--ring: oklch(62% 0.2063 32.56);
 	--primary: oklch(26.25% 0.0162 102.18);
 	--primary-foreground: oklch(94.6% 0.0083 91.48);
@@ -167,7 +171,7 @@
 	--sidebar-primary-foreground: oklch(22.46% 0.0094 107.13);
 	--sidebar-accent: oklch(27.1% 0.0143 101.41);
 	--sidebar-accent-foreground: oklch(94.3% 0.0042 91.45);
-	--sidebar-border: oklch(27.1% 0.0143 101.41);
+	--sidebar-border: oklch(34.69% 0.0186 98.75);
 	--sidebar-ring: oklch(65.11% 0.2063 32.56);
 
 	/* ----------------------------------------------------------------------
@@ -216,8 +220,9 @@
 	 * only the edge separates. Caught by the non-text contrast gate.
 	 */
 	--border: oklch(34.69% 0.0186 98.75);
-	--border-strong: oklch(34.69% 0.0186 98.75);
+	--border-strong: oklch(44% 0.0225 96); /* one visible step above --border, which was lifted to the old strong value */
 	--input: oklch(34.69% 0.0186 98.75);
+	--control-border: oklch(60% 0.002 0);
 	--ring: oklch(65.11% 0.2063 32.56);
 	--primary: oklch(94.3% 0.0042 91.45);
 	--primary-foreground: oklch(22.46% 0.0094 107.13);
@@ -250,6 +255,6 @@
 	--sidebar-primary-foreground: oklch(22.46% 0.0094 107.13);
 	--sidebar-accent: oklch(27.1% 0.0143 101.41);
 	--sidebar-accent-foreground: oklch(94.3% 0.0042 91.45);
-	--sidebar-border: oklch(27.1% 0.0143 101.41);
+	--sidebar-border: oklch(34.69% 0.0186 98.75);
 	--sidebar-ring: oklch(65.11% 0.2063 32.56);
 }

package/dist/themes/poppy/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CYScOdf5.js';
+import { T as ThemeManifest } from '../../_contract-o3tUc8Ig.js';
 
 /** Original Sable preset; no third-party artwork or reference-site code. */
 declare const poppyTheme: ThemeManifest;

package/dist/themes/poppy/poppy.css

@@ -69,6 +69,8 @@
 	--border: oklch(69.96908% 0.055090 333.3586);
 	--border-strong: oklch(54.87925% 0.056525 333.9456);
 	--input: oklch(69.96908% 0.055090 333.3586);
+	/* The resting edge of a control whose outline IS the control (checkbox, radio, an off switch track). Held to WCAG 1.4.11 3:1 on every surface, unlike the quieter --input field outline. */
+	--control-border: oklch(60% 0.0598 321.39);
 	--ring: oklch(40.99289% 0.130336 325.3125);
 	--primary: oklch(38.38082% 0.116390 323.6155);
 	--primary-foreground: oklch(100.00000% 0.000000 89.8756);
@@ -119,14 +121,27 @@
 	--spacing: 0.28rem;
 	--theme-button-radius: 12px;
 	--button-radius: var(--theme-button-radius);
+	/* Hard offsets the whole way up. Only sm and md were declared, so the
+	   default, lg and xl steps fell through to Base's soft blurs and one ladder
+	   spoke two shadow languages. Offset doubles roughly per step. */
 	--theme-shadow-sm: 3px 3px 0 oklch(32% 0.05 320 / 0.12);
+	--theme-shadow: 4px 4px 0 oklch(32% 0.05 320 / 0.13);
 	--theme-shadow-md: 5px 5px 0 oklch(32% 0.05 320 / 0.14);
+	--theme-shadow-lg: 8px 8px 0 oklch(32% 0.05 320 / 0.16);
+	--theme-shadow-xl: 12px 12px 0 oklch(32% 0.05 320 / 0.18);
 }
 
 .dark[data-sable-theme="poppy"],
 [data-sable-theme="poppy"].dark,
 [data-sable-theme="poppy"] .dark,
 .dark [data-sable-theme="poppy"]:not(.light) {
+	/* The light ladder's ink is 32% lightness — LIGHTER than this 20% page, so
+	   in dark mode it drew a faint glow, not a shadow. Same offsets, near-black. */
+	--theme-shadow-sm: 3px 3px 0 oklch(8% 0.03 320 / 0.5);
+	--theme-shadow: 4px 4px 0 oklch(8% 0.03 320 / 0.52);
+	--theme-shadow-md: 5px 5px 0 oklch(8% 0.03 320 / 0.55);
+	--theme-shadow-lg: 8px 8px 0 oklch(8% 0.03 320 / 0.6);
+	--theme-shadow-xl: 12px 12px 0 oklch(8% 0.03 320 / 0.65);
 	--background: oklch(20.33265% 0.047438 308.8247);
 	--foreground: oklch(96.99788% 0.031195 84.5922);
 	--card: oklch(28.82474% 0.059607 315.2029);
@@ -138,6 +153,7 @@
 	--border: oklch(62.48980% 0.070560 325.5308);
 	--border-strong: oklch(72.17143% 0.060424 328.9840);
 	--input: oklch(62.48980% 0.070560 325.5308);
+	--control-border: oklch(67.3% 0.0412 332.63);
 	--ring: oklch(86.64637% 0.118528 86.6791);
 	--primary: oklch(86.64637% 0.118528 86.6791);
 	--primary-foreground: oklch(27.91553% 0.070219 323.8141);

package/dist/themes/prism/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CYScOdf5.js';
+import { T as ThemeManifest } from '../../_contract-o3tUc8Ig.js';
 
 /** Original Sable preset; no third-party artwork or reference-site code. */
 declare const prismTheme: ThemeManifest;

package/dist/themes/prism/prism.css

@@ -12,7 +12,7 @@
 	--region-ultrawide: 1800px;
 	--theme-radius-none: 0px;
 	--theme-radius-xs: 2px;
-	--theme-radius-sm: 4px;
+	--theme-radius-sm: 3px; /* a step of its own — sm and md were both 4px, which erased a rung of the ladder */
 	--theme-radius-md: 4px;
 	--theme-radius-lg: 6px;
 	--theme-radius-xl: 8px;
@@ -69,6 +69,8 @@
 	--border: oklch(79.84882% 0.029246 251.5080);
 	--border-strong: oklch(64.27577% 0.042824 253.1390);
 	--input: oklch(79.84882% 0.029246 251.5080);
+	/* The resting edge of a control whose outline IS the control (checkbox, radio, an off switch track). Held to WCAG 1.4.11 3:1 on every surface, unlike the quieter --input field outline. */
+	--control-border: oklch(60% 0.0298 252.77);
 	--ring: oklch(50.45463% 0.203215 263.5596);
 	--primary: oklch(50.45463% 0.203215 263.5596);
 	--primary-foreground: oklch(100.00000% 0.000000 89.8756);
@@ -147,6 +149,7 @@
 	--border: oklch(58.06940% 0.052170 251.5856);
 	--border-strong: oklch(69.19219% 0.042050 253.1082);
 	--input: oklch(58.06940% 0.052170 251.5856);
+	--control-border: oklch(67.7% 0.0275 255.1);
 	--ring: oklch(82.28684% 0.088371 261.1846);
 	--primary: oklch(82.28684% 0.088371 261.1846);
 	--primary-foreground: oklch(25.20350% 0.047984 259.9119);

package/dist/themes/verdant/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CYScOdf5.js';
+import { T as ThemeManifest } from '../../_contract-o3tUc8Ig.js';
 
 /**
  * Verdant — a Sable theme. Concrete token values live in

package/dist/themes/verdant/verdant.css

@@ -90,15 +90,19 @@
 	   ---------------------------------------------------------------------- */
 	--background: oklch(98.6% 0.004 106);
 	--foreground: oklch(24% 0.035 175);
-	--card: oklch(96.1% 0.005 106);
+	/* Cards, fields and popovers sit at or above the page, never recessed into it:
+	   a card darker than the page made every field read as a filled grey box. */
+	--card: oklch(99.7% 0.002 106);
 	--card-foreground: oklch(24% 0.035 175);
-	--popover: oklch(98.6% 0.004 106);
+	--popover: oklch(99.7% 0.002 106);
 	--popover-foreground: oklch(24% 0.035 175);
 	--muted: oklch(93% 0.007 106);
 	--muted-foreground: oklch(49% 0.018 175);
 	--border: oklch(88.5% 0.005 106);
 	--border-strong: oklch(81% 0.008 130);
 	--input: oklch(88.5% 0.005 106);
+	/* The resting edge of a control whose outline IS the control (checkbox, radio, an off switch track). Held to WCAG 1.4.11 3:1 on every surface, unlike the quieter --input field outline. */
+	--control-border: oklch(59.9% 0.0149 175);
 	--ring: oklch(24% 0.035 175);
 	--primary: oklch(24% 0.035 175);
 	--primary-foreground: oklch(98.6% 0.004 106);
@@ -174,6 +178,7 @@
 	--border: oklch(36% 0.03 175);
 	--border-strong: oklch(40% 0.028 175);
 	--input: oklch(36% 0.03 175);
+	--control-border: oklch(58.7% 0.0158 172);
 	--ring: oklch(85% 0.015 170);
 	--primary: oklch(98.6% 0.004 106);
 	--primary-foreground: oklch(24% 0.035 175);

package/llms/components/bubble.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The surface a message's content sits on: four treatments, an align-aware tail corner, a readable measure cap, and an optional row of reaction pills.
+The surface a message's content sits on: four treatments, an align-aware tail, a readable measure cap, and an optional row of reaction pills.
 
 **Keywords:** chat bubble, message bubble, speech bubble, reactions, conversation, messaging, ai chat
 
@@ -14,7 +14,7 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 
 - Do: Use `muted` for the other party and `primary` for the reader's own messages. Two treatments is the whole vocabulary a conversation needs to say who is speaking.
 - Do: Reach for `variant="plain"` for long-form assistant output — rendered markdown, code blocks, tables. A tinted box around three paragraphs reads as a quote block rather than as a turn, and `plain` drops the measure cap with the surface.
-- Do: Pass the same `align` you gave the enclosing Message, so the flattened corner lands on the speaker's side.
+- Do: Pass the same `align` you gave the enclosing Message, so the tail lands on the speaker's side.
 - Do: Set `tail={false}` on the continuation bubbles in a grouped run — the tail marks where a speaker starts, and repeating it on every line makes a block of one person's messages look like four separate turns.
 - Do: Let the register size it. Inside `<Density value="compact">` a Bubble sets itself in the workspace prose tier automatically — a docked agent panel needs no per-call-site sizing, and hardcoding one defeats the mechanism.
 - Don't: Do not remove the measure cap to fill a wide window. ~42rem is a reading measure; a bubble spanning a 1600px viewport is a paragraph at 140 characters per line.
@@ -26,7 +26,7 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 
 | Part | Required | Description |
 | --- | --- | --- |
-| Bubble | yes | The surface itself. Holds the variant, the side, and the flattened tail corner. |
+| Bubble | yes | The surface itself. Holds the variant, the side, and the tail. |
 | BubbleReactions | no | The row of reaction pills, just under the bubble at the message column's small gap, so it reads as belonging to that message rather than the next row. |
 | BubbleReaction | no | One reaction pill — emoji, count (hidden at 1), and pressed state. |
 
@@ -42,8 +42,8 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | variant | "muted" \| "primary" \| "outline" \| "plain" | "muted" | Surface treatment. `muted` for the other party, `primary` for the reader's own messages, `outline` for a quieter own-side, `plain` for long-form output that should not sit in a box (also drops the measure cap and padding). |
-| align | "start" \| "end" | "start" | Which side of the conversation the bubble is on — flattens the corner nearest the speaker. Match it to the enclosing Message. |
-| tail | boolean | true | Flatten the speaker-side corner. A flattened corner rather than a drawn arrow, so it holds up in every theme's radius language (flat through fully pilled) with no per-theme geometry. Turn it off for the continuation bubbles in a grouped run. |
+| align | "start" \| "end" | "start" | Which side of the conversation the bubble is on — puts the tail on the speaker's side. Match it to the enclosing Message. |
+| tail | boolean | true | Draw the tail: a small ear off the speaker-side top corner, which goes square to meet it. The same 5px in every theme's radius language, flat through fully pilled. The bubble keeps the ear's space either way, so turning it off for the continuation bubbles in a grouped run keeps the run aligned. |
 | ...div props | ComponentPropsWithRef<"div"> | — | Spread onto the surface element. |
 
 ## Variants

package/llms/components/checkbox-card.md

@@ -39,7 +39,7 @@ Use CheckboxCard when an option needs more visual weight, supporting text, or ic
 | onCheckedChange | (checked: boolean, eventDetails) => void | — | Fires with the next checked state (Base UI passes eventDetails second). Pair with `checked` for a controlled card; omit both to let it manage its own state. |
 | title | ReactNode | — | The card's primary label (text-title-sm). |
 | description | ReactNode | — | Optional supporting copy beneath the title (text-body-sm, muted). |
-| icon | ReactNode | — | Optional leading glyph (a solid <Icon>); takes the tone colour. |
+| icon | ReactNode | — | Optional glyph (a solid <Icon>) in the tone colour. Its presence switches to the two-dimensional card RadioCard uses — icon top-left, checkbox top-right, copy below — so the two cards match in one form. |
 | tone | "neutral" \| "standard" \| "collectible" \| "edition" \| "info" \| "warning" | "neutral" | Semantic colour the checked state carries across the border, checkbox box, and icon. |
 | value | string | — | Names the card inside a group-owned CheckboxGroup: the card is checked when the group's value array includes it. Also the value submitted with a form. Inside a CheckboxGroup, `name` stands in for `value` when `value` is omitted. |
 | checked / onCheckedChange / defaultChecked / disabled | Base UI Checkbox.Root props | — | Standard checkbox state. Without a group-owned value, each card is independent — drive checked/onCheckedChange per item for multi-select. |

package/llms/components/context-card.md

@@ -67,7 +67,7 @@ import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Entity } f
 ### With stat row
 
 ```tsx
-import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Description, DescriptionItem, Entity } from "@sableui/react"
+import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Entity } from "@sableui/react"
 
-<ContextCard><ContextCardTrigger render={<a href='/u/nyx' className='text-title-sm underline-offset-2 hover:underline'>@nyx</a>} /><ContextCardContent><Entity className='[--entity-px:0] [--entity-py:0]' leading={<Avatar fallback='NY' size='lg' />} title='Nyx' subtitle='@nyx' /><Description cols='2' className='mt-4 border-t border-border pt-3'><DescriptionItem term='Posts' detail='128' /><DescriptionItem term='Followers' detail='4.2k' /></Description></ContextCardContent></ContextCard>
+<ContextCard><ContextCardTrigger render={<a href='/u/nyx' className='text-title-sm underline-offset-2 hover:underline'>@nyx</a>} /><ContextCardContent><Entity className='[--entity-px:0] [--entity-py:0]' leading={<Avatar fallback='NY' size='lg' />} title='Nyx' subtitle='@nyx' /><div className='@container mt-4 border-t border-border pt-3'><dl className='sable-list-dl sable-list-dl-2'><dt>Posts</dt><dd>128</dd><dt>Followers</dt><dd>4.2k</dd></dl></div></ContextCardContent></ContextCard>
 ```

package/llms/components/dialog.md

@@ -38,7 +38,7 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 | Name | Type | Description |
 | --- | --- | --- |
 | DialogContent | Base UI Popup props + size?: "default" \| "fullscreen" + showCloseButton?: boolean + scroll?: boolean + className | Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. |
-| DialogOverlay | Base UI Backdrop props + size?: "default" \| "fullscreen" + className | The styleable scrim/backdrop — bg-overlay/50 by default, near-opaque bg-overlay/95 at size="fullscreen". Composed into DialogContent (at the matching size) by default; exported for manual styling. |
+| DialogOverlay | Base UI Backdrop props + size?: "default" \| "fullscreen" + className | The styleable scrim/backdrop — bg-overlay/(--scrim-alpha) by default (50% light, 72% dark, so it dims a near-black page as visibly as a white one), near-opaque bg-overlay/95 at size="fullscreen". Composed into DialogContent (at the matching size) by default; exported for manual styling. |
 | DialogTrigger | Base UI Dialog.Trigger props (render) | Element that opens the dialog. Compose via render prop. |
 | DialogClose | Base UI Dialog.Close props (render) | Element that dismisses the dialog. Compose via render prop. |
 | DialogHeader | ComponentProps<"div"> | Top section holding DialogTitle/DialogDescription. |

package/llms/components/empty-state.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The centered empty / error block: optional icon disc or error code, title, description and an action. tone="destructive" makes it an announced error, size="lg" a page-level state, surface="card" a self-contained card.
+The centered empty / error block: optional icon or error code, title, description and an action. tone="destructive" makes it an announced error, size="lg" a page-level state, surface="card" a self-contained card.
 
 **Keywords:** empty, zero state, blank slate, no results, placeholder, onboarding, no data
 
@@ -33,12 +33,12 @@ Use EmptyState when a content area has no items, no search results, or no first-
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| icon | ReactNode | — | Optional leading glyph — pass an `<Icon />`. Rendered in a soft muted disc. |
+| icon | ReactNode | — | Optional glyph above the title — an `<Icon />` takes the muted ink at 3xl; an image or illustration renders as given. |
 | title | ReactNode | — | The headline. Short and direct. |
 | description | ReactNode | — | Optional supporting line beneath the title. |
 | action | ReactNode | — | Optional action below the copy — typically a `<Button />`. |
 | code | ReactNode | — | A large figure above the title, such as an error code (404). |
-| tone | "neutral" \| "destructive" | "neutral" | destructive is an error state: a destructive icon disc (a warning by default) and role="alert" so it is announced. |
+| tone | "neutral" \| "destructive" | "neutral" | destructive is an error state: a destructive icon (a warning by default) and role="alert" so it is announced. |
 | size | "md" \| "lg" | "md" | lg is page-level: the title is an h2 and the block takes more room. md sits in a panel, list or card. |
 | surface | "none" \| "card" | "none" | card draws it as a Card, for an error or empty block standing on its own in a page. |
 
@@ -54,7 +54,7 @@ Use EmptyState when a content area has no items, no search results, or no first-
 
 ## Accessibility
 
-- Decorative icon discs should not carry meaning the title doesn't already convey.
+- Decorative icons should not carry meaning the title doesn't already convey.
 - Pair with an actionable next step so the zero-state is a path forward, not a dead end.
 
 ## Related

package/llms/components/entity.md

@@ -46,7 +46,7 @@ Use Entity to show a compact identity block for a person, organization, file, pr
 
 ## Related
 
-- Components: Avatar, Badge, Description
+- Components: Avatar, Badge
 
 ## Examples
 

package/llms/components/fieldset.md

@@ -56,7 +56,7 @@ Use Fieldset to group related controls under a shared label or explanation.
 
 ## Related
 
-- Components: Form, Label, Description
+- Components: Form, Label
 
 ## Examples
 

package/llms/components/kbd.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-A keyboard key indicator. Renders a styled <kbd> key cap in monospace; compose several with a + between to show a shortcut combo. `mod` renders the platform modifier (⌘ or Ctrl).
+A keyboard key indicator. Renders a raised <kbd> key cap sized from the surrounding text, so one Kbd fits body copy, menus and tooltips; KbdGroup sets one cap per key for a combo. `mod` renders the platform modifier (⌘ or Ctrl); `variant="ghost"` is the bare label for menu rows and tooltips.
 
 **Keywords:** keyboard, shortcut, key, kbd
 
@@ -13,8 +13,10 @@ Use Kbd to display keyboard keys or shortcuts in help text, menus, and docs.
 ### Best practices
 
 - Do: Use it only for literal keyboard input such as Cmd, Enter, or Esc.
-- Do: Keep multi-key shortcuts readable by separating individual keys.
+- Do: Show a combo as one cap per key inside KbdGroup — `<KbdGroup><Kbd mod /><Kbd>K</Kbd></KbdGroup>` — not several keys typed into one cap.
+- Do: Use `variant="ghost"` where the shortcut sits on a surface of its own — a menu row's trailing slot, a tooltip — so it reads as a hint, not a second control.
 - Don't: Do not use Kbd as a decorative badge or button replacement.
+- Don't: Do not set a text size on a Kbd. It sizes itself from the text around it.
 - Don't: Do not hardcode ⌘ or Ctrl. The modifier differs by platform; use `<Kbd mod />`, which renders ⌘ on macOS/iOS and Ctrl elsewhere, or Windows users read Mac keys.
 
 ## Props
@@ -22,17 +24,19 @@ Use Kbd to display keyboard keys or shortcuts in help text, menus, and docs.
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | mod | boolean | false | Render the platform's shortcut modifier in place of children: ⌘ on macOS and iOS, Ctrl everywhere else. Server-rendered as Ctrl and corrected on hydration. |
+| variant | "key" \| "ghost" | "key" | `key`: a raised cap on the surface it sits on, with a heavier bottom edge as the key's lip. `ghost`: the bare label, for menu rows, tooltips and other surfaces that are already a frame. |
 | className | string | — | Merge additional classes onto the key cap. |
 | ...props | ComponentPropsWithRef<"kbd"> | — | All native <kbd> attributes (children, ref, etc.). |
 
 ## Tokens used
 
-`border`, `muted`, `muted-foreground`
+`border`, `border-strong`, `background`, `muted-foreground`
 
 ## Accessibility
 
 - Uses the semantic <kbd> element so assistive tech announces keyboard input.
-- Monospace key text keeps single keys and symbols legible at small sizes.
+- KbdGroup is itself a <kbd> around the per-key caps — the HTML spelling of one key combination — so the combo is announced as a single piece of input.
+- Sized in em from the surrounding text, so it scales with the user's text size and never shrinks below 12px.
 
 ## Related
 
@@ -51,7 +55,15 @@ import { Kbd } from "@sableui/react"
 ### Combo
 
 ```tsx
-import { Kbd, Row } from "@sableui/react"
+import { Kbd, KbdGroup } from "@sableui/react"
 
-<Row gap={1}><Kbd mod /><span>+</span><Kbd>K</Kbd></Row>
+<KbdGroup><Kbd mod /><Kbd>K</Kbd></KbdGroup>
+```
+
+### In a menu row
+
+```tsx
+import { Kbd, MenuItem } from "@sableui/react"
+
+<MenuItem>Search<KbdGroup className="ms-auto"><Kbd variant="ghost" mod /><Kbd variant="ghost">K</Kbd></KbdGroup></MenuItem>
 ```

package/llms/components/pill.md

@@ -24,7 +24,7 @@ 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" | sm sits on the density ladder's xs control height, for chips under or inside other content. |
+| 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. |
 | icon | ReactNode | — | Optional leading glyph (e.g. <Icon name="lock" />), rendered before the children with the base gap. |
 
 ## Variants

package/llms/components/side-nav.md

@@ -15,7 +15,7 @@ Use SideNav for vertical navigation inside a settings page, documentation area,
 - Do: Use aria-label on SideNav when a page contains more than one nav landmark.
 - Do: Group related items with SideNavGroup when the rail has more than one conceptual area.
 - Do: Use size='lg' and activeVariant='sidebar' when the nav is part of persistent app chrome.
-- Do: Inside a rounded, padded frame, give each item rounded-concentric-<outer>/<inset> (e.g. rounded-concentric-lg/2 in a rounded-lg p-2 box). The rows' own radius is fixed per size, and a same-radius row inset into a frame reads as a second system.
+- Do: Rows are rounded-sm, which nests in the usual rounded-lg p-2 frame. In any other rounded, padded frame give each item rounded-concentric-<outer>/<inset> — a same-radius row inset into a frame reads as a second system.
 - Don't: Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot.
 - Don't: Mix content and sidebar active variants in the same rail unless individual items intentionally override the group.
 

package/llms/components/skeleton.md

@@ -32,7 +32,7 @@ Use Skeleton to reserve space and hint at the shape of content while data is loa
 - **arrival** · Root · _no motion_ — A skeleton stands in for content that has not arrived; fading the placeholder in adds a wait before the wait.
 - **response** · Root · _no motion_ — Nothing here is interactive. A skeleton that reacted to the pointer would invite a click on a thing that cannot be clicked.
 - **transition** · Root · _no motion_ — The skeleton has one state. Swapping it for real content is the parent's job, and the parent decides whether that swap is animated.
-- **activity** · Root · `motion-shimmer` — The sweep is the entire point of the component: it is what separates 'still loading' from 'loaded, and empty'. A static grey block is indistinguishable from a broken layout, which is why users reload the page.
+- **activity** · Root · `motion-shimmer` — The sweep is the entire point of the component: it is what separates 'still loading' from 'loaded, and empty'. A static grey block is indistinguishable from a broken layout, which is why users reload the page. It is one band of light against the viewport, so every skeleton in a loading layout lights in sequence as a single wave rather than each block flashing at its own speed; each pass eases in, glides and settles, then rests off-screen before the next.
 
 ## Accessibility
 

package/llms/components/theme-selector.md

@@ -12,7 +12,7 @@ Use ThemeSelector wherever a person picks a theme. The default `cards` layout is
 
 ### Best practices
 
-- Do: Use layout="list" in a popover, a menu, or a docked panel. Rows sit on the --control-sm ladder and still show each theme's swatch strip, so the choice stays visible rather than described. Rows take `sable-frame-inner`, so host the list in a sable-frame (a Popover, or `sable-frame sable-surface sable-surface-popover sable-frame-popover`) and their corners nest concentrically.
+- Do: Use layout="list" in a popover, a menu, or a docked panel. Rows sit on the --control-sm ladder and still show each theme's swatch strip, so the choice stays visible rather than described. Rows take `sable-frame-inner`, so host the list in a sable-frame (`sable-frame sable-surface sable-surface-popover sable-frame-popover` — PopoverContent is not one; give it that class list, or its p-4 leaves the rows unnested) and their corners nest concentrically.
 - Do: Pass mode={useSableTheme().mode} so every preview renders in the colour mode actually in use, rather than in each theme's manifest default.
 - Do: Load each theme's fonts in the host app. Every card carries a type specimen in that theme's own face so people can compare typography as well as color. A theme whose fonts are not loaded falls back to system-ui, and its specimen stops telling the truth.
 - Don't: Add a viewport breakpoint to force a column count — `className="sm:grid-cols-1"` or similar. `sm:` keys off the VIEWPORT, not this component's container, so on a wide screen it does nothing for a narrow parent. The cards grid already reflows on its own width via auto-fit.

package/llms/foundations/shape.md

@@ -30,7 +30,7 @@ Each step is 4px apart, so common insets land on a real step. Themes and the cus
 ## Rules
 
 1. **Nested corners are concentric: inner radius = outer radius − inset. Write it as rounded-concentric-<outer>/<inset>, not a hardcoded step.** A 12px popover with 4px padding takes 8px items. The utility computes the subtraction from the live tokens, so the pair stays concentric when a theme or the customizer rescales the radius ladder; a hardcoded rounded-sm drifts.
-2. **A list of rows inside a rounded popup uses popup-inset on the popup, rounded-popup-item on the rows and popup-bleed on a separator.** All three derive from the popup's radius: the inset grows to a third of it (never below --spacing(1), so density moves it too), the rows take what is left, and a separator bleeds by exactly the inset. A rounder look gets more room instead of rows that round into pills, and the default ladder still lands on the familiar 4px inset and 8px rows. *Enforced by sable-lint: popup-separator-bleed.*
+2. **A list of rows inside a rounded popup uses popup-inset on the popup, rounded-popup-item on the rows and popup-bleed on a separator.** All three derive from the popup's radius: the inset grows to a third of it (never below --spacing(1), so density moves it too), the rows take what is left after the inset and the 1px border, and a separator bleeds by exactly the inset. A rounder look gets more room instead of rows that round into pills; the default ladder lands on a 4px inset and 7px rows. *Enforced by sable-lint: popup-separator-bleed.*
 3. **A Button, Pill or Badge gets its look from a variant, never from override classes.** border, bg, rounded, ring and shadow classes on a component fight the variant's own hover, selected and focus states, and give one call site a look no other site can ask for. Use the variant that exists (Button variant="floating" over content, "on-color" on a fill; Pill appearance="outline"; Badge appearance and tone) or add one to the component. *Enforced by sable-lint: component-restyle.*
 4. **The outer radius is always at least the inner radius.** If the inset is larger than the outer radius, square the inner element or step the container up.
 5. **Never mix radii within one component.** A component reads as one object when its corners agree.