actual-css 0.12.0 → 0.13.0

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,74 @@ JavaScript involved:
 </nav>
 ```
 
+## Equal-width tabs
+
+To make a few tabs share the strip's width (segmented, 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.
+
+```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
+  (segmented, 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/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/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>

package/docs/pages/foundations/philosophy.md

@@ -1,6 +1,102 @@
 # Philosophy
 
-How components, intents, variants, and density compose — and what each layer is responsible for.
+Actual CSS is a composition-first component framework: let HTML and the
+cascade do the work, compose layout separately from components, and add an
+abstraction only for a real, repeated need. The outlook is close to
+[CUBE CSS](https://cube.fyi/), without adopting its methodology or naming.
+
+**Related terms:** principles, architecture, CUBE, BEM, naming, methodology, guidelines.
+
+## Layers
+
+| Layer     | In Actual                         | Owns                                |
+| --------- | --------------------------------- | ----------------------------------- |
+| Baseline  | reset, tokens, themes, base       | HTML defaults, cascade, inheritance |
+| Layout    | `.stack`, `.cluster`, `.grid`, …  | space between children              |
+| Utility   | `.list-reset`, `.measure`, …      | one reusable adjustment             |
+| Component | `.card`, `.btn`, form controls, … | intrinsic anatomy and appearance    |
+| State     | native attributes, ARIA, `data-*` | what the element is doing           |
+
+## Principles
+
+**Components own their inside; compositions own the space between them.** A
+card sets its padding, surface and slots. Where it sits, and how far it is from
+the next card, belongs to the layout around it:
+
+```html
+<section class="stack">
+  <article class="card">…</article>
+  <article class="card">…</article>
+</section>
+```
+
+A rule such as `.card + .card { margin-block-start: 2rem }` moves page layout
+into the component; put a composition around the cards instead.
+
+**A composition on a component takes over its default layout.** A component's
+own layout sits at zero specificity, so `<article class="card media">` lays out
+as a `.media` without an override, whatever the import order.
+
+**State uses the most semantic attribute; classes choose presentation.**
+
+| Kind             | Mechanism      | Examples                                     |
+| ---------------- | -------------- | -------------------------------------------- |
+| Native state     | HTML attribute | `disabled`, `open`, `checked`                |
+| Accessible state | ARIA           | `aria-current`, `aria-expanded`, `aria-busy` |
+| Runtime state    | `data-*`       | no native or ARIA equivalent                 |
+| Presentation     | class          | `.soft`, `.outline`, `.sm`, `.compact`       |
+
+Write `<a class="nav-link" aria-current="page">`, not `.nav-link.active`. The
+few `.is-*` classes (`.is-open`, `.is-static`) are runtime internals: neither
+set nor select them. `data-enhance` activates behavior and is never a styling
+hook.
+
+**A utility does one thing.** A class that sets a surface, a border, padding and
+type together is a component: give it a name in application CSS.
+
+**Configure before overriding.** Documented public hooks (`--grid-min`,
+`--card-pad`, `--cluster-justify`) are the API. Other custom properties are
+internal and may change.
+
+## Before adding CSS
+
+Go down the layers and stop at the first that answers the need:
+
+1. Does HTML already express it, or the browser already do it?
+2. Is it a relationship between children? Use a composition.
+3. Is it one small adjustment? Use a utility.
+4. Is it the anatomy of a component? Use the component and its hooks.
+5. Is it a state of that component? Use the attribute that names the state.
+
+What remains is product-specific: write it as application CSS, as described in
+[Building with Actual CSS](../guides/integrating-actual-css.md).
+
+## Class grammar
+
+A component takes optional intent, variant and size classes:
+`<button class="btn primary soft sm">`. The sections below describe each axis.
+
+### Flat names, not BEM
+
+A modifier is a separate class that combines with others (`.btn.primary.soft`,
+not `.btn--primary`), and a part gets a prefixed class (`.alert-icon`,
+`.list-item-title`) only when its element does not already say what it is.
+There is no `__` or `--` in Actual's names, because:
+
+- **Modifiers are shared axes.** `.primary`, `.soft` and `.sm` mean the same
+  thing on every component that supports them, so one class serves `.btn`,
+  `.badge` and `.alert`. BEM names a modifier per block, which multiplies the
+  vocabulary and keeps a custom intent such as `.tertiary` from working
+  everywhere at once.
+- **State is not a modifier.** `disabled`, `aria-current` and `open` already
+  name the state; a `--disabled` or `--active` class would duplicate them and
+  drift out of sync.
+- **Elements come from HTML.** A card's `header` and `footer`, an avatar's
+  `<img>` need no `__element` class; a prefixed class is kept for the parts
+  HTML cannot name.
+
+Application CSS can use any convention, BEM included, alongside Actual's
+classes: `<article class="card pricing-plan pricing-plan--featured">`.
 
 ## Components
 

package/docs/pages/foundations/tokens.md

@@ -35,6 +35,28 @@ Global tokens are the ones to reach for in application CSS. Write a relay only t
 }
 ```
 
+### Which hooks inherit
+
+A hook either describes one element's own layout, or a policy its context
+hands down. Instance geometry stops at every new instance; policy inherits.
+
+| Kind              | Examples                                  | Inherits |
+| ----------------- | ----------------------------------------- | -------- |
+| Palette, theme    | `--text`, `--primary`                     | yes      |
+| Rhythm, density   | `--gap`, `--control-size`                 | yes      |
+| Page policy       | `--center-size`, `--measure`              | yes      |
+| Role policy       | `--form-actions-justify`, `--frame-ratio` | yes      |
+| Instance geometry | `--cluster-justify`, `--grid-columns`     | no       |
+
+Set instance geometry on the element itself (a class or inline style), and
+select nested instances to change them (`.toolbar > .cluster`). Set a policy
+once on the region or on `:root` that owns it. A new hook follows the same
+test: "how this element lays out" stops at the element, "what this context
+hands down" inherits. The stop needs the instance to read its own hook:
+`.switcher` and `.sidebar-layout` hooks are read by their children, and a
+nested instance that is itself such a child still needs its parent's value,
+so those keep inheriting.
+
 ### Color
 
 Intent tokens are used by `.primary`, `.secondary`, `.success`, `.warning`, `.danger`, and `.neutral`. They are curated color/foreground pairs. Actual CSS does not compute foregrounds automatically in the core theme contract.
@@ -85,21 +107,34 @@ Surfaces are painted material and may be translucent. Two roles must stay opaque
 
 A theme with translucent surfaces overrides both with opaque values.
 
+`--border` separates surfaces: cards, tables, dividers, panels. `--border-control`
+is the resting edge that tells a control apart from the surface — fields,
+checkboxes and radios, switches, OTP cells, choice cards, join addons, the color
+and file inputs. It defaults to `--border`; set it alone to make controls
+stand out (input border, field outline, form control contrast) without
+darkening every separator. Hover, checked, invalid and disabled states keep
+their own colors.
+
 Use `*-fg` pairs only for solid backgrounds where the component controls both foreground and background. Do not require a foreground token for every surface token.
 
-Focus styling is outline-first. A global focus baseline applies `--focus-outline` and `--focus-outline-offset`: older browsers show it on `:focus`, while modern browsers limit it to `:focus-visible`. The baseline is a `currentColor` line, so text-like elements (links, `summary`, nav and menu items) follow whatever surface the application painted. Boxed components draw a solid `--focus-ring-width` line in `--focus`: inside the border box on text fields (`.input`, `.textarea`, `.select`), outside at `--focus-outline-offset` on actions (`.btn`, `.close`, choices, switches). The color never follows an intent or a local surface, so `--focus` must hold 3:1 against both `--surface` and `--surface-solid` — the page, fields and a solid band all rely on it. Both lines are `--focus-ring-width` wide. Under `forced-colors: active`, outlines map to the system focus color.
+Focus styling is outline-first. A global focus baseline draws a `--focus-ring-width` line in `--focus-outline-color`, offset by `--focus-outline-offset`: older browsers show it on `:focus`, while modern browsers limit it to `:focus-visible`. The baseline is a `currentColor` line, so text-like elements (links, `summary`, nav and menu items) follow whatever surface the application painted. Boxed components draw a solid `--focus-ring-width` line in `--focus`: inside the border box on text fields (`.input`, `.textarea`, `.select`), outside at `--focus-outline-offset` on actions (`.btn`, `.close`, choices, switches). The color never follows an intent or a local surface, so `--focus` must hold 3:1 against both `--surface` and `--surface-solid` — the page, fields and a solid band all rely on it. Both lines are `--focus-ring-width` wide. Under `forced-colors: active`, outlines map to the system focus color.
 
 ```css
 :root {
   --focus: hsl(268 30% 55%);
 
   --focus-outline-color: currentColor;
-  --focus-outline: var(--focus-ring-width) solid var(--focus-outline-color);
   --focus-outline-offset: 2px;
   --focus-ring-width: 2px;
 }
 ```
 
+The line is composed on the focused element, so a theme island or a region
+that sets `--focus-ring-width` widens links and buttons alike. Set
+`--focus-outline` to replace the whole generic line (`4px dashed currentColor`);
+it has no default value. Application CSS that draws the generic line itself
+writes `var(--focus-ring-width) solid var(--focus-outline-color)`.
+
 ### Palette coherence
 
 A coherent palette treats surfaces, text, borders, intents, and shadows as related roles rather than isolated colors.
@@ -376,7 +411,7 @@ Motion durations keep transitions consistent and easy to disable.
 }
 ```
 
-Ordinary interaction/state transitions have **no easing token**: they use the CSS default `ease` directly, and the dialog shake feedback plus the `actual-dialog` View Transition keep that default deliberately. The presence pair exists only for one-shot open/close where open and closed states own separate transition declarations (`.status-bar`/`.is-open`, `dialog.modal[open]`, `dialog.drawer[open]`): `--ease-enter` decelerates the appearance, `--ease-exit` accelerates the departure. The pair follows Material's standard rhythm; the emphasized-decelerate entrance is deliberately not offered because it only pays off at 250–400ms durations, beyond this vocabulary. Backdrops keep `ease` — a scrim only fades, it does not travel — but track their surface's duration. Toggles that share one transition list at `--duration-fast` (flyout, tooltip) also stay on `ease`: at 100ms the curve barely resolves and entry/exit cannot split on a single rule. These absences are deliberate, not gaps; a theme with a different motion character overrides `--ease-enter` / `--ease-exit`.
+Ordinary interaction/state transitions have **no easing token**: they use the CSS default `ease` directly, and the dialog shake feedback plus the `actual-dialog` View Transition keep that default deliberately. The presence pair exists only for one-shot open/close where open and closed states own separate easing values (`.status-bar`/`.is-open`, `dialog.modal[open]`, `dialog.drawer[open]`): `--ease-enter` decelerates the appearance, `--ease-exit` accelerates the departure. The pair follows Material's standard rhythm; the emphasized-decelerate entrance is deliberately not offered because it only pays off at 250–400ms durations, beyond this vocabulary. Backdrops keep `ease` — a scrim only fades, it does not travel — but track their surface's duration. Toggles that share one transition list at `--duration-fast` (flyout, tooltip) also stay on `ease`: at 100ms the curve barely resolves and entry/exit cannot split on a single rule. These absences are deliberate, not gaps; a theme with a different motion character overrides `--ease-enter` / `--ease-exit`.
 
 `reset.css` clamps raw animation and transition durations to `0.01ms`, resets their delays, and restores `html` scroll behavior under `prefers-reduced-motion: reduce`. Decorative loops effectively complete immediately without blanket-disabling animation support.
 
@@ -503,7 +538,7 @@ Rules:
 
 Themes override tokens, not selectors. The themes in `src/css/themes/` are repository-only demo examples, not included in the default stylesheet or the npm package; they exist to show valid ways to use this contract, such as `ocean`, `square`, `cyberpunk`, and `brutalist`.
 
-A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, hover overlay, and shadow color. Pick `--focus` as a mid-tone that holds 3:1 against both `--surface` and `--surface-solid` in every scheme the theme declares; a pastel dark-scheme primary usually fails on the light solid surface. `bunx --bun actual-css contrast --theme FILE` measures both pairs, and exits 1 when a pair misses.
+A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, hover overlay, and shadow color. Pick `--focus` as a mid-tone that holds 3:1 against both `--surface` and `--surface-solid` in every scheme the theme declares; a pastel dark-scheme primary usually fails on the light solid surface. `bunx --bun actual-css contrast --theme FILE` measures both pairs, and exits 1 when a pair misses. The file may declare a `[data-theme]` island or set the tokens on `:root`; the tool reads each scheme through `color-scheme`, so write dark values with `light-dark()` — a `prefers-color-scheme` media block is not measured.
 
 When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. A theme that declares no hook falls back to the `--soft-fg-mix` derivation: one global percentage applied to every role, so it carries no contrast guarantee for a palette it was not tuned against. `actual-css contrast` prints the resting and hovered soft pair for every intent in every scheme the theme declares, which is how a theme finds the roles that need a hook or a lower `--soft-fg-mix`.
 
@@ -518,6 +553,7 @@ A full theme can override:
 - intent colors and foreground pairs
 - surface, text, border, focus, and overlay colors
 - `--surface-opaque` and `--surface-solid-fg`, when surfaces are translucent
+- `--border-control`, when controls need a stronger edge than separators
 - radius tokens
 - optional shadow, motion, typography, and soft-variant mix tokens
 

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

@@ -6,7 +6,7 @@
 bunx --bun actual-css design --theme src/theme.css --out design/
 ```
 
-`--theme` is a file declaring one `[data-theme="…"]` block (see [Theming](../foundations/theming.md)); without it the default theme is exported. The command needs Bun, and `--bun` makes `bunx` run it under Bun instead of the CLI's Node shebang: it reads the theme in headless Chrome, so every `light-dark()`, `color-mix()` and `var()` chain resolves exactly as the browser paints it.
+`--theme` is a file declaring one theme, on `:root` or in a `[data-theme="…"]` block (see [Theming](../foundations/theming.md)); without it the default theme is exported. The command needs Bun, and `--bun` makes `bunx` run it under Bun instead of the CLI's Node shebang: it reads the theme in headless Chrome, so every `light-dark()`, `color-mix()` and `var()` chain resolves exactly as the browser paints it.
 
 ## What is exported
 

package/docs/pages/guides/integrating-actual-css.md

@@ -8,7 +8,8 @@ In short: **use Actual for generic structure and behavior; add product-specific
 classes for brand and compositions rather than forcing a generic primitive.** A
 local rule is not a failure of Actual — overfitting the framework to a
 product-specific look is. Reach for an Actual primitive first, and write
-application CSS when the need is genuinely product-specific (see §6–7).
+application CSS when the need is genuinely product-specific (see §9–10). The
+principles behind this order are in [Philosophy](../foundations/philosophy.md).
 
 ## 1. Start with the theme
 
@@ -60,7 +61,29 @@ For example, three panels that must all stack together are a `.switcher`, not au
 
 If local CSS mainly makes one layout primitive behave like another, reconsider the primitive first.
 
-## 3. Tune before replacing
+## 3. Keep outer spacing in the layout
+
+Components own their internal rhythm; layout primitives own the space between
+components.
+
+```html
+<div class="stack">
+  <article class="card">…</article>
+  <article class="card">…</article>
+</div>
+```
+
+```css
+/* Avoid */
+.card + .card {
+  margin-block-start: var(--space-50);
+}
+```
+
+A card then moves between a stack, a grid or a sidebar without its outer
+spacing to undo.
+
+## 4. Tune before replacing
 
 Actual primitives expose public hooks for common adjustments.
 
@@ -97,7 +120,12 @@ over reimplementing their layout:
 
 **Rule:** tune the recipe before replacing the recipe.
 
-## 4. Reuse the existing vocabulary
+`--gap` is inherited: set on a region, it re-spaces every nested stack, cluster
+and grid too. Set it on the layout that reads it, as `.feature-grid` does above.
+For a region's own rhythm, set the `gap` property instead; see
+[Region rhythm](../layout/stack.md#region-rhythm-goes-on-gap-not-on-gap).
+
+## 5. Reuse the existing vocabulary
 
 Before introducing a generic application class, check whether Actual already expresses the idea.
 
@@ -113,7 +141,7 @@ Small alignment change    → existing utility
 
 Application classes should primarily describe product-specific concepts, not recreate generic framework utilities.
 
-## 5. Use structural component markup
+## 6. Use structural component markup
 
 When a component exposes meaningful structure, use it.
 
@@ -140,7 +168,44 @@ Connection restored.
 
 Persistent state such as metrics, availability, queue size or account information belongs in normal page content.
 
-## 6. Keep application CSS for application identity
+## 7. Style state through its attribute
+
+Use the native attribute or the ARIA state the markup already needs, then
+`data-*` for state with no equivalent. Classes stay for presentation.
+
+```html
+<a class="nav-link" aria-current="page">Settings</a>
+<button class="btn primary" disabled>Save</button>
+```
+
+```css
+.checkout-form[aria-busy="true"] { … }
+```
+
+Not `.nav-link.active` or `.is-disabled`: a state class duplicates the attribute
+and drifts from it. Two runtime markers are off limits too:
+
+- `data-enhance` turns behavior on; it is never a styling hook.
+- `.is-*` classes (`.is-open`, `.is-static`) are runtime internals: neither set
+  nor select them.
+
+## 8. Bring third-party widgets onto the tokens
+
+A date picker, rich text editor or data grid can come from a dedicated package.
+Map its public visual hooks to Actual tokens instead of restyling it:
+
+```css
+.third-party-picker {
+  --picker-bg: var(--surface-raised);
+  --picker-border: var(--border);
+  --picker-text: var(--text);
+  --picker-focus: var(--focus);
+}
+```
+
+The package keeps its behavior; the theme reaches it through the tokens.
+
+## 9. Keep application CSS for application identity
 
 Custom CSS is expected for things such as:
 
@@ -166,7 +231,7 @@ A better target is:
 
 > No duplicated framework behavior and no palette literals outside the token layer.
 
-## 7. Before adding a CSS rule
+## 10. Before adding a CSS rule
 
 Ask, in this order:
 
@@ -175,9 +240,10 @@ Ask, in this order:
 3. Can a public hook configure it?
 4. Does an existing utility express the adjustment?
 5. Can the color be derived from a theme token?
-6. Is this genuinely application-specific CSS?
+6. Does an attribute already name the state?
+7. Is this genuinely application-specific CSS?
 
-If the answer reaches step 6, write the CSS.
+If the answer reaches step 7, write the CSS.
 
 That is the intended integration model:
 

package/docs/pages/guides/introduction.md

@@ -22,7 +22,8 @@ cascade layers, import order, or a project-owned build-time prefix transform.
 The distinction is structural, not stylistic: presentation lives in classes,
 JavaScript behavior opts in through `data-enhance` tokens, semantics come from
 ARIA and native HTML, and per-widget configuration uses self-describing
-`data-*` attributes.
+`data-*` attributes. [Philosophy](../foundations/philosophy.md) lays out the
+layers and the order to follow before adding CSS.
 
 ## Install
 
@@ -52,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.12/dist/actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.13/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map

package/docs/pages/guides/modular-import.md

@@ -99,7 +99,7 @@ cells, so they read as a list:
   base and extra utilities
 
 `.form-actions` composes with `.cluster`: a build that takes forms without the
-layout family imports `actual-css/css/layout/cluster` before the forms.
+layout family also imports `actual-css/css/layout/cluster`, in any order.
 
 Individual modules can be imported through their domain path: