@cube-dev/ui-kit 0.162.0 → 0.164.0

package/docs/Usage.md

@@ -142,6 +142,33 @@ The neutral palette uses a `surface` / `surface-text` model. Each surface depth
 | `#overlay` | Dim backdrop (50% transparent) |
 | `#clear` | `transparent` |
 
+### Context Hooks
+
+Tokens a **container** sets to steer a component that cannot resolve the color on
+its own. They ship with a default, so nothing has to be set unless the default is
+wrong.
+
+| Token | Default | Role |
+|-------|---------|------|
+| `#current-fill` | `#surface` | The label color `current.primary` punches out of its `currentcolor` chip — read by that one flavour and nothing else |
+
+`theme="current" type="primary"` fills with the color it **inherits**, so its
+label cannot come from that color too and reads `#current-fill` instead. The page
+(`#surface`) is the right answer almost everywhere, and wrong in exactly one
+place: a container whose own text color is the page paints `#white`, which *is*
+`#surface` in light mode, so the label would vanish into its own chip. Such a container sets
+the token to its own fill, which contrasts with its own text by construction:
+
+```jsx
+<Block fill="#fixed-dark" color="#white" styles={{ '#current-fill': '#fixed-dark' }}>
+  <Button theme="current" type="primary">Legible in both schemes</Button>
+</Block>
+```
+
+Setting it moves the label, the icon slots and the chip's rim together. It also
+takes the alpha suffix like any other token (`#current-fill.5` is the disabled
+label), because it is a declared token rather than a bare custom property.
+
 ### Accent System
 
 Each themed color (default, primary, success, danger, warning, note) provides an `accent-*` family anchored to a fixed white "accent surface text". These tokens stay recognizable across schemes (used for branded buttons, CTAs, etc.):
@@ -179,7 +206,7 @@ For example, a success banner uses `fill: '#success-surface'` + `color: '#succes
 ```ts
 import { resetPaletteConfig, setPaletteConfig } from '@cube-dev/ui-kit';
 
-setPaletteConfig({ hue: 210, themes: { danger: { hue: 12 } } });
+setPaletteConfig({ accent: { hue: 210 }, themes: { danger: '#b91c1c' } });
 resetPaletteConfig();
 ```
 
@@ -188,7 +215,7 @@ Also available: `getPaletteConfig()`, `subscribePaletteConfig()`, the `usePalett
 To theme a *region* instead of the document — a theme preview, or a dark panel inside a light page — use `renderColorTokens()`. It resolves one config and one scheme to flat values you apply via a `tokens` prop, without touching the live palette:
 
 ```tsx
-<Block tokens={renderColorTokens({ hue: 210, scheme: 'dark' })} fill="#surface">
+<Block tokens={renderColorTokens({ accent: { hue: 210 }, scheme: 'dark' })} fill="#surface">
   …
 </Block>
 ```
@@ -306,6 +333,7 @@ Component themes are set via the `theme` prop or `theme=name` modifier:
 | `success` | Success / positive states |
 | `warning` | Warning / caution states |
 | `note` | Informational / note states |
+| `current` | No palette of its own — every color is mixed from the inherited text color (`#current`), so the component adopts whatever its container paints with. Supported by `Button`, `Item` (and `ItemButton`, `Item.Action`, `ItemBadge`) |
 
 ## Recipes
 
@@ -367,6 +395,13 @@ Icons live in `src/icons/`. Use existing icons when possible; otherwise use `@ta
 - Always wrap tabler icons with `<Icon>` for custom size/color. Never add props directly to tabler icons.
 - To add new icons run: `pnpm add-icons`
 
+Illustrations are not icons and do not live in `src/icons/`: `CubeLogo` and
+`NoDataIcon` are `Icon`-based components under `src/components/other/`. They size
+like an icon, but `NoDataIcon` is a three-tone drawing on the shared cube-face
+tokens (`#loading-face-1` … `#loading-face-3`) rather than a `currentColor`
+glyph, so it ignores `color` and belongs at illustration sizes (`size="8x"` and
+up).
+
 ## Form System
 
 ### Form Component

package/docs/components/Root.md

@@ -13,7 +13,7 @@ The root application wrapper. Provides theme context, global styles, portal cont
 - **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
 - **`tracking`** `TrackingProps` — Analytics/tracking event configuration
 - **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
-- **`palette`** `PaletteConfig` — Tune the generated color palette: brand `hue` / `saturation`, per-status theme seeds, `pastel`, `contrastLevel`. Applied during render, so the first paint is already correct. Describes the whole palette, so dropping a field drops that customization. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
+- **`palette`** `PaletteConfig` — Tune the generated color palette. Every zone — `accent`, `base` and each status theme — takes the same seed: a color, or `{ hue, saturation }`. Plus the global `surfaceMode`, `pastel` and `contrastLevel`. Applied during render, so the first paint is already correct. Describes the whole palette, so dropping a field drops that customization. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
 - **`fonts`** `boolean` — Whether to load default fonts
 - **`font`** `string` — Custom font family name
 - **`monospaceFont`** `string` — Custom monospace font family name

package/docs/components/actions/Button.md

@@ -15,8 +15,8 @@ A versatile action component that triggers commands and navigates users.
 
 ## Properties
 
-- **`type`** `'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'current'` (default: `outline`) — Visual style variant of the button (`outline-2` is identical to `outline` but uses `#surface-3` as the base fill; not available for the `special` theme. `current` derives its colors from the inherited text color and ignores `theme`)
-- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
+- **`type`** `'primary' | 'outline' | 'outline-2' | 'clear' | 'link'` (default: `outline`) — Visual style variant of the button (`outline-2` is identical to `outline` but uses `#surface-3` as the base fill; not available for the `special` theme)
+- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special' | 'current'` (default: `default`) — Semantic colour palette theme. `current` is not a brand palette: it mixes every color from the inherited text color, so the button adopts the color of whatever container it sits in
 - **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Button size. Use `'inline'` for link-type buttons or a number/string for custom sizes (e.g. `64` or `'8x'`)
 - **`icon`** — Icon rendered before the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
 - **`rightIcon`** — Icon rendered after the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
@@ -82,7 +82,6 @@ The `mods` prop accepts the following modifiers you can override:
 - `outline` – Border with transparent background; `isSelected` adds brand-tinted fill.
 - `clear` – No border, transparent background; `isSelected` adds brand-tinted fill.
 - `link` – Styled as a textual link.
-- `current` – Fill, border and label are mixed from the inherited text color (`#current`), so the button adopts the color of whatever container it sits in. The resting chip is a `#current.03` fill inside a `#current.08` border, and hover, pressed and selected step the same alpha ramp up from there; the label stays fully opaque. The focus ring stays `#primary-accent-text`, like every other type. Theme-agnostic — there is a single variant, and `theme` has no effect. Use it inside colored containers (alerts, banners, dark overlays, tooltips). `Item` has a `current` type too, shaped like its neutral `item` type instead: borderless and invisible at rest.
 
 ### Themes. `theme` prop
 
@@ -92,6 +91,13 @@ The `mods` prop accepts the following modifiers you can override:
 - `warning` – Yellow/amber palette for caution or attention.
 - `note` – Violet palette for informational context.
 - `special` – White palette for dark backgrounds.
+- `current` – Not a palette at all: fill, border and label are mixed from the inherited text color (`#current`), so the button adopts the color of whatever container it sits in and keeps adopting it if that color changes. Every `type` has a `current` flavour, so the shape is still yours to pick — `outline` is the resting `#current.03` chip inside a `#current.08` border, `primary` escalates the same construction to a filled chip, `clear` paints nothing at rest, `link` is the label alone. `primary` is the one flavour that needs a second color: the fill is the inherited color at full strength, so the label is punched out of it with `#current-fill`, which defaults to `#surface`. A container whose own text color collides with the page (a `Banner` labels itself `#white`, and `#surface` is white in light mode) should override `#current-fill` with its own fill, which contrasts with its own text by construction; ordinary containers need nothing. The label stays fully opaque and the focus ring stays `#primary-accent-text`, like every other theme. Use it inside colored containers (alerts, banners, dark overlays, tooltips), where a brand theme would either clash with the container or have to be picked to match it.
+
+  ```jsx
+  <Alert theme="note">
+    <Button theme="current" type="outline">Adopts the note color</Button>
+  </Alert>
+  ```
 
 ### Sizes. `size` prop
 

package/docs/components/actions/ItemAction.md

@@ -1,6 +1,6 @@
 # ItemAction
 
-A compact action button designed for use inside `Item`, `ItemButton`, and `ItemCard`. Automatically inherits `type` and `theme` from its parent context.
+A compact action button designed for use inside `Item`, `ItemButton`, and `ItemCard`. Defaults to the `current` theme, so it takes its colors from whatever row hosts it.
 
 ## When to Use
 
@@ -15,8 +15,8 @@ A compact action button designed for use inside `Item`, `ItemButton`, and `ItemC
 ## Properties
 
 - **`icon`** `ReactNode | 'checkmark'` — Icon element or `'checkmark'` for a selection indicator
-- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. Inherits from parent context.
-- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `'default'`) — Color theme. Inherits from parent context.
+- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. `clear` is borderless and paints nothing at rest, so a row full of actions does not read as busy.
+- **`theme`** `'current' | 'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `'current'`) — Color theme. `current` derives every color from the inherited `currentcolor`, so the action tracks whatever row hosts it without being told the row's type or theme. Name any other theme to have the action paint itself instead.
 - **`isLoading`** `boolean` (default: `false`) — Shows loading spinner
 - **`isSelected`** `boolean` (default: `false`) — Selected state (works with `icon="checkmark"`)
 - **`isDisabled`** `boolean` (default: `false`) — Disables the action. Inherits from parent; use `isDisabled={false}` to override.

package/docs/components/actions/MenuTrigger.md

@@ -19,6 +19,8 @@ Wraps a trigger element and a `Menu` to create a dropdown menu. Positions the me
 - **`offset`** `number` (default: `8`) — Distance from trigger in pixels
 - **`crossOffset`** `number` (default: `0`) — Cross-axis offset in pixels
 - **`containerPadding`** `number` — Minimum padding from viewport edges in pixels
