actual-css 0.12.0 → 0.14.0

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

@@ -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.
@@ -116,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.
 
@@ -158,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
@@ -376,7 +421,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 +548,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 +563,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
 
@@ -563,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

@@ -6,20 +6,26 @@
 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
 
-| 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/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.14/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:
 

package/docs/pages/guides/progressive-enhancement.md

@@ -63,11 +63,30 @@ handle, and cleanup happens per element when an element leaves the DOM.
 
 ## The full runtime
 
-Loading `dist/actual.full.js` as a plain `<script>` (no `type="module"`, no
-bundler, no `import`) gets the full runtime. Static HTML that needs to trigger
-something from its own inline `<script>` dispatches the module's public event
-instead of calling into a global — `actual:status` for the status bar, for
-example:
+Import `actual-css/js/full` to enable the full runtime:
+
+```js
+import "actual-css/js/full";
+```
+
+The same entrypoint exposes the public enhancement API from the same runtime
+instance, for adopters that extend the runtime they already run:
+
+```js
+import { applyEnhancement, enhance, registerEnhancement } from "actual-css/js/full";
+
+registerEnhancement("autosubmit", (form) => {
+  // ...
+});
+```
+
+For anything beyond that extension API, keep using `actual-css/js/*`.
+
+The same entrypoint produces the `dist/actual.full.js` standalone for a
+classic `<script>`, where no global API is exposed. Static HTML that needs to
+trigger something from its own inline `<script>` dispatches the module's
+public event instead of calling into a global — `actual:status` for the
+status bar, for example:
 
 ```html
 <script src="actual.full.js"></script>
@@ -110,8 +129,7 @@ needed.
 The JS is designed to run on its own, without Actual's stylesheet.
 
 - **`data-enhance` tokens** register named behaviors. The runtime discovers
-  components through `data-enhance="tabs"`, `data-enhance="flyout"`,
-  `data-enhance="range"`, `data-enhance="scrollspy"`, and
+  components through `data-enhance="tabs"`, `data-enhance="flyout"`, `data-enhance="range"`, `data-enhance="scrollspy"`, and
   `data-enhance="validation"` — no Actual presentation class needed.
   Self-describing attributes (`data-mask`, `data-tooltip`,
   `data-context-menu`) stay framework-neutral by construction.