@justanarthur/modo-ui 0.6.0-canary.6 → 0.6.0-canary.8

package/DESIGN.md

@@ -67,6 +67,8 @@ colors:
   image-edge-dark: "rgb(255 255 255 / 0.1)"
   progress-track: "color-mix(in oklab, oklch(0.205 0 0) 10%, transparent)"
   progress-track-dark: "color-mix(in oklab, oklch(0.97 0 0) 10%, transparent)"
+  well: "oklch(0.967 0.001 286.375)"
+  well-dark: "oklch(0 0 0 / 0.25)"
   surface-1: "oklch(0.985 0 0)"
   surface-2: "oklch(0.991 0 0)"
   surface-3: "oklch(1 0 0)"
@@ -284,7 +286,7 @@ components:
     padding: 24px
     width: 400px
   tabs-list:
-    backgroundColor: "{colors.muted}"
+    backgroundColor: "{colors.well}"
     rounded: "{rounded.xl}"
     height: "{spacing.control}"
     padding: 4px
@@ -357,7 +359,11 @@ Two text colors, a greyscale ground, one blue.
   button (until `--primary-foreground` is re-pointed) and the tooltip (`text-background`).
 - **Surfaces (`bg-surface-1` … `bg-surface-8`)** — the elevation ladder (see Elevation & Depth). Prefer a
   surface level over `card`/`background` for anything that floats or nests.
