themelia-ui 1.0.3 → 2.0.0

package/.agents/skills/themelia-ui/references/components/base--cards.md

@@ -42,7 +42,7 @@ Kind: callable.
 **Alternatives:** ContentBlock, Overlay.
 
 ```text
-({ icon, title, titleSuffix, tooltip, description, surface, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps) => React.JSX.Element
+({ icon, title, titleSuffix, tooltip, description, surface, titleLevel, media, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps) => React.JSX.Element
 ```
 
 ### `CardAction`
@@ -105,25 +105,19 @@ Kind: callable.
 
 Kind: callable.
 
-The header region.
-
-A single row of title-line content with trailing controls pushed to the end, plus an
-optional full-width row above it. The title truncates rather than pushing the controls
-off the row — a header that reflows when a name gets longer is the usual failure.
+The header region: a title row with trailing controls, plus an optional full-width row
+above. The title truncates rather than pushing the controls off the row.
 
 ```text
-({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & { icon?: React.ReactNode; title?: React.ReactNode; titleSuffix?: React.ReactNode; tooltip?: React.ReactNode; tooltipLabel?: string; description?: React.ReactNode; headerStart?: React.ReactNode; headerEnd?: React.ReactNode; headerAction?: React.ReactNode; divider?: boolean; }) => React.JSX.Element
+({ icon, title, titleSuffix, tooltip, tooltipLabel, description, headerStart, headerEnd, headerAction, divider, titleLevel, className, ...props }: Omit<React.ComponentProps<"div">, "title"> & { icon?: React.ReactNode; title?: React.ReactNode; titleSuffix?: React.ReactNode; tooltip?: React.ReactNode; tooltipLabel?: string; description?: React.ReactNode; headerStart?: React.ReactNode; headerEnd?: React.ReactNode; headerAction?: React.ReactNode; divider?: boolean; titleLevel?: 1 | 2 | 3 | 4 | 5 | 6; }) => React.JSX.Element
 ```
 
 ### `CardPrimaryAction`
 
 Kind: callable.
 
