actual-css 0.13.0 → 0.14.0

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

@@ -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/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/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/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
 

package/docs/pages/foundations/tokens.md

@@ -151,34 +151,42 @@ Color should reinforce structure and meaning, not carry them alone. Information
 
 The default palette is **Ink & Terra**: a near-neutral aubergine `primary`, terracotta `secondary`, and pigment-toned statuses (sage, ochre, brick) tuned to equal perceived weight. The neutral ramp (text, borders, subtle surfaces) is tinted toward the primary hue so the whole page quietly carries the identity. Optional themes can re-introduce vivid intent palettes on top of this foundation.
 
-Soft surfaces (`.btn.soft`, `.badge.soft`, and the default `.alert`) are generated from intent colors through `color-mix()`. Themes can tune the mix globally instead of rewriting component selectors.
+Soft surfaces are generated from intent colors through `color-mix()`, in two
+recipes that share one ink:
+
+- **Tint** — the default `.badge` and `.alert`, and `.btn.soft`: a translucent
+  intent laid over whatever surface is underneath, with no rim. It keeps
+  separating on `--surface-subtle` and `--surface-raised`, where a fixed mix
+  with `--surface` would match the surface it sits on.
+- **Mix** — the shared `.soft` on zones (`.card`, `.chat-bubble`, `.navbar`,
+  `.app-nav`): an opaque mix of `--surface` with the intent and a tinted rim.
+  A zone may sit over an image, where a translucent fill would hand the text's
+  contrast to whatever is behind it.
+
+Themes tune both globally instead of rewriting component selectors:
 
 ```css
 :root {
-  --soft-bg-mix: 88%;
-  --soft-border-mix: 65%;
-  --soft-hover-alpha: 12%;
+  --soft-bg-mix: 88%;     /* share of surface; the tint's opacity is 100% minus it */
+  --soft-hover-alpha: 6%; /* extra intent share on hover */
   --soft-fg-mix: 100%;
 }
 ```
 
-`--soft-border-mix` is the same lever for the rim. The `65%` default keeps a
-visibly tinted border around every soft surface; pointing it at `--soft-bg-mix`
-resolves the rim to the fill, and soft treatments become a tint carrying text
-with no contour — the flatter language of a modern component set, from one
-declaration:
+`--soft-border-mix` has no default. Unset, the tint draws no rim and the mix
+keeps a 65% one. A theme that sets it gives every soft treatment a tinted rim
+of that weight — contoured badges and alerts, from one declaration:
 
 ```css
-[data-theme="flat"] {
-  --soft-border-mix: var(--soft-bg-mix);
+[data-theme="contoured"] {
+  --soft-border-mix: 65%;
 }
 ```
 
-It reaches the default `.badge` and `.alert` plus every explicit `.soft`
-(`.btn`, `.card`, `.chat`, `.navbar`, `.app-nav`), and nothing else: a component
-on its own surface keeps its `--border` rim. The dial is also
-rendering-only — the baseline path below `color-mix()` keeps `var(--border)`, so
-borderless soft is a look, not a contract the Degraded tier upholds.
+A rule that re-derives a soft color reads it with the recipe's own fallback:
+`var(--soft-border-mix, 100%)` for a tint, `var(--soft-border-mix, 65%)` for a
+mix. Both recipes are rendering-only — the baseline path below `color-mix()`
+keeps `var(--surface-subtle)` and `var(--border)`.
 
 `--soft-fg-mix` is the share of raw intent in soft *text*. At its `100%` default soft ink is the intent color itself, which is what a palette of dark, muted intents wants. A vivid or light palette cannot afford that: a soft badge then paints intent-tinted ink on an intent-tinted surface, and the two converge. Lowering the mix rebates the ink toward `--text`, which is the right direction in both schemes because `--text` is dark on a light theme and light on a dark one. Around `45%` a fully saturated palette recovers AA while the ink still reads as its intent.
 
@@ -193,17 +201,19 @@ hook, and the soft recipe reads it before falling back to the global mix:
 - `--soft-fg-mix` — the **global fallback derivation**, unchanged.
 
 **Soft foregrounds are calibrated against the darkest or closest interactive