-- **Muted (`bg-muted`)** — a recessed track: the segmented tabs' well, a sunken field at rest.
+- **Muted (`bg-muted`)** — a sunken fill: a field's hover wash, a queued row. In dark it is surface 2, so
+  it never carries a track: it would vanish on a card or the inset.
+- **Well (`bg-well`)** — the recessed track under a segmented control's indicator (the tabs list). Light is
+  muted; dark is black at 25%, which darkens whatever it sits on, so the track reads on the page, a card
+  and the inset alike.
 - **Accent (`bg-accent`)** — the secondary button and the switch's off track. `selected` is a firmer
   grey for persistent selection fills.
 - **Hover / Active (`bg-hover`, `bg-active`)** — translucent overlays (black 4% / 7% in light, white 6% /

package/README.md

@@ -106,7 +106,7 @@ Every vendored file opens with a plain `/* */` header. The header names the
 upstream path and commit, carries the MIT notice, and lists every local
 modification. The vendored code below the header keeps upstream's formatting.
 Files written for this port (`preset.ts`, `uno.config.ts`, `vite.ts`, `index.ts`,
-`scripts/build-css.ts`, `modo.components.tsx`,
+`scripts/build-css.ts`, `docs/*`,
 `lib/use-controllable-state.ts`, `primitives/code/index.tsx`, `primitives/craft/*`, the morph files
 in `lib/` (`use-morph.ts`, `reduced-motion.ts`, `morph-layers.tsx`, `morph-part.tsx`, `goo-indicator.tsx`,
 `slot.ts`) and `primitives/morph/index.tsx`, `blocks/sidebar-app/index.tsx`,
@@ -137,13 +137,13 @@ positioning) are ported.
 | `DESIGN.md` | The design language in Google's [DESIGN.md](https://github.com/google-labs-code/design.md) format: the tokens as front matter, the rules as prose. Agents building here follow the `modo-ui` skill (`.claude/skills/modo-ui` at the repo root). |
 | `tokens/*.css` | Colors, typography (`--font-sans`, `--text-*`), motion (`--duration-*`), radius and spacing. Shipped per group as `dist/tokens/*.css` (`./tokens/*`). |
 | `base.css` | Theme switching, base styles, focus fallback, scrollbars, shimmer/spinner keyframes and `.scroll-fade`. Shipped in the package. The inline `code` chip applies only inside the docs shell, `data-modo="prose"` and `.modo-prose`. |
-| `global.css` | The docs site's stylesheet (`modo.config.ts` `css`): imports `base.css`, then the modo-only focus revert and the docs chrome. |
+| `global.css` | The docs site's stylesheet (`modo.config.ts` `css`): imports `base.css`, then `docs/chrome.css`. |
 | `preset.ts` | The UnoCSS preset (theme and token utilities), shipped as `@justanarthur/modo-ui/unocss`. |
-| `uno.config.ts`, `vite.ts` | The UnoCSS setup of the docs site and the prebuilt CSS (see below). |
+| `uno.config.ts`, `vite.ts` | The UnoCSS setup of the docs site and the prebuilt CSS (see below); `vite.ts` also applies the docs chrome's `docsTheme` plugin. |
 | `index.ts`, `bunup.config.ts`, `scripts/build-css.ts` | The package build: `bun run build` writes the components, their types and the stylesheets to `dist/`. The docs site builds with `bun run build:docs` into `docs-dist/`. |
 | `scripts/exports.ts`, `scripts/use-client.ts`, `scripts/check-singletons.ts` | Packaging around that build. `exports.ts` (first step of `bun run build`) writes one `./lib/<name>` export per `lib/` module into `package.json`, plus `./components/*/variants` and `./blocks/*/variants` for the items' server-callable `variants.ts` entries; commit the `package.json` it leaves. `use-client.ts` (after bunup) puts `"use client"` on the emitted modules that render, call a hook or create a context, or use a binding from one; pure helpers (`cn`, class tables, springs, `variants.ts`) and re-export entries stay directive-free so a React Server Component can call them (`--list` prints the split). `check-singletons.ts` (`bun run check:dist`) checks that every React context and the `toast()` manager exist once in `dist/`, and that every entry has its `.d.ts`. `typesVersions` in `package.json` maps every public subpath to `dist/**/*.d.ts`, so `moduleResolution: node` consumers do not type-check the shipped source. |
 | `lib/` | FF's shared system files (upstream `lib/`, `hooks/` and the fluid-hover highlight, flat, upstream names), imported relatively by items. modo only scans the tier folders, so it never mistakes them for items. |
-| `modo.components.tsx` | Components only the docs site uses: the `Icon`, `Select` and `DocsNav` shell-slot adapters and the `ThemeSwitcher` panel item, picked in `modo.config.ts` by export name (`./modo.components.tsx#Select`). |
+| `docs/` | The docs chrome, shipped: `chrome.tsx` (the `Button`, `Link`, `Icon`, `Select` and `DocsNav` shell-slot adapters and the `ThemeSwitcher` panel item, re-exported by `index.ts` as `@justanarthur/modo-ui/docs`), `chrome.css` (the inset layout and the look of the chrome, `@justanarthur/modo-ui/docs/chrome.css`) and `vite.ts` (`docsTheme`, the pre-paint theme controller, `@justanarthur/modo-ui/docs/vite`). `modo.config.ts` picks the slots by export name (`./docs#DocsNav`); another design system documented with modo points at the same module by package specifier (see **The docs chrome, for another design system**). The barrel (`index.ts`) never imports it, `bun run check:dist` fails if it does. |
 | `primitives/<id>/` | FF's "System" pages: `index.tsx` (component + TSDoc prose) and `examples.mdx`, pulled in by `@example {@include ./examples.mdx}`. |
 | `components/[<group>/]<id>/` | FF's "Components" pages, same shape. The `AI/`, `inputs/` (with `inputs/date-time/`), `navigation/` and `overlays/` group folders become sidebar sub-groups and overview sections; the core display items stay ungrouped. |
 | `blocks/<id>/` | Compositions of several items, same shape: `sidebar-app`, FF's sidebar preset `sa1FQfCxH6` as an app shell, with the header and footer blocks it is built from beside it. |
@@ -158,7 +158,8 @@ positioning) are ported.
 | `lib/springs.ts` | `lib/springs.ts` | `goo` tier added (the morph engine's goo: 250ms to land, bounce 0.15, a 200ms spring back); `exitFallbackMs` also reads a spring exit's `visualDuration` |
 | `lib/font-weight.ts` | — | not ported: its `fontWeights` became the `--weight-*` tokens in `tokens/typography.css` (the `weight-*` utilities) |
 | `lib/popup.ts` | `lib/popup.ts` | `popupMotionClass` dropped (unused since the popups morph) |
-| `lib/shape-context.tsx` | `lib/shape-context.tsx` | `"use client"` dropped |
+| `lib/shape-context.tsx` | `lib/shape-context.tsx` | `"use client"` dropped; `--shape-input-radius` is published through `claimShapeRadius` and given back on unmount |
+| — (new) | `lib/shape-radius.ts` | Local addition: the stack of `ShapeProvider` claims on `--shape-input-radius` (`<html>`), so an unmounting provider restores the one below it or the page's own value; plain data, tested without a DOM |
 | `lib/size-context.tsx` | `lib/size-context.tsx` | `"use client"` dropped; `SizeProvider` moved to `primitives/sizes` (the documented item), with `SizeContext` exported for it; `sizeMap`, `typeScale` and their types moved to `size-scale.ts` and re-exported |
 | `lib/size-context.tsx` (`sizeMap`, `typeScale`) | `lib/size-scale.ts` | The ladder's plain data, split out so server code can read it (no JSX, hooks or contexts); `sizeMap` text classes → `text-body` / `text-body-compact` |
 | `lib/icon-context.tsx` | `lib/icon-context.tsx` | `"use client"` dropped; `size`/`strokeWidth` widened to `number \| string` for lucide v1 + React 18 types |
@@ -292,17 +293,17 @@ only what is specific to it:
 | — | `registry/blocks/sidebar-app/inset-topbar.tsx` | `blocks/sidebar-app/inset-topbar.tsx` | the trigger's peek-time fade dropped (the sidebar opens on hover in flow, so the trigger stays) |
 | — | `registry/default/lib/sidebar-menu-grid.ts` | `blocks/sidebar-app/menu-grid.ts` | the width reads `--anchor-width` only; the `-ml-1` shift dropped (it would move the morph surface's content off its background) |
 
-`Select` in `modo.components.tsx` is not an item: modo's docs chrome renders its Select slot
+`Select` in `docs/chrome.tsx` is not an item: modo's docs chrome renders its Select slot
 with a flat `value` / `onChange` / `options` contract
 (`lib/src/lib/slots.tsx`), and this adapter maps it onto
 `Select.Trigger` / `Select.Content` / `Select.Item` so the chrome runs on the
 design system's own Select. The
 `components/inputs/select` item keeps the upstream API untouched.
 
-`DocsNav` in `modo.components.tsx` is the chrome's Sidebar slot, pinned as
+`DocsNav` in `docs/chrome.tsx` is the chrome's Sidebar slot, pinned as
 `shell.Sidebar` (by name alone modo would adopt the documented `Sidebar`, an
 app shell that needs its provider). Each aside is an inset `Sidebar` with its
-own provider, and `global.css` turns the content between them into the inset
+own provider, and `docs/chrome.css` turns the content between them into the inset
 card (the lib's grid columns become `auto`, so they follow the sidebars' width
 springs). Each provider has `openOnHover`, and its `Sidebar.Trigger` sits in
 the card's corner: the trigger, `[` for the nav and `]` for the panel, switch
@@ -315,7 +316,7 @@ below xl. A section of links is a collapsible `Sidebar.Group` with one
 highlight melt from link to link; a panel section (Theme) keeps its control
 under the group label.
 
-`ThemeSwitcher` in `modo.components.tsx` is not an item either: it is the `Theme` entry in
+`ThemeSwitcher` in `docs/chrome.tsx` is not an item either: it is the `Theme` entry in
 `modo.config.ts` `panel.items`, a `Select` of Light / Dark / System (each row
 with its icon, the trigger showing the active one) that reads and sets
 `window.__uiTheme` and re-reads it on `ui:themechange`. All switching logic lives in the pre-paint controller
@@ -323,6 +324,75 @@ described under **Tailwind → UnoCSS**, so the control holds no theme state of
 its own. `demo/scripts/run-design-systems.ts` appends its own `Switcher` panel
 item to whatever a design system declares, so both show up under the runner.
 
+The chrome's own elements (the corner triggers, the panel section's gutter) are
+styled in `docs/chrome.css` through `data-modo-ui` attributes, not utility
+classes: nothing in `docs/` needs a UnoCSS or Tailwind scan, so a host with
+either generator loads the same file. `Button` and `Link` are pinned too, so a
+design system with items of those names but another prop shape is not matched
+by name (modo would warn on every start).
+
+### The docs chrome, for another design system
+
+A design system documented with modo (an `@utegsk/ui`-style package that
+depends on `@justanarthur/modo-ui`) gets the same sidebars, inset card layout,
+panel and Theme switcher as this site by pointing its `modo.config.ts` at the
+shipped module. A `shell` / `panel` value may be a package specifier (the
+viewer resolves it from the project root through the package's `exports`, the
+`source` file first), which needs an `@justanarthur/modo` release after
+0.9.0-canary.0; with an older viewer keep a one-line local re-export instead
+(`export * from '@justanarthur/modo-ui/docs'` in a `docs/shell.tsx`, and point
+the slots at `./docs/shell.tsx#DocsNav`).
+
+```ts
+// modo.config.ts
+import { defineConfig } from '@justanarthur/modo/config'
+
+export default defineConfig({
+  name: 'My DS',
+  css: './docs.css',
+  vite: './vite.mjs',
+  shell: {
+    Button: '@justanarthur/modo-ui/docs#Button',
+    Link: '@justanarthur/modo-ui/docs#Link',
+    Select: '@justanarthur/modo-ui/docs#Select',
+    Icon: '@justanarthur/modo-ui/docs#Icon',
+    Sidebar: '@justanarthur/modo-ui/docs#DocsNav',
+  },
+  panel: { items: [{ label: 'Theme', component: '@justanarthur/modo-ui/docs#ThemeSwitcher' }] },
+})
+```
+
+```css
+/* docs.css: the package stylesheet (or base.css with your own utilities), then the chrome */
+@import "@justanarthur/modo-ui/styles.css";
+@import "@justanarthur/modo-ui/docs/chrome.css";
+```
+
+```js
+// vite.mjs: plain JS, Node loads it as is. Add your own plugins (Tailwind, UnoCSS) beside docsTheme.
+import { docsTheme } from '@justanarthur/modo-ui/docs/vite'
+
+export default config => {
+  config.plugins = [...(config.plugins ?? []), docsTheme({ storageKey: 'my-ds-theme' })]
+  return config
+}
+```
+
+- `chrome.css` also loads by itself, as the stylesheet beside the slot module,
+  when modo bundles `@justanarthur/modo-ui/docs` from its source; the explicit
+  `@import` fixes where it sits in your cascade and is the one to rely on.
+- `docsTheme` puts `.light` / `.dark` on `<html>` before first paint and
+  exposes `window.__uiTheme` for `ThemeSwitcher`; `storageKey` (default
+  `modo-ui-theme`) keeps two sites on one origin apart.
+- The panel's narrow-screen behavior (below xl the panel is a drawer, opened on
+  hover or with `]`, never a strip above the content) comes with `chrome.css`.
+  A stylesheet that re-implements the layout instead of importing it can
+  recreate the lib's `grid-template-rows: auto` strip: a viewport-tall blank
+  row with the Theme select behind it.
+- `lucide-react` (the `Icon` slot) is already a dependency of the package;
+  the docs entry adds no other. `@justanarthur/modo-ui` itself must be a
+  dependency of the host: modo resolves the specifier from the project root.
+
 ## Tier mapping
 
 The tiers mirror the FF docs navigation. FF's "System" pages become
@@ -371,7 +441,7 @@ No ported file imports any of them.
 
 The files only they, or the FF docs site's nav, use are left out too:
 `mobile-drawer`, `nav-item`, `nav-menu`, `lib/theme-context.tsx` (the
-`ThemeSwitcher` panel item and vite.ts's pre-paint controller take its
+`ThemeSwitcher` panel item and docs/vite.ts's pre-paint controller take its
 place) and the blocks other than the sidebar's (`queued-stack`,
 `dialog-sidebar`). Inside kept files, the same rule removed
 `SURFACE_HOVER_BG`, `SURFACE_HOVER_SHADOW` and `surfaceHoverClasses` from
@@ -398,7 +468,8 @@ prebuilt `styles.css`, and turns `preset.ts` into `tailwind.css`.
 
 - **Dark mode.** `dark: 'class'` produces `.dark .dark\:x`, the same "inside a
   `.dark` ancestor" contract as FF's `@custom-variant dark (&:is(.dark *))`.
-  modo ships no theme of its own, so `vite.ts` injects a small controller into
+  modo ships no theme of its own, so `docsTheme` (`docs/vite.ts`, applied by
+  `vite.ts`) injects a small controller into
   `index.html` (`transformIndexHtml`, `head-prepend`). Before first paint it
   puts `light` or `dark` on `<html>` — the stored preference, or the OS one
   under `system` — which is also what flips every `light-dark()` token through
