actual-css 0.7.0 → 0.9.0

package/docs/pages/forms/combobox.md

@@ -75,7 +75,7 @@ contrast contracts apply to the combobox for free:
   background: color-mix(in oklab, var(--surface) var(--soft-bg-mix), var(--primary));
   color: color-mix(in oklab, var(--primary) var(--soft-fg-mix), var(--text));
   font-size: var(--font-size-xs);
-  font-weight: var(--font-weight-strong);
+  font-weight: var(--font-weight-semibold);
 }
 ```
 

package/docs/pages/forms/floating-field.md

@@ -68,11 +68,12 @@ every state, so their label always sits at the top.
 </div>
 ```
 
-## Density
+## Size and density
 
 The reserved headroom responds to control density through `--control-size`:
-`.sm` and `.lg` on the cell or an ancestor resize the control geometry and the
-label spacing with it. Typography is untouched, as everywhere in the framework.
+`.sm` and `.lg` on the cell resize the control geometry and typography. A
+`.compact` or `.spacious` ancestor changes geometry only, including the label
+spacing with it; typography stays unchanged under density.
 The floating label does add height — the headroom reserves a second vertical
 line on top of the control's minimum size.
 

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

@@ -13,6 +13,8 @@
 
 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.
+
 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.
 
 ```html demo
@@ -33,6 +35,26 @@ the focus ring surrounds the complete joined field. Attached buttons keep their
 own focus indicator when reached directly, so the actionable segment remains
 identifiable.
 
+## Linting `role="group"`
+
+Biome's `a11y/useSemanticElements` reports the wrapper and offers `<fieldset>`
+as the replacement. That is the only element it suggests, and it does not fit:
+`<fieldset>` groups form controls under a `<legend>`, while ARIA's `group` is
+any labelled set of related objects. Suppress it on the element:
+
+```html
+<!-- biome-ignore lint/a11y/useSemanticElements: ARIA group has no HTML
+     equivalent here; fieldset expects form controls under a legend. -->
+<div class="join" role="group" aria-label="Date navigation">
+```
+
+Unlike the menu rule in
+[flyout](../enhancements/flyout.html#linting-rolemenu), do not switch this one
+off globally: it correctly catches `<div role="navigation">`,
+`<div role="button">` and `<div role="separator">`. And drop `role="group"`
+rather than suppressing it when the wrapper has no label to give — an unnamed
+group adds a boundary and nothing else.
+
 ## CSS hooks
 
 - `--join-radius` — outer corner radius of the joined group. The per-corner

package/docs/pages/forms/otp.md

@@ -36,7 +36,8 @@ Add exactly one visual `span` per expected character. Their count must match
 a numeric keyboard but does not enforce numeric input; validate the submitted
 value as usual.
 
-The component follows shared `.sm` and `.lg` density through `--control-size`.
+The component follows shared `.sm` and `.lg` size through `--control-size` and
+`--control-font-size`.
 Use `aria-invalid="true"` for explicit invalid state, or place it in the
 standard `.needs-validation.was-validated` form flow.
 

package/docs/pages/forms/overview.md

@@ -98,7 +98,7 @@ A full form using the control classes, field wrappers, and form actions:
 
     <fieldset class="field-group">
       <legend class="field-label">Availability</legend>
-      <div class="stack sm">
+      <div class="stack compact">
         <label class="choice">
           <input class="radio" type="radio" name="availability" value="available" checked />
           <span>Available for work</span>

package/docs/pages/forms/states-and-sizes.md

@@ -4,23 +4,23 @@
 
 ## Class reference
 
-| Class | Kind     | Description                                |
-| ----- | -------- | ------------------------------------------ |
-| `.sm` | Modifier | Compact control height and spacing rhythm. |
-| `.lg` | Modifier | Large control height and spacing rhythm.   |
+| Class | Kind     | Description                              |
+| ----- | -------- | ---------------------------------------- |
+| `.sm` | Modifier | Smaller control geometry and typography. |
+| `.lg` | Modifier | Larger control geometry and typography.  |
 
-Each sets `--control-size` to `--control-size-sm` or `--control-size-lg`.
+Each maps `--control-size` and `--control-font-size` to the matching step.
 
 Use `readonly` for text-like values that can still be focused, selected, and submitted. Use `disabled` for unavailable controls that should not receive focus or submit a value.
 
-The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, selects, textareas, and buttons. Put the modifier on the control itself, or on a `.field` wrapper when the whole field should share that size.
+The `.sm` and `.lg` modifiers set the shared control tokens used by inputs,
+selects, textareas, buttons, and inline choices. Put the modifier on the control
+itself, or on a `.field` wrapper when the whole field should share that size.
 
-Inline choices — `.check`, `.radio`, `.switch` — are the exception. They sit on
-a line of text rather than standing as a field, so they are sized off the
-control typography (`--choice-control-size`, an em value) and `.sm` / `.lg`
-leave them alone: density changes field heights, not type. Resizing the control
-without its label would only break the alignment. Scale them by scaling their
-type instead.
+Inline choices — `.check`, `.radio`, `.switch` — sit on a line of text, so their
+geometry follows the local control typography through `--choice-control-size`.
+Apply `.sm` or `.lg` to the `.choice` wrapper so its label and control scale
+together. Density contexts leave both unchanged.
 
 ```html demo
 <form class="stack" novalidate>