+- **`mobileType`** `'popover' | 'tray'` (default: `'popover'`) — Overlay variant on mobile screens. `'tray'` opts into the bottom-sheet overlay
+- **`shouldRestoreFocus`** `boolean` (default: `true`) — Whether focus returns to the trigger when the menu closes. See [Focus restoration](#focus-restoration)
 
 Extends React Aria `AriaMenuTriggerProps` and `PositionProps`.
 
@@ -31,11 +33,61 @@ Supports [Base properties](../../BaseProperties.md).
 These properties allow direct style application without using the `styles` prop:
 
 - **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
-- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
 - **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
 - **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
 - **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
+## Focus restoration
+
+When the menu closes, focus returns to the trigger — **unless the action that
+closed it moved focus somewhere else**. An item whose action opens a panel, a
+dialog or an inline editor just focuses that surface; a single `focus()` call
+from a mount effect is enough, and the menu leaves it alone:
+
+```jsx
+function Panel() {
+  const ref = useRef(null);
+
+  // One call. No retry loop, no racing the closing menu.
+  useEffect(() => {
+    ref.current?.focus({ preventScroll: true });
+  }, []);
+
+  return (
+    <div ref={ref} tabIndex={-1}>
+      …
+    </div>
+  );
+}
+
+<MenuTrigger>
+  <Button icon={<MoreIcon />} aria-label="Actions" />
+  <Menu onAction={(key) => key === 'configure' && setPanelOpen(true)}>
+    <Menu.Item key="configure">Configure…</Menu.Item>
+  </Menu>
+</MenuTrigger>;
+```
+
+Focusing the surface's own container rather than its first tabbable child
+matters when a header carries a close button — `<FocusScope autoFocus>` would
+land the user on ✕, with <kbd>Enter</kbd> already meaning "close the thing that
+just opened".
+
+`shouldRestoreFocus={false}` covers the remaining case: a surface that claims
+focus *later* than the menu's restore — after an async load, an entry
+animation, or a `requestAnimationFrame`. Without it the trigger takes focus
+first and the user sees a flash.
+
+```jsx
+<MenuTrigger shouldRestoreFocus={false}>
+  <Button icon={<MoreIcon />} aria-label="Actions" />
+  <Menu onAction={openPanelThatFocusesAfterItsData}>
+    <Menu.Item key="configure">Configure…</Menu.Item>
+  </Menu>
+</MenuTrigger>
+```
 
 ## Examples
 

package/docs/components/actions/SubMenuTrigger.md

@@ -31,11 +31,11 @@ Supports [Base properties](../../BaseProperties.md).
 These properties allow direct style application without using the `styles` prop:
 
 - **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
-- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
 - **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
 - **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
 - **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
 ## Examples
 

package/docs/components/content/CopySnippet.md

@@ -15,6 +15,7 @@ A code block with copy-to-clipboard functionality and syntax highlighting. Exten
 - **`title`** `string` (default: `'Code example'`) — Accessible title used in the copy toast message
 - **`prefix`** `string` (default: `''`) — Prefix for each line of code (e.g. `'$ '` for bash snippets)
 - **`nowrap`** `boolean` — Force single-line display even for multi-line code
+- **`isWrapped`** `boolean` — Soft-wrap long content onto multiple lines instead of scrolling it horizontally. The block grows to fit, so even a single long line stays fully readable, and unbreakable runs (URLs, tokens, identifiers) wrap too. Useful for error messages and logs. Ignored when `nowrap` is set (a different axis: `nowrap` collapses newlines into one scrolling line, `isWrapped` breaks long lines).
 - **`serif`** `boolean` — Use serif (non-monospace) font for the code
 - **`hideText`** `string | string[] | boolean` — Hide sensitive text with bullet characters. `true` hides all text, a string hides that substring, an array hides multiple substrings. A toggle button appears to reveal hidden content.
 - **`actions`** `ReactNode` — Additional action buttons displayed alongside the copy button. Use `CopySnippet.Button` for consistent styling.
@@ -49,14 +50,13 @@ These properties allow direct style application without using the `styles` prop:
 ```jsx
 <CopySnippet code="const x = 1;" language="javascript" />
 
-<CopySnippet
-  code={'{\n  "key": "value"\n}'}
-  language="json"
-  multiline
-/>
+<CopySnippet code={'{\n  "key": "value"\n}'} language="json" />
 
 <CopySnippet
   code={'<button type="button" class="primary">Save</button>'}
   language="html"
 />
+
+// Wrap a long single-line error instead of scrolling it sideways
+<CopySnippet code={longErrorMessage} language="bash" isWrapped />
 ```

package/docs/components/content/InlineInput.md

@@ -261,7 +261,7 @@ When `InlineInput` is embedded in a host that already owns keyboard activation (
 
 ### Focus Management
 
-When entering edit mode, focus is taken explicitly by a `FocusScope` with `autoFocus`. This makes the transition deterministic even when triggered from a closing menu (which would otherwise restore focus to the menu trigger). The text content is selected automatically.
+When entering edit mode, focus is taken explicitly by a `FocusScope` with `autoFocus`, and the text content is selected automatically. On top of that, a blur arriving in the same tick as a programmatic `startEditing()` re-focuses the input instead of committing, so hosts that drive editing through the imperative ref stay in edit mode even if something else grabs focus as the input mounts. The guard clears on the user's first keystroke, so later click-aways commit normally.
 
 When leaving edit mode, focus is not restored automatically — the host is responsible for moving focus back to a meaningful element (e.g. the parent button or row).
 

package/docs/components/content/Item.md

@@ -22,8 +22,8 @@ A foundational component that provides a standardized layout and styling for ite
 - **`suffix`** `ReactNode` — Element rendered after the content (before rightIcon)
 - **`description`** `ReactNode` — Description text displayed with the item
 - **`descriptionPlacement`** `'inline' | 'block'` (default: `inline`) — How the description is positioned relative to the main content. Defaults to `'block'` for `type="card"` and `type="header"`
-- **`type`** `'item' | 'header' | 'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'card' | 'current'` (default: `item`) — Visual style variant
-- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
+- **`type`** `'item' | 'header' | 'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'card'` (default: `item`) — Visual style variant
+- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special' | 'current'` (default: `default`) — Semantic colour palette theme. `current` is not a brand palette: it mixes every color from the inherited text color, so the item adopts the color of whatever container it sits in
 - **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Item size. Accepts custom number or string values
 - **`shape`** `'card' | 'button' | 'sharp' | 'pill'` (default: `button`) — Shape of the item border radius. Defaults to `'card'` for `type="card"`
 - **`isSelected`** `boolean` (default: `false`) — Marks the item as selected
@@ -84,8 +84,8 @@ The `mods` property accepts the following modifiers:
 - **`disabled`** `boolean` — Applied when isDisabled is true or when loading
 - **`loading`** `boolean` — Applied when isLoading is true
 - **`size`** `string` — Applied based on size prop value (xsmall, small, medium, large, xlarge, inline)
-- **`type`** `string` — Applied based on type prop value (item, header, primary, outline, outline-2, clear, link, card, current)
-- **`theme`** `string` — Applied based on theme prop value (default, danger, success, special, warning, note)
+- **`type`** `string` — Applied based on type prop value (item, header, primary, outline, outline-2, clear, link, card)
+- **`theme`** `string` — Applied based on theme prop value (default, danger, success, special, warning, note, current)
 - **`shape`** `string` — Applied based on shape prop value (card, button, sharp, pill)
 
 ## Variants
@@ -99,8 +99,7 @@ The `mods` property accepts the following modifiers:
 - `outline-2` - Same as `outline` but uses `#surface-3` as the base fill, designed to sit on `#surface-2` containers without blending in (not available for the `special` theme)
 - `clear` - Transparent item with minimal styling; `isSelected` adds brand-tinted fill
 - `link` - Link-styled item appearance (does not support icons or loading state)
-- `card` - Card appearance for notifications (supports `default`, `success`, `danger`, `warning`, `note` themes; defaults to `shape="card"`, `descriptionPlacement="block"`, uses semantic heading tags via `level` prop, and has `.5x` padding)
-- `current` - Same shape as `item` — no border, nothing painted at rest — but every color is derived from the inherited text color (`#current`) instead of the fixed `#surface-text`, so the item adopts the color of whatever container it sits in. The fill steps in on hover (`.04`), pressed (`.06`) and selected (`.09` → `.15`); the label stays fully opaque. Theme-agnostic: only supports the `default` theme (any other theme warns, since there is nothing for it to change). Use it inside colored containers — alerts, banners, dark overlays, tooltips. `Button` has a `current` type too, shaped like a standalone control instead: a resting `#current.03` chip inside a `#current.08` border
+- `card` - Card appearance for notifications (supports `default`, `success`, `danger`, `warning`, `note`, `current` themes; defaults to `shape="card"`, `descriptionPlacement="block"`, uses semantic heading tags via `level` prop, and has `.5x` padding)
 
 ### Themes
 
@@ -110,6 +109,7 @@ The `mods` property accepts the following modifiers:
 - `warning` - Yellow/amber theme for caution or attention
 - `note` - Violet theme for informational context
 - `special` - Special theme with unique styling (not available for `card` or `header` types)
+- `current` - Not a palette at all: every color is derived from the inherited text color (`#current`) instead of a brand ramp, so the item adopts the color of whatever container it sits in. Every type except `header` has a `current` flavour, so the shape is still yours to pick — `item` keeps its borderless shape (nothing painted at rest, the fill stepping in on hover, pressed and selected), `outline` adds the chip and border, `primary` escalates it further. `primary` is the one flavour that needs a second color: its fill is the inherited color at full strength, so the label is punched out of it with `#current-fill` (default `#surface`) — a container whose own text color collides with the page, such as a `Banner` labelling itself `#white`, should override `#current-fill` with its own fill. The label stays fully opaque. Use it inside colored containers — alerts, banners, dark overlays, tooltips
 
 ### Sizes
 
@@ -257,17 +257,17 @@ Like headers, card labels use semantic heading tags (h1-h6) controlled by the `l
 </Item>
 ```
 
-### Current Type
+### Current Theme
 
-Use `type="current"` inside a container that paints its own text color. The fill and label are mixed from that inherited color, so the item matches the container without picking a theme — and keeps matching it if the container's color changes:
+Use `theme="current"` inside a container that paints its own text color. The fill and label are mixed from that inherited color, so the item matches the container without picking a brand theme — and keeps matching it if the container's color changes. Every type composes with it:
 
 ```jsx
 <Block fill="#note-surface" color="#note-accent-text" padding="1.5x" radius="1cr">
-  <Item type="current" icon={<IconInfo />}>Adopts the note color</Item>
+  <Item theme="current" icon={<IconInfo />}>Adopts the note color</Item>
 </Block>
 
 <Block fill="#fixed-dark" color="#white" padding="1.5x" radius="1cr">
-  <Item type="current" icon={<IconInfo />}>Adopts white on a dark banner</Item>
+  <Item theme="current" type="outline" icon={<IconInfo />}>An outlined chip on a dark banner</Item>
 </Block>
 ```
 

package/docs/components/content/ItemBadge.md

@@ -11,8 +11,8 @@ A non-interactive badge indicator for list items. Similar to `ItemAction` but wi
 ## Properties
 
 - **`icon`** `ReactNode | 'checkmark'` — Icon or checkmark display
-- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. `isSelected` applies brand-tinted fill to `outline` and `clear`. Inherits from parent context.
-- **`theme`** `'default' | 'danger' | 'success' | 'special'` (default: `'default'`) — Color theme. Inherits from parent context.
+- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. `isSelected` applies brand-tinted fill to `outline` and `clear`.
+- **`theme`** `'current' | 'default' | 'danger' | 'success' | 'special'` (default: `'current'`) — Color theme. `current` derives every color from the inherited `currentcolor`, so the badge tracks whatever row hosts it. Name any other theme to have the badge paint itself instead.
 - **`isLoading`** `boolean` (default: `false`) — Show loading spinner
 - **`isSelected`** `boolean` (default: `false`) — Selected state (for checkmark)
 - **`tooltip`** `string | object` — Tooltip content shown on hover for icon-only badges. A string shows tooltip text; an object supports `{ title, ...tooltipProps }` for advanced configuration.

package/docs/components/content/PrismCode.md

@@ -12,6 +12,7 @@ Syntax-highlighted code block using Prism. Supports multiple languages.
 
 - **`code`** `string` (default: `''`) — The code snippet to highlight
 - **`language`** `string` (default: `'javascript'`) — Language for syntax highlighting (`javascript`, `typescript`, `json`, `yaml`, `bash`, `sql`, `css`, `html`, etc.)
+- **`isWrapped`** `boolean` — Soft-wrap long lines onto multiple lines instead of scrolling them horizontally. Unbreakable runs (URLs, tokens, identifiers) wrap too. Useful for error messages and logs.
 
 ### Style Defaults
 

package/docs/components/fields/ColorSwatch.md

@@ -0,0 +1,155 @@
+# ColorSwatch
+
+A square of color. It is the smallest piece of the color family —
+[ColorPicker](./ColorPicker.md),
+[ColorInput](./ColorInput.md) and
+[ColorSwatchGroup](./ColorSwatchGroup.md) all draw one, and it is
+exported so a legend, a list row or a table cell can draw the same one.
+
+It is decorative on its own: it carries no text and no accessible name. Pair it
+with the value written out, or put it in a control that names it.
+
+## When to Use
+
+- Next to a color value in a list, a table or a chart legend
+- In the `icon` / `rightIcon` / `prefix` / `suffix` slot of an `Item` or `Button`
+- As the color part of a custom control built on top of the color fields
+
+## Component
+
+---
+
+### Properties
+
+- **`color`** `string | ColorValue | null` — The color to show. Anything the color fields accept — `#7a4dbf`, `rgb(122 77 191)`, `oklch(…)`. `null`, or a string that cannot be parsed, shows the empty state
+- **`size`** `'small' | 'medium' | 'large'` — The edge of the swatch: `20px`, `24px` or `28px`. Left unset, the swatch tracks the control around it (see below)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the swatch itself. `width` and `height` set here win over both the
+`size` prop and the automatic sizing.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier | Type      | Description                                                    |
+| -------- | --------- | -------------------------------------------------------------- |
+| `empty`  | `boolean` | No color to show — drawn as the conventional diagonal stroke     |
+
+## Sizes
+
+- `small` — `20px`
+- `medium` — `24px`
+- `large` — `28px`
+
+### Sizing inside a control
+
+Leave `size` off and the swatch sizes itself to whatever it sits in. `Item`,
+`Button` and the text inputs publish their own height as the `$size` custom
+property, and the swatch reads it and lands `8px` inside — `20px` in a `small`
+control, `24px` in a `medium` one, `28px` in a `large` one. Nothing has to be
+passed between the two, so a control that changes size takes its swatch with it.
+
+Outside a control there is nothing to read, and the swatch falls back to
+`medium`.
+
+`ColorInput` and `ColorPicker` deliberately do **not** use this. Their swatch is a
+fixed `20px` badge at every field size — it reads as a value the field is showing
+rather than as part of the control, and a text input hangs its prefix off the border
+with no padding of its own, so a tracking swatch in a large field would sit against
+the edge. Automatic fitting is for a swatch you place yourself, in a `Button` or an
+`Item`, where the host has the padding that makes it work.
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<ColorSwatch color="#7a4dbf" />
+```
+
+### In a control
+
+```jsx
+<Button icon={<ColorSwatch color={color} />}>{color}</Button>
+
+<Item icon={<ColorSwatch color={color} />} suffix={<ColorSwatch color={hover} />}>
+  Accent
+</Item>
+```
+
+### With the value spelled out
+
+The swatch has no accessible name of its own, so the text beside it is what a
+screen reader announces.
+
+```jsx
+<Space gap="1x" placeItems="center start">
+  <ColorSwatch color={value} />
+  <Text>{value}</Text>
+</Space>
+```
+
+### A fixed size
+
+```jsx
+<ColorSwatch size="large" color="#26fcb2" />
+```
+
+### Any other shape
+
+```jsx
+<ColorSwatch color="#26fcb2" radius="round" width="6x" height="6x" />
+```
+
+## Accessibility
+
+`ColorSwatch` renders a plain `div` with no role and no name — a color on its
+own is not information a screen reader can use, and an announced hex is rarely
+what the user wants to hear.
+
+- **Do** put the value, or the name of the thing the color belongs to, next to it
+- **Do** rely on the surrounding control's `aria-label` when the swatch is its icon
+- **Don't** use color as the only way to tell two rows apart
+
+## Best Practices
+
+1. **Do**: let a swatch inside a control size itself
+
+   ```jsx
+   <Button size="small" icon={<ColorSwatch color={color} />}>
+     {color}
+   </Button>
+   ```
+
+2. **Don't**: hand-tune the box to match a control
+
+   ```jsx
+   <Button size="small" icon={<ColorSwatch color={color} width="2.5x" height="2.5x" />}>
+     {color}
+   </Button>
+   ```
+
+3. **Accessibility**: never let the swatch be the only carrier of the meaning
+
+## Related Components
+
+- [ColorPicker](./ColorPicker.md) — a swatch that opens the color popover
+- [ColorInput](./ColorInput.md) — the color as editable text, with a swatch inside
+- [ColorSwatchGroup](./ColorSwatchGroup.md) — a selectable grid of swatches

package/docs/components/fields/RadioGroup.md

@@ -21,12 +21,38 @@ A radio group allows users to select exactly one option from a set of mutually e
 - **`defaultValue`** `string` — The default selected value (uncontrolled)
 - **`type`** `'radio' | 'button' | 'tabs'` (default: `radio`) — Visual type for all radios in the group (button/tabs default to horizontal)
 - **`orientation`** `undefined | 'vertical' | 'horizontal'` (default: `undefined`) — Orientation of the radio group. When unset it is derived from `type`: `horizontal` for `button` and `tabs`, `vertical` otherwise
-- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `xsmall`) — Size for all radio buttons in the group
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `medium`) — Size for all radio buttons in the group
 - **`buttonType`** `'outline' | 'outline-2' | 'clear' | 'primary'` — Button type for button-style radios (ignored in tabs mode). When set to "primary", selected buttons use primary style and non-selected use outline with brand tint. `outline-2` is identical to `outline` but uses `#surface-3` as its base fill, so it stands out when the radio group sits on a `#surface-2` container
 - **`onChange`** `function` — Callback fired when the selected value changes
 - **`onBlur`** `function` — Callback fired when the radio group loses focus
 - **`onFocus`** `function` — Callback fired when the radio group receives focus
 
+### Radio Properties
+
+Each option is a `Radio` (also exported as `Radio.Button`).
+
+- **`value`** `string` — The value this option contributes to the group
+- **`children`** — The option label
+- **`isDisabled`** `boolean` — Whether this option is disabled. Falls back to the group's `isDisabled`
+- **`type`** `'radio' | 'button'` — Overrides the group's visual type for this option
+- **`size`**, **`buttonType`** — Override the group's `size` / `buttonType` for this option
+
+A `button`- or `tabs`-type radio renders an [Item](../content/Item.md), so it takes the same content props an [ItemButton](../actions/ItemButton.md) does. These are ignored by a classic radio:
+
+- **`icon`**, **`rightIcon`** — Icons before / after the label
+- **`prefix`**, **`suffix`** — Content before / after the label
+- **`description`**, **`descriptionPlacement`**, **`descriptionProps`** — Secondary line, placed `inline` (default) or `block`
+- **`tooltip`** — Tooltip content, or `true` to show one only when the label is truncated
+- **`hotkeys`**, **`keyboardShortcutProps`** — Keyboard shortcut that selects the option, rendered as a hint
+- **`isLoading`**, **`loadingSlot`** — Replaces a slot with a spinner and disables the option
+- **`highlight`**, **`highlightCaseSensitive`**, **`highlightStyles`** — Highlights a substring of the label
+- **`level`** — Heading level for the label when `buttonType` is `card` or `header`
+- **`labelRef`** — Ref to the label element
+
+Container [style properties](#style-properties) also apply to button-type radios (they style the `Item`). A classic radio only reads the outer subset — `margin`, `width`, `height`, `flex*`, `grid*`, `place*`, `position`, `inset`, `zIndex`, `border`, `radius`, `shadow`, `outline`.
+
+`shape` and `actions` are not forwarded: the corner radius is owned by the group layout, which keeps only the outer-side radius on the first and last option so the group reads as one continuous control, and a button radio renders as a `<label>`, where a click on a nested action button would select the option.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md)
@@ -101,12 +127,10 @@ Controls the size of all radio buttons in the group:
 
 **Size Mapping in Tabs Mode:**
 When `type="tabs"`, sizes are automatically mapped to maintain visual consistency:
-- `small` and `medium` → `xsmall`
 - `large` → `medium`
-- `xlarge` → `large`
-- `xsmall` remains `xsmall`
+- every other size → `xsmall`
 
-This ensures tab groups remain compact and cohesive.
+Only `large` is carried through; `xsmall`, `small`, `medium` and `xlarge` all collapse to `xsmall`. This ensures tab groups remain compact and cohesive.
 
 ### Button Type
 
@@ -160,6 +184,16 @@ When using `type="button"`, you can customize the button appearance:
 </Radio.Tabs>
 ```
 
+### Rich Button Content
+
+```jsx
+<Radio.ButtonGroup label="Region" defaultValue="eu">
+  <Radio value="eu" icon={<GlobeIcon />} description="Frankfurt">EU</Radio>
+  <Radio value="us" icon={<GlobeIcon />} description="Oregon" hotkeys="alt+2">US</Radio>
+  <Radio value="ap" icon={<GlobeIcon />} isLoading>AP</Radio>
+</Radio.ButtonGroup>
+```
+
 ### Custom Button Type
 
 ```jsx