actual-css 0.6.0 → 0.8.0

package/docs/pages/foundations/tokens.md

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

package/docs/pages/foundations/typography.md

@@ -38,7 +38,7 @@ It applies everywhere — cards, dialogs, heroes, app shells — not only in pro
 
 It does not own visual hierarchy. No global `font-size` on headings, no global `font-weight` on headings, no global margins on headings, no global `text-decoration` on links. These choices would shape app UI in ways the framework cannot predict.
 
-The mildly opinionated defaults at the baseline are few: line-height on headings (tight, so multi-line headings stay readable), `text-wrap: balance` on headings where supported, the `hr` rule, the `::selection` rule, the `code` / `kbd` / `samp` / `pre` font family, `small` font size, and a global link underline offset that prose and components reuse. Everything else stays neutral so components and `.prose` can take over without fighting the baseline.
+The mildly opinionated defaults at the baseline are few: line-height on headings (tight, so multi-line headings stay readable), `text-wrap: balance` on headings where supported, the `hr` rule, the `::selection` rule, the `code` / `kbd` / `samp` / `pre` font family, `pre` overflow containment, `small` font size, and a global link underline offset that prose and components reuse. Everything else stays neutral so components and `.prose` can take over without fighting the baseline.
 
 Global links inherit color. The visual affordance of a link is the responsibility of `.prose` (for authored content) or of a component (for nav links, button-like links, tabs, breadcrumbs, etc.). Underlining every `a` globally would collide with all of those.
 
@@ -54,10 +54,11 @@ The reason for that boundary: a dialog title, a card heading, or a sidebar secti
 
 ### Fluid module
 
-`src/css/typography/fluid.css` is a small module that is not imported by
-`actual.css`. Projects that need display, title, and lead sizes that scale
-with the viewport (landing pages, marketing pages, hero sections,
-documentation homepages) import it manually:
+`src/css/typography/fluid.css` ships with the typography family
+(`actual-css/css/typography`) and `actual-css/full`, but not with the minimal
+core. A core-only entry point that needs display, title, and lead sizes that
+scale with the viewport (landing pages, marketing pages, hero sections,
+documentation homepages) imports it explicitly:
 
 ```css
 @import "actual-css/css/typography/fluid";
@@ -116,14 +117,14 @@ baseline stays sans so app UI inherits predictably.
 
 The framework exposes a small set of weights:
 
-- `--font-weight` (400) — body default
-- `--font-weight-medium` (500) — slightly heavier than body, for nav links
-- `--font-weight-strong` (650) — emphasis, prose headings, badges, tabs, table headers
-- `--font-weight-bold` (700) — the strongest weight exposed, used by the navbar brand and the accordion summary
+- `--font-weight-normal` (400) — body default
+- `--font-weight-medium` (500) — slightly heavier than body, for nav links and accordion summaries
+- `--font-weight-semibold` (600) — emphasis, prose headings, badges, tabs, table headers
+- `--font-weight-bold` (700) — the strongest weight exposed, used by the navbar brand
 
 No `--font-weight-light`. Light weights depend on the typeface, are rarely a good default, and add surface area without a recurring need.
 
-These weights are also the values used by components. Components do not use literal `font-weight: 600` or `font-weight: 750`; they reference the tokens. Theme authors can re-map them in one place.
+These weights are also the values used by components. Components reference the tokens instead of literal weights, so theme authors can re-map the scale in one place.
 
 ## Line heights
 
@@ -159,7 +160,7 @@ Headings are split between the global baseline and `.prose`.
 
 Globally, headings get a tight line-height, a color from `--heading` (or inherited), and progressive `text-wrap: balance`. They do not get a `font-size`, a `font-weight`, or margins. The reason is that a card heading, a dialog title, or a sidebar section should not be auto-magically enlarged by selector.
 
-Inside `.prose`, headings get a `font-weight` from `--font-weight-strong`, a tighter line-height from `--prose-heading-line-height`, margin rhythm, and keep the global `text-wrap: balance`. Their color follows the contextual `--heading` alias, so prose also composes correctly with a contextual surface. The `h1` to `h4` font sizes are scoped to `.prose`, remain low-specificity, and are not exposed as a public scale.
+Inside `.prose`, headings get a `font-weight` from `--font-weight-semibold`, a tighter line-height from `--prose-heading-line-height`, margin rhythm, and keep the global `text-wrap: balance`. Their color follows the contextual `--heading` alias, so prose also composes correctly with a contextual surface. The `h1` to `h4` font sizes are scoped to `.prose`, remain low-specificity, and are not exposed as a public scale.
 
 The `hgroup` element gets only structural styling: a grid layout, a gap, and a reset of internal margins. No font-size, no color, no weight. Its visual identity is the responsibility of the headings and paragraphs it contains.
 
@@ -175,7 +176,27 @@ Three logical alignment utilities exist (`.text-start`, `.text-center`, `.text-e
 
 `small` gets a smaller font size globally (`0.875em`) because it is a semantic element, not a utility. There is no `.small` class competing with the element.
 
-`code`, `kbd`, `samp`, and `pre` get the mono font family globally. Visual treatment (background, padding, radius) is left to `.prose` or to code-block components.
+`code`, `kbd`, `samp`, and `pre` get the mono font family globally. `pre` also gets `overflow-x: auto`, because one unbreakable line widens the whole page and nothing in the markup warns you. That is containment, not decoration: background, padding, and radius are still left to `.prose` or to a code-block component.
+
+For a standalone snippet outside authored content, `.prose` is the ready-made box — opt out of the reading measure so the code can use the full width:
+
+```html
+<div class="prose" style="--prose-measure: none">
+  <pre><code>bun add actual-css</code></pre>
+</div>
+```
+
+`hr` resets the UA's `margin-inline: auto`. In document flow that changes nothing — auto inline margins on an auto-width block resolve to zero — but as a flex or grid item they replace the cross-axis stretch, which made an `<hr>` inside a `.stack` compute to zero width and disappear. `.stack` deliberately leaves the inline axis free (self-centering children keep working), so the reset belongs to the element.
+
+Its block margin is tunable with `--hr-space`. The `--space-60` default suits a rule closing a page section; a rule separating two rows inside a panel wants far less.
+
+```css
+.settings-panel hr {
+  --hr-space: var(--space-10);
+}
+```
+
+The hook applies to an `hr` in document flow. Inside `.stack` or `.prose` the parent owns the distance between siblings and overrides the element's own margin — express the rhythm there instead, with `--gap` or `--prose-flow`.
 
 ## Tables
 
@@ -198,14 +219,14 @@ To enable fluid display type on a marketing or documentation surface, import the
 
 The module does not change anything in the core: it adds three size tokens and three classes. Body text, app UI, and the default prose scale are not affected.
 
-Projects that do not need fluid display type do nothing — the module is not part of the default bundle.
+Projects on `actual-css/css/typography` or `actual-css/full` already have the module. A minimal-core project that does not need fluid display type does nothing — the module is not in the core.
 
 ## What not to reintroduce
 
 These are decisions that the framework has already made. Re-introducing them silently would regress the system.
 
 - Do not add `font-size` on global `h1` to `h6`. Headings inherit size from context (component or `.prose`).
-- Do not add `font-weight` on global `h1` to `h6`. Strong weight is scoped to `.prose` and to components that need it.
+- Do not add `font-weight` on global `h1` to `h6`. Heavier weights are scoped to `.prose` and to components that need them.
 - Do not add global `text-decoration: underline` on `a`. Links get their visual affordance from `.prose` or from their component.
 - Do not add `transition: all`. Transitions target specific properties.
 - Do not add a `--font-weight-light`. It is rarely a good default and depends on the typeface.

package/docs/pages/guides/introduction.md

@@ -78,7 +78,9 @@ 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 controls consistently.
+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.
 Undocumented `is-*` classes are runtime internals.
 
 ```html
@@ -139,16 +141,16 @@ 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+     |
-| Recommended  | 129+    | 17.5+     | 123+     |
+| Tier        | Firefox  | Safari  | Chromium |
+| ----------- | -------- | ------- | -------- |
+| Degraded    | 78+      | 14+     | 88+      |
+| **Minimal** | **125+** | **17+** | **116+** |
+| Recommended | 129+     | 17.5+   | 123+     |
 
 **Degraded** — semantic HTML and core CSS remain usable. JavaScript
 enhancements are outside the supported contract.
 
 **Minimal** — full Actual support, including the JavaScript runtime. The
-runtime assumes modern browser APIs and ships no legacy compatibility layers or
-polyfills.
+runtime assumes modern browser APIs — including the native manual Popover
+transport used by interactive surfaces — and ships no legacy compatibility
+layers or polyfills.