@@ -276,12 +276,11 @@ type instead.
         <button class="btn outline lg" type="button">Large</button>
       </div>
 
-      <!-- Density is a deliberate no-op on inline choices: these three are
-           identical even though the modifiers differ. -->
+      <!-- Size belongs on the choice wrapper so label and control move together. -->
       <div class="grid items-start">
         <label class="choice sm">
           <input class="check" type="checkbox" checked />
-          <span>.sm checkbox</span>
+          <span>Small checkbox</span>
         </label>
         <label class="choice">
           <input class="radio" type="radio" name="demo-radio-size" checked />
@@ -289,7 +288,7 @@ type instead.
         </label>
         <label class="choice lg">
           <input class="switch" type="checkbox" role="switch" checked />
-          <span>.lg switch</span>
+          <span>Large switch</span>
         </label>
         <label class="choice">
           <input class="check" type="checkbox" id="indet-size" />
@@ -297,8 +296,7 @@ type instead.
         </label>
       </div>
 
-      <!-- Typography is the knob that does resize them — control and label
-           together, so the alignment survives. -->
+      <!-- The underlying typography hook remains available for custom scales. -->
       <div class="grid items-start" style="--control-font-size: var(--font-size-sm);">
         <label class="choice">
           <input class="check" type="checkbox" checked />

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

@@ -57,7 +57,7 @@ Scroll the page to see the actions stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack sm">
+      <div class="stack compact">
         <label class="choice">
           <input class="radio" type="radio" name="theme" value="light" checked />
           <span>Light</span>
@@ -141,7 +141,7 @@ Scroll the page to see the detached footer stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack sm">
+      <div class="stack compact">
         <label class="choice">
           <input class="radio" type="radio" name="theme-detached" value="light" checked />
           <span>Light</span>

package/docs/pages/forms/switch.md

@@ -62,7 +62,7 @@ naturally or via an explicit line break — still sit cleanly.
 
 A switch is sized off the control typography, not field density. Its track
 comes from `--choice-control-size` — the same token a checkbox and a radio use
-— so the three sit on a line of text at matching weight. `.sm` and `.lg` change
+— so the three sit on a line of text at matching weight. Density contexts change
 `--control-size`, which is field height, and deliberately leave inline choices
 alone.
 

package/docs/pages/foundations/philosophy.md

@@ -29,12 +29,15 @@ There is no `.btn-primary` or `.badge-success`. Intents are generic and reusable
 
 Components fall back to their own default intent when no intent class is set. Buttons, badges, and alerts use the neutral palette (`--neutral` / `--neutral-fg`) by default.
 
-Custom intents need no framework support — define `--intent` and `--intent-fg` on a class:
+Custom intents need no framework support — define `--intent` and `--intent-fg`
+(and `--intent-soft-fg` when the custom role needs its own soft foreground) on a
+class:
 
 ```css
 .tertiary {
   --intent: var(--tertiary);
   --intent-fg: var(--tertiary-fg);
+  --intent-soft-fg: var(--tertiary-soft-fg);
 }
 ```
 
@@ -52,34 +55,60 @@ Custom intents need no framework support — define `--intent` and `--intent-fg`
 `.ghost` and `.link` are button-only variants.
 
 ```html demo
-<button class="btn soft primary">Soft primary</button>
-<span class="badge outline success">Outline success</span>
-<div class="alert solid warning">Solid warning</div>
+<div class="stack">
+  <div class="cluster">
+    <button class="btn soft primary">Soft primary</button>
+    <span class="badge outline success">Outline success</span>
+  </div>
+  <div class="alert solid warning">Solid warning</div>
+</div>
 ```
 