@@ -411,7 +482,10 @@ prebuilt `styles.css`, and turns `preset.ts` into `tailwind.css`.
   `global.css` (and the `base.css` it imports) and fixes the order of the
   layer its `@layer base` rules join.
   `vite.ts` is loaded by Node with type stripping, so it may only use erasable
-  TypeScript and hands `uno.config.ts` to UnoCSS by absolute path.
+  TypeScript, names the `.ts` extension of the one relative module it imports
+  (`./docs/vite.ts`) and hands `uno.config.ts` to UnoCSS by absolute path.
+  `docs/vite.ts` ships built (`dist/docs/vite.js`): Node never strips types
+  from a file under `node_modules`.
 - **Colors.** Theme colors point at the CSS variables directly (for example
   `accent: 'var(--accent)'`, `surface.1..8`). wind4 applies opacity modifiers
   to `var()` colors with `color-mix(in srgb, …)`, so `bg-accent/12` works on
@@ -435,7 +509,7 @@ prebuilt `styles.css`, and turns `preset.ts` into `tailwind.css`.
   after the reset, so utilities (in `default`) still win. This is the same
   arrangement as Tailwind's base/utilities split.
 - **Content.** UnoCSS scans `{lib,primitives,components,blocks}/**/*.{ts,tsx,mdx}`
-  and `modo.components.tsx` from disk (`content.filesystem`, and the same
+  from disk (`content.filesystem`, and the same
   globs in `content.pipeline.include`, since the default pipeline skips
   `.ts`). Two reasons:
   - modo serves items pre-bundled, so the sources never pass through Vite's

package/components/AI/input-message/examples.mdx

@@ -2,7 +2,9 @@ import InputMessage from './index'
 import Button from '../../button'
 import { ChevronDown, Plus } from 'lucide-react'
 
-# Basic
+# Basics
+
+## Basic
 
 No props at all: the composer keeps its own draft, grows as you type and
 clears itself on Enter.
@@ -11,7 +13,31 @@ clears itself on Enter.
   <InputMessage />
 </div>
 
-# Suggestions
+## Send Handler
+
+`onSend` receives the trimmed text and the attached files; an uncontrolled
+composer clears its own draft afterwards. The handler here is an empty
+arrow — in an app it is where the message joins the transcript.
+
+<div className="w-full max-w-xl">
+  <InputMessage
+    onSend={() => {}}
+    placeholder="Press Enter to send. Shift+Enter for newline."
+  />
+</div>
+
+## Disabled
+
+Dims the panel to 50% and drops pointer events — textarea, send button and
+drag-and-drop all go inert.
+
+<div className="w-full max-w-xl">
+  <InputMessage defaultValue="This composer is disabled" disabled />
+</div>
+
+# Content
+
+## Suggestions
 
 The ghost placeholder renders with a Tab keycap — Tab fills it into the
 composer. ArrowDown/ArrowUp walk the list below (focus stays in the
@@ -30,7 +56,7 @@ shows a ↓ hint until a row is highlighted. Typing collapses the list.
   />
 </div>
 
-# Attachments
+## Attachments
 
 `defaultFiles` seeds the composer and turns attachment behavior on: drop a
 PNG, JPEG or PDF anywhere on the panel, or use the render-fn slot's
@@ -52,7 +78,7 @@ for its × button.
   />
 </div>
 
-# Queued messages
+## Queued messages
 
 `defaultStatus="streaming"` plus `defaultQueue` runs the composer as if a
 response were in flight: the send button is a Queue action, so a typed
@@ -71,7 +97,9 @@ response, and that streaming→idle edge dispatches the row at the top.
   />
 </div>
 
-# Left Slot Only
+# Slots
+
+## Left Slot Only
 
 `leftSlot` takes the bottom-left action area — an attach button, a model
 switcher, a mode toggle.
@@ -86,7 +114,7 @@ switcher, a mode toggle.
   />
 </div>
 
-# Right Slot Only
+## Right Slot Only
 
 `rightSlot` sits in the bottom-right, just before the built-in send
 button.
@@ -100,25 +128,3 @@ button.
     }
   />
 </div>
-
-# Send Handler
-
-`onSend` receives the trimmed text and the attached files; an uncontrolled
-composer clears its own draft afterwards. The handler here is an empty
-arrow — in an app it is where the message joins the transcript.
-
-<div className="w-full max-w-xl">
-  <InputMessage
-    onSend={() => {}}
-    placeholder="Press Enter to send. Shift+Enter for newline."
-  />
-</div>
-
-# Disabled
-
-Dims the panel to 50% and drops pointer events — textarea, send button and
-drag-and-drop all go inert.
-
-<div className="w-full max-w-xl">
-  <InputMessage defaultValue="This composer is disabled" disabled />
-</div>

package/components/AI/input-message/index.tsx

@@ -924,6 +924,8 @@ const InputMessage = forwardRef<HTMLDivElement, InputMessageProps>(
         if (!clickToFocus || disabled) return
         const target = e.target as HTMLElement
         if (target === textareaRef.current) return
+        // A press in a popup portalled out of the box reaches it through the React tree only.
+        if (!e.currentTarget.contains(target)) return
         if (target.closest('button, a, input, select, textarea, [contenteditable], [role="button"], [data-im-queue]')) {
           return
         }

package/components/accordion/examples.mdx

@@ -2,7 +2,9 @@ import Accordion from './index'
 import Button from '../button'
 import { ArrowRight } from 'lucide-react'
 
-# Standalone
+# Basics
+
+## Standalone
 
 A single collapsible item with its own hover state.
 
@@ -15,7 +17,7 @@ A single collapsible item with its own hover state.
   </Accordion.Item>
 </Accordion>
 
-# Single Expand
+## Single Expand
 
 Multiple items with fluid hover — only one can be expanded at a time.
 
@@ -50,7 +52,7 @@ Multiple items with fluid hover — only one can be expanded at a time.
   </Accordion.Item>
 </Accordion.Group>
 
-# Multi Expand
+## Multi Expand
 
 Multiple items with fluid hover — several can be expanded at once.
 
@@ -75,34 +77,7 @@ Multiple items with fluid hover — several can be expanded at once.
   </Accordion.Item>
 </Accordion.Group>
 
-# Row highlight
-
-With `highlight="trigger"` an expanded item holds no tint — the fill
-scopes to the row and waits for hover. Suits dense panels, where a block
-per open item reads as a second layer.
-
-<Accordion.Group type="single" collapsible defaultValue="item-1" highlight="trigger">
-  <Accordion.Item value="item-1" index={0}>
-    <Accordion.Trigger>Expanded, but not tinted</Accordion.Trigger>
-    <Accordion.Content>
-      The panel reads as part of the page rather than a filled block.
-    </Accordion.Content>
-  </Accordion.Item>
-  <Accordion.Item value="item-2" index={1}>
-    <Accordion.Trigger>Hover any row</Accordion.Trigger>
-    <Accordion.Content>
-      The fill follows your cursor instead of marking a state.
-    </Accordion.Content>
-  </Accordion.Item>
-  <Accordion.Item value="item-3" index={2}>
-    <Accordion.Trigger>Compare with the sections above</Accordion.Trigger>
-    <Accordion.Content>
-      Those hold a block across the row and its panel while open.
-    </Accordion.Content>
-  </Accordion.Item>
-</Accordion.Group>
-
-# Morph
+## Morph
 
 Each panel drips out of the row where it was pressed (its middle, from the keyboard) and widens into the item, its content revealed by the same shape; closing folds it back into the row. The rows below ride its bottom edge.
 
@@ -130,7 +105,36 @@ Each panel drips out of the row where it was pressed (its middle, from the keybo
   </Accordion.Item>
 </Accordion.Group>
 
-# Without the goo
+# Variants
+
+## Row highlight
+
+With `highlight="trigger"` an expanded item holds no tint — the fill
+scopes to the row and waits for hover. Suits dense panels, where a block
+per open item reads as a second layer.
+
+<Accordion.Group type="single" collapsible defaultValue="item-1" highlight="trigger">
+  <Accordion.Item value="item-1" index={0}>
+    <Accordion.Trigger>Expanded, but not tinted</Accordion.Trigger>
+    <Accordion.Content>
+      The panel reads as part of the page rather than a filled block.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-2" index={1}>
+    <Accordion.Trigger>Hover any row</Accordion.Trigger>
+    <Accordion.Content>
+      The fill follows your cursor instead of marking a state.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-3" index={2}>
+    <Accordion.Trigger>Compare with the sections above</Accordion.Trigger>
+    <Accordion.Content>
+      Those hold a block across the row and its panel while open.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion.Group>
+
+## Without the goo
 
 `effect="morph"` grows the same shape with no liquid neck to its row; `tier="moderate"` runs the goo on the quicker, critically damped spring.
 
@@ -149,7 +153,7 @@ Each panel drips out of the row where it was pressed (its middle, from the keybo
   </Accordion.Item>
 </Accordion.Group>
 
-# Without the chevron
+## Without the chevron
 
 `icon={false}` drops the glyph at the row's end, for a row whose own content says it opens. A component passed as `icon` replaces the chevron and turns a quarter turn on open, so give it a right-pointing glyph.
 
@@ -174,7 +178,9 @@ Each panel drips out of the row where it was pressed (its middle, from the keybo
   </Accordion.Item>
 </Accordion.Group>
 
-# Rich headers
+# Composition
+
+## Rich headers
 
 By default the trigger renders its label twice: a hidden semibold copy reserves the width, so the label gets heavier on open without moving. A header made of components would be duplicated in the DOM, so `weightShift={false}` renders it once and leaves the weight to its content. `contentClassName` is merged over the inner row's inset, padding and muted body text: the first panel below turns its text to full strength, the second takes a wider inset and the caption size. The label lives inside the trigger `<button>`, so build it from phrasing content (spans, as below), never a `div`-based header. Text that fixes its own colour stays that colour when the item opens: the chevron, the highlight and the open tint are what signal the state.
 
@@ -203,7 +209,7 @@ By default the trigger renders its label twice: a hidden semibold copy reserves
   </Accordion.Item>
 </Accordion.Group>
 
-# Your own trigger
+## Your own trigger
 
 `asChild` (or `render`) makes your element the trigger, so a Button, a link-styled control or anything else can open the item. It is rendered as it is: the row's label copy, the chevron and the row padding are not added, so the element brings its own content and look. Base UI still wires `aria-expanded`, `aria-controls`, `data-panel-open` and the keys onto it, so style the open state with `data-[panel-open]`.
 

package/components/badge/examples.mdx

@@ -1,7 +1,9 @@
 import Badge from './index'
 import ChangeDemo from './change-demo'
 
-# Solid
+# Variants
+
+## Solid
 
 The default variant: a tinted background in the badge's color.
 
@@ -13,7 +15,7 @@ The default variant: a tinted background in the badge's color.
   <Badge color="rose">Poetry</Badge>
 </div>
 
-# Dot
+## Dot
 
 `variant="dot"` keeps a neutral bordered badge and shows the color as an
 indicator dot.
@@ -26,7 +28,7 @@ indicator dot.
   <Badge variant="dot" color="rose">Poetry</Badge>
 </div>
 
-# Outline
+## Outline
 
 `variant="outline"` is the dot badge's neutral frame without the dot: a label
 that carries no status.
@@ -37,22 +39,7 @@ that carries no status.
   <Badge variant="outline" size="compact">Archived</Badge>
 </div>
 
-# Status mapping
-
-Hosts with a shadcn-style badge map its variants onto a hue: default and
-secondary → `gray`, destructive → `red`, success → `green`, outline →
-`variant="outline"`. The tint stays a wash with foreground text, never a solid
-fill.
-
-<div className="flex flex-wrap items-center gap-2">
-  <Badge color="gray">Default</Badge>
-  <Badge color="gray">Secondary</Badge>
-  <Badge color="red">Destructive</Badge>
-  <Badge color="green">Success</Badge>
-  <Badge variant="outline">Outline</Badge>
-</div>
-
-# Colors
+## Colors
 
 All seventeen palette colors, solid and dot.
 
@@ -73,18 +60,24 @@ All seventeen palette colors, solid and dot.
   </div>
 </div>
 
-# Compact
+# Usage
 
-`size="compact"` steps the badge down the size ladder (20px tall, 11px
-text) for dense rows and table cells.
+## Status mapping
+
+Hosts with a shadcn-style badge map its variants onto a hue: default and
+secondary → `gray`, destructive → `red`, success → `green`, outline →
+`variant="outline"`. The tint stays a wash with foreground text, never a solid
+fill.
 
 <div className="flex flex-wrap items-center gap-2">
-  <Badge size="compact" color="blue">History</Badge>
-  <Badge size="compact" variant="dot" color="green">Philosophy</Badge>
-  <Badge size="compact">Draft</Badge>
+  <Badge color="gray">Default</Badge>
+  <Badge color="gray">Secondary</Badge>
+  <Badge color="red">Destructive</Badge>
+  <Badge color="green">Success</Badge>
+  <Badge variant="outline">Outline</Badge>
 </div>
 
-# Changes
+## Changes
 
 Press a button. A new label springs the badge to its new width while the
 text crossfades, a new color fades in, and the dot slides in or out with
@@ -118,3 +111,14 @@ the variant. `ChangeDemo` is a docs stage: a Badge that steps through its
     ]}
   />
 </div>
+
+## Compact
+
+`size="compact"` steps the badge down the size ladder (20px tall, 11px
+text) for dense rows and table cells.
+
+<div className="flex flex-wrap items-center gap-2">
+  <Badge size="compact" color="blue">History</Badge>
+  <Badge size="compact" variant="dot" color="green">Philosophy</Badge>
+  <Badge size="compact">Draft</Badge>
+</div>