-surface they are expected to appear on.** For interactive soft treatments the
-fill moves toward the intent on hover (`--soft-hover-alpha`), so the binding
-surface is the *hovered* one and the resting fill simply carries more margin;
-the default palette ships its own `--primary`/`--secondary`/… `-soft-fg` hooks
-to keep that pair ≥ 4.5:1 in both color schemes, enforced by
-`tests/browser/soft-recipe.test.js`. The hard line stops at the default theme:
+surface they are expected to appear on.** The tint is translucent, so the same
+pair reads differently on each surface — usually closest on `--surface-subtle`.
+For interactive soft treatments the fill moves toward the intent on hover
+(`--soft-hover-alpha`), so the binding pair is the *hovered* tint over
+`--surface-subtle` and the resting fill simply carries more margin; the default
+palette ships its own `--primary`/`--secondary`/… `-soft-fg` hooks to keep
+every pair ≥ 4.5:1 on `--surface`, `--surface-raised` and `--surface-subtle` in
+both color schemes, enforced by `tests/browser/soft-recipe.test.js`. The hard line stops at the default theme:
 presets and custom `[data-theme]` islands keep the `--soft-fg-mix` derivation
 unless they declare the hooks themselves (the framework resets them outside
 the default boundary). A theme that overrides the soft palette is responsible
 for preserving sufficient text contrast; `bunx --bun actual-css contrast --theme FILE`
-measures its resting and hovered pairs.
+measures its resting and hovered pairs, composited on each of those surfaces.
 
 A theme whose primary should read more muted than its statuses sets only
 `--primary-soft-fg`, and every soft `.primary` foreground follows it. Without a
@@ -599,12 +609,33 @@ A minimal recolor theme (illustrative, not a shipped theme):
 
 Several tokens are theme-derived aliases that reference other tokens — `--state-selected`/`--state-selected-fg`/`--state-disabled`, `--indicator-ring`, `--shadow`/`--shadow-popout`, `--heading`, `--selection-bg`/`--selection-fg`, and `--surface-opaque`/`--surface-solid-fg`. They are declared on `:root, [data-theme]` so they recompute on every theme boundary: a custom property resolves its `var()` references at computed-value time on the element that declares it, so an alias declared only on `:root` would be inherited as an already-resolved value and would not follow a `[data-theme]` island's overridden tokens. A theme that wants a distinct alias (e.g. a `--selection-bg` of its own) overrides it explicitly afterwards, which wins by cascade order.
 
+Selected state has three roles:
+
+- `--state-selected` — the selected fill or accent: a pressed button, a checked switch, a completed step.
+- `--state-selected-fg` — ink on that fill.
+- `--state-selected-text` — selected ink on a regular surface: the current nav link, the selected tab, the current step's number and ring.
+
+`--state-selected-text` has no default: the core resets it to the guaranteed-invalid value on every theme boundary, and each consumer reads `var(--state-selected-text, var(--state-selected))`. The reset is what lets a nested theme island reach its own `--state-selected`: a theme that resolves the hook to another token bakes the reference where it is declared, so an island that sets nothing would otherwise inherit the resolved value and never fall back. Set it when one color cannot be both a fill under its `-fg` and text on the page — typically a dark scheme, where a fill dark enough for white ink is too dark to read as text. Pulling the accent toward `--text` keeps its hue in both schemes:
+
+```css
+[data-theme="my-theme"] {
+  --state-selected-text: light-dark(
+    var(--primary),
+    color-mix(in oklab, var(--primary) 50%, var(--text))
+  );
+}
+```
+
+`actual-css contrast` measures it on each surface (4.5:1 for text, 3:1 for the step ring).
+
 Without `data-theme`, the default theme advertises `color-scheme: light dark` and follows the user's OS preference in browsers that support `light-dark()`. Dark themes should set `color-scheme: dark`. Light themes should set `color-scheme: light`. Browsers without `light-dark()` receive the light fallback.
 
 Because the native select chevron is an SVG background image and cannot inherit `currentColor`, the select hands the arrow back to the browser under `prefers-contrast: more` (same treatment as `forced-colors: active`) instead of shipping a recolored chevron per theme — one native fallback covers every theme without a high-contrast icon variant to maintain.
 
 Under `prefers-contrast: more`, the user's contrast preference wins over a theme's palette by contract: the core collapses `--text-muted`/`--text-subtle` to `--text` and thickens borders and focus so no theme can defeat a legibility requirement. This is a deliberate decision, not a specificity quirk — the repeated `[data-theme][data-theme]` attribute only outranks a preset theme stylesheet loaded after the core.
 
