actual-css 0.12.0 → 0.14.0

package/docs/pages/guides/upgrading.md

@@ -1,12 +1,90 @@
-# Upgrading to 0.12
+# Upgrading
 
 Each step below is a search for a removed class or hook and its replacement.
 The [changelog](https://github.com/lekoala/actual-css/blob/master/CHANGELOG.md)
-lists every change; this page keeps the ones that need an edit.
+lists every change; this page keeps the ones that need an edit. Apply the
+sections in order when skipping a release.
 
 **Related terms:** migration, breaking changes, update, version.
 
-## Action rows
+## 0.12 to 0.13
+
+### Layout hooks stop at each layout
+
+`--cluster-justify`, `--cluster-align` and `--cluster-wrap` are reset on every
+`.cluster`, and `--grid-columns` and `--grid-min` on every `.grid`. A value set
+on an ancestor, including an outer cluster or grid, no longer reaches the
+layout inside it. Search application CSS and inline styles for these hooks on
+anything but the layout itself, then set them on the row or grid, or select it:
+
+```css
+.toolbar > .cluster {
+  --cluster-justify: space-between;
+}
+```
+
+`--gap` still inherits, so a density context keeps reaching every nested
+layout.
+
+### Avatar stacks
+
+`.avatar-stack` no longer takes its size from a child `.avatar.sm` or
+`.avatar.lg`. Move the size class to the stack and drop it from its avatars:
+
+```html
+<div class="avatar-stack sm" role="group" aria-label="Team members">
+  <div class="avatar" role="img" aria-label="John Doe">…</div>
+</div>
+```
+
+### Focus outline
+
+`--focus-outline` has no default value any more. Search application CSS for
+`var(--focus-outline)` and write the generic line instead:
+
+```css
+outline: var(--focus-ring-width) solid var(--focus-outline-color);
+```
+
+Setting `--focus-outline` still replaces the generic line.
+
+### List rows
+
+`.list-item` regions center on the row. For rows with long supporting text,
+add `.items-start` to the row or to the `.list` to keep them top-aligned.
+
+### Step rows
+
+`.steps-horizontal` budgets each step from its marker instead of `7rem`, so a
+row fits narrower widths before it scrolls. To keep the previous budget on a
+row, set `--step-min: 7rem` on it.
+
+### Current links and rows
+
+`.nav-link` shows its current state only for `aria-current="page"` or
+`aria-current="location"`, and `a.list-item` only for `aria-current="page"` or
+`aria-current="true"`. Search markup for other values on these classes and
+use the matching one.
+
+### Tabs
+
+`data-enhance="tabs"` only wires an element that also carries
+`role="tablist"`. Search markup for the token and add the role where it is
+missing; the console names each list it skipped.
+
+### Rendering changes without an edit
+
+- A horizontal `.tabs` strip never wraps: a strip that does not fit scrolls
+  horizontally, with no scrollbar and faded edges.
+- `.breadcrumb` never wraps either: a trail that does not fit truncates its
+  labels with an ellipsis, ancestors first. Ancestor labels need an `<a>` or
+  `<span>`.
+- The focus reserve of a scrolling dialog or drawer body no longer grows with
+  `--border-width`: 1px narrower under `prefers-contrast: more`.
+
+## 0.11 to 0.12
+
+### Action rows
 
 `.actions`, `.navbar-nav` and the layout of `.form-actions` are gone. A row of
 actions is a `.cluster`; a vertical list is `stack list-reset`. Replace
@@ -27,12 +105,11 @@ actions is a `.cluster`; a vertical list is `stack list-reset`. Replace
   `gap: var(--space-10)` on that row in application CSS.
 - `.form-actions` has no top margin and no `--form-actions-margin-block-start`:
   put `.stack` on the form. `--form-actions-justify` and `--form-actions-align`
-  still apply. In a modular build, import `layout/cluster` before
-  `forms/form-actions`.
+  still apply. In a modular build, also import `layout/cluster`.
 - `.justify-content-*` aligns only its own element and no longer reaches a
   nested `.cluster`. Put the utility on the row it should align.
 
-## Dialogs
+### Dialogs
 
 - `.dialog-confirmation` is removed. Compose `.media` with `.dialog-icon`, then
   a `<footer class="bleed background-subtle cluster justify-content-space-between">`;
@@ -46,7 +123,7 @@ actions is a `.cluster`; a vertical list is `stack list-reset`. Replace
   `.dialog-confirmation` used 1.5rem. Set `--modal-pad: var(--space-50)` on
   the dialog to keep the roomier treatment.
 
-## Cards
+### Cards
 
 The layout of a `.card` header or footer row is a zero-specificity default: any
 author rule that targets the slot replaces it, not only a `.media`, `.cluster`,
@@ -54,7 +131,7 @@ author rule that targets the slot replaces it, not only a `.media`, `.cluster`,
 element rules such as `header { … }` or `footer { … }`, which now win over the
 card's slot row.
 
-## Themes and density
+### Themes and density
 
 - A theme sets `--control-pad-x-sm`, `--control-pad-x-md` and
   `--control-pad-x-lg` instead of `--control-pad-x`. Used as a nested island,
@@ -63,7 +140,7 @@ card's slot row.
 - `--font-width-dense` is removed, and `.compact` no longer condenses type: set
   `font-stretch` on the element that should render condensed.
 
-## Rendering changes without an edit
+### Rendering changes without an edit
 
 These need no markup change; compare the affected screens.
 

package/docs/pages/layout/center.md

@@ -15,7 +15,8 @@ Constrain readable content and center it in the viewport, with width and padding
 </main>
 ```
 
-Tune width and side padding with local variables.
+Tune width and side padding with `--center-size` and `--center-pad`. Both
+inherit: set them on `:root` for the site's content width, or on one region.
 
 ```css
 .docs-page {

package/docs/pages/layout/cluster.md

@@ -61,11 +61,15 @@ separate `.split` or `.spread` primitive; this is the same relationship.
 </div>
 ```
 
+Once the row wraps, `space-between` puts an item alone on its line at the
+start. To keep the end item on the end edge when it wraps, add
+`.margin-inline-start-auto` to it.
+
 To align a row to its top edge instead of centering it — useful when one item
-wraps to several lines — set `--cluster-align`.
+wraps to several lines — set `--cluster-align` on the cluster itself.
 
 ```css
-.filters {
+.cluster.filters {
   --cluster-align: start;
   --cluster-justify: space-between;
 }
@@ -74,8 +78,11 @@ wraps to several lines — set `--cluster-align`.
 The optional utility layer ships `.justify-content-start`, `.justify-content-center`,
 `.justify-content-end` and `.justify-content-space-between`. They set
 `justify-content` on that one row only; a nested `.cluster` keeps its own
-alignment. `--cluster-justify` is inherited, so setting it on a region reaches
-nested clusters too. See the utilities page.
+alignment. The `--cluster-*` hooks behave the same way: each cluster resets
+them, so a value applies to the cluster it is set on and never to a nested
+one. To align nested rows, select them (`.toolbar > .cluster`). `--gap` keeps
+inheriting, so a density context still reaches every nested cluster. See the
+utilities page.
 
 ## Controls inside a wrapping cluster
 

package/docs/pages/layout/grid.md

@@ -172,3 +172,5 @@ stacked, prefer `.switcher`.
 - `--grid-min` tunes the minimum item width of the intrinsic `.grid` recipe.
   It does not apply to `.grid-N`.
 - `--grid-columns` replaces that recipe with an author-owned template.
+
+Both stop at a nested `.grid`: set them on the grid itself.

package/docs/pages/layout/scroll-snap.md

@@ -40,8 +40,10 @@ Items snap to the inline start edge by default, with `proximity` snapping so a s
 
 - `--scroll-snap-item-size` — item `flex` basis; set it for card rails.
 - `--scroll-snap-gap` — space between items.
-- `--scroll-snap-padding` — inline scroll padding, so a snapped item does not sit
-  flush against the container edge. Not declared; falls back to `--scroll-snap-gap`.
+- `--scroll-snap-padding` — preferred inline scroll inset; defaults to
+  `--scroll-snap-gap`. Use a length (`0px` for zero); conforming values stay at
+  least large enough for the focus gutter, and the rail's edge items keep that
+  gutter even at rest.
 - `--scroll-snap-align` — item snap alignment. Prefer `data-snap-align="center"`
   over setting this directly.
 

package/docs/pages/layout/sidebar-layout.md

@@ -47,3 +47,6 @@ When the layout stacks (narrow space), the aside stays on top.
 
 - `--sidebar-layout-size` sets the aside's preferred width.
 - `--sidebar-content-min` sets the main region's minimum viable width.
+
+The regions read both, so they also reach the regions of a nested
+`.sidebar-layout`; set them on the nested layout to give it its own sizes.

package/docs/pages/layout/switcher.md

@@ -18,3 +18,5 @@ independently.
 ### Hooks
 
 - `--switcher-threshold` controls the space needed before all peers share a row.
+  The children read it, so it also reaches the children of a nested
+  switcher; set it on the nested switcher to give it its own threshold.

package/docs/pages/layout/topbar.md

@@ -11,10 +11,12 @@ Use `.topbar` for the structural shell of an app-shell header: sticky positionin
   <button class="btn neutral ghost" type="button" aria-label="Open navigation">
     <i class="ti ti-menu-2" aria-hidden="true"></i>
   </button>
-  <ol class="breadcrumb" aria-label="Breadcrumb">
-    <li><a href="#">Overview</a></li>
-    <li aria-current="page">Accounts</li>
-  </ol>
+  <nav aria-label="Breadcrumb">
+    <ol class="breadcrumb">
+      <li><a href="#">Overview</a></li>
+      <li aria-current="page">Accounts</li>
+    </ol>
+  </nav>
   <div class="grow"></div>
   <span class="avatar sm"><abbr>LW</abbr></span>
 </header>

package/docs/pages/patterns/icon-slot.md

@@ -42,6 +42,22 @@ For a round disc, add the `.circle` utility — it supplies the `border-radius`:
 }
 ```
 
+## Webfont glyphs
+
+An icon font draws nothing measurable until it loads, so a button or nav link
+shifts when the glyph arrives. Reserve a `1em` square on the icon library's
+class in application CSS; it follows the surrounding font size:
+
+```css
+.ti {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  inline-size: 1em;
+  block-size: 1em;
+}
+```
+
 ## Reuse the existing icon slots
 
 Several components already embody this slot — reach for them before composing
@@ -55,7 +71,7 @@ your own:
 ```html demo
 <div class="media">
   <span class="avatar primary"><abbr>AM</abbr></span>
-  <div class="stack">
+  <div class="stack gap-none">
     <strong>Ada Meridian</strong>
     <span class="muted">Senior designer.</span>
   </div>

package/docs/pages/utilities/flex.md

@@ -80,7 +80,7 @@ These helpers work by setting a custom property that participating components re
 so they also apply inside a component's own grid anatomy rather than only on plain
 flex containers:
 
-- `.items-start` / `.items-center` / `.items-end` / `.items-baseline` set `--items-align`, read by `.alert` and `.card`.
+- `.items-start` / `.items-center` / `.items-end` / `.items-baseline` set `--items-align`, read by `.alert`, `.card` and `.list-item`.
 - `.text-start` / `.text-center` / `.text-end` set `--text-align`, read by `.table` cells.
 
 `.justify-content-*` and `.flex-wrap` / `.flex-nowrap` (utilities/extra) set the property

package/docs/pages/utilities/sizing-wrapping.md

@@ -66,11 +66,10 @@ Use `.truncate` on the flexible item that should ellipsize inside a constrained
 
 ## Scroller
 
-Use `.scroller` to apply optional framework scrollbar treatment to a scroll container. It styles the scrollbar only; pair it with `.overflow-auto` or a component that already creates overflow.
+Use `.scroller` to apply optional framework overflow treatment to a scroll container: a quieter scrollbar. It does not create overflow; pair it with `.overflow-auto` or a component that already creates overflow.
 
-The utility is two standard declarations and nothing else — the engine keeps
-drawing the scrollbar, `.scroller` only hands it a density and a colour that
-follow the theme. There is no `::-webkit-scrollbar` chrome: rebuilding a thumb
+The engine keeps drawing the scrollbar; `.scroller` only hands it a density
+and a colour that follow the theme. There is no `::-webkit-scrollbar` chrome: rebuilding a thumb
 by hand means re-implementing the hover, the corner and the light/dark
 adaptation that `color-scheme` already provides, and the hand-built version
 never quite matches the native one anyway.
@@ -80,6 +79,9 @@ above the capability floor. An engine that knows neither ignores both
 declarations and draws its native scrollbar — the intended fallback, not a
 broken state.
 
+`.scroller` does not apply to touch screens, where the native overlay scrollbar
+stays: it hides at rest, where a styled bar would stay visible.
+
 `.scroller` is a layout primitive, so it comes with `actual.full.css` and with
 `actual-css/css/layout` like `.stack` or `.cluster`. A project importing module
 by module reaches it directly:
@@ -102,9 +104,13 @@ by module reaches it directly:
 .scroller {
   --scroller-track: transparent;
   --scroller-thumb: var(--border);
+}
 
-  scrollbar-color: var(--scroller-thumb) var(--scroller-track);
-  scrollbar-width: thin;
+@media not all and (pointer: coarse) {
+  .scroller {
+    scrollbar-color: var(--scroller-thumb) var(--scroller-track);
+    scrollbar-width: thin;
+  }
 }
 ```
 
@@ -120,6 +126,45 @@ Thickness is not a hook: `scrollbar-width` takes `thin` or `auto`, not a length.
 Hover is left to the engine — it varies by platform, and matching it by hand was
 the part of a custom scrollbar that never held up.
 
+### One-row strips
+
+Components that never wrap scroll horizontally when they do not fit: `.tabs`,
+`.steps-horizontal`, and `.table-wrap`. (`.breadcrumb` truncates its labels
+instead; see [Breadcrumb](../components/breadcrumb.md). `.pagination` wraps.)
+In supporting browsers, a strip that loads on a current link tab or step starts
+scrolled to it; elsewhere it starts at its first item.
+
+`.tabs` hides its scrollbar and fades its edges instead: selecting the clipped
+tab scrolls it into view. The others leave the scrollbar to the engine, so an
+OS-default horizontal scrollbar can sit under a short strip, and on touch
+screens it overlays the strip and hides at rest, leaving a clipped item as the
+cue that the strip continues. Put `.scroller` on the strip itself — the element
+that scrolls — for a thin, theme-coloured bar under a mouse; touch keeps the
+overlay. These strips have no edge fade (overflow shadow, scroll hint): the
+clipped item and the scrollbar already say there is more. Keyboard focus stops
+an item with its focus line inside the strip.
+
+```html
+<ol class="steps steps-horizontal scroller">
+```
+
+There is no class that hides the scrollbar: on a strip whose items do not
+scroll it themselves, it is the only visible scroll control for a mouse without
+a horizontal wheel. Apply `.scroller` to every such strip of a page, or to
+none, so the bars stay consistent.
+
+A strip keeps scrolling inside a flex or grid row, such as a label and link
+tabs on one `.cluster`: a `<nav>` directly around `.tabs` shrinks with the row
+(and around `.breadcrumb`, which then truncates). Any other wrapper needs
+`min-inline-size: 0`, or the row pushes the whole page into scrolling.
+
+```html
+<div class="cluster">
+  <span>Sections</span>
+  <nav aria-label="Account sections"><ul class="tabs">…</ul></nav>
+</div>
+```
+
 ## CSS hooks
 
 - `--scroller-track` — scrollbar track color.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "actual-css",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
-  "packageManager": "bun@1.4.2",
+  "packageManager": "bun@1.4.3",
   "license": "MIT",
   "author": "Thomas <thomas@lekoala.be>",
   "repository": {
@@ -112,7 +112,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "lint": "biome check",
+    "hooks:install": "bun scripts/install-hooks.js",
+    "lint": "biome check --reporter concise",
     "lint:fix": "biome check --write",
     "build:docs": "bun run build:themes && bun scripts/build-docs.js",
     "watch:docs": "bun run build:themes && bun scripts/build-docs.js --watch",
@@ -139,7 +140,6 @@
     "check:catalog": "bun scripts/check-catalog.js",
     "check:links": "bun scripts/check-doc-links.js",
     "check:templates": "bun scripts/check-templates.js",
-    "check:markup": "bun scripts/check-markup.js",
     "shot:crop": "bun scripts/shot-crop.js",
     "shot:forced": "bun scripts/forced-colors-shot.js",
     "shot:multi": "bun scripts/multi-shot.js",
@@ -152,11 +152,11 @@
     "release:notes": "bun scripts/release-notes.js",
     "test": "bun test",
     "test:changed": "bun test --changed=master",
-    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run build:size && bun run format:docs && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run generate:catalog && bun run check:catalog && bun run check:sync && bun run check:links && bun run check:templates && bun run check:markup && bun run test",
+    "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run build:size && bun run format:docs && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run generate:catalog && bun run check:catalog && bun run check:sync && bun run check:links && bun run check:templates && bun run test",
     "prepublishOnly": "bun run build:all"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.12",
+    "@biomejs/biome": "^2.5.15",
     "happy-dom": "^20.14.0"
   },
   "dependencies": {

package/reserved-classes.json

@@ -48,6 +48,7 @@
   "close",
   "cluster",
   "color",
+  "color-swatch",
   "column-gap-context",
   "column-layout",
   "compact",
@@ -198,6 +199,8 @@
   "scroller",
   "scrollspy",
   "secondary",
+  "segment",
+  "segmented",
   "select",
   "separated",
   "shadow-context",

package/src/cli/actual-css.js

@@ -12,7 +12,7 @@ function usage() {
     "",
     "  -o, --out FILE   write the bundle to FILE / the export to DIR (required)",
     "      --minify     collapse comments and whitespace",
-    "      --theme FILE read this [data-theme] file instead of the default theme",
+    "      --theme FILE read this theme file ([data-theme] or :root) over the default",
     "      --name NAME  the data-theme name, when the file declares several",
     "  -h, --help       show this message",
     "      --version    print the actual-css version",
@@ -22,9 +22,9 @@ function usage() {
     "stands for. Remote imports are kept and hoisted to the top of the bundle.",
     "Leaves modern CSS syntax untouched; this is a bundler, not a transpiler.",
     "",
-    "design: export a theme's tokens for Figma and Penpot, plus Button, Input, Badge,",
-    "Alert and Card measured in headless Chrome and a Penpot plugin that builds them.",
-    "Needs Bun (bunx --bun actual-css design ...).",
+    "design: export a theme's tokens for Figma, Penpot and a portable DTCG profile,",
+    "plus Button, Input, Badge, Alert and Card measured in headless Chrome and a",
+    "Penpot plugin that builds them. Needs Bun (bunx --bun actual-css design ...).",
     "",
     "contrast: measure the pairs a theme tunes by hand in headless Chrome, in every",
     "scheme it declares: soft ink on its resting and hovered fill, the focus line on",