-## Density
-
-`.sm` and `.lg` establish inherited density tokens. Density adjusts how much
-space UI consumes — spacing and component geometry — not how large its content
-is: typography and icon size never change. Components opt into the density
-dimensions that make sense for them. The same modifiers can also be applied
-directly to a component for local density.
+## Size and density
+
+`.sm` and `.lg` mean one size role below or above a component's natural size.
+Size names are shared roles, not shared measurements. Each participating
+component family maps them to its own optical scale: badges use `xs / sm / md`,
+while controls use `sm / md / lg`. Components without an explicit mapping do
+not change.
+
+A size role is applied to the component that participates in the scale and
+never styles arbitrary descendants. It propagates through token inheritance,
+though: components in the shared control scale set local `--control-size` and
+`--control-font-size`, and descendants consume them by their own rules. That is
+how `.field sm`, `.input-icon sm`, `.join sm`, and `.flyout sm` size the
+controls inside them, while a bare `.sm` on a plain element does nothing.
+
+`.compact` and `.spacious` establish inherited density tokens. Density arranges
+how tightly UI sits — spacing and component geometry — while typography and
+icon size stay unchanged. Participation is opt-in, and a component only joins
+where density has an effect independent from its optical size: if the result is
+merely that the component looks smaller or larger, that is size, not density.
+
+Density participation takes three levels:
+
+- **Geometry + rhythm** — controls and their wrappers (`.field`, `.join`,
+  `.flyout`, …). Height, padding, and gap respond; typography is untouched.
+- **Rhythm only** — content rows and shells such as `.list`. Spacing tightens
+  (`--list-item-gap: var(--gap)`), but the structural size stays stable.
+- **No density effect** — components whose geometry is intrinsic to their
+  content (`.badge`, `.avatar`, `.spinner`, `.rating`, `.key`, prose, inline
+  `.choice`/`.switch`). Their optical size belongs to `sm`/`lg` or local hooks.
 
 As inherited contexts, one class tightens or loosens the whole subtree:
 
 ```html demo
-<div class="sm">
+<div class="compact stack">
   <button class="btn">Compact button</button>
   <input class="input">
   <span class="badge">Compact badge</span>
 </div>
 ```
 
-Application chrome can use the same scope; no separate `.compact` mode is
-needed:
+Application chrome can use the same scope:
 
 ```html demo
-<header class="navbar sm">
+<header class="navbar compact">
   <a class="navbar-brand" href="/">Workspace</a>
   <nav class="cluster" aria-label="Workspace actions">
     <button class="btn ghost">Search</button>
@@ -88,22 +117,24 @@ needed:
 </header>
 ```
 
-The same class on a component is local density, not a second meaning:
+Component geometry remains local and wins over inherited density when both
+affect the same dimension:
 
 ```html demo
-<button class="btn sm">Compact button</button>
-<span class="badge lg">Spacious badge</span>
+<div class="compact">
+  <button class="btn lg">Large button in a compact context</button>
+</div>
 ```
 
-This is not "`.sm` sometimes means density and sometimes size": `.sm` always
-establishes the same density tokens — only the scope changes. The density
-tokens are `--gap`, `--density-space`, `--control-size`, and
-`--density-compact-size`. Components consume the dimensions that make sense
-for them and opt out of the rest. The absolute `--space-*` scale is not rebound
-by density scopes.
+The density tokens are `--gap`, `--density-space`, and `--control-size`.
+Components consume the dimensions that make sense for them and opt out of the
+rest. The absolute `--space-*` scale is not rebound by density scopes.
+Components with bespoke geometry (`.badge`, `.avatar`,
+`.spinner`, `.rating`) own their local `.sm`/`.lg` mappings.
 
-Components with bespoke sizing (`.avatar`, `.spinner`) define local `.sm`/`.lg`
-instead of consuming the shared tokens.
+`.compact` also remains a meaningful local modifier for `.card` and `.table`.
+On those components it tightens their own padding and establishes the compact
+density context for descendants.
 
 ## Child semantics
 

package/docs/pages/foundations/theming.md

@@ -20,7 +20,7 @@ Set `--cluster-align`.
 
 ### Change spacing without changing control size
 
-Set `--gap` locally on the layout primitive. The extra utilities (`src/css/utilities/extra.css`) ship `.gap-sm` / `.gap-md` / `.gap-lg` for row/column containers.
+Set `--gap` on the layout primitive to retune it and everything nested. To change only that element's rhythm without reaching nested primitives, set the `gap` property instead.
 
 → Layout
 
@@ -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, set `--choice-control-size` instead — the checkbox, the radio, and the switch track all follow it. `.sm` / `.lg` are field density and leave inline choices alone.
+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.
 
 → Forms · Switch
 

package/docs/pages/foundations/tokens.md

@@ -76,6 +76,18 @@ Focus styling is outline-first. `--focus` names the theme's focus color, and a r
 }
 ```
 
+### Palette coherence
+
+A coherent palette treats surfaces, text, borders, intents, and shadows as related roles rather than isolated colors.
+
+Coherence does not mean that every token must be chromatic. Pure or near-pure whites and blacks remain legitimate where their role calls for them; what matters is that the surrounding neutral ramp and derived treatments belong to the same visual family.
+
+Neutral roles may lean toward the palette's ambient hue — by default the primary's — while lightness and chroma stay curated per role. Chroma runs strongest through the ramp's mid-lightness rungs, often around `--border` and `--text-muted` depending on the color scheme, and tapers toward both ends. A palette whose accent is deliberately warmer or cooler than its paper picks an ambient hue of its own.
+
+Semantic intents are curated colors, not mechanical derivatives of `--primary`. Danger, warning, and success stay recognizable for their function, but they are chosen as members of the theme palette rather than copied independently from a generic scale. Neither intents nor neutrals are derived from `--primary` at runtime: the relationship is a design decision recorded in the theme's own values.
+
+Color should reinforce structure and meaning, not carry them alone. Information hierarchy and semantic states should remain understandable when hue is removed or unavailable. Desaturating a composition is a useful review heuristic, not a conformance test.
+
 ### Default theme philosophy
 
 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.
@@ -91,8 +103,62 @@ Soft surfaces (`.btn.soft`, `.badge.soft`, and the default `.alert`) are generat
 }
 ```
 
+`--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:
+
+```css
+[data-theme="flat"] {
+  --soft-border-mix: var(--soft-bg-mix);
+}
+```
+
+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.
+
 `--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.
 
