actual-css 0.9.1 → 0.10.0

package/docs/pages/foundations/tokens.md

@@ -17,6 +17,24 @@ Component custom properties fall into three header categories in the source: **P
 
 As a convention, component-prefixed properties owned by the component's base rule are usually author hooks. Properties owned by states/variants, derived from other hooks, or written by JavaScript are not. This convention is indicative, not algorithmic: runtime-written, derived, and state-relay properties stay internal even when their form resembles a hook.
 
+### Where a token is declared
+
+A hook is only defined inside the scope that declares it. Reading one outside that scope is not an error a browser reports: `var()` resolves to nothing, the whole declaration becomes invalid at computed-value time, and the property falls back to its initial value — `padding: var(--card-pad)` outside a card computes to `0`, silently.
+
+| Scope     | Declared on                 | Examples                               |
+| --------- | --------------------------- | -------------------------------------- |
+| Global    | `:root`, every theme island | `--space-40`, `--radius`, `--primary`  |
+| Component | the component's base rule   | `--card-pad`, `--drawer-size`          |
+| Relay     | a variant, state, or script | `--ui-bg`, `--intent`, `--surface-pad` |
+
+Global tokens are the ones to reach for in application CSS. Write a relay only to override what a variant sets on one element (Button · Variants); read one only where its owner documents it (`--bleed-pad`). When you do want a component token outside its component — matching a bare block to the card rhythm, say — give `var()` the default explicitly, so the declaration survives where the hook is absent:
+
+```css
+.panel {
+  padding: var(--card-pad, var(--space-40));
+}
+```
+
 ### 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.
@@ -62,17 +80,16 @@ The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surf
 
 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. `--focus` names the theme's focus color, and a ring is derived from it with `color-mix()`. 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`. Components add `--focus-ring-shadow` only where a softer halo helps; `--focus-ring-width` sets its thickness. Under `forced-colors: active`, the outline maps to `Highlight` and the shadow is disabled.
+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`. 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. Under `forced-colors: active`, outlines map to the system focus color.
 
 ```css
 :root {
-  --focus: var(--neutral);
+  --focus: hsl(268 30% 55%);
 
   --focus-outline-color: currentColor;
   --focus-outline: calc(var(--border-width) * 2) solid var(--focus-outline-color);
   --focus-outline-offset: 2px;
-  --focus-ring-width: 3px;
-  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
+  --focus-ring-width: 2px;
 }
 ```
 
@@ -211,6 +228,8 @@ Typography tokens cover the document baseline and common component needs.
 :root {
   --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --font-width: 100%;
+  --font-width-dense: 95%;
 
   --line-height: 1.5;
   --font-weight-normal: 400;
@@ -264,24 +283,41 @@ Disabled controls and disabled-prone components read `--disabled-opacity` for th
 
 ### Density
 
-Density contexts swap shared spacing and geometry:
+Density contexts swap shared spacing and geometry, plus a slight typographic
+width bonus:
 
 ```css
+:root {
+  --font-width: 100%;
+  --font-width-dense: 95%;
+}
+
 .compact {
   --gap: var(--space-20);
   --density-space: var(--space-20);
   --control-size: var(--control-size-sm);
+  font-stretch: var(--font-width-dense);
 }
 
 .spacious {
   --gap: var(--space-50);
   --density-space: var(--space-50);
   --control-size: var(--control-size-lg);
+  font-stretch: var(--font-width);
 }
 ```
 
-Density covers spacing and geometry only — it never touches typography or icon
-size. Participation is opt-in and selective: controls consume `--control-size`
+Density never changes font size or icon size — it may only use the denser font
+width. `font-stretch` uses a variable `wdth` axis when available, or
+participates in normal width-face matching for families that expose multiple
+widths. Layout must never depend on the narrowing being available. Compact
+density may slightly narrow variable typefaces when they support a width axis.
+This is a density enhancement, not an overflow strategy: never condense a
+component just because its label overflows at some viewport — that hides a
+composition problem. A theme whose typeface has no useful width axis opts out
+with `--font-width-dense: 100%`.
+
+Participation is opt-in and selective: controls consume `--control-size`
 for geometry; spacing helpers and rhythms consume `--density-space` and `--gap`;
 components whose size is intrinsic (badge, avatar, spinner, rating, key, prose,
 inline choice/switch) keep their own scales. A local component size overrides
@@ -426,9 +462,7 @@ Text controls (`.input`/`.textarea`/`.select`) expose the same lower-edge extens
 
 Alerts expose the same idea on the leading edge instead of the lower one: `--alert-border-inline-start-color` and `--alert-border-inline-start-width` are unset by default and fall back to the regular `--ui-border`, so a theme can turn an alert into a callout with a colored flag on the inline-start side, matching the classic notice pattern, without a per-variant override.
 
-A theme is not limited to the tokens above; it can restate any component-local token under a state selector to change the interaction recipe itself, not just the palette. The `edge` theme does this for focus: the base input recipe (forms/control.css) flips `--control-border` to `--focus` on top of the shared outline + ring, which would stack with a lower-edge accent. Edge instead restores `--control-border` under `:focus-visible` and thickens the accent edge so the edge, not a second ring, carries the focus.
-
-Buttons don't consume `--focus-outline` — button.css computes its own ring inline so the color can follow `--btn-focus-color` (intent-aware, unlike the plain `--focus`). It reuses the shared `--focus-ring-width` for the ring thickness and derives the color through `--btn-focus-ring-color` (a `color-mix()` of `--btn-focus-color` when supported, falling back to the shared `--focus-ring`).
+A theme is not limited to the tokens above; it can restate any component-local token or rule under a state selector to change the interaction recipe itself, not just the palette. The `gradient` theme does this for field focus: it restores a `--focus` border plus an outer translucent halo in place of the core inset outline.
 
 Rules:
 
@@ -445,9 +479,11 @@ 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, and hover overlay. In browsers with `color-mix()` support, the core derives `--focus-ring` from the island's `--focus`; override the ring only for a deliberate visual treatment or when a matching pre-`color-mix()` fallback is required.
+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. `bun run report:theme-contrast` measures both pairs.
+
+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. `bun run report:theme-contrast` prints the resting and hovered soft pair for every intent of every island, which is how a theme finds the roles that need a hook or a lower `--soft-fg-mix`.
 
-When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. The generic soft fallback (`--soft-fg-mix` derivation, above) may already be sufficient.
+The default palette's hooks apply to `:root` and to the `light`/`dark` boundaries only. Any other `data-theme` value resets them to the derivation, whether the attribute sits on `<html>` or on a nested island.
 
 Shape, shadow, motion, typography, and soft-variant mix tokens are optional knobs. Override them only when the theme actually changes that part of the system.
 
@@ -488,6 +524,7 @@ A minimal recolor theme (illustrative, not a shipped theme):
   --border: hsl(260 24% 84%);
   --focus: var(--primary);
   --hover-overlay: hsl(260 30% 10% / 0.04);
+  --shadow-color: hsl(260 30% 10%);
   --soft-bg-mix: 84%;
   --soft-border-mix: 58%;
 
@@ -497,7 +534,7 @@ 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 `--focus-ring-shadow`. 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.
+Several tokens are theme-derived aliases that reference other tokens — `--state-selected`/`--state-selected-fg`/`--state-disabled`, `--indicator-ring`, `--shadow`/`--shadow-popout`, `--heading`, and `--selection-bg`/`--selection-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.
 
 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.
 

package/docs/pages/foundations/typography.md

@@ -113,6 +113,16 @@ the document) and `--font-mono` (for `code` / `kbd` / `samp` / `pre`). There is
 theme-level token in your own theme when a project actually needs one; the
 baseline stays sans so app UI inherits predictably.
 
+### Font width
+
+Two public hooks carry the typographic side of density: `--font-width` (normal
+width) and `--font-width-dense` (compact width). The document reads
+`--font-width` through `font-stretch`; `.compact` applies
+`--font-width-dense` and `.spacious` restores `--font-width`. A theme whose
+typeface has no useful width axis sets `--font-width-dense: 100%`. Width is a
+density token, not a responsive escape hatch — never condense text to fix an
+overflowing label.
+
 ## Font weights
 
 The framework exposes a small set of weights:

package/docs/pages/guides/introduction.md

@@ -30,37 +30,29 @@ ARIA and native HTML, and per-widget configuration uses self-describing
 npm install actual-css
 ```
 
-Import the full framework in your CSS:
+Import what you use. The simplest start is the package's full entry, copied
+into your project and pruned — see
+[Start from the full entry](modular-import.md#start-from-the-full-entry):
 
 ```css
