actual-css 0.13.0 → 0.14.1

package/docs/design-notes/widget-primitives.md

@@ -35,6 +35,10 @@ The named exports each module carries:
 - `selectors` — `CLASSES`
 
 `surface` also owns outside-click and Escape dismissal, and focus restore.
+A click on an element with `data-flyout-close` closes the open panel around
+it, whichever widget opened that panel. The attribute keeps the `flyout` name
+because the panels authors write are flyouts; `surface` is only the code that
+opens and closes them.
 `menu` filters to usable items.
 
 ## Focus group

package/docs/navigation.json

@@ -69,6 +69,7 @@
         "pagination",
         "progress",
         "rating",
+        "segmented",
         "shimmer",
         "skeleton",
         "spinner",
@@ -91,6 +92,7 @@
         "form-actions",
         "joined-controls",
         "choice-cards",
+        "color-swatches",
         "switch",
         "range",
         "otp",

package/docs/pages/components/alert.md

@@ -12,7 +12,7 @@
 - Could have simple or complex html content.
 - A title and a description are plain siblings: the alert owns the small space between its direct content blocks, so neither needs a wrapper. Nested content keeps its own rhythm — wrap several paragraphs in `.prose`, or a differently spaced group in `.stack`, when the message needs a rhythm of its own.
 - Alerts may include a decorative leading icon. Use `.alert-icon` on the icon element; the rest of the content flows into the remaining text column.
-- Use `.compact` or `.spacious` for density changes. The inline padding stays stable.
+- Use `.compact` or `.spacious` on the alert to step its block padding. The inline padding stays stable.
 - Use a [`.close`](close.md) button to make the alert dismissible. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions; the alert makes it compact.
 
 Because alerts are soft by default, adding `.soft` to an intent (`.alert.soft.primary`,
@@ -216,7 +216,7 @@ full-bleed notice.
 
 ## Admonition
 
-An admonition is a structured box with a tinted title bar, an optional icon, and body content on the page surface — like the `!!! note` callouts in mkdocs. Use `.alert-title` for the header and `.alert-body` for the content. Intent classes tint the title bar background and the border.
+An admonition is a structured box with a tinted title bar, an optional icon, and body content on the page surface — like the `!!! note` callouts in mkdocs. Use `.alert-title` for the header and `.alert-body` for the content. Intent classes tint the title bar background and the border; shared variants paint the title bar, so `.solid` fills it — and keeps the body's frame neutral — for a notification that needs to stand out.
 
 ```html demo
 <div class="stack">
@@ -239,6 +239,16 @@ An admonition is a structured box with a tinted title bar, an optional icon, and
       <p>The intent tints the title bar, the border, and the body uses <code>var(--surface)</code>.</p>
     </div>
   </div>
+
+  <div class="alert success admonition solid">
+    <div class="alert-title">
+      <i class="ti ti-circle-check" aria-hidden="true"></i>
+      Saved
+    </div>
+    <div class="alert-body">
+      <p>A solid title bar for an action response.</p>
+    </div>
+  </div>
 </div>
 ```
 

package/docs/pages/components/button.md

@@ -153,8 +153,9 @@ Keep one variant family inside a group. Because each button keeps its own
 classes, nothing stops `.btn`, `.btn outline` and `.btn soft` from sitting side
 by side — but three fills and three border treatments in one shape read as
 unrelated controls that happen to touch, not as one unit. Change the variant
-only to carry meaning: [Toggle](#toggle) marks the active segment with a solid
-button among outlines, which is the pattern a segmented control wants.
+only to carry meaning: [Toggle](#toggle) marks a pressed button with a solid
+fill among outlines. For one choice among a few on a shared track, use a
+[segmented control](segmented.md) instead.
 
 ## Sizes
 

package/docs/pages/components/list.md

@@ -29,9 +29,12 @@ list markers when order or bullets carry meaning.
 ```
 
 Leading and trailing content are unconstrained: avatars, native choices,
-badges, text, switches, and buttons retain their own component sizing.
-`.list-item-content` has no minimum content floor, so supporting text and long
-tokens wrap instead of widening the page.
+badges, text, switches, and buttons retain their own component sizing. In a
+narrow row, the trailing region moves under the content rather than breaking a
+word of the title; supporting text still wraps beside it, and a token longer
+than the row breaks instead of widening the page. A `.truncate` line inside
+`.list-item-content` gives up its width, so it ellipsizes next to the trailing
+region (wrap, responsive row, overflow).
 
 Both outer regions are optional, and an absent one costs neither space nor a
 gap: `.list-item-content` always takes the row's free space and

package/docs/pages/components/segmented.md

@@ -0,0 +1,83 @@
+# Segmented control
+
+> One compact choice among a few options, on a shared track with the selected segment raised.
+
+**Related terms:** segmented control, toggle group, pill tabs, view switcher, button group.
+
+`.segmented` is the track and each `.segment` a direct child. The look is
+shared; the semantics come from the markup, so pick the anatomy by what the
+choice does:
+
+| Use           | Markup                 | Selected               | Keyboard      |
+| ------------- | ---------------------- | ---------------------- | ------------- |
+| Pick a value  | `<fieldset>` of radios | `:checked`             | Native arrows |
+| Switch panels | `role="tablist"`       | `aria-selected="true"` | Tabs runtime  |
+| Navigate      | `<nav>` of links       | `aria-current="page"`  | Tab, Enter    |
+
+Segments share the width equally and the track is at least `--control-size`
+tall, so it lines up with `.btn` and `.input`; `.sm` and `.lg` size it like
+any control. A long label wraps instead of truncating, and the row grows with
+it. A parent that stretches its children (`.stack`) makes it full width; add
+`.align-self-start` to keep it at its content width.
+
+## Pick a value
+
+Wrap each radio in its label. The radio is visually hidden but stays focusable
+and submitted; in a browser without `:has()` it stays visible beside the
+label.
+
+```html demo
+<fieldset class="segmented">
+  <legend class="sr-only">Range</legend>
+  <label class="segment"><input type="radio" name="range" value="day">Day</label>
+  <label class="segment"><input type="radio" name="range" value="week" checked>Week</label>
+  <label class="segment"><input type="radio" name="range" value="month">Month</label>
+</fieldset>
+```
+
+## Switch panels
+
+A tablist with `data-enhance="tabs"` takes the [tabs](../enhancements/tabs.md)
+runtime unchanged: it reads the roles, not the classes.
+
+```html demo
+<div class="segmented" role="tablist" aria-label="View" data-enhance="tabs">
+  <button class="segment" type="button" role="tab" id="view-list-tab" aria-selected="true" aria-controls="view-list">List</button>
+  <button class="segment" type="button" role="tab" id="view-grid-tab" aria-selected="false" aria-controls="view-grid" tabindex="-1">Grid</button>
+</div>
+<section role="tabpanel" id="view-list" aria-labelledby="view-list-tab">List view</section>
+<section role="tabpanel" id="view-grid" aria-labelledby="view-grid-tab" hidden>Grid view</section>
+```
+
+## Navigate
+
+```html demo
+<nav class="segmented" aria-label="Period">
+  <a class="segment" href="#day" aria-current="page">Day</a>
+  <a class="segment" href="#week">Week</a>
+  <a class="segment" href="#month">Month</a>
+</nav>
+```
+
+## When to use something else
+
+- Several options on at once (bold, italic): `.join` of `.btn` with
+  `aria-pressed`, see [joined controls](../forms/joined-controls.md).
+- More options than fit on one row: [tabs](../enhancements/tabs.md), whose
+  strip scrolls.
+- Long or descriptive options: [choice cards](../forms/choice-cards.md) or
+  plain radios.
+
+## Hooks
+
+- `--segmented-bg` — track fill.
+- `--segmented-pad` — inset between the track and its segments, also the gap
+  between segments; the segment radius is the track radius minus it.
+- `--segmented-radius` — track corner radius.
+- `--segmented-fg` — label ink of the unselected segments; the selected one
+  takes `--text`.
+- `--segmented-selected-bg` — fill of the selected segment. Its shadow follows
+  `--shadow`, so a flat theme removes it at the theme level.
+- `--segmented-selected-border` — hairline around the selected segment. It is
+  what sets the segment apart where its fill is darker than the track; a theme
+  whose fill is lighter can fade it.

package/docs/pages/components/steps.md

@@ -80,9 +80,11 @@ accent, override the tokens on the component:
 }
 ```
 
-`--state-selected` drives the completed fill, connector and the current ring;
+`--state-selected` drives the completed fill and connector;
 `--state-selected-fg` corrects the number inside a completed marker when the
-accent needs a lighter ink.
+accent needs a lighter ink. The current marker sits on the surface, so its
+number and ring read `--state-selected-text` first
+([tokens](../foundations/tokens.md)).
 
 ## Horizontal steps
 

package/docs/pages/enhancements/flyout.md

@@ -67,9 +67,10 @@ For a modal bottom sheet or action sheet, use `dialog.drawer`; use
 `dialog.modal` for a centered modal. Those components own modal focus,
 dismissal, scroll locking, and backdrop behavior explicitly.
 
-Use `data-flyout-placement` for the preferred anchored placement. It accepts the
-placement strings supported by the floating runtime, such as `bottom-start`,
-`bottom-end`, `top-start`, `right`, or `left`.
+Use `data-flyout-placement` for the preferred anchored placement: a side
+(`top`, `bottom`, `left`, `right`), optionally followed by `-start` or `-end`,
+such as `bottom-start` or `right`. An unknown value logs a console warning and
+falls back to `bottom-start`.
 
 Use `data-flyout-distance` for the trigger gap in pixels. The default is `4`.
 
@@ -180,6 +181,11 @@ flyout when that specific control must close it regardless of the automatic
 policy. This is useful for an Apply or Done action in an `outside` or `false`
 panel. The trigger and Escape continue to close the flyout in every mode.
 
+Arrow keys and Space in a radio group never close the flyout: they move
+through the options, and a pointer pick closes it. Opening from the keyboard
+focuses a group at its checked radio. The [palette picker](../forms/color-swatches.md#palette-in-a-flyout)
+relies on both.
+
 ```html
 <div class="flyout"
      id="filters"

package/docs/pages/enhancements/overview.md

@@ -56,7 +56,8 @@ is a no-op until the module is loaded again with a DOM.
 Load the full bundle **or** the source modules, never both: each evaluation
 owns its registry and document handlers, so a dist bundle mixed with
 `actual-css/js/*` source subpaths (or two dist bundles) registers every
-behavior twice and a flyout opens then immediately closes.
+behavior twice and a flyout opens then immediately closes. The second copy
+logs a console warning when it loads.
 
 ## Component pages
 

package/docs/pages/enhancements/tabs.md

@@ -91,10 +91,15 @@ JavaScript involved:
 
 ## Equal-width tabs
 
-To make a few tabs share the strip's width (segmented, full-width, fill), set
+To make a few tabs share the strip's width (full-width, fill), set
 `--tab-flex: 1 1 0` on the strip. `.switcher` does not apply here: a tab strip
 never wraps, so it could never stack.
 
+For a few tabs on a track with a raised selected tab (segmented control, pill
+tabs), put the same tablist on [`.segmented`](../components/segmented.md):
+the runtime is unchanged. Its labels wrap instead of scrolling, so keep it to
+what fits on one row.
+
 ```html demo
 <nav aria-label="Pricing sections">
   <ul class="tabs" style="--tab-flex: 1 1 0">
@@ -158,5 +163,5 @@ Do not put a flyout trigger in a `role="tablist"`: a tablist holds only
 ## CSS hooks
 
 - `--tab-flex` — flex of each item; set `1 1 0` on the strip for equal-width tabs
-  (segmented, fill the width). A strip that cannot fit its labels still scrolls.
+  (fill the width). A strip that cannot fit its labels still scrolls.
 - `--tab-gap` — space between an icon and the label text (default `0.375em`).

package/docs/pages/enhancements/tooltip.md

@@ -115,7 +115,9 @@ viewport-aware maximum width.
 ## Positioning
 
 Set `data-tooltip-placement` to control where the tooltip appears relative to
-its trigger. The arrow follows the placement automatically.
+its trigger: a side (`top`, `bottom`, `left`, `right`), optionally followed by
+`-start` or `-end`. An unknown value logs a console warning and falls back to
+`top`. The arrow follows the placement automatically.
 
 The runtime also picks the coordinate space, and writes `position` to match. A
 tooltip whose trigger scrolls with the page is placed in document coordinates

package/docs/pages/examples/overview.md

@@ -4,8 +4,8 @@
 
 The examples live in the repository under `demo/` and load `actual.full.css`
 and `actual.full.js` from `dist/`, plus the theme palettes bundle from
-`demo/assets/`. The bundle is committed and regenerated by
-`bun run build:themes`, so the pages open from a fresh checkout.
+`demo/assets/`. Both are build output: in a clone, run `bun run build:dist`,
+`bun run build:js` and `bun run build:themes` before opening a page.
 
 ## Templates
 
@@ -23,13 +23,15 @@ rest show it composed, isolated, or under stress.
 Whole pages, composed the way a real product would.
 
 - [Dashboard](../../demo/templates/dashboard.html) - data-heavy overview page
+- [Order management](../../demo/templates/order-management.html) - one state at three levels (a badge in a selectable list, a message in context, a notification with its own action) composed on the `admin-neutral` business-interface theme
 - [App](../../demo/templates/app.html) - application shell with sidebar
 - [Workspaces](../../demo/templates/workspaces.html) - sectioned sidebar, master/detail list with native current state, and workspace cards
 - [Marketing](../../demo/templates/marketing.html) - landing page with typography and fluid type
 - [Blog](../../demo/templates/blog.html) - article page with prose
 - [Settings modal](../../demo/templates/settings-modal.html) - two-pane preferences dialog, with the local CSS it needs audited rule by rule
 - [Modal patterns](../../demo/templates/modal-patterns.html) - eight application modals, each the modal surface plus the smallest application CSS it needs
-- [Workspace settings](../../demo/templates/settings-pricing.html) - plans with visible native choices, preferences and a local segmented tab treatment
+- [Workspace settings](../../demo/templates/settings-pricing.html) - plans with visible native choices, preferences and segmented tabs
+- [iOS-style settings](../../demo/templates/settings-ios.html) - iOS-like controls and grouped settings from unchanged framework markup, a local theme, and its findings listed rule by rule
 - [Card compositions](../../demo/templates/card-compositions.html) - editorial, team, sign-in and horizontal cards composed from existing primitives
 - [Register form](../../demo/templates/register-form.html) - registration page with choice cards, masks, the password toggle, `tel-prefix` validation, an OTP verification dialog, and status feedback
 

package/docs/pages/forms/color-swatches.md

@@ -0,0 +1,131 @@
+# Color swatches
+
+> Pick a color from a palette the application defines, inline or from a flyout.
+
+**Related terms:** color picker, palette, swatch, color chip, accent color, label color.
+
+`.color-swatch` is a `<label>` wrapping a native radio, with the color in
+`--color-swatch-value`. The radio stays the control: it submits, takes the
+arrow keys and carries the name in `aria-label`. The checked swatch shows a
+double ring that reads on any color. Use checkboxes for several colors at once.
+
+For a free color, use the native [`.color`](controls.md) picker; a custom
+spectrum or RGB sliders are outside Actual.
+
+## Palette
+
+Lay the swatches out with `.cluster` or `.grid`, and space them with `--gap`
+(`.tight`, `.loose` or an inline value), not `gap`: the hit area reaches
+half of `--gap` past the swatch, up to `--control-size`, so neighbours split
+the gap between them. A tighter palette trades target size for density. Set
+the column count with `--grid-columns: repeat(6, max-content)` on `.grid`.
+
+```html demo
+<fieldset class="field-group cluster">
+  <legend>Category color</legend>
+  <label class="color-swatch" style="--color-swatch-value: #2563eb"><input type="radio" name="category" value="#2563eb" aria-label="Blue" checked></label>
+  <label class="color-swatch" style="--color-swatch-value: #10b981"><input type="radio" name="category" value="#10b981" aria-label="Green"></label>
+  <label class="color-swatch" style="--color-swatch-value: #f59e0b"><input type="radio" name="category" value="#f59e0b" aria-label="Amber"></label>
+  <label class="color-swatch" style="--color-swatch-value: #e11d48"><input type="radio" name="category" value="#e11d48" aria-label="Rose"></label>
+  <label class="color-swatch" style="--color-swatch-value: #ffffff"><input type="radio" name="category" value="#ffffff" aria-label="White"></label>
+</fieldset>
+```
+
+## Palette in a flyout
+
+A `<button class="color-swatch">` shows the current color and opens the
+palette as a [flyout](../enhancements/flyout.md). A pointer pick closes it;
+the arrow keys move through the colors with the panel open, and Escape returns
+to the button. Give the panel `--flyout-pad` so the focus ring fits inside it.
+Application code shows the pick on the button.
+
+```html demo
+<span class="field-label" id="accent-label">Accent color</span>
+<div class="flyout-trigger">
+  <button class="color-swatch" type="button" data-enhance="flyout"
+          aria-controls="accent-palette" aria-expanded="false"
+          aria-labelledby="accent-label accent-name"
+          style="--color-swatch-value: #2563eb">
+    <span class="sr-only" id="accent-name">Blue</span>
+  </button>
+  <div class="flyout" id="accent-palette" style="--flyout-pad: var(--space-30)" hidden>
+    <div class="cluster" role="radiogroup" aria-labelledby="accent-label">
+      <label class="color-swatch" style="--color-swatch-value: #2563eb"><input type="radio" name="accent" value="#2563eb" aria-label="Blue" checked></label>
+      <label class="color-swatch" style="--color-swatch-value: #10b981"><input type="radio" name="accent" value="#10b981" aria-label="Green"></label>
+      <label class="color-swatch" style="--color-swatch-value: #f59e0b"><input type="radio" name="accent" value="#f59e0b" aria-label="Amber"></label>
+      <label class="color-swatch" style="--color-swatch-value: #e11d48"><input type="radio" name="accent" value="#e11d48" aria-label="Rose"></label>
+    </div>
+  </div>
+</div>
+<script>
+  (() => {
+    const preview = document.currentScript.closest(".docs-preview");
+    const trigger = preview.querySelector("button.color-swatch");
+    preview.querySelector(".flyout").addEventListener("change", (event) => {
+      trigger.style.setProperty("--color-swatch-value", event.target.value);
+      trigger.querySelector(".sr-only").textContent = event.target.getAttribute("aria-label");
+    });
+  })();
+</script>
+```
+
+## Palette and custom color
+
+Add the native [`.color`](controls.md) picker to the panel for a color
+outside the palette. Two changes to the flyout above:
+
+- `data-flyout-auto-close="outside"` on the panel, so opening the color dialog
+  does not close it, and `data-flyout-close` on each swatch, so a pointer pick
+  still does. The arrow keys still move through the palette with the panel
+  open.
+- The custom input sits in a `<label class="cluster">`, which centers it on
+  its text; `.choice` aligns checkboxes, radios and switches only.
+- The custom input takes its own name. Application code unchecks the palette
+  when a custom color is chosen, so the form sends `brand`, or `brand-custom`
+  when no palette color is checked.
+
+```html demo
+<span class="field-label" id="brand-label">Brand color</span>
+<div class="flyout-trigger">
+  <button class="color-swatch" type="button" data-enhance="flyout"
+          aria-controls="brand-palette" aria-expanded="false"
+          aria-labelledby="brand-label brand-name"
+          style="--color-swatch-value: #2563eb">
+    <span class="sr-only" id="brand-name">Blue</span>
+  </button>
+  <div class="flyout stack" id="brand-palette" data-flyout-auto-close="outside"
+       style="--flyout-pad: var(--space-30)" hidden>
+    <div class="cluster" role="radiogroup" aria-labelledby="brand-label">
+      <label class="color-swatch" data-flyout-close style="--color-swatch-value: #2563eb"><input type="radio" name="brand" value="#2563eb" aria-label="Blue" checked></label>
+      <label class="color-swatch" data-flyout-close style="--color-swatch-value: #10b981"><input type="radio" name="brand" value="#10b981" aria-label="Green"></label>
+      <label class="color-swatch" data-flyout-close style="--color-swatch-value: #f59e0b"><input type="radio" name="brand" value="#f59e0b" aria-label="Amber"></label>
+      <label class="color-swatch" data-flyout-close style="--color-swatch-value: #e11d48"><input type="radio" name="brand" value="#e11d48" aria-label="Rose"></label>
+    </div>
+    <label class="cluster"><input class="color" type="color" name="brand-custom" value="#7048e8"> Custom…</label>
+  </div>
+</div>
+<script>
+  (() => {
+    const preview = document.currentScript.closest(".docs-preview");
+    const trigger = preview.querySelector("button.color-swatch");
+    const palette = preview.querySelector(".flyout");
+    palette.addEventListener("change", (event) => {
+      const custom = event.target.type === "color";
+      if (custom) for (const radio of palette.querySelectorAll('[type="radio"]')) radio.checked = false;
+      trigger.style.setProperty("--color-swatch-value", event.target.value);
+      trigger.querySelector(".sr-only").textContent = custom
+        ? `Custom ${event.target.value}`
+        : event.target.getAttribute("aria-label");
+    });
+  })();
+</script>
+```
+
+The color dialog is the browser's own and looks different on each platform.
+
+## Hooks
+
+- `--color-swatch-value` — the color, set on each swatch.
+- `--color-swatch-size` — visible swatch size, the height of a `.switch` track
+  by default. `.sm` and `.lg` scale it and the hit area.
+- `--color-swatch-radius` — corner radius; round by default.

package/docs/pages/forms/combobox.md

@@ -93,9 +93,9 @@ contrast contracts apply to the combobox for free:
 
 .actual-combobox .cb-chip {
   border: var(--border-width) solid
-    color-mix(in oklab, var(--surface) var(--soft-border-mix), var(--primary));
+    color-mix(in oklab, var(--primary) calc(100% - var(--soft-border-mix, 100%)), transparent);
   border-radius: var(--radius-full);
-  background: color-mix(in oklab, var(--surface) var(--soft-bg-mix), var(--primary));
+  background: color-mix(in oklab, var(--primary) calc(100% - var(--soft-bg-mix)), transparent);
   color: color-mix(in oklab, var(--primary) var(--soft-fg-mix), var(--text));
   font-size: var(--font-size-xs);
   font-weight: var(--font-weight-semibold);

package/docs/pages/forms/controls.md

@@ -6,9 +6,12 @@ Native-only control chrome: the file input and color picker mostly defeat custom
 
 > Small, theme-aware chrome for the native color picker.
 
-Use `.color` on an `input[type="color"]` to give the native picker a control-sized
-box with the framework's border, radius, surface, disabled, and focus styles.
-The color dialog and selected-color swatch remain browser-native.
+Use `.color` on an `input[type="color"]` to show the native picker as a round
+swatch the height of a [switch](switch.md), on a control-sized hit area, with
+the framework's edge, disabled, and focus styles. `--color-size` sets the
+swatch. The color dialog remains browser-native. To choose from a fixed
+palette instead, use [color swatches](color-swatches.md), which share this
+geometry.
 
 ```html demo
 <label class="field">

package/docs/pages/forms/joined-controls.md

@@ -2,7 +2,11 @@
 
 > Use `.join` when controls need to be visually joined into a single unit.
 
-**Related terms:** segmented control, button group, input group.
+**Related terms:** button group, input group, toolbar.
+
+`.join` groups controls that keep their own identity and function. For one
+choice among a few on a shared track, use a
+[segmented control](../components/segmented.md).
 
 ## Class reference
 
@@ -13,7 +17,7 @@
 
 Add `.join` to the wrapper that groups the controls. Use `.join-addon` for static prefix/suffix content such as currency symbols, units, or protocol text. Action buttons inside the group should use `.btn`. The wrapper should still carry `role="group"` with a label for accessibility.
 
-`.join` reshapes corners and shared edges; it does not unify the segments' treatments, and the children keep whatever classes they carry. Give them one variant family so the group reads as a single unit, and change a segment's variant only to mark state — a solid button among outlines for the active segment of a segmented control. A group mixing `.btn`, `.btn outline` and `.btn soft` is valid markup that renders as three unrelated controls stuck together.
+`.join` reshapes corners and shared edges; it does not unify the segments' treatments, and the children keep whatever classes they carry. Give them one variant family so the group reads as a single unit, and change a segment's variant only to mark state — a solid button among outlines for a pressed toggle. A group mixing `.btn`, `.btn outline` and `.btn soft` is valid markup that renders as three unrelated controls stuck together.
 
 When composing source files manually, import `components/join.css` after the controls it groups. `.join` writes child border-radius longhands directly so joined corners win at equal specificity.
 

package/docs/pages/forms/overview.md

@@ -28,6 +28,7 @@
 | `.range`        | Component   | Native range slider, theme-aware accent.      |
 | `.file`         | Component   | Native file input, themed picker button.      |
 | `.color`        | Component   | Native color picker in a control-sized box.   |
+| `.color-swatch` | Component   | Palette color on a radio, or its trigger.     |
 | `.field`        | Composition | Field wrapper, on `<label>` or `<div>`.       |
 | `.field-label`  | Composition | Label text, element-agnostic.                 |
 | `.field-help`   | Composition | Supporting helper text under a control.       |

package/docs/pages/forms/switch.md

@@ -132,8 +132,10 @@ same optical line. Change the type or the control size and they stay level:
 - `--switch-width` — track width.
 - `--switch-block-size` — track height.
 - `--switch-knob-margin` — inset between knob and track.
+- `--switch-knob-inline-size` — knob width; wider than its height makes a
+  capsule knob. Defaults to the knob height.
 
-Knob size and travel distance are derived from the three `--switch-*` hooks; set
-those rather than the derived values. The knob is concentric in its track: the
+Knob size and travel distance are derived from these hooks; set them rather
+than the derived values. The knob is concentric in its track: the
 inset is measured inside the border on both axes, so it clears the rails by the
 same distance it clears the ends.

package/docs/pages/foundations/theming.md

@@ -56,7 +56,7 @@ Set `--form-actions-justify` (and `--form-actions-align`).
 
 ### Customize a switch's size
 
-Change `--switch-width`, `--switch-block-size`, and `--switch-knob-margin`; knob size and travel are derived from them. To rescale the whole row of inline choices at once, use `.sm` / `.lg` on `.choice`, or set `--choice-control-size` directly — the checkbox, the radio, and the switch track all follow it. Density contexts leave inline choices alone.
+Change `--switch-width`, `--switch-block-size`, and `--switch-knob-margin`; knob size and travel are derived from them. `--switch-knob-inline-size` widens the knob into a capsule. To rescale the whole row of inline choices at once, use `.sm` / `.lg` on `.choice`, or set `--choice-control-size` directly — the checkbox, the radio, and the switch track all follow it. Density contexts leave inline choices alone.
 
 → Forms · Switch