actual-css 0.12.0 → 0.14.0

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
 
@@ -145,23 +147,28 @@ names, or when a step should be navigable:
 ```
 
 **Actual CSS never hides an authored step label.** Labels stay visible at every
-width. If a labelled row does not fit its space, it scrolls — and the honest
-answers to that are more room, fewer stages, or `.steps-vertical`.
+width. Stacked steps keep their markers evenly spaced, and long names wrap
+inside their share, hyphenated when the page declares a `lang`. The first and
+last steps align with the row's edges, labels included, so the track lines up
+with the heading above it. Short labels fit a phone with no width budget.
 
-Since scrolling is the fallback, a labelled row is worth pairing with
-`.scroller`, which gives the native scrollbar the theme's density and colour
-instead of the OS default:
+Set `--step-min` when names need a wider minimum share. If the markers or that
+minimum do not fit, the row scrolls; use `.steps-vertical` when every name must
+remain visible without horizontal scrolling.
+
+In supporting browsers, a row that scrolls starts on its `aria-current="step"`
+instead of step 1. A row
+that raises `--step-min` can scroll, so it is worth pairing with `.scroller`,
+which gives the native scrollbar the theme's density and colour instead of the
+OS default:
 
 ```html
 <ol class="steps steps-horizontal scroller">
 ```
 
-Steps does not apply it for you, because scrollbar treatment is an app-wide
-decision rather than a per-component one. Every other scroll container —
-`.table`, a `.flyout`, a scrolling `dialog` — leaves the scrollbar alone too,
-so a page that thinned only its stepper would show two kinds of scrollbar. Put
-`.scroller` on whatever scrolls, once. See the sizing and wrapping page for its
-hooks.
+Steps does not apply it for you; see
+[one-row strips](../utilities/sizing-wrapping.md#one-row-strips) for the
+page-wide rule and the hooks.
 
 Do not add `.stable-gutter` here. It reserves gutter on the inline axis, for a
 vertical scrollbar this row never draws, so it narrows the row instead of
@@ -361,8 +368,9 @@ On `.steps`, so both orientations read them:
 
 `.steps-horizontal` only:
 
-- `--step-min` — minimum item width in the stacked horizontal layout
-- `--step-gap` — marker-to-label space in the stacked horizontal layout
+- `--step-min` — minimum width budget for stacked steps; the first and last
+  cells use half that budget plus half the marker width
+- `--step-gap` — marker-to-label and between-step space in the stacked layout
 - `--step-connector` — default horizontal connector background
 - `--step-inline-connector` — optional connector background for wide horizontal steps
 
@@ -372,12 +380,11 @@ On `.steps`, so both orientations read them:
 
 ## Notes
 
-Do not mix labelled and unlabelled steps in one sequence. Each step is sized on
-its own content, so a mixed sequence renders a narrow marker between reading-
-width steps — it lays out, but it reads as a gap rather than as progress.
+Do not mix labelled and unlabelled steps in one sequence. Empty steps align
+their markers to the start; labelled steps centre them over their names.
 
 A step name belongs in a `.step-label`. Bare text in an `<li>` is outside the
-contract: it is content, so it gets a reading width like a label, but no rule
+contract: it takes the same item floor as a label, but no rule
 places or aligns it.
 
 The **2 to 5** range applies to the horizontal orientation, and the inline
@@ -399,9 +406,8 @@ to stay distinguishable there. Steps deliberately ships no forced-colors
 override of its own: painting the marker `Highlight` makes the number or glyph
 inside it unreadable, which is worse than the ambiguity it removes.
 
-The inline threshold is calibrated to the default `--step-min`. Container
-queries cannot read custom properties, so changing `--step-min` moves the
-scroll budget but not the threshold.
+The inline threshold reserves connector space for five named stages. Changing
+`--step-min` moves the stacked scroll budget without moving that threshold.
 
 See [Steps representations and thresholds](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/steps.md)
 for why the contract is shaped this way, and which alternatives were measured

package/docs/pages/enhancements/flyout.md

@@ -180,6 +180,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/scrollspy.md

@@ -4,15 +4,15 @@
 
 Scrollspy is a behavior hook, not a visual component. It marks a navigation
 region for the JavaScript enhancement. Pair it with `.nav-list` and `.nav-link`,
-or style `[aria-current]` yourself.
+or style `[aria-current="location"]` yourself.
 
 ## Class reference
 
-| Class        | Kind        | Description                                                     |
-| ------------ | ----------- | --------------------------------------------------------------- |
-| `.scrollspy` | Component   | Marks the nav region for the enhancer; adds no visual styles.   |
-| `.nav-list`  | Composition | Vertical list of navigation links.                              |
-| `.nav-link`  | Component   | Navigation link whose active state comes from `[aria-current]`. |
+| Class        | Kind        | Description                                                   |
+| ------------ | ----------- | ------------------------------------------------------------- |
+| `.scrollspy` | Component   | Marks the nav region for the enhancer; adds no visual styles. |
+| `.nav-list`  | Composition | Vertical list of navigation links.                            |
+| `.nav-link`  | Component   | Navigation link, current on `aria-current="location"`.        |
 
 ## Usage
 

package/docs/pages/enhancements/tabs.md

@@ -14,14 +14,17 @@
 
 - Use real tab semantics when panels switch in place.
 - Use normal links and `aria-current="page"` for page navigation that only looks like tabs.
-- On that link variant, `aria-current="page"` on the current link gets the same
-  color and underline treatment as `aria-selected="true"` on a widget tab;
-  `primary` tints it.
+- On that link variant, `aria-current="page"` gets the same color and
+  underline treatment as `aria-selected="true"` on a widget tab; `primary`
+  tints it. A flyout trigger takes `"true"` (see below); any other value is
+  inert.
 - Tab selection never changes text metrics: the active tab keeps the shared
   weight and is marked by color and the indicator line.
 - JavaScript owns roving `tabindex`, `aria-selected`, `hidden`, and keyboard behavior.
 - Left/Right select tabs and wrap at the ends. Home/End jump to first/last. Down moves focus into the selected panel.
 - A tab list needs both `.tabs` and `role="tablist"`; `.tab` styles each trigger.
+  A tab belongs to its closest `role="tablist"`. `data-enhance="tabs"` on an
+  element without that role wires nothing and warns in the console.
 - Naming follows the container/item convention (like `menu` / `menu-item`):
   `.tabs` is the strip, `.tab` is one trigger. The JS module
   (`actual-css/js/tab`) is named for the file; the behavior token
@@ -86,6 +89,79 @@ JavaScript involved:
 </nav>
 ```
 
+## Equal-width tabs
+
+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">
+    <li><a class="tab primary" href="#reasons" aria-current="page">Reasons</a></li>
+    <li><a class="tab" href="#rates">Rates</a></li>
+  </ul>
+</nav>
+```
+
+## Too many tabs
+
+A horizontal strip is one row and never wraps, nor does a label: a second line
+would not match the Left/Right keys and reads as a nested level. When the tabs
+do not fit (narrow screen, mobile, long translations), the strip scrolls
+horizontally without a scrollbar; in supporting browsers, the edges it can
+still scroll toward fade out. Selecting or focusing the tab clipped at the edge
+scrolls it into view with the next one peeking, so a click, the arrow keys or a
+swipe move along the strip. A tab selected in the markup starts in view too,
+when the strip is visible at connect; the placement moves the strip only, never
+the page. In supporting browsers, so does the current link tab (or flyout
+trigger), without the runtime; elsewhere the strip starts at its first tab. A
+vertical strip (`aria-orientation="vertical"`) keeps wrapping its labels.
+
+Scrolling is the fallback, not a responsive design. If a strip regularly
+overflows, shorten the labels, group sections, or switch to a vertical rail.
+
+## Tab with a flyout
+
+In navigation tabs, a `.tab` can be a [flyout](flyout.md) trigger for a group of
+pages. The link to the current page inside its panel carries
+`aria-current="page"`. The trigger is not a page, so it takes
+`aria-current="true"` while its panel holds the current page: the section is
+the current item of the strip. This is the only place a `.tab` takes `true`.
+
+```html demo
+<nav aria-label="Account">
+  <ul class="tabs">
+    <li><a class="tab" href="#profile">Profile</a></li>
+    <li><a class="tab" href="#security">Security</a></li>
+    <li class="flyout-trigger">
+      <button class="tab"
+              type="button"
+              data-enhance="flyout"
+              aria-current="true"
+              aria-expanded="false"
+              aria-controls="billing-menu">
+        Billing <i class="ti ti-chevron-down" aria-hidden="true"></i>
+      </button>
+      <ul class="flyout menu" id="billing-menu" hidden>
+        <li><a class="menu-item" href="#invoices" aria-current="page">Invoices</a></li>
+        <li><a class="menu-item" href="#payment">Payment methods</a></li>
+      </ul>
+    </li>
+  </ul>
+</nav>
+```
+
+Do not put a flyout trigger in a `role="tablist"`: a tablist holds only
+`role="tab"` items, and the arrow keys of the two widgets collide.
+
 ## CSS hooks
 
+- `--tab-flex` — flex of each item; set `1 1 0` on the strip for equal-width tabs
+  (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/examples/overview.md

@@ -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/floating-field.md

@@ -7,11 +7,12 @@ the label rests inside the control and floats to the top when the control is
 focused or filled. It composes the existing `.field` layout and the text
 controls (`.input`, `.textarea`, `.select`) with zero JavaScript.
 
-The cell holds exactly one control and its label, with the control before the
-label. Label placement is linked through the general sibling combinator, so an
-injected node between the two (a password manager, an extension wrapper) is
-tolerated. Help and error messages stay in the surrounding `.field`, otherwise
-the resting label centers on the whole field instead of the control.
+The cell holds exactly one control and its label, in either order: a form
+theme that renders the label before the widget needs no reordering. An
+injected sibling (a password manager, an extension wrapper) is tolerated as
+long as the control stays a direct child of the cell. Help and error messages
+stay in the surrounding `.field`, otherwise the resting label centers on the
+whole field instead of the control.
 
 ```html demo
 <div class="field">
@@ -28,6 +29,17 @@ can detect emptiness — the space keeps the placeholder invisible while making
 the state detectable. `:autofill` is covered too, so a password manager that
 prefills a field still lifts the label.
 
+The same cell with the label first, as a label-then-widget form theme renders it:
+
+```html demo
+<div class="field">
+  <label class="floating-field">
+    <span class="field-label">Full name</span>
+    <input class="input" type="text" autocomplete="name" placeholder=" " />
+  </label>
+</div>
+```
+
 ## Textarea
 
 A textarea's empty label starts at the control's normal first-line position,
@@ -89,8 +101,10 @@ line on top of the control's minimum size.
 Validation and focus come from the existing form contracts: the control's
 border and focus ring flip through `--form-invalid-border` and the shared
 control focus rules. Coloring the label itself on focus or invalid state is
-left to the surrounding recipe — the joined floating form in the
-[blocks demo](../../demo/templates/blocks.html) shows one such recipe.
+left to the surrounding recipe; select the label through the cell
+(`.floating-field:has(> :focus) > .field-label`) so it holds in both orders.
+The joined floating form in the [blocks demo](../../demo/templates/blocks.html)
+shows one such recipe.
 
 > Not currently compatible with `.input-icon`; use standard labels when an
 > embedded leading icon is required.

package/docs/pages/forms/form-actions.md

@@ -8,10 +8,6 @@
 policy for form actions and the sticky behaviour. The space before the row
 belongs to the parent layout: put `.stack` on the form.
 
-`.form-actions` refines `.cluster` with alignment rules of equal specificity,
-so it wins on import order. In a modular build, import `layout/cluster` before
-`forms/form-actions`; the family entries and the full bundle already do.
-
 ```html demo
 <form class="stack" novalidate>
   <label class="field">
@@ -65,8 +61,9 @@ In application CSS, the same policy is one declaration on the region:
 }
 ```
 
-On a form action row, `--cluster-justify` and `--cluster-align` have no effect;
-use the hooks above, or a `.justify-content-*` / `.items-*` utility on one row.
+On a form action row, use the hooks above rather than `--cluster-justify` /
+`--cluster-align`: the role writes those from its own hooks. For one row, a
+`.justify-content-*` / `.items-*` utility also works.
 A split pair keeps the dismissive action at the leading edge and the committing
 one at the trailing edge:
 

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/states-and-sizes.md

@@ -26,8 +26,8 @@ together. Density contexts leave both unchanged.
 <form class="stack" novalidate>
   <fieldset class="field-group">
     <legend class="field-label">Text control states</legend>
-    <div class="stack" style="--grid-min: 14rem;">
-      <div class="grid items-start">
+    <div class="stack">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="field">
           <span class="field-label">Editable</span>
           <input class="input" type="text" value="Ocean Beach Clinic" />
@@ -46,7 +46,7 @@ together. Density contexts leave both unchanged.
         </label>
       </div>
 
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="field">
           <span class="field-label">Editable notes</span>
           <textarea class="textarea">Patient asked for an invoice copy.</textarea>
@@ -67,8 +67,8 @@ together. Density contexts leave both unchanged.
 
   <fieldset class="field-group">
     <legend class="field-label">Choice and select states</legend>
-    <div class="stack" style="--grid-min: 14rem;">
-      <div class="grid items-start">
+    <div class="stack">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="field">
           <span class="field-label">Editable select</span>
           <select class="select">
@@ -98,7 +98,7 @@ together. Density contexts leave both unchanged.
         </label>
       </div>
 
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="choice">
           <input class="check" type="checkbox" />
           <span>
@@ -140,7 +140,7 @@ together. Density contexts leave both unchanged.
         </label>
       </div>
 
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="choice">
           <input class="radio" type="radio" name="demo-radio-state" />
           <span>
@@ -174,7 +174,7 @@ together. Density contexts leave both unchanged.
         </label>
       </div>
 
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="choice">
           <input class="switch" type="checkbox" role="switch" />
           <span>
@@ -212,8 +212,8 @@ together. Density contexts leave both unchanged.
 
   <fieldset class="field-group">
     <legend class="field-label">Control sizes</legend>
-    <div class="stack" style="--grid-min: 14rem;">
-      <div class="grid items-start">
+    <div class="stack">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="field sm">
           <span class="field-label">Small field</span>
           <input class="input" type="text" value="sm" />
@@ -230,7 +230,7 @@ together. Density contexts leave both unchanged.
         </label>
       </div>
 
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="field sm">
           <span class="field-label">Small select</span>
           <select class="select">
@@ -253,7 +253,7 @@ together. Density contexts leave both unchanged.
         </label>
       </div>
 
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="field sm">
           <span class="field-label">Small textarea</span>
           <textarea class="textarea" rows="2">Short note</textarea>
@@ -270,14 +270,14 @@ together. Density contexts leave both unchanged.
         </label>
       </div>
 
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <button class="btn outline sm" type="button">Small</button>
         <button class="btn outline" type="button">Default</button>
         <button class="btn outline lg" type="button">Large</button>
       </div>
 
       <!-- Size belongs on the choice wrapper so label and control move together. -->
-      <div class="grid items-start">
+      <div class="grid items-start" style="--grid-min: 14rem;">
         <label class="choice sm">
           <input class="check" type="checkbox" checked />
           <span>Small checkbox</span>
@@ -297,7 +297,7 @@ together. Density contexts leave both unchanged.
       </div>
 
       <!-- The underlying typography hook remains available for custom scales. -->
-      <div class="grid items-start" style="--control-font-size: var(--font-size-sm);">
+      <div class="grid items-start" style="--grid-min: 14rem; --control-font-size: var(--font-size-sm);">
         <label class="choice">
           <input class="check" type="checkbox" checked />
           <span>Smaller type</span>