+Under `prefers-reduced-transparency: reduce`, `.topbar` and `.form-actions.sticky` paint `--surface` without a backdrop blur. A theme with translucent `--surface-*` redeclares them opaque inside the same media query; the glass demo theme shows the recipe.
+
 Under `forced-colors: active`, the browser automatically remaps `color`, `background`, and `border` properties to system colors. The core only adjusts what the remapping cannot express on its own — `--state-disabled` becomes `GrayText` and `--disabled-opacity` becomes `1` — declared on `:root` and `[data-theme]` so every theme boundary follows. Keep local forced-color rules only for custom control geometry, native bar parts, or selected/checked states that would otherwise be communicated only by background color.
 
 ## Component mapping

package/docs/pages/guides/design-tools.md

@@ -10,16 +10,22 @@ bunx --bun actual-css design --theme src/theme.css --out design/
 
 ## What is exported
 
-| File                                          | Content                              |
-| --------------------------------------------- | ------------------------------------ |
-| `figma/foundations.tokens.json`               | spacing, radius, borders, type sizes |
-| `figma/light.tokens.json`, `dark.tokens.json` | colors, one file per scheme          |
-| `penpot/tokens.json`                          | all tokens, as sets and themes       |
-| `penpot/plugin/`                              | the plugin and component spec        |
+| File                                          | Content                                |
+| --------------------------------------------- | -------------------------------------- |
+| `figma/foundations.tokens.json`               | spacing, radius, borders, type sizes   |
+| `figma/light.tokens.json`, `dark.tokens.json` | colors, one file per scheme            |
+| `dtcg/foundations.tokens.json`                | the portable profile, every foundation |
+| `dtcg/light.tokens.json`, `dark.tokens.json`  | colors, one file per scheme            |
+| `penpot/tokens.json`                          | all tokens, as sets and themes         |
+| `penpot/plugin/`                              | the plugin and component spec          |
 
 Token names are the CSS names without `--`: `surface-raised` in the design tool is `var(--surface-raised)` in code. A scheme exists when the theme declares it: `color-scheme: light dark` exports both, anything else one. Lengths are exported in px, with the CSS value kept in `$extensions["actual-css"]`.
 
-Colors no theme token paints — the soft fills and borders of `.soft` — are exported as recipe tokens named `<variant>-<intent>-<role>` (`soft-danger-bg`, `soft-danger-border`, `soft-danger-fg`), next to the theme colors so they switch with the scheme. Font stacks, line heights, shadows, motion and z-index have no design-tool equivalent and are not exported.
+Colors no theme token paints — the soft fills and borders of `.soft` — are exported as recipe tokens named `<variant>-<intent>-<role>` (`soft-danger-bg`, `soft-danger-border`, `soft-danger-fg`), next to the theme colors so they switch with the scheme.
+
+## DTCG
+
+`dtcg/` is the portable profile, for any reader that follows the [Design Tokens Format](https://www.designtokens.org/format/): every foundation carries the `$type` the spec defines (`dimension`, `fontWeight`, `fontFamily`, `duration`, `cubicBezier`, `number`), and each color carries a 6-digit `hex` with `alpha` separate. It keeps font stacks, line heights and motion, which `figma/` drops, and omits Figma's adaptations: a font weight is a `fontWeight` here, a `number` there. Shadows and z-index are not exported anywhere.
 
 ## Figma
 

package/docs/pages/guides/introduction.md

@@ -53,7 +53,7 @@ optimizing — the bare `actual-css` entrypoint and `actual-css/full` both resol
 to the complete compiled framework:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.13/dist/actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.14/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map