-@import "actual-css/full";
-```
-
-`actual-css/full` ships every functional family. The bare `actual-css` entrypoint
-is the minimal core (reset, tokens, theme, base, intents, variants, focus,
-print).
-
-Or compose only the pieces you use:
-
-```css
-@import "actual-css/css";
+@import "actual-css/css";                   /* core */
 @import "actual-css/css/layout";
+@import "actual-css/css/forms/all";
 @import "actual-css/css/components/button";
 @import "actual-css/css/components/card";
-@import "actual-css/css/forms";
-@import "actual-css/css/components/flyout";
 @import "actual-css/css/utilities";
 ```
 
-`actual-css/css` is the minimal core. Family manifests (`css/layout`,
-`css/forms`, `css/components`, `css/typography`, `css/effects`,
-`css/utilities`) and their modules map one-to-one to `src/css/`. See the
-[modular import guide](modular-import.md) for the full map.
+`actual-css/css` is the core (reset, tokens, theme, base, intents, variants,
+focus, print). Each family and module is its own import; the
+[modular import guide](modular-import.md) has the full map.
 
-You can also use the compiled full bundle directly:
+For zero-config use — prototypes, CDN, or when bundle size is not worth
+optimizing — the bare `actual-css` entrypoint and `actual-css/full` both resolve
+to the complete compiled framework:
 
 ```html
-<link rel="stylesheet" href="actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.10/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map
@@ -76,11 +68,12 @@ 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`, `.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 typography and
+shared by buttons, badges, alerts, and cards; a subtree that needs another
+palette is a `data-theme` island, not a class. `.ghost` and `.link` are
+button-only. Size variants `.sm` and `.lg` scale typography and
 participating component geometry consistently. Density contexts `.compact` and
-`.spacious` change geometry and spacing without changing typography or icons.
+`.spacious` change geometry and spacing without changing font size or icons;
+`.compact` may slightly narrow typefaces that support a width axis.
 Undocumented `is-*` classes are runtime internals.
 
 ```html

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

@@ -1,19 +1,26 @@
 # Modular imports
 
-Actual CSS ships one minimal core (`actual-css`) and one all-in entrypoint (`actual-css/full`). Projects can also compose the framework from family manifests or individual modules.
+Actual CSS has two kinds of entrypoint. Without `/css`, you get a compiled artifact ready to serve. With `/css`, you compose the sources.
 
 ## Entrypoints
 
-```css
-@import "actual-css";        /* minimal core */
-@import "actual-css/full";   /* complete framework */
+```text
+Composable source CSS (recommended)
+  actual-css/css             core
+  actual-css/css/<family>    one family, e.g. css/layout, css/forms/all
+  actual-css/css/<family>/*  one module, e.g. css/components/button
+  actual-css/css/full        every family, as source
+
+Zero-config distribution
+  actual-css                 complete compiled framework
+  actual-css/full            the same bundle, named explicitly
 ```
 
-`actual-css` contains the shared baseline: reset, tokens, theme, document defaults, intents, universal variants, focus, and print.
+`actual-css/css` contains the shared baseline: reset, tokens, theme, document defaults, intents, universal variants, focus, and print.
 
 It contains no typography, layout, forms, components, effects, or utilities.
 
-`actual-css/full` starts from the core and adds every family in cascade order:
+The full framework starts from the core and adds every family in cascade order:
 
 ```text
 core → typography → layout → forms → components → effects → utilities
@@ -27,6 +34,46 @@ Components may enhance or replace that treatment in interactive states, but thei
 
 When an interactive state replaces the outline, it must preserve a visible focus indicator in forced-colors, either with an outline-based fallback or by keeping the replacement out of forced-colors.
 
+## Start from the full entry
+
+Deleting is easier than adding, and it keeps the cascade order right. Copy the
+package's full entry into your project, rewrite its relative imports to
+package paths, then delete what you do not need:
+
+- CSS: `src/css/actual.full.css`. Prefix each import with `actual-css/css/`
+  and drop `.css` and `/index`; `./actual.css` is `actual-css/css`. To go below
+  family level, replace a family line with the imports of its `index.css`,
+  rewritten the same way.
+- JS: `src/js/full.js`. Prefix each import with `actual-css/js/` and drop
+  `.js`; `./index.js` is `actual-css/js`.
+
+```css
+/* app/index.css — actual.full.css, rewritten, components expanded and pruned */
+@import "actual-css/css";
+@import "actual-css/css/typography";
+@import "actual-css/css/layout";
+@import "actual-css/css/forms/all";
+@import "actual-css/css/components/button";
+@import "actual-css/css/components/close";
+@import "actual-css/css/components/card";
+@import "actual-css/css/components/modal";
+@import "actual-css/css/utilities";
+```
+
+```js
+// app/index.js — full.js, rewritten and pruned
+import "actual-css/js/flyout";
+import "actual-css/js/dialog";
+import "actual-css/js/dismiss";
+import "actual-css/js/tooltip";
+import "actual-css/js";
+```
+
+JS modules import what they depend on. CSS modules do not, and three are
+shared: keep `components/close` with modal, drawer, alert, or a removable
+badge; `components/bleed` with a `.bleed` child of card, drawer, or accordion;
+`components/spinner` with `components/busy`.
+
 ## Family manifests
 
 Each family is one import. The contents are enumerations rather than table

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

@@ -49,7 +49,10 @@ never tracked.
 
 `enhance()` observes DOM insertions and removals, not attribute changes. If an
 already-connected element receives a behavior attribute later, call the returned
-`refresh(node)` handle. Behavior attributes are setup-time contracts: removing
+`refresh(node)` handle of your own `enhance()`, or `applyEnhancement()` for a
+`data-enhance` token. The built-in `data-*` behaviors (`data-mask`,
+`data-filter`, …) expose no handle: insert the element with the attribute
+already set. Behavior attributes are setup-time contracts: removing
 one does not disconnect an active behavior. If an application needs a live
 enable/disable switch, keep that state inside its enhancer and clean it up when
 the element leaves the DOM.
@@ -229,8 +232,8 @@ Three non-obvious requirements:
 
 Lifecycle: `prepareSurface` → `openSurface` → `closeSurface` →
 `disconnectSurface`. `retainSurface(panel)` reference-counts a surface shared by
-several triggers and returns a release function; `isSurfaceOpen` and
-`getSurfaceAutoClose` read current state. The separate `escape` primitive adds
+several triggers and returns a release function; `isSurfaceOpen` reads the
+current state. The separate `escape` primitive adds
 visible dismissable UI to the shared per-document Escape stack.
 
 Actual-managed surfaces are mutually exclusive within a document. Opening a
@@ -785,8 +788,9 @@ document.addEventListener("actual:invalid", (event) => {
 
 Custom rules go in `data-validation-rules` and resolve through
 `FormValidator.registerRule`. Built-in rules are `same`, `number`, `digits`,
-`alnum`, and `date`. The library never performs network validation; server
-errors flow back through `FormValidator.setErrors(form, { name: message })` and
+`alnum`, `starts-with`, `ends-with`, `date`, and `tel-prefix`. The library never
+performs network validation; server errors flow back through
+`FormValidator.setErrors(form, { name: message })` and
 `FormValidator.clearFieldError(field)`.
 
 ```js

package/docs/pages/guides/tailwind.md

@@ -25,17 +25,29 @@ The layered import is the cleanest way to keep both stylesheets during the
 migration:
 
 ```css
+/* Tailwind v4 emits its own layers (theme, base, components, utilities),
+   so declare the order explicitly: Actual sits above Tailwind components
+   but below Tailwind utilities during the migration. */
+@layer theme, base, components, actual, utilities;
+
 @import "tailwind.css";        /* your compiled Tailwind output */
-@layer actual;
 @import "actual-css/full" layer(actual);
+
 /* Unlayered project overrides stay on top */
 @import "app.css";
 ```
 
-The full import places every Actual rule in a single `actual` layer, so
-unlayered Tailwind output and project CSS keep precedence while the migration
-runs. See [Cascade layer strategy](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/cascade-layer.md) for the
-limitations of the approach.
+The full import places every Actual rule in a single `actual` layer. The
+explicit `@layer` order is what keeps Tailwind utilities above Actual while
+the migration runs — not the unlayered status of either output. See
+[Cascade layer strategy](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/cascade-layer.md)
+for the limitations of the approach.
+
+Layers do not scope custom properties: both frameworks define
+`--font-sans`, `--font-mono`, `--font-weight-*`, and `--radius-sm` /
+`--radius-lg`. With `actual` after `theme`, `font-sans` takes Actual's font
+stack and `rounded-lg` resolves to Actual's `--radius-lg`. Expect these
+token collisions on migrated screens until Tailwind is removed.
 
 Do not assume that loading both complete stylesheets is automatically safe.