actual-css 0.6.0 → 0.8.0

package/docs/pages/examples/overview.md

@@ -9,19 +9,52 @@ and `actual.full.js` from `dist/`, plus the theme palettes bundle from
 
 ## Templates
 
-`demo/templates/` are standalone pages covering common page shapes.
+`demo/templates/` are standalone pages. The first three explain the system; the
+rest show it composed, isolated, or under stress.
+
+### Start here
+
+- [Visual guide](../../demo/templates/visual-guide.html) - seventeen illustrated figures on the spacing scale, the layout primitives, and density versus local size
+- [Color guide](../../demo/templates/color-guide.html) - theming principles measured live on `ocean` and `sunset`, in light and dark, as `data-theme` islands
+- [Kitchen sink](../../demo/templates/kitchen-sink.html) - one-screen test bed for themes, scopes, variants and interactions
+
+### Page shapes
+
+Whole pages, composed the way a real product would.
 
-- [Kitchen sink](../../demo/templates/kitchen-sink.html) - every component and variant on one page
-- [Keyboard controls](../../demo/templates/keyboard-controls.html) - hands-on keyboard support matrix and focus test bench
-- [Surface contracts](../../demo/templates/surfaces.html) - .inverted, cascade precedence, and the intent boundary
 - [Dashboard](../../demo/templates/dashboard.html) - data-heavy overview page
 - [App](../../demo/templates/app.html) - application shell with sidebar
+- [Workspaces](../../demo/templates/workspaces.html) - sectioned sidebar, master/detail list with native current state, and workspace cards
 - [Marketing](../../demo/templates/marketing.html) - landing page with typography and fluid type
 - [Blog](../../demo/templates/blog.html) - article page with prose
-- [Blocks](../../demo/templates/blocks.html) - layout building blocks
+- [Settings modal](../../demo/templates/settings-modal.html) - two-pane preferences dialog, with the local CSS it needs audited rule by rule
+- [Workspace settings](../../demo/templates/settings-pricing.html) - plans with visible native choices, preferences and a local segmented tab treatment
+- [Card compositions](../../demo/templates/card-compositions.html) - editorial, team, sign-in and horizontal cards composed from existing primitives
+
+### Layout references
+
+One mechanism at a time, with its contract and its pitfalls.
+
 - [Layout reference](../../demo/templates/layouts.html) - canonical compositions built only with the layout primitives
+- [Blocks](../../demo/templates/blocks.html) - layout building blocks
 - [Grid density](../../demo/templates/grid.html) - the grid contracts on resizable stages, with the pitfalls called out
+- [Column layout](../../demo/templates/column-layout.html) - the twelve-column canvas: spans, starts, and the narrow-container recomposition the framework leaves to the application
 - [Density](../../demo/templates/density.html) - compact control density
+
+### System benches
+
+Contracts you cannot read off a static screenshot: state, motion, focus, and
+extension points.
+
+- [Surface contracts](../../demo/templates/surfaces.html) - `.inverted`, cascade precedence, and the intent boundary
+- [Presence motion](../../demo/templates/motion.html) - status bar, tooltip, flyout, modal and drawer replayed side by side, with easing swaps and a reduced-motion simulation
+- [Keyboard controls](../../demo/templates/keyboard-controls.html) - hands-on keyboard support matrix and focus test bench
+- [Adaptive filter surface](../../demo/templates/adaptive-surface.html) - app-level flyout/drawer composition with one synchronized filter state
+- [Select intents](../../demo/templates/select-intents.html) - extending the enhancer with a project's own `data-enhance` behavior, injected markup included, with no framework change
+- [Popover transport probe](../../demo/templates/popover-transport.html) - self-scoring bench for the native popover transport go/no-go
+
+### Third-party components on Actual tokens
+
 - [Data grid](../../demo/templates/data-grid.html) - an external data grid component themed with Actual tokens (sort, filter, search, selection)
 - [Combobox](../../demo/templates/combobox.html) - an external combobox themed with Actual tokens (search, tags, autocomplete)
 

package/docs/pages/forms/choice-cards.md

@@ -88,7 +88,10 @@ Validation follows the shared pattern: `aria-invalid="true"` on the input (set m
 </fieldset>
 ```
 
-Sizes follow the shared `.sm` and `.lg` modifiers. Intent classes (`.primary`, `.secondary`) are supported on the `.choice-card` element.
+Sizes follow the shared `.sm` and `.lg` typography scale; the check indicator
+follows through its `em` sizing. Padding is density, so use a `.compact` or
+`.spacious` context to change it. Intent classes (`.primary`, `.secondary`) are
+supported on the `.choice-card` element.
 
 ## CSS hooks
 
@@ -100,7 +103,8 @@ Plain `.check` / `.radio` controls expose two hooks:
 
 - `--choice-control-size` — the control's own size, in `em` off the surrounding
   type. The switch track derives from it too, so a checkbox and a switch on the
-  same line stay proportionate. `.sm` / `.lg` do not touch it.
+  same line stay proportionate. A `.choice.sm` or `.choice.lg` scales it through
+  the surrounding typography.
 - `--choice-control-offset` — top offset that aligns the control with the first
   line of a multi-line label. Left unset, each control derives its own offset
   from its height and the line box, which keeps a checkbox and a taller switch

package/docs/pages/forms/combobox.md

@@ -75,7 +75,7 @@ contrast contracts apply to the combobox for free:
   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);
+  font-weight: var(--font-weight-semibold);
 }
 ```
 

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

@@ -68,11 +68,12 @@ every state, so their label always sits at the top.
 </div>
 ```
 
-## Density
+## Size and density
 
 The reserved headroom responds to control density through `--control-size`:
-`.sm` and `.lg` on the cell or an ancestor resize the control geometry and the
-label spacing with it. Typography is untouched, as everywhere in the framework.
+`.sm` and `.lg` on the cell resize the control geometry and typography. A
+`.compact` or `.spacious` ancestor changes geometry only, including the label
+spacing with it; typography stays unchanged under density.
 The floating label does add height — the headroom reserves a second vertical
 line on top of the control's minimum size.
 

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

@@ -13,6 +13,8 @@
 
 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.
 
+`.join` reshapes corners and shared edges; it does not unify the segments' treatments, and the children keep whatever classes they carry. Give them one variant family so the group reads as a single unit, and change a segment's variant only to mark state — a solid button among outlines for the active segment of a segmented control. A group mixing `.btn`, `.btn outline` and `.btn soft` is valid markup that renders as three unrelated controls stuck together.
+
 When composing source files manually, import `components/join.css` after the controls it groups. `.join` writes child border-radius longhands directly so joined corners win at equal specificity.
 
 ```html demo
@@ -33,6 +35,26 @@ the focus ring surrounds the complete joined field. Attached buttons keep their
 own focus indicator when reached directly, so the actionable segment remains
 identifiable.
 
+## Linting `role="group"`
+
+Biome's `a11y/useSemanticElements` reports the wrapper and offers `<fieldset>`
+as the replacement. That is the only element it suggests, and it does not fit:
+`<fieldset>` groups form controls under a `<legend>`, while ARIA's `group` is
+any labelled set of related objects. Suppress it on the element:
+
+```html
+<!-- biome-ignore lint/a11y/useSemanticElements: ARIA group has no HTML
+     equivalent here; fieldset expects form controls under a legend. -->
+<div class="join" role="group" aria-label="Date navigation">
+```
+
+Unlike the menu rule in
+[flyout](../enhancements/flyout.html#linting-rolemenu), do not switch this one
+off globally: it correctly catches `<div role="navigation">`,
+`<div role="button">` and `<div role="separator">`. And drop `role="group"`
+rather than suppressing it when the wrapper has no label to give — an unnamed
+group adds a boundary and nothing else.
+
 ## CSS hooks
 
 - `--join-radius` — outer corner radius of the joined group. The per-corner

package/docs/pages/forms/otp.md

@@ -36,7 +36,8 @@ Add exactly one visual `span` per expected character. Their count must match
 a numeric keyboard but does not enforce numeric input; validate the submitted
 value as usual.
 
-The component follows shared `.sm` and `.lg` density through `--control-size`.
+The component follows shared `.sm` and `.lg` size through `--control-size` and
+`--control-font-size`.
 Use `aria-invalid="true"` for explicit invalid state, or place it in the
 standard `.needs-validation.was-validated` form flow.
 

package/docs/pages/forms/overview.md

@@ -98,7 +98,7 @@ A full form using the control classes, field wrappers, and form actions:
 
     <fieldset class="field-group">
       <legend class="field-label">Availability</legend>
-      <div class="stack sm">
+      <div class="stack compact">
         <label class="choice">
           <input class="radio" type="radio" name="availability" value="available" checked />
           <span>Available for work</span>

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

@@ -4,23 +4,23 @@
 
 ## Class reference
 
-| Class | Kind     | Description                                |
-| ----- | -------- | ------------------------------------------ |
-| `.sm` | Modifier | Compact control height and spacing rhythm. |
-| `.lg` | Modifier | Large control height and spacing rhythm.   |
+| Class | Kind     | Description                              |
+| ----- | -------- | ---------------------------------------- |
+| `.sm` | Modifier | Smaller control geometry and typography. |
+| `.lg` | Modifier | Larger control geometry and typography.  |
 
-Each sets `--control-size` to `--control-size-sm` or `--control-size-lg`.
+Each maps `--control-size` and `--control-font-size` to the matching step.
 
 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.
 
-The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, selects, textareas, and buttons. Put the modifier on the control itself, or on a `.field` wrapper when the whole field should share that size.
+The `.sm` and `.lg` modifiers set the shared control tokens used by inputs,
+selects, textareas, buttons, and inline choices. Put the modifier on the control
+itself, or on a `.field` wrapper when the whole field should share that size.
 
-Inline choices — `.check`, `.radio`, `.switch` — are the exception. They sit on
-a line of text rather than standing as a field, so they are sized off the
-control typography (`--choice-control-size`, an em value) and `.sm` / `.lg`
-leave them alone: density changes field heights, not type. Resizing the control
-without its label would only break the alignment. Scale them by scaling their
-type instead.
+Inline choices — `.check`, `.radio`, `.switch` — sit on a line of text, so their
+geometry follows the local control typography through `--choice-control-size`.
+Apply `.sm` or `.lg` to the `.choice` wrapper so its label and control scale
+together. Density contexts leave both unchanged.
 
 ```html demo
 <form class="stack" novalidate>
@@ -276,12 +276,11 @@ type instead.
         <button class="btn outline lg" type="button">Large</button>
       </div>
 
-      <!-- Density is a deliberate no-op on inline choices: these three are
-           identical even though the modifiers differ. -->
+      <!-- Size belongs on the choice wrapper so label and control move together. -->
       <div class="grid items-start">
         <label class="choice sm">
           <input class="check" type="checkbox" checked />
-          <span>.sm checkbox</span>
+          <span>Small checkbox</span>
         </label>
         <label class="choice">
           <input class="radio" type="radio" name="demo-radio-size" checked />
@@ -289,7 +288,7 @@ type instead.
         </label>
         <label class="choice lg">
           <input class="switch" type="checkbox" role="switch" checked />
-          <span>.lg switch</span>
+          <span>Large switch</span>
         </label>
         <label class="choice">
           <input class="check" type="checkbox" id="indet-size" />
@@ -297,8 +296,7 @@ type instead.
         </label>
       </div>
 
-      <!-- Typography is the knob that does resize them — control and label
-           together, so the alignment survives. -->
+      <!-- The underlying typography hook remains available for custom scales. -->
       <div class="grid items-start" style="--control-font-size: var(--font-size-sm);">
         <label class="choice">
           <input class="check" type="checkbox" checked />

package/docs/pages/forms/sticky-actions.md

@@ -57,7 +57,7 @@ Scroll the page to see the actions stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack sm">
+      <div class="stack compact">
         <label class="choice">
           <input class="radio" type="radio" name="theme" value="light" checked />
           <span>Light</span>
@@ -141,7 +141,7 @@ Scroll the page to see the detached footer stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack sm">
+      <div class="stack compact">
         <label class="choice">
           <input class="radio" type="radio" name="theme-detached" value="light" checked />
           <span>Light</span>

package/docs/pages/forms/switch.md

@@ -62,7 +62,7 @@ naturally or via an explicit line break — still sit cleanly.
 
 A switch is sized off the control typography, not field density. Its track
 comes from `--choice-control-size` — the same token a checkbox and a radio use
-— so the three sit on a line of text at matching weight. `.sm` and `.lg` change
+— so the three sit on a line of text at matching weight. Density contexts change
 `--control-size`, which is field height, and deliberately leave inline choices
 alone.
 

package/docs/pages/foundations/philosophy.md

@@ -29,12 +29,15 @@ There is no `.btn-primary` or `.badge-success`. Intents are generic and reusable
 
 Components fall back to their own default intent when no intent class is set. Buttons, badges, and alerts use the neutral palette (`--neutral` / `--neutral-fg`) by default.
 
-Custom intents need no framework support — define `--intent` and `--intent-fg` on a class:
+Custom intents need no framework support — define `--intent` and `--intent-fg`
+(and `--intent-soft-fg` when the custom role needs its own soft foreground) on a
+class:
 
 ```css
 .tertiary {
   --intent: var(--tertiary);
   --intent-fg: var(--tertiary-fg);
+  --intent-soft-fg: var(--tertiary-soft-fg);
 }
 ```
 
@@ -52,44 +55,86 @@ Custom intents need no framework support — define `--intent` and `--intent-fg`
 `.ghost` and `.link` are button-only variants.
 
 ```html demo
-<button class="btn soft primary">Soft primary</button>
-<span class="badge outline success">Outline success</span>
-<div class="alert solid warning">Solid warning</div>
+<div class="stack">
+  <div class="cluster">
+    <button class="btn soft primary">Soft primary</button>
+    <span class="badge outline success">Outline success</span>
+  </div>
+  <div class="alert solid warning">Solid warning</div>
+</div>
 ```
 
-## Density
-
-`.sm` and `.lg` establish inherited density tokens. Density adjusts how much
-space UI consumes — spacing and component geometry — not how large its content
-is: typography and icon size never change. Components opt into the density
-dimensions that make sense for them. The same modifiers can also be applied
-directly to a component for local density.
+## Size and density
+
+`.sm` and `.lg` mean one size role below or above a component's natural size.
+Size names are shared roles, not shared measurements. Each participating
+component family maps them to its own optical scale: badges use `xs / sm / md`,
+while controls use `sm / md / lg`. Components without an explicit mapping do
+not change.
+
+A size role is applied to the component that participates in the scale and
+never styles arbitrary descendants. It propagates through token inheritance,
+though: components in the shared control scale set local `--control-size` and
+`--control-font-size`, and descendants consume them by their own rules. That is
+how `.field sm`, `.input-icon sm`, `.join sm`, and `.flyout sm` size the
+controls inside them, while a bare `.sm` on a plain element does nothing.
+
+`.compact` and `.spacious` establish inherited density tokens. Density arranges
+how tightly UI sits — spacing and component geometry — while typography and
+icon size stay unchanged. Participation is opt-in, and a component only joins
+where density has an effect independent from its optical size: if the result is
+merely that the component looks smaller or larger, that is size, not density.
+
+Density participation takes three levels:
+
+- **Geometry + rhythm** — controls and their wrappers (`.field`, `.join`,
+  `.flyout`, …). Height, padding, and gap respond; typography is untouched.
+- **Rhythm only** — content rows and shells such as `.list`. Spacing tightens
+  (`--list-item-gap: var(--gap)`), but the structural size stays stable.
+- **No density effect** — components whose geometry is intrinsic to their
+  content (`.badge`, `.avatar`, `.spinner`, `.rating`, `.key`, prose, inline
+  `.choice`/`.switch`). Their optical size belongs to `sm`/`lg` or local hooks.
 
 As inherited contexts, one class tightens or loosens the whole subtree:
 
 ```html demo
-<div class="sm">
+<div class="compact stack">
   <button class="btn">Compact button</button>
   <input class="input">
   <span class="badge">Compact badge</span>
 </div>
 ```
 
-The same class on a component is local density, not a second meaning:
+Application chrome can use the same scope:
 
 ```html demo
-<button class="btn sm">Compact button</button>
-<span class="badge lg">Spacious badge</span>
+<header class="navbar compact">
+  <a class="navbar-brand" href="/">Workspace</a>
+  <nav class="cluster" aria-label="Workspace actions">
+    <button class="btn ghost">Search</button>
+    <button class="btn primary">Create</button>
+  </nav>
+</header>
+```
+
+Component geometry remains local and wins over inherited density when both
+affect the same dimension:
+
+```html demo
+<div class="compact">
+  <button class="btn lg">Large button in a compact context</button>
+</div>
 ```
 
-This is not "`.sm` sometimes means density and sometimes size": `.sm` always
-establishes the same density tokens — only the scope changes. The density
-tokens are `--gap`, `--density-space`, `--control-size`, and
-`--density-compact-size`. Components consume the dimensions that make sense
-for them and opt out of the rest.
+The density tokens are `--gap`, `--density-space`, and `--control-size`.
+Components consume the dimensions that make sense for them and opt out of the
+rest. The absolute `--space-*` scale is not rebound by density scopes.
+Components with bespoke geometry (`.badge`, `.avatar`,
+`.spinner`, `.rating`) own their local `.sm`/`.lg` mappings.
 
-Components with bespoke sizing (`.avatar`, `.spinner`) define local `.sm`/`.lg`
-instead of consuming the shared tokens.
+`.compact` also remains a meaningful local modifier for `.card` and `.table`.
+On those components it tightens their own padding and establishes the compact
+density context for descendants.
 
 ## Child semantics
 

package/docs/pages/foundations/theming.md

@@ -20,7 +20,7 @@ Set `--cluster-align`.
 
 ### Change spacing without changing control size
 
-Set `--gap` locally on the layout primitive. The extra utilities (`src/css/utilities/extra.css`) ship `.gap-sm` / `.gap-md` / `.gap-lg` for row/column containers.
+Set `--gap` on the layout primitive to retune it and everything nested. To change only that element's rhythm without reaching nested primitives, set the `gap` property instead.
 
 → Layout
 
@@ -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, set `--choice-control-size` instead — the checkbox, the radio, and the switch track all follow it. `.sm` / `.lg` are field density and leave inline choices alone.
+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.
 
 → Forms · Switch
 
@@ -70,6 +70,14 @@ Native controls that no component class restyles — a bare checkbox, radio, ran
 
 → Forms · Overview · Foundations · Tokens (theme contract)
 
+### Store a theme name without applying it
+
+`data-theme` is an active theme boundary on every element that carries it, not
+a generic storage attribute. Use a different name such as `data-theme-value`,
+or a form control's `value`, when the element should only hold a theme name.
+Apply `data-theme` deliberately when that element and its subtree should paint
+with the selected palette — a theme swatch is a useful example.
+
 ### Loading / busy overlay on a container
 
 Use `aria-busy="true"` with a direct last-child `.spinner`; tint the overlay with `--busy-overlay-bg`.