-Makes a whole card one target.
-
-A covering link rather than a wrapping one: wrapping the card in an anchor nests its
-buttons and menus inside it, which is invalid and makes them unreachable. This sits
-behind the content, and anything interactive is lifted above it in CSS.
+Makes a whole card one target with a covering link (wrapping the card would nest its
+controls inside an anchor). Interactive children are lifted above it in CSS.
 
 ```text
 ({ label, className, ...props }: CardPrimaryActionProps) => import("react").JSX.Element
@@ -150,13 +144,15 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 | `icon` | no | `React.ReactNode` | Leading glyph on the title line. |
 | `title` | no | `React.ReactNode` |  |
 | `titleSuffix` | no | `React.ReactNode` | Badges, status, or counts immediately after the title. |
-| `tooltip` | no | `React.ReactNode` | Explanatory copy behind an info affordance on the title line.<br><br>For the sentence that would make the description too long — a definition, a caveat,<br>how a number was arrived at. It is a real focusable control, not a title attribute,<br>so a keyboard reader can reach it. |
+| `tooltip` | no | `React.ReactNode` | Explanatory copy behind a focusable info button on the title line — for a definition or<br>caveat too long for the description. |
 | `description` | no | `React.ReactNode` |  |
 | `surface` | no | `CardSurface` | Outer chrome. |
 | `headerStart` | no | `React.ReactNode` | Full-width row above the title — an eyebrow or breadcrumb. Rare. |
 | `headerEnd` | no | `React.ReactNode` | Metadata or a secondary control before the action and overflow menu. |
 | `headerAction` | no | `React.ReactNode` | A single control at the end of the header. Use `actions` for a list of commands. |
 | `actions` | no | `CardAction[]` | Overflow commands, collapsed into one menu trigger. |
+| `titleLevel` | no | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Renders the title as a heading of this level. Unset, the title is a span that heading<br>navigation can't find; set it when the card titles a page section. |
+| `media` | no | `React.ReactNode` | A full-bleed strip above the header — a cover image, an illustration, a preview. |
 | `alert` | no | `React.ReactNode` | Banner between header and content. A plain string is wrapped for you. |
 | `alertTone` | no | `CardAlertTone` |  |
 | `contentTop` | no | `React.ReactNode` |  |
@@ -165,7 +161,7 @@ Extends: `Omit<React.ComponentProps<"div">, "title">`.
 | `footerSlot` | no | `React.ReactNode` | Footer band under the content — a single primary action fits well here. |
 | `headerDivider` | no | `boolean` |  |
 | `footerDivider` | no | `boolean` |  |
-| `expandable` | no | `boolean \| { collapsedMaxHeight?: number \| string; }` | Clips the content to a collapsed height with a fade, and adds a toggle.<br>Clips content to a collapsed height with a fade, and adds a toggle.<br><br>The object form sets the height for this card only; the bare `true` uses<br>`--card-collapsed-height`. A fixed token is right for a grid of equal cards and<br>wrong for one card whose natural fold is somewhere else. |
+| `expandable` | no | `boolean \| { collapsedMaxHeight?: number \| string; }` | Clips content to a collapsed height with a fade, and adds a toggle. `true` uses<br>`--card-collapsed-height`; the object form sets the height for this card only. |
 | `expanded` | no | `boolean` |  |
 | `defaultExpanded` | no | `boolean` |  |
 | `onExpandedChange` | no | `(expanded: boolean) => void` |  |
@@ -187,7 +183,7 @@ Extends: `Omit<ComponentProps<"div">, "title">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `surface` | no | `CardSurface` | Match the real card, or the placeholder is the wrong shape. |
+| `surface` | no | `CardSurface` | Match the real card's surface. Unset, it takes the card's default (the provider's<br>`defaults.card.surface`, framed out of the box). |
 | `showHeader` | no | `boolean` | Reserves the header's height. |
 | `lines` | no | `number` |  |
 | `label` | no | `string` |  |

package/.agents/skills/themelia-ui/references/components/base--carousel.md

@@ -122,13 +122,6 @@ Kind: callable.
 
 Kind: interface.
 
-The compound parts.
-
-`Carousel` with children is the whole story for most cases. These exist for a track
-whose controls belong somewhere the single component cannot put them — beside a
-heading, in a card footer — and they read the same context, so the two APIs cannot
-disagree about which slide is current.
-
 Extends: `ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
@@ -145,7 +138,7 @@ Kind: interface.
 | `previous` | yes | `string` | The controls are icon-only, so these are the only names they have. |
 | `next` | yes | `string` |  |
 | `goToSlide` | yes | `(index: number) => string` | Accessible name for a pagination dot, by the slide it jumps to. |
-| `roleDescription` | yes | `string` | What the region and each slide ARE, announced before their name.<br><br>`aria-roledescription` is read aloud, so it is copy — it was the one accessible<br>string in this family still written into the markup as English. |
+| `roleDescription` | yes | `string` | What the region and each slide are (`aria-roledescription`), announced before their name. |
 | `slideRoleDescription` | yes | `string` |  |
 
 ### `defaultCarouselStrings`

package/.agents/skills/themelia-ui/references/components/base--chart.md

@@ -50,7 +50,7 @@ Record<string, ChartSeriesConfig>
 Kind: callable.
 
 ```text
-({ config, className, children, style, ...props }: ChartContainerProps) => React.JSX.Element
+({ config, label, description, className, children, style, ...props }: ChartContainerProps) => React.JSX.Element
 ```
 
 ### `ChartContainerProps`
@@ -63,13 +63,15 @@ Extends: `Omit<React.ComponentProps<"div">, "children">`.
 | --- | :-: | --- | --- |
 | `config` | yes | `ChartConfig` |  |
 | `children` | yes | `React.ComponentProps<typeof Recharts.ResponsiveContainer>["children"]` |  |
+| `label` | no | `string` | What the chart shows, as a sentence a screen reader can speak ("Monthly revenue against<br>expenses, January to June"). Without it the focusable plot is announced by its tick text. |
+| `description` | no | `string` | A longer summary of the data or its takeaway, read after the label. |
 
 ### `ChartLegend`
 
-Kind: const.
+Kind: callable.
 
 ```text
-React.MemoExoticComponent<(outsideProps: Recharts.LegendProps) => React.ReactPortal | null>
+({ itemSorter, ...props }: React.ComponentProps<typeof Recharts.Legend>) => React.JSX.Element
 ```
 
 ### `ChartLegendContent`
@@ -170,7 +172,7 @@ Extends: `Omit<React.ComponentProps<"div">, "children">`.
 | --- | :-: | --- | --- |
 | `data` | yes | `readonly number[]` | The series, in chronological order. |
 | `tone` | no | `SemanticTone` | Colours the stroke and its fade. |
-| `animated` | no | `boolean` | Off by default.<br><br>A sparkline is usually one of many on a dashboard, and a screenful of them all<br>drawing themselves at once reads as the page malfunctioning rather than as motion. |
+| `animated` | no | `boolean` | Off by default: many sparklines animating at once reads as a malfunction. |
 | `label` | no | `string` | What the shape says. Without it the chart is decorative and hidden from readers. |
 
 ## Preview recipes
@@ -185,7 +187,7 @@ const config = {
   expenses: { label: "Expenses", color: "var(--chart-2)" },
 } satisfies ChartConfig
 
-<ChartContainer config={config}>
+<ChartContainer config={config} label="Monthly revenue and expenses">
   <BarChart data={data}>
     <CartesianGrid vertical={false} />
     <XAxis dataKey="month" tickLine={false} axisLine={false} />

package/.agents/skills/themelia-ui/references/components/base--choice-inputs.md

@@ -110,9 +110,8 @@ Extends: `Omit<React.ComponentProps<"input">, "type" | "size">`.
 
 Kind: type.
 
-There is no `size` on any of these. Geometry comes from `--density-scale`, so a card
-group and the pill group beside it cannot end up at different densities. See
-styles/FACTORS.md.
+Column cap for card groups. There is no `size` prop: geometry follows `--density-scale`
+(styles/FACTORS.md).
 
 ```text
 1 | 2 | 3 | 4
@@ -128,16 +127,15 @@ Kind: interface.
 | `disabled` | no | `boolean` | Disables every option. |
 | `invalid` | no | `boolean` | Applies the invalid treatment. Pair it with a message on the FormField. |
 | `className` | no | `string` |  |
+| `"aria-label"` | no | `string` |  |
+| `"aria-labelledby"` | no | `string` |  |
+| `"aria-describedby"` | no | `string` |  |
 
 ### `ChoiceOption`
 
 Kind: interface.
 
-One option, shared across every choice group — card, list, and pill.
-
-The shape is deliberately the same in all four: a settings page that uses cards for
-one question and a list for the next should not need two option shapes, and the moment
-it does the two drift.
+One option shape shared by every choice group — card, list and pill — so they can't drift.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
@@ -145,7 +143,7 @@ it does the two drift.
 | `label` | yes | `ReactNode` |  |
 | `description` | no | `ReactNode` | Supporting sentence. Card and list groups show it; a pill has no room for one. |
 | `icon` | no | `ComponentType<{ className?: string; }> \| ReactNode` | Leading glyph. A Lucide icon, any component taking a className, or a rendered node. |
-| `tooltip` | no | `ReactNode` | Detail that does not fit the row, behind an info affordance beside the label.<br>A real button, so it is reachable from the keyboard — a tooltip that only opens on<br>hover is invisible to anyone not using a mouse. |
+| `tooltip` | no | `ReactNode` | Detail that doesn't fit the row, shown in a tooltip from an info glyph beside the label.<br>The glyph isn't focusable; the text also becomes the option's accessible description. |
 | `disabled` | no | `boolean` |  |
 
 ### `defaultSelectStrings`
@@ -335,7 +333,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `options` | yes | `SelectOption[]` |  |
-| `placeholder` | no | `string` | Shown while nothing is selected.<br>Shorthand for `strings.placeholder`. |
+| `placeholder` | no | `string` | Shorthand for `strings.placeholder`. |
 | `strings` | no | `Partial<SelectStrings>` | Overrides this select's own copy — the placeholder and the clear row. |
 | `allowClear` | no | `boolean` | Prepends an option that clears the selection. |
 | `invalid` | no | `boolean` | Applies the invalid treatment. Pair it with a message on the FormField. |
@@ -422,19 +420,11 @@ import('react').ForwardRefExoticComponent<SwitchCardProps & import('react').RefA
 
 Kind: interface.
 
+Extends: `Omit<ToggleFieldProps, "kind" | "surface" | "controlPosition" | "uncheckedValue" | "label">`.
+
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `label` | yes | `string` | Card title, and the switch's accessible name. |
-| `description` | no | `ReactNode` |  |
-| `hint` | no | `ReactNode` | Short guidance below the description. |
-| `icon` | no | `ChoiceOption["icon"]` |  |
-| `name` | no | `string` |  |
-| `value` | no | `boolean` | Controlled state. |
-| `defaultValue` | no | `boolean` |  |
-| `onValueChange` | no | `(checked: boolean) => void` |  |
-| `disabled` | no | `boolean` |  |
-| `invalid` | no | `boolean` |  |
-| `className` | no | `string` |  |
 
 ### `SwitchProps`
 
@@ -470,68 +460,62 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `label` | yes | `ReactNode` |  |
 | `description` | no | `ReactNode` |  |
+| `hint` | no | `ReactNode` | Short guidance under the description. |
+| `icon` | no | `ChoiceOption["icon"]` | Leading glyph, drawn in a medallion. Most at home on `surface="card"`. |
 | `kind` | no | `ToggleFieldKind` | Which control renders. |
+| `surface` | no | `"row" \| "card"` | `row` is a plain settings row; `card` is a bordered card that takes the checked<br>colour — the form `SwitchCard` presets. |
 | `value` | no | `boolean` | Controlled state. |
 | `defaultValue` | no | `boolean` |  |
 | `onValueChange` | no | `(checked: boolean) => void` |  |
 | `disabled` | no | `boolean` |  |
 | `invalid` | no | `boolean` |  |
 | `name` | no | `string` |  |
+| `uncheckedValue` | no | `string` | What the field submits when off. Unset, an unchecked control submits nothing (the<br>platform rule). Set, a hidden input always submits `"1"` when on and this when off.<br>`SwitchCard` sets `"0"`. |
 | `controlPosition` | no | `"leading" \| "trailing"` | Puts the control on the leading edge instead of the trailing one. |
 | `className` | no | `string` |  |
 
 ## Preview recipes
 
-Preview route: Card radio group — `/card-radio-group`
+Preview route: Checkbox — `/checkbox`
 
-### CardRadioGroup
+### Checkbox
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<CardRadioGroup
-  options={plans}
-  value={plan}
-  onValueChange={setPlan}
-  columns={3}
-/>
+<Checkbox label="Checked" defaultChecked />
+<Checkbox label="Indeterminate" indeterminate />
 ```
 
-### CardCheckboxGroup
+### Radio group
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<CardCheckboxGroup
-  options={channels}
-  value={selected}
-  onValueChange={setSelected}
-  columns={4}
-/>
+<RadioGroup name="shipping">
+  <Radio label="Standard" value="standard" defaultChecked />
+  <Radio label="Express" value="express" />
+</RadioGroup>
 ```
 
-### Checkbox
+### Cards
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<Checkbox label="Checked" defaultChecked />
-<Checkbox label="Indeterminate" indeterminate />
+<CardRadioGroup options={plans} value={plan} onValueChange={setPlan} columns={3} />
 ```
 
-### ListRadioGroup
+### Cards, several at once
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<ListRadioGroup options={roles} value={role} onValueChange={setRole} />
+<CardCheckboxGroup options={channels} value={selected} onValueChange={setSelected} columns={4} />
 ```
 
-### PillRadioGroup
+### List
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<PillRadioGroup options={views} value={view} onValueChange={setView} allowClear />
+<ListRadioGroup options={roles} value={role} onValueChange={setRole} />
 ```
 
-### Radio group
+### Pills
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<RadioGroup name="plan">
-  <Radio label="Free" value="free" />
-  <Radio label="Pro" value="pro" defaultChecked />
-</RadioGroup>
+<PillRadioGroup options={views} value={view} onValueChange={setView} allowClear />
 ```
 
 ### Select
@@ -551,9 +535,10 @@ Preview route: Card radio group — `/card-radio-group`
 <Switch label="Email notifications" defaultChecked />
 ```
 
-### SwitchCard and ToggleField
+### Settings rows and feature cards
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 <SwitchCard label="Two-factor authentication" icon={ShieldIcon} description="…" />
 <ToggleField label="Email notifications" description="…" />
+<ToggleField surface="card" kind="checkbox" label="Usage reports" />
 ```

package/.agents/skills/themelia-ui/references/components/base--combobox.md

@@ -47,8 +47,13 @@ Kind: callable.
 
 Kind: callable.
 
+One selection inside `ComboboxChips`, with its remove control.
+
+The remove control is named from the chip's text, so pass the label as plain text. For
+a chip with richer content, `strings.removeChip` supplies the name instead.
+
 ```text
-({ className, children, ...props }: ComboboxPrimitive.Chip.Props) => import("react").JSX.Element
+({ className, children, strings, ...props }: ComboboxPrimitive.Chip.Props & { strings?: Partial<Pick<ComboboxStrings, "removeChip">>; }) => import("react").JSX.Element
 ```
 
 ### `ComboboxChips`
@@ -119,12 +124,11 @@ Kind: callable.
 
 Kind: callable.
 
-The input with its trailing chevron, and optionally a clear button — the shape a
-searchable combobox almost always wants, with the padding that keeps the text clear of
-both computed rather than guessed.
+The input with its trailing chevron and optional clear button, padded so text never
+runs under them. `strings` names the two trailing controls.
 
 ```text
-({ className, showClear, invalid, ...props }: ComboboxPrimitive.Input.Props & { showClear?: boolean; invalid?: boolean; }) => import("react").JSX.Element
+({ className, showClear, invalid, strings, ...props }: ComboboxPrimitive.Input.Props & { showClear?: boolean; invalid?: boolean; strings?: Partial<Pick<ComboboxStrings, "clear" | "toggle">>; }) => import("react").JSX.Element
 ```
 
 ### `ComboboxItem`
@@ -161,12 +165,26 @@ Kind: callable.
 ({ className, ...props }: ComboboxPrimitive.Popup.Props) => import("react").JSX.Element
 ```
 
+### `ComboboxPopupInput`
+
+Kind: callable.
+
+The search band inside the popup, for the `ComboboxTrigger` shape: focus lands here when
+the popup opens, typing filters the list, and the arrow keys and Enter drive it. Give it
+an `aria-label` — its placeholder is not a name.
+
+```text
+({ className, ...props }: ComboboxPrimitive.Input.Props) => import("react").JSX.Element
+```
+
 ### `ComboboxPortal`
 
-Kind: const.
+Kind: callable.
+
+The popup's portal, routed through the nearest `UIPortalHost` like every kit popup.
 
 ```text
-import('react').ForwardRefExoticComponent<Omit<import('@base-ui/react').AutocompletePortalProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>
+({ container, ...props }: ComboboxPrimitive.Portal.Props) => import("react").JSX.Element
 ```
 
 ### `ComboboxPositioner`
@@ -211,13 +229,15 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `clear` | yes | `string` | Accessible name for the field's clear control. |
 | `toggle` | yes | `string` | Accessible name for the control that opens the list. |
-| `removeChip` | yes | `(label: string) => string` | Accessible name for a chip's remove control.<br><br>Takes the chip's own text, because "Remove" repeated down a row of eight chips tells<br>a screen-reader user which control they are on and nothing about what it removes. |
+| `removeChip` | yes | `(label: string) => string` | Accessible name for a chip's remove control, from the chip's text so it says what it removes. |
 
 ### `ComboboxTrigger`
 
 Kind: callable.
 
-The whole field as one trigger — a select-like combobox with no free text.
+The whole field as one trigger — a select-like combobox with no free text. Pair it with
+`ComboboxPopupInput`: Base UI drives the list's keyboard cursor from an input. For a
+short list with no search, use `Select`.
 
 ```text
 ({ className, children, ...props }: ComboboxPrimitive.Trigger.Props) => import("react").JSX.Element
@@ -251,7 +271,7 @@ typeof ComboboxPrimitive.useFilter
 
 Preview route: Combobox — `/combobox`
 
-### One field surface
+### The pickers do not filter
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 <ComboboxInputTrigger placeholder="Search…" showClear />
@@ -263,6 +283,15 @@ Preview route: Combobox — `/combobox`
 <ComboboxTrigger>
   <ComboboxValue placeholder="Choose a country" />
 </ComboboxTrigger>
+<ComboboxPortal>
+  <ComboboxPositioner>
+    <ComboboxPopup>
+      <ComboboxPopupInput aria-label="Search countries" placeholder="Search countries" />
+      <ComboboxEmpty>No country matches.</ComboboxEmpty>
+      <ComboboxList>…</ComboboxList>
+    </ComboboxPopup>
+  </ComboboxPositioner>
+</ComboboxPortal>
 ```
 
 ### Multiple

package/.agents/skills/themelia-ui/references/components/base--command.md

@@ -20,7 +20,7 @@ import "themelia-ui/base/command.css"
 
 ## Composition
 
-This family composes `base/dialog`, `base/input-group`.
+This family composes `base/dialog`, `base/input-group`, `base/overlay`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -48,7 +48,7 @@ Kind: callable.
 Kind: type.
 
 ```text
-Omit<React.ComponentProps<typeof Dialog>, "children"> & { title?: string; description?: string; strings?: Partial<CommandStrings>; commandProps?: CommandProps; className?: string; showCloseButton?: boolean; children: React.ReactNode; }
+Omit<OverlayRootProps, "children"> & { title?: string; description?: string; strings?: Partial<CommandStrings>; commandProps?: CommandProps; className?: string; showCloseButton?: boolean; children: React.ReactNode; }
 ```
 
 ### `CommandEmpty`
@@ -64,7 +64,7 @@ Kind: callable.
 Kind: callable.
 
 ```text
-({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Group>) => React.JSX.Element
+({ className, ref, ...props }: React.ComponentProps<typeof CommandPrimitive.Group>) => React.JSX.Element
 ```
 
 ### `CommandInput`
@@ -80,7 +80,7 @@ Kind: callable.
 Kind: callable.
 
 ```text
-({ className, children, ...props }: React.ComponentProps<typeof CommandPrimitive.Item>) => React.JSX.Element
+({ className, children, ref, ...props }: React.ComponentProps<typeof CommandPrimitive.Item>) => React.JSX.Element
 ```
 
 ### `CommandList`
@@ -121,9 +121,8 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `title` | yes | `string` | Names the dialog. Hidden from view — the palette's field is the visible label. |
+| `title` | yes | `string` | Names the dialog (visually hidden; the search field is the visible cue). |
 | `description` | yes | `string` | Describes it to assistive technology, also hidden. |
-| `empty` | yes | `string` | Shown when the query matches nothing. |
 
 ### `defaultCommandStrings`
 
@@ -135,7 +134,7 @@ CommandStrings
 
 ## Preview recipes
 
-Preview route: Command — `/command`
+Preview route: Command palette — `/command`
 
 ### Command
 

package/.agents/skills/themelia-ui/references/components/base--context-menu.md

@@ -159,9 +159,9 @@ The region a right-click opens the menu over.
 
 ## Preview recipes
 
-Preview route: Context menu — `/context-menu`
+Preview route: Dropdown & context menu — `/dropdown-menu`
 
-### Context menu
+### Opened by right-click
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
 <ContextMenu>

package/.agents/skills/themelia-ui/references/components/base--copyable.md

@@ -47,7 +47,7 @@ Extends: `Omit<ComponentPropsWithoutRef<"span">, "children" | "onCopy" | "onErro
 | `displayValue` | no | `ReactNode` | Display content, when it differs from the copied value. |
 | `mono` | no | `boolean` | Monospace the display content. For ids, keys, and hashes. |
 | `truncate` | no | `boolean` | Truncates the display content at the width the caller allots. |
-| `compact` | no | `boolean` | Sizes the trigger to the TEXT rather than to a control.<br><br>A copy button is a control, and a control is 36px tall — which is right beside a<br>field and wrong inside a list row, where the value is a description under a title.<br>At full height the affordance was twice the height of the line it belonged to, and<br>the row's own rhythm bent around it. Compact keeps every behaviour, and gives up only<br>the pointer target a standalone control is entitled to. |
+| `compact` | no | `boolean` | Sizes the trigger to the text rather than a control's height, for values inside a list<br>row. The target keeps its minimum hit area. |
 | `strings` | no | `Partial<CopyableStrings>` | Overrides this control's own copy. |
 | `silent` | no | `boolean` | Suppresses the toasts. The copied state on the control is the confirmation then. |
 | `buttonProps` | no | `Omit<ButtonProps, "children" \| "onClick" \| "type">` |  |
@@ -62,7 +62,7 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `copy` | yes | `string` | Accessible name for the control before it has been used. |
 | `copied` | yes | `string` | Accessible name while the copied state is showing. The name IS the state here. |
-| `success` | yes | `string` | Toast raised on success. `null` on the prop suppresses the toast entirely. |
+| `success` | yes | `string` | Toast raised on success. The component's `silent` prop suppresses toasts. |
 | `error` | yes | `string` | Toast raised when the clipboard write is refused — no permission, no secure context. |
 
 ### `defaultCopyableStrings`
@@ -85,24 +85,14 @@ Kind: callable.
 
 Kind: interface.
 
-Copy a value, confirm it, and reset — the behaviour five surfaces had written out.
-
-`Copyable` owned a careful version of this and four other places re-implemented it:
-both AI-chat surfaces, the theme tweaker's export panel, and the docs site's code block.
-They disagreed, and the disagreements were defects — the docs block wrote to the
-clipboard without checking there is one, never caught the rejection when there is not,
-and set state from a timeout it never cleared.
-
-── Why a counter and not a boolean ──────────────────────────────────────────────────
-Setting a boolean that is already `true` is a no-op: React bails out, the effect never
-re-runs, and the second copy inherits whatever was left of the first one's window.
-Copying twice in a row then flashes the confirmation for a fraction of a second. A
-counter changes on every copy, so each one restarts the window.
+Copy a value, confirm it, and reset — the shared implementation for every copy surface.
+The window is keyed off a counter, not a boolean: re-setting `true` is a no-op, so a
+second copy would inherit the first one's remaining window.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `confirmMs` | no | `number` | How long the confirmation stands. |
-| `write` | no | `(value: string) => void \| Promise<void>` | Where the value goes, when it is not the platform clipboard.<br><br>The theme tweaker takes a writer from its caller so an embedding app can handle the<br>environments where `navigator.clipboard` is absent — a webview, an insecure origin. |
+| `confirmMs` | no | `number` | How long the confirmation stands, in ms. Defaults to 2000, Copyable's window. |
+| `write` | no | `(value: string) => void \| Promise<void>` | Where the value goes when it is not the platform clipboard — for environments without<br>`navigator.clipboard` (webviews, insecure origins). |
 | `onCopy` | no | `(value: string) => void` |  |
 | `onError` | no | `(error: unknown) => void` |  |