+Soft ink can also be corrected per role. The intent classes relay a per-role
+hook, and the soft recipe reads it before falling back to the global mix:
+
+- `--primary-soft-fg`, `--secondary-soft-fg`, `--success-soft-fg`,
+  `--warning-soft-fg`, `--danger-soft-fg`, `--neutral-soft-fg` — **theme hooks
+  per role**; the ones whose palette needs a softer ink than the others.
+- `--intent-soft-fg` — the **current relay** (framework plumbing), set by each
+  intent class to its own `--*-soft-fg`.
+- `--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:
+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; `bun run report:theme-contrast`
+reports every preset's resting and hovered pairs without failing the build.
+
+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
+`--*-soft-fg` the recipe resolves byte-identically to the old `--soft-fg-mix`
+derivation. A custom intent class provides the relay directly:
+
+```css
+.tertiary {
+  --intent: var(--tertiary);
+  --intent-fg: var(--tertiary-fg);
+  --intent-soft-fg: var(--tertiary-soft-fg);
+}
+```
+
 **When an intent is tinted against a theme-controlled surface or border, the mix interpolates in `oklab`.** That covers the soft recipe, the checked `.choice-card` tint, and the `.overline.pill` border.
 
 Not because rectangular interpolation is more faithful to the intent hue — across the shipped presets it is a few degrees *less* faithful. A browser treats hue as powerless below a small chroma epsilon, so for the low-chroma surfaces and borders the presets actually use, a polar mix snaps cleanly onto the intent and wins.
@@ -147,8 +213,10 @@ Typography tokens cover the document baseline and common component needs.
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
 
   --line-height: 1.5;
-  --font-weight: 400;
-  --font-weight-strong: 650;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
 
   --font-size-xs: 0.8125rem;
   --font-size-sm: 0.875rem;
@@ -161,7 +229,9 @@ Components can use local font variables for their own mapping, but should inheri
 
 ### Controls
 
-Controls share sizing so buttons, inputs, selects, and compact app UI always align. `.sm`/`.lg` set shared density tokens for controls, compact labels, and spacing helpers.
+Controls share geometry so buttons, inputs, selects, and compact app UI align.
+Local `.sm`/`.lg` sizes map `--control-size`, `--control-font-size`, and
+`--control-pad-x`.
 
 ```css
 :root {
@@ -169,41 +239,53 @@ Controls share sizing so buttons, inputs, selects, and compact app UI always ali
   --control-size-md: 2.375rem;  /* 38px → default */
   --control-size-lg: 2.75rem;   /* 44px → .lg */
   --control-size: var(--control-size-md);
-  --control-pad-x: 1em;
+  --control-pad-x: var(--font-size-md);
   --control-font-size: var(--font-size-md);
   --disabled-opacity: 0.65;
 }
 ```
 
+`--control-pad-x` is a resolved geometry length, stated in the typographic
+tokens rather than an `em`. Every part of one control must see the same
+horizontal distance; an `em` would change value on a descendant with its own
+font size, which is exactly what `--input-icon-size` does to the icon glyph. It
+mirrors `--control-font-size` and is rebound beside it at the `.sm`/`.lg`
+boundaries.
+
 - `.lg` — 44px control height
 - default — 38px control height
 - `.sm` — 32px control height
 
-The font size stays at the baseline (`--control-font-size` = `--font-size-md`) in every density — density changes how much space controls consume, not how large their text is.
+The default font size is `--font-size-md`; `.sm` maps it to `--font-size-sm` and
+`.lg` to `--font-size-lg`. Density contexts change `--control-size` without
+changing the font size.
 
 Disabled controls and disabled-prone components read `--disabled-opacity` for their dimmed state — buttons, tabs, menu items, badges, avatars, choice cards, native inputs, and range sliders.
 
 ### Density
 
-Density modifiers swap the shared control geometry:
+Density contexts swap shared spacing and geometry:
 
 ```css
-.sm {
+.compact {
   --gap: var(--space-20);
   --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
-  --density-compact-size: 1.25rem;
 }
 
-.lg {
+.spacious {
   --gap: var(--space-50);
   --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
-  --density-compact-size: 1.875rem;
 }
 ```
 
-Density covers spacing and geometry only — it never touches typography or icon size. Compact labels such as `.badge` consume `--density-compact-size`; display elements with special geometry, such as avatar and spinner, keep their own size scales. Content blocks like alert, card, dialog, table, and accordion do not participate.
+Density covers spacing and geometry only — it never touches typography or icon
+size. Participation is opt-in and selective: controls consume `--control-size`
+for geometry; spacing helpers and rhythms consume `--density-space` and `--gap`;
+components whose size is intrinsic (badge, avatar, spinner, rating, key, prose,
+inline choice/switch) keep their own scales. A local component size overrides
+inherited density for the dimensions they share.
 
 ### Elevation
 
@@ -258,7 +340,7 @@ A single icon token can serve both `background-image` (native select) and `mask-
 A few cross-component helpers:
 
 - `--indicator-offset` / `--indicator-ring` — positioning and contrast ring for a status dot attached to `.avatar > .badge:empty`.
-- `--backdrop-color` / `--backdrop-opacity` / `--backdrop-fill` — scrim color and opacity shared by `dialog.modal::backdrop`, `dialog.drawer::backdrop`, and `.surface-backdrop`. Override `--backdrop-opacity` per theme for a denser or lighter scrim.
+- `--backdrop-color` / `--backdrop-opacity` / `--backdrop-fill` — scrim color and opacity shared by `dialog.modal::backdrop` and `dialog.drawer::backdrop`. Override `--backdrop-opacity` per theme for a denser or lighter scrim.
 
 ```css
 :root {
@@ -274,18 +356,30 @@ Under `forced-colors: active`, `--backdrop-fill` maps to `Canvas`.
 
 ### Layering
 
-A small z-index scale orders non-dialog overlays. Native `<dialog>` elements (modal, drawer) render on the platform top-layer, which has no numeric z-index and always paints above the page — they never compete with this scale.
+Two systems order overlays, and only one of them uses numbers.
+
+**The platform top layer** holds native `<dialog>` (modal, drawer) and every element currently showing as a popover — which, since the runtime drives flyouts, context menus and tooltips with `popover="manual"`, is all of Actual's anchored overlays. Top-layer ordering does not use `z-index`. Such an element always paints above the document, and its order among the others is its top-layer promotion order — the most recently promoted on top. A `z-index` declaration on it still computes; it just does not decide where it lands.
+
+**The document layer** is everything else, and the scale below is what orders it. Nothing in it can reach the other system: `z-index: 999999` on a document-layer element still paints under any open dialog or popover.
 
-| Token         | Value | Used by                         |
-| ------------- | ----- | ------------------------------- |
-| `--z-sticky`  | 10    | `form-actions.sticky`, `topbar` |
-| `--z-menu`    | 20    | Floating menus (`flyout`)       |
-| `--z-tooltip` | 50    | Tooltips                        |
-| `--z-status`  | 60    | `status-bar`                    |
+| Token        | Value | Used by                         |
+| ------------ | ----- | ------------------------------- |
+| `--z-sticky` | 10    | `form-actions.sticky`, `topbar` |
+| `--z-menu`   | 20    | `fab`, static `.flyout`         |
+| `--z-status` | 60    | `status-bar`                    |
 
-`.surface-backdrop` sits just under the menus, at `calc(var(--z-menu) - 1)`.
+`.flyout` keeps the `--z-menu` declaration for a panel the runtime does not
+manage — one the platform has not promoted still stacks by number.
 
-Stacking-context traps: a flyout or tooltip that is a DOM descendant of a dialog, or of a container with `transform`, `filter`, `contain`, `isolation`, or `will-change`, is confined to that ancestor's stacking context. Its z-index token only orders it against siblings within that context. When a dialog's top-layer clips a descendant flyout, move the flyout markup outside the dialog or use a portal/popover to escape the stacking context.
+`status-bar` is at the top of the document layer: above sticky bars and the FAB,
+and below any open dialog, menu or tooltip. That is the boundary between the
+two systems rather than a gap in the scale. Status messages are transient,
+non-critical feedback and their real contract is the live-region announcement
+— which is why `status.js` moves the singleton into an open modal dialog's
+subtree, since a modal inerts the rest of the document and promotion would not
+undo that.
+
+Stacking-context traps: these apply to overlays painted in the page, not to promoted ones. An element that is a DOM descendant of a container with `transform`, `filter`, `contain`, `isolation`, or `will-change` is confined to that ancestor's stacking context, and its z-index token only orders it against siblings within that context. Promotion escapes all of it — but do not move the markup to chase the effect: a panel or tooltip used from inside a modal dialog must be authored *inside* that dialog, because the top layer does not lift an element out of a modal's inertness.
 
 Scrollbar gutter: modal open/close can shift page layout when the classic scrollbar disappears. When a measured scrollbar is present, `modal.css` applies `scrollbar-gutter: stable` to the viewport so the page doesn't jump.
 
@@ -342,6 +436,7 @@ Rules:
 - Prefix shared variant plumbing with `--ui-*`.
 - The shared relays `--ui-*`, `--intent*`, and `--density-*` are framework plumbing: they are classified once at framework level, not restated in every component file.
 - Keep component-specific variants in component code when they do not generalize.
+- `flush` is a shared modifier: it removes the component's outer chrome so the component sits directly inside an existing surface (`.accordion.flush`). Reuse the term one component at a time when the same integration need appears elsewhere; `separated` stays component-local until a second real consumer exists.
 - Do not require users to override internal tokens for ordinary theming.
 - Promote an internal token to public only when there is a repeated, reasonable customization need.
 - A custom property used only in a fallback position (`var(--x, default)`) and never declared is an unset extension point and must carry a classification — public, framework plumbing, or internal. `check:css-api` fails on any unclassified fallback-only property; it does not force an artificial declaration to satisfy the audit.
@@ -352,6 +447,8 @@ Themes override tokens, not selectors. The themes in `src/css/themes/` are repos
 
 A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, and hover overlay. In browsers with `color-mix()` support, the core derives `--focus-ring` from the island's `--focus`; override the ring only for a deliberate visual treatment or when a matching pre-`color-mix()` fallback is required.
 
+When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. The generic soft fallback (`--soft-fg-mix` derivation, above) may already be sufficient.
+
 Shape, shadow, motion, typography, and soft-variant mix tokens are optional knobs. Override them only when the theme actually changes that part of the system.
 
 A full theme can override: