actual-css 0.4.2 → 0.6.0

package/docs/pages/forms/combobox.md

@@ -0,0 +1,87 @@
+# Combobox
+
+> A searchable or multi-value combobox is not shipped by the framework — the native `<select>` and `<datalist>` stay the baseline. Theme an external combobox with Actual tokens instead.
+
+The `.select` class keeps the native baseline with a CSS chevron, and the optional
+`custom-select` module adds the `appearance: base-select` native picker where the
+browser supports it. Beyond those, apply the framework's judgment from the
+[data grid template](../../demo/templates/data-grid.html) to the problem: when a
+real product needs a JavaScript combobox (searchable select, removable tags,
+autocomplete suggestions), load a dedicated component and bridge its custom
+properties onto Actual's tokens.
+
+**Related terms:** combo box, combobox, autocomplete, datalist, searchable select, enhanced select, multiple select, tags, chips, tag input, pill input.
+
+## Theme bridge
+
+The [combobox template](../../demo/templates/combobox.html) themes
+[`@lekoala/combobox`](https://github.com/lekoala/combobox) entirely with Actual
+tokens: the control mirrors `.input`, chips re-derive the `.badge` soft recipe,
+and the picker popover follows `--surface-raised` and `--shadow-popout`. No
+adapter, no compatibility layer — a handful of `--cb-*` assignments and shared
+mix tokens.
+
+```html
+<label class="field actual-combobox">
+  <span class="field-label">Skills</span>
+  <combo-box placeholder="Search or add a skill…">
+    <select class="select" name="skills[]" multiple>
+      <option value="design" selected>Design</option>
+      <option value="css" selected>CSS</option>
+      <option value="javascript" selected>JavaScript</option>
+    </select>
+  </combo-box>
+</label>
+```
+
+The card in the template documents the full token map of this recipe.
+
+## Lightweight pass-through
+
+Most of the skin is three one-line token bridges. The visible vocabulary —
+surface, border, radius, focus ring, danger, hover overlay and the `--soft-*`
+mix — stays the Actual one, so light/dark mode, the preset themes and their
+contrast contracts apply to the combobox for free:
+
+```css
+.actual-combobox {
+  --cb-bg: var(--surface);
+  --cb-color: var(--text);
+  --cb-border-color: var(--border);
+  --cb-border-radius: var(--radius);
+  --cb-focus-color: var(--focus);
+  --cb-muted-color: var(--text-muted);
+  --cb-error-color: var(--danger);
+  --cb-chip-bg: transparent;
+  --cb-control-height: var(--control-size);
+  --cb-option-min-height: var(--control-size);
+}
+
+.actual-combobox .cb-control:focus-within,
+.actual-combobox .cb-text-control:focus {
+  outline: 2px solid transparent;
+  box-shadow: var(--focus-ring-shadow);
+}
+
+.actual-combobox .cb-chip-remove:focus-visible {
+  outline: 2px solid transparent;
+  box-shadow: 0 0 0 2px var(--focus-ring);
+}
+
+.actual-combobox .cb-chip {
+  border: var(--border-width) solid
+    color-mix(in oklab, var(--surface) var(--soft-border-mix), var(--primary));
+  border-radius: var(--radius-full);
+  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);
+}
+```
+
+The composite focus ring follows any internal focus, not just the search
+input: focus a chip or its remove × and the control shows the same field ring,
+with the local `:focus-visible` indicator on the chip or its × on top.
+
+The same approach works for any widget that exposes a custom-property skin —
+keep the widget's behavior, restyle its tokens through the shared vocabulary.

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

@@ -7,9 +7,11 @@ 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 the control and its label only. 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, 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.
 
 ```html demo
 <div class="field">

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

@@ -2,12 +2,14 @@
 
 > Use `.join` when controls need to be visually joined into a single unit.
 
+**Related terms:** segmented control, button group, input group.
+
 ## Class reference
 
-| Class         | Kind        | Description                                                                     |
-|---------------|-------------|---------------------------------------------------------------------------------|
-| `.join`       | Composition | Visually joins adjacent controls into a single unit.                            |
-| `.join-addon` | Composition | Static prefix/suffix content such as currency symbols, units, or protocol text. |
+| Class         | Kind        | Description                                 |
+| ------------- | ----------- | ------------------------------------------- |
+| `.join`       | Composition | Joins adjacent controls into a single unit. |
+| `.join-addon` | Composition | Static prefix or suffix content.            |
 
 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.
 

package/docs/pages/forms/labels.md

@@ -4,11 +4,14 @@
 
 ## Class reference
 
-| Class            | Kind        | Description                                                                                  |
-|------------------|-------------|----------------------------------------------------------------------------------------------|
-| `.field`         | Composition | Field wrapper; canonical on `<label>` or `<div>`.                                            |
-| `.field-label`   | Composition | Label text, element-agnostic — works on `<span>`, a detached `<label for>`, or a `<legend>`. |
-| `.required-mark` | Composition | Visual required marker (`aria-hidden`) added inside a label.                                 |
+| Class            | Kind        | Description                                       |
+| ---------------- | ----------- | ------------------------------------------------- |
+| `.field`         | Composition | Field wrapper; canonical on `<label>` or `<div>`. |
+| `.field-label`   | Composition | Label text, element-agnostic.                     |
+| `.required-mark` | Composition | Visual required marker (`aria-hidden`).           |
+
+`.field-label` works on a `<span>`, on a detached `<label for>`, or on a
+`<legend>`. `.required-mark` goes inside a label.
 
 Use a **wrapped label** for simple hand-authored forms. The whole label area becomes the click target, there is no `id` noise, and the markup is harder to break.
 

package/docs/pages/forms/overview.md

@@ -9,27 +9,34 @@
 - Proper focus style that preserves keyboard navigation.
 - `.field-group` and `.choice` provide layout without depending on parent scope.
 - Customizable select is progressive enhancement only — the native select remains the baseline.
+- Searchable selects, tags and autocomplete are a JavaScript widget concern; theme an external combobox with Actual tokens — see the [combobox template](../../demo/templates/combobox.html).
 
 ## Class reference
 
-| Class           | Kind        | Description                                                                   |
-|-----------------|-------------|-------------------------------------------------------------------------------|
-| `.input`        | Component   | Text input; shares the text-control recipe with `.textarea` and `.select`.    |
-| `.textarea`     | Component   | Multi-line text control.                                                      |
-| `.select`       | Component   | Dropdown — native baseline with a CSS chevron and an opt-in enhanced picker.  |
-| `.check`        | Component   | Styled checkbox.                                                              |
-| `.radio`        | Component   | Styled radio button.                                                          |
-| `.switch`       | Component   | Toggle switch on a checkbox input with `role="switch"`.                       |
-| `.range`        | Component   | Native range slider with a theme-aware accent color.                          |
-| `.file`         | Component   | Native file input with a themed picker button.                                |
-| `.color`        | Component   | Native color picker in a control-sized box.                                   |
-| `.field`        | Composition | Field wrapper that works on `<label>` and `<div>`.                            |
-| `.field-label`  | Composition | Label text; element-agnostic — `<span>`, detached `<label>`, or `<legend>`.   |
-| `.field-help`   | Composition | Supporting helper text under a control.                                       |
-| `.field-error`  | Composition | Inline error message shown while the field is invalid.                        |
-| `.field-group`  | Composition | Grouped `<fieldset>` container with a tunable legend gutter.                  |
-| `.choice`       | Composition | Choice-label layout wrapping a `.check`, `.radio`, or `.switch`.              |
-| `.form-actions` | Composition | Class-only flex row that closes a form; works inside or outside the `<form>`. |
+| Class           | Kind        | Description                                   |
+| --------------- | ----------- | --------------------------------------------- |
+| `.input`        | Component   | Text input.                                   |
+| `.textarea`     | Component   | Multi-line text control.                      |
+| `.select`       | Component   | Dropdown, native baseline with a CSS chevron. |
+| `.check`        | Component   | Styled checkbox.                              |
+| `.radio`        | Component   | Styled radio button.                          |
+| `.switch`       | Component   | Toggle switch on a `role="switch"` checkbox.  |
+| `.range`        | Component   | Native range slider, theme-aware accent.      |
+| `.file`         | Component   | Native file input, themed picker button.      |
+| `.color`        | Component   | Native color picker in a control-sized box.   |
+| `.field`        | Composition | Field wrapper, on `<label>` or `<div>`.       |
+| `.field-label`  | Composition | Label text, element-agnostic.                 |
+| `.field-help`   | Composition | Supporting helper text under a control.       |
+| `.field-error`  | Composition | Inline error message, shown while invalid.    |
+| `.field-group`  | Composition | `<fieldset>` with a tunable legend gutter.    |
+| `.choice`       | Composition | Choice-label layout around an inline control. |
+| `.form-actions` | Composition | Class-only flex row that closes a form.       |
+
+`.input` shares the text-control recipe with `.textarea` and `.select`, and
+`.select` also has an opt-in enhanced picker. `.field-label` works on a
+`<span>`, a detached `<label>` or a `<legend>`. `.choice` wraps a `.check`,
+`.radio` or `.switch`, and `.form-actions` works inside or outside the
+`<form>`.
 
 ## Example form
 
@@ -164,7 +171,7 @@ A full form using the control classes, field wrappers, and form actions:
 - `required` is the semantic source of truth. Add `<span class="required-mark" aria-hidden="true">*</span>` inside a label only when a visual required marker is wanted; the framework does not add one automatically.
 - `.field` is the canonical field wrapper. It works on `<label>` and `<div>`.
 - `.field-label` is element-agnostic. Use it on `<span>` inside a wrapped label, on `<label for="…">` in a detached layout, or on `<legend>` inside a fieldset.
-- `.field-group` styles a `<fieldset class="field-group">` as a grouped field container. Its legend gutter is tunable with `--fieldset-legend-padding-inline` (`var(--space-10)`).
+- `.field-group` styles a `<fieldset class="field-group">` as a grouped field container. Its legend gutter is tunable with `--fieldset-legend-padding-inline` (`var(--space-10)`). It carries no sibling margin: space consecutive groups with `.stack` on the form, so the rhythm follows the layout instead of the component.
 - Use native `<optgroup>` and `disabled` options in `.select` controls when applicable; the customizable picker preserves both as a progressive enhancement.
 - `.choice` is the choice-label API. Use `.check` or `.radio` on the nested control. The control goes first, the label group second, so multi-line labels align the control with the first line.
 - For a switch, use `class="switch"` and `role="switch"`.

package/docs/pages/forms/password.md

@@ -1,8 +1,9 @@
 # Password Toggle
 
 > A password field reveals its value through a linked button. The markup is a
-> plain command invoker; the behavior ships with the JS runtime
-> (`actual-css/js` or `actual-css/js/password`).
+> plain command invoker; the behavior ships with the full JS runtime
+> (`actual-css/js/full`) and can also be imported independently
+> (`actual-css/js/password`).
 
 Point a `button` at the input with `commandfor` and
 `command="--password-toggle"`. Use `.join` when the button should sit attached

package/docs/pages/forms/range.md

@@ -1,8 +1,13 @@
 # Range
 
-> Native range inputs with theme-aware accent color.
+> Native range input with a lightweight theme-aware custom skin.
 
-Core: native range, enhanced by `accent-color`. Optional richer skin may come later.
+`.range` keeps the native range control and its interaction semantics, while
+customizing the track, thumb, focus state, intents, and disabled state. The
+focus ring targets the thumb — the surface the user actually manipulates —
+rather than the CSS box.
+
+**Related terms:** slider, range input, scrubber.
 
 ```html demo
 <label class="field">
@@ -11,7 +16,15 @@ Core: native range, enhanced by `accent-color`. Optional richer skin may come la
 </label>
 ```
 
+Actual deliberately does not emulate filled tracks, tick marks, value labels,
+or multi-thumb ranges. Those still require engine-specific pseudo-elements or a
+value duplicated out of the HTML into CSS. Prefer the platform as richer range
+styling becomes interoperable — see
+[Enhanced range controls](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/platform-alignment.md).
+
 ## CSS hooks
 
 - `--range-thumb-size` — thumb diameter.
 - `--range-track-height` — track thickness.
+- `--range-thumb-bg` — thumb color. Defaults to the local intent, then `--primary`.
+- `--range-track-bg` — track color.

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

@@ -4,10 +4,12 @@
 
 ## Class reference
 
-| Class | Kind     | Description                                                                              |
-|-------|----------|------------------------------------------------------------------------------------------|
-| `.sm` | Modifier | Compact control height and spacing rhythm; sets `--control-size` to `--control-size-sm`. |
-| `.lg` | Modifier | Large control height and spacing rhythm; sets `--control-size` to `--control-size-lg`.   |
+| Class | Kind     | Description                                |
+| ----- | -------- | ------------------------------------------ |
+| `.sm` | Modifier | Compact control height and spacing rhythm. |
+| `.lg` | Modifier | Large control height and spacing rhythm.   |
+
+Each sets `--control-size` to `--control-size-sm` or `--control-size-lg`.
 
 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.
 
@@ -21,7 +23,7 @@ without its label would only break the alignment. Scale them by scaling their
 type instead.
 
 ```html demo
-<form novalidate>
+<form class="stack" novalidate>
   <fieldset class="field-group">
     <legend class="field-label">Text control states</legend>
     <div class="stack" style="--grid-min: 14rem;">

package/docs/pages/forms/validation.md

@@ -2,16 +2,22 @@
 
 > Inline error feedback that respects assistive technology and form state.
 
+**Related terms:** inline validation, field error.
+
 ## Class reference
 
-| Class               | Kind        | Description                                                                     |
-|---------------------|-------------|---------------------------------------------------------------------------------|
-| `.field-error`      | Composition | Canonical inline error message; shown while the field is invalid.               |
-| `.field-help`       | Composition | Canonical helper text; carries supporting copy before and after validation.     |
-| `.field.danger`     | Modifier    | Manual invalid marking on the field wrapper.                                    |
-| `.needs-validation` | Modifier    | Opt-in class for the validation enhancer and `:user-invalid` styling.           |
-| `.was-validated`    | Modifier    | Added to the form by the enhancer after the first submit attempt.               |
-| `.status-bar`       | Component   | Optional status element that shows `data-validation-message` on invalid submit. |
+| Class               | Kind        | Description                                  |
+| ------------------- | ----------- | -------------------------------------------- |
+| `.field-error`      | Composition | Canonical inline error message.              |
+| `.field-help`       | Composition | Canonical helper text.                       |
+| `.field.danger`     | Modifier    | Manual invalid marking on the wrapper.       |
+| `.needs-validation` | Modifier    | Opt-in for the enhancer and `:user-invalid`. |
+| `.was-validated`    | Modifier    | Set by the enhancer after a submit attempt.  |
+| `.status-bar`       | Component   | Optional form-level status element.          |
+
+`.field-error` shows while the field is invalid; `.field-help` carries
+supporting copy before and after validation. `.status-bar` shows
+`data-validation-message` on an invalid submit.
 
 - `.field-error` is the canonical error message. It is wired to `aria-invalid="true"` via the input, so the visual border and the assistive-tech announcement move together.
 - `.field-help` is the canonical helper text. It carries supporting copy before and after validation.
@@ -47,7 +53,7 @@
 
 Native validation first; the enhancer only adds state and focus behavior.
 
-Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the default runtime (`actual-css/js`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
+Actual CSS ships validation *styles*. Invalid fields are marked with `aria-invalid="true"` (or the manual `.field.danger` wrapper class). The default forms bundle imports `forms/validation.css`; custom builds may omit that file when validation styling is app-owned. A small enhancer (`actual-css/js/validation`), included in the full runtime (`actual-css/js/full`) and also importable on its own, prevents premature error display, marks invalid fields on blur and submit, focuses the first invalid field on submit, and supports a few custom rules. It is not a validation framework — server and AJAX validation stay in app code.
 
 Opt in with the `.needs-validation` class. Importing the module registers the behavior; there is no init call.
 

package/docs/pages/foundations/philosophy.md

@@ -10,9 +10,19 @@ Components are semantic boxes: `.btn`, `.badge`, `.alert`, `.card`, `.avatar`, e
 
 `.primary`, `.secondary`, `.success`, `.warning`, `.danger` do not style elements directly. They only expose `--intent` and `--intent-fg`. Components and variants decide how to consume them.
 
+Intent classes define the current `--intent` value; they do not form a
+general-purpose color utility system. Use `.intent-color` when a simple element
+should consume the current intent as its foreground color. It works with an
+intent on the same element or inherited from an ancestor.
+
 ```html demo
 <button class="btn primary">Primary</button>
 <span class="badge success">Success</span>
+<span class="success intent-color">Success text</span>
+<span class="danger">
+  <i class="ti ti-alert-triangle intent-color" aria-hidden="true"></i>
+  Something needs attention
+</span>
 ```
 
 There is no `.btn-primary` or `.badge-success`. Intents are generic and reusable across any component that supports them.
@@ -35,7 +45,7 @@ Custom intents need no framework support — define `--intent` and `--intent-fg`
 
 ## Variants
 
-`.solid`, `.soft`, `.outline` define the visual treatment by setting `--ui-bg`, `--ui-fg`, `--ui-border`. Components consume these tokens with sensible fallbacks. Interactive components also set a `--ui-hover-bg` recipe that their hover rule reads.
+`.solid`, `.soft`, `.outline`, `.surface` define the visual treatment by setting `--ui-bg`, `--ui-fg`, `--ui-border`. Components consume these tokens with sensible fallbacks. Interactive components also set a `--ui-hover-bg` recipe that their hover rule reads.
 
 `.btn` defaults to `.solid`; `.badge` and `.alert` default to `.soft`.
 

package/docs/pages/foundations/tokens.md

@@ -133,7 +133,7 @@ Spacing should be useful without becoming a design-token encyclopedia.
 }
 ```
 
-Official steps are named in tens so the scale stays extensible: Actual CSS only publishes multiples of 10, and applications can intercalate intermediate values (`--space-15`, `--space-45`, …) without colliding with a future framework step.
+Official steps are named in tens so the scale stays extensible. **Actual CSS will never define a `--space-*` token that is not a multiple of 10.** The intermediate names (`--space-15`, `--space-45`, …) are reserved for application-level interpolation: defining them is not writing into the framework namespace, it is using the half of the scale the framework has permanently given up.
 
 Use `em` for spacing that should scale with the component text size, such as button gaps and inline padding. Use `rem` for global rhythm, layouts, and fixed density.
 
@@ -220,7 +220,7 @@ With `color-mix()` support the shadows derive from `--shadow-color` (a theme tok
 
 ### Motion
 
-Motion tokens keep transitions consistent and easy to disable.
+Motion durations keep transitions consistent and easy to disable.
 
 ```css
 :root {
@@ -229,10 +229,13 @@ Motion tokens keep transitions consistent and easy to disable.
   --duration-slow: 200ms;     /* one-shot open/close */
   --duration-spin: 0.75s;     /* continuous spin (.spinner) */
   --duration-shimmer: 1.2s;   /* continuous shimmer (.skeleton, indeterminate .progress) */
-  --ease: ease;
+  --ease-enter: cubic-bezier(0.2, 0, 0, 1);
+  --ease-exit: cubic-bezier(0.4, 0, 1, 1);
 }
 ```
 
+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`.
+
 `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.
 
 ### Icons
@@ -244,6 +247,7 @@ Icons used by CSS-only controls are public tokens because users may need to repl
   --icon-chevron: url("data:image/svg+xml,...");
   --icon-check: url("data:image/svg+xml,...");
   --icon-close: url("data:image/svg+xml,...");
+  --icon-plus: url("data:image/svg+xml,...");
 }
 ```
 
@@ -272,12 +276,14 @@ Under `forced-colors: active`, `--backdrop-fill` maps to `Canvas`.
 
 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.
 
-| Token         | Value | Used by                                                                           |
-|---------------|-------|-----------------------------------------------------------------------------------|
-| `--z-sticky`  | 10    | Sticky page chrome (`form-actions.sticky`, `topbar`).                             |
-| `--z-menu`    | 20    | Floating menus (`flyout`); `.surface-backdrop` sits at `calc(var(--z-menu) - 1)`. |
-| `--z-tooltip` | 50    | Tooltips.                                                                         |
-| `--z-status`  | 60    | `status-bar`.                                                                     |
+| 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`                    |
+
+`.surface-backdrop` sits just under the menus, at `calc(var(--z-menu) - 1)`.
 
 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.
 
@@ -294,6 +300,7 @@ The shared visual variants are:
 - `.solid`: full background, paired foreground. This is the default for buttons.
 - `.soft`: lightly tinted background, colored text. Good for alerts, badges, and secondary actions.
 - `.outline`: transparent background, colored border and text.
+- `.surface`: the page surface with the theme border, and the intent only in the text. The neutral chrome neither `.soft` (the intent-tinted treatment) nor `.outline` (no fill) can give.
 
 Buttons also support two button-only variants:
 

package/docs/pages/foundations/typography.md

@@ -66,7 +66,7 @@ documentation homepages) import it manually:
 The module exposes three size tokens and three composed classes. It is deliberately not the foundation: body text, app UI, and the default prose scale stay static.
 
 | Token             | Class           | Purpose                               |
-|-------------------|-----------------|---------------------------------------|
+| ----------------- | --------------- | ------------------------------------- |
 | `--fluid-display` | `.text-display` | Hero / display sizes.                 |
 | `--fluid-title`   | `.text-title`   | Section titles.                       |
 | `--fluid-lead`    | `.text-lead`    | Intro paragraphs on display surfaces. |
@@ -77,7 +77,15 @@ There is also a non-fluid `.lead` utility in the core, for a simple readable int
 
 Global links are intentionally neutral. Only `.prose` styles them as prose links, and only components style their own link-like elements (nav links, button-as-link, tabs, breadcrumbs, etc.). The reason is that underlining every `a` globally fights against button-like links, nav links, clickable cards, menu items, and tab triggers. Components that need link semantics should opt in with their own rule.
 
-Prose links take `--primary`. That breaks down for a theme whose primary is a light or fully saturated accent: it can carry a filled button, where it is the background under its own `--primary-fg`, but not inline body text, where it has to hold contrast against `--surface` on its own. `--link` is the optional override for exactly that case — a theme sets it and `.prose` link ink follows, hover included, with no rule to restate. Unset, it falls back to `--primary`, so existing themes are unaffected.
+`--link` is the theme-level link ink. It is unset by default, so a bare `a` inherits its color and `.prose` links fall back to `--primary` — nothing changes until a theme opts in. Setting it is that opt-in, and it reaches both places at once:
+
+```css
+:root {
+  --link: var(--primary); /* bare links become link-colored, prose included */
+}
+```
+
+The `.prose` fallback to `--primary` breaks down for a theme whose primary is a light or fully saturated accent: it can carry a filled button, where it is the background under its own `--primary-fg`, but not inline body text, where it has to hold contrast against `--surface` on its own. `--link` is the override for exactly that case — hover included, with no rule to restate.
 
 ```css
 [data-theme="vivid"] {
@@ -133,7 +141,7 @@ There is no `--line-height-normal`. It would be redundant with `--line-height`.
 - `--prose-line-height` — body line height inside `.prose`.
 - `--prose-heading-line-height` — heading line height inside `.prose`.
 - `--prose-flow` — vertical rhythm between sibling blocks inside `.prose`.
-- `--link` — prose link ink; falls back to `--primary` when a theme leaves it unset.
+- `--link` — theme-level link ink, listed here because `.prose` is its main consumer. Unset, bare links inherit and prose links fall back to `--primary`.
 
 ## text-wrap
 

package/docs/pages/guides/bootstrap.md

@@ -43,7 +43,7 @@ Remove the compatibility mechanism when Bootstrap is gone. The public Actual API
 Many common Bootstrap components translate directly.
 
 | Bootstrap                  | Actual CSS              |
-|----------------------------|-------------------------|
+| -------------------------- | ----------------------- |
 | `.btn .btn-primary`        | `.btn .primary`         |
 | `.btn .btn-outline-danger` | `.btn .danger .outline` |
 | `.btn .btn-sm`             | `.btn .sm`              |
@@ -101,7 +101,7 @@ Actual:
 Common translations include:
 
 | Bootstrap                     | Actual CSS                     |
-|-------------------------------|--------------------------------|
+| ----------------------------- | ------------------------------ |
 | `.form-control` on an input   | `.input`                       |
 | `.form-control` on a textarea | `.textarea`                    |
 | `.form-select`                | `.select`                      |
@@ -213,7 +213,7 @@ Think in terms of the relationship between children rather than translating each
 Typical choices are:
 
 | Bootstrap pattern                          | Actual approach                            |
-|--------------------------------------------|--------------------------------------------|
+| ------------------------------------------ | ------------------------------------------ |
 | flex row that may wrap                     | `.cluster`                                 |
 | vertical flex stack                        | `.stack`                                   |
 | exact structural columns                   | `.grid-2`, `.grid-3`, `.grid-4`, `.grid-6` |

package/docs/pages/guides/introduction.md

@@ -75,7 +75,7 @@ Actual CSS uses a small unprefixed class grammar:
 ```
 
 Intents are `.primary`, `.secondary`, `.success`, `.warning`, and `.danger`, and
-work across components. Variants such as `.solid`, `.soft`, and `.outline` are
+work across components. Variants such as `.solid`, `.soft`, `.outline`, and `.surface` are
 shared by buttons, badges, alerts, and cards; `.inverted` is a shared surface
 modifier that paints any block with the inverse surface. `.ghost` and `.link`
 are button-only. Size variants `.sm` and `.lg` scale controls consistently.
@@ -140,7 +140,7 @@ internal design documents for contributors.
 Actual CSS is built around progressive enhancement.
 
 | Tier         | Firefox | Safari    | Chromium |
-|--------------|---------|-----------|----------|
+| ------------ | ------- | --------- | -------- |
 | Degraded     | 78+     | 14+       | 88+      |
 | **Minimal**  | **98+** | **15.4+** | **99+**  |
 | Intermediate | 121+    | 16+       | 106+     |

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

@@ -29,16 +29,27 @@ When an interactive state replaces the outline, it must preserve a visible focus
 
 ## Family manifests
 
-| Family           | Import                      | Contents                                                                                                                        |
-| ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Core             | `actual-css/css`            | reset, tokens, theme, base, intents, variants, focus, print                                                                     |
-| Typography       | `actual-css/css/typography` | prose, overline, fluid                                                                                                          |
-| Layout           | `actual-css/css/layout`     | stack, cluster, center, frame, media, switcher, sidebar-layout, grid, scroller, scroll-snap, topbar, container-query, app-shell |
-| Forms            | `actual-css/css/forms`      | native control baseline                                                                                                         |
-| Forms (complete) | `actual-css/css/forms/all`  | base plus input-icon, switch, range, choice-card, custom-select, floating-field, otp                                            |
-| Components       | `actual-css/css/components` | buttons, surfaces, overlays, feedback, navigation, data and composed controls                                                   |
-| Effects          | `actual-css/css/effects`    | aura                                                                                                                            |
-| Utilities        | `actual-css/css/utilities`  | base and extra utilities                                                                                                        |
+Each family is one import. The contents are enumerations rather than table
+cells, so they read as a list:
+
+- **Core** — `actual-css/css`
+  reset, tokens, theme, base, intents, variants, focus, print
+- **Typography** — `actual-css/css/typography`
+  prose, overline, fluid
+- **Layout** — `actual-css/css/layout`
+  stack, cluster, center, frame, media, switcher, sidebar-layout, grid,
+  scroller, scroll-snap, topbar, container-query, app-shell
+- **Forms** — `actual-css/css/forms`
+  native control baseline
+- **Forms (complete)** — `actual-css/css/forms/all`
+  base plus input-icon, switch, range, choice-card, custom-select,
+  floating-field, otp
+- **Components** — `actual-css/css/components`
+  buttons, surfaces, overlays, feedback, navigation, data and composed controls
+- **Effects** — `actual-css/css/effects`
+  aura
+- **Utilities** — `actual-css/css/utilities`
+  base and extra utilities
 
 Individual modules can be imported through their domain path: