actual-css 0.10.0 → 0.11.1

package/docs/pages/foundations/tokens.md

@@ -76,18 +76,25 @@ Surface tokens describe the canvas and elevation model. Components should prefer
 }
 ```
 
-The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surfaces), `surface-subtle` (the working subtle level — for hover overlays, form fields, table headers), and `surface-solid` (the dark inverse surface, used for accent areas).
+The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surfaces), `surface-subtle` (the working subtle level — for hover overlays, form fields, table headers), and `surface-solid` (the inverse surface, used for accent areas).
+
+Surfaces are painted material and may be translucent. Two roles must stay opaque, so they have their own tokens, both defaulting to `--surface`:
+
+- `--surface-solid-fg` — the ink on `--surface-solid`: tooltips, the status bar, an inverse band.
+- `--surface-opaque` — an opaque neutral used where a component must hide or separate what is painted beneath it: the status-dot and avatar-stack rings, range-thumb and meter separators, step markers, the mask under an `.aura` child. It is not a surface fill; paint panels with `--surface-*`.
+
+A theme with translucent surfaces overrides both with opaque values.
 
 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. 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.
+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`. The baseline is a `currentColor` line, so text-like elements (links, `summary`, nav and menu items) follow whatever surface the application painted. Boxed 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. Both lines are `--focus-ring-width` wide. Under `forced-colors: active`, outlines map to the system focus color.
 
 ```css
 :root {
   --focus: hsl(268 30% 55%);
 
   --focus-outline-color: currentColor;
-  --focus-outline: calc(var(--border-width) * 2) solid var(--focus-outline-color);
+  --focus-outline: var(--focus-ring-width) solid var(--focus-outline-color);
   --focus-outline-offset: 2px;
   --focus-ring-width: 2px;
 }
@@ -381,7 +388,7 @@ A few cross-component helpers:
 ```css
 :root {
   --indicator-offset: 14.65%;      /* circle-aware inset */
-  --indicator-ring: var(--surface);
+  --indicator-ring: var(--surface-opaque);
   --backdrop-color: rgb(0 0 0);
   --backdrop-opacity: 0.45;
   --backdrop-fill: rgb(0 0 0 / var(--backdrop-opacity));
@@ -485,12 +492,15 @@ When overriding an intent color, review its paired `--*-fg` and `--*-soft-fg`. A
 
 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.
 
+Contrast is measured between opaque colors. A translucent `--surface` has no ratio until it is composited over its backdrop, so `report:theme-contrast` refuses such a theme, and `.soft` mixes over it come out more opaque and more saturated than the surface. A translucent theme owns both: it measures against its real backdrop and replaces any recipe that does not hold there.
+
 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:
 
 - intent colors and foreground pairs
 - surface, text, border, focus, and overlay colors
+- `--surface-opaque` and `--surface-solid-fg`, when surfaces are translucent
 - radius tokens
 - optional shadow, motion, typography, and soft-variant mix tokens
 
@@ -534,7 +544,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`, 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.
+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 `--surface-opaque`/`--surface-solid-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/guides/bootstrap.md

@@ -18,7 +18,8 @@ For an incremental migration, use one of these approaches:
 
 * migrate isolated pages or application areas;
 * control precedence with cascade layers or import order;
-* use a project-side prefix transform for Actual while both frameworks coexist.
+* use a project-side prefix transform for Actual while both frameworks coexist,
+  renaming the runtime's state classes in `actual-css/js/selectors` as well.
 
 The layered import is the cleanest way to keep both stylesheets during the
 migration:

package/docs/pages/guides/design-tools.md

@@ -0,0 +1,36 @@
+# Design tools (Figma, Penpot)
+
+`actual-css design` exports a theme to design tools: its tokens for Figma and Penpot, and a Penpot plugin that builds Button, Input, Badge, Alert and Card bound to those tokens. Use it to hand designers the same palette, scale and components the code ships — a design kit, a UI kit, a Figma or Penpot library generated from your theme.
+
+```sh
+bunx actual-css design --theme src/theme.css --out design/
+```
+
+`--theme` is a file declaring one `[data-theme="…"]` block (see [Theming](../foundations/theming.md)); without it the default theme is exported. The command needs Bun: it reads the theme in headless Chrome, so every `light-dark()`, `color-mix()` and `var()` chain resolves exactly as the browser paints it.
+
+## What is exported
+
+| File                                          | Content                              |
+| --------------------------------------------- | ------------------------------------ |
+| `figma/foundations.tokens.json`               | spacing, radius, borders, type sizes |
+| `figma/light.tokens.json`, `dark.tokens.json` | colors, one file per scheme          |
+| `penpot/tokens.json`                          | all tokens, as sets and themes       |
+| `penpot/plugin/`                              | the plugin and component spec        |
+
+Token names are the CSS names without `--`: `surface-raised` in the design tool is `var(--surface-raised)` in code. A scheme exists when the theme declares it: `color-scheme: light dark` exports both, anything else one. Lengths are exported in px, with the CSS value kept in `$extensions["actual-css"]`.
+
+Colors no theme token paints — the soft fills and borders of `.soft` — are exported as recipe tokens named `<variant>-<intent>-<role>` (`soft-danger-bg`, `soft-danger-border`, `soft-danger-fg`), next to the theme colors so they switch with the scheme. Font stacks, line heights, shadows, motion and z-index have no design-tool equivalent and are not exported.
+
+## Figma
+
+Import each file from the Variables panel. Figma makes one collection per file: import `light`, then add `dark` to that collection as a second mode (a paid-plan feature; the free plan allows one mode per collection).
+
+## Penpot
+
+1. Tokens tab → Tools → Import `penpot/tokens.json`. It replaces the file's tokens.
+2. Serve `penpot/plugin/` over http with CORS, and add its `manifest.json` URL in the plugin manager (`Ctrl + Alt + P`).
+3. Run **Build components**.
+
+The components are built on their own page, "Actual CSS components"; drag instances from Assets onto any page. Each is a variant set whose properties are the classes an author stacks — `Intent`, `Variant` and `Size` on Button and Badge, `Intent` and `Variant` on Alert, `Size` on Input — defaulting to the bare class (`.btn`, `.badge`). Fills, borders and text colors are bound to tokens, so switching the Penpot theme between Light and Dark repaints every variant. Radius, padding, height and type are the measured values: run the export again after changing them in the theme.
+
+The components are measured, not modelled: the browser renders the classes and the plugin replays the result, so a theme's own radius or padding shows up without configuration. States (hover, focus, disabled) stay a code concern.

package/docs/pages/guides/introduction.md

@@ -52,7 +52,7 @@ optimizing — the bare `actual-css` entrypoint and `actual-css/full` both resol
 to the complete compiled framework:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.10/dist/actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.11/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map

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

@@ -94,7 +94,7 @@ cells, so they read as a list:
 - **Components** — `actual-css/css/components`
   buttons, surfaces, overlays, feedback, navigation, data and composed controls
 - **Effects** — `actual-css/css/effects`
-  aura
+  aura, shimmer
 - **Utilities** — `actual-css/css/utilities`
   base and extra utilities
 

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

@@ -92,6 +92,7 @@ example:
 | `actual-css/js/filter`             | Input value filtering on `data-filter`                      |
 | `actual-css/js/mask`               | Input masks on `data-mask`                                  |
 | `actual-css/js/password`           | Password reveal toggle                                      |
+| `actual-css/js/range`              | Range fill and named values (token `range`)                 |
 | `actual-css/js/validation`         | Form validation (token `validation`)                        |
 | `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`      |
 | `actual-css/js/enhancement-loader` | Declared enhancement manifests                              |
@@ -108,11 +109,12 @@ needed.
 
 The JS is designed to run on its own, without Actual's stylesheet.
 
-- **`data-enhance` tokens** register root-controller behaviors. The runtime
-  discovers components through `data-enhance="tabs"`, `data-enhance="flyout"`,
-  `data-enhance="scrollspy"`, and `data-enhance="validation"` — no Actual
-  presentation class needed. Self-describing attributes (`data-mask`,
-  `data-tooltip`, `data-context-menu`) stay framework-neutral by construction.
+- **`data-enhance` tokens** register named behaviors. The runtime discovers
+  components through `data-enhance="tabs"`, `data-enhance="flyout"`,
+  `data-enhance="range"`, `data-enhance="scrollspy"`, and
+  `data-enhance="validation"` — no Actual presentation class needed.
+  Self-describing attributes (`data-mask`, `data-tooltip`,
+  `data-context-menu`) stay framework-neutral by construction.
 - **`selectors.js`** lists the state classes the runtime *writes* (`is-open`,
   `was-validated`, …). Edit this file (or alias it in a bundler) to
   match a different CSS framework's state vocabulary. It is a read-side-only
@@ -326,7 +328,6 @@ import { registerCommands } from "actual-css/js/command";
 
 registerCommands("--toggle-hidden", {
   handle(event, trigger, target) {
-    event.preventDefault();
     target.hidden = !target.hidden;
     trigger.setAttribute("aria-expanded", String(!target.hidden));
   },
@@ -335,10 +336,10 @@ registerCommands("--toggle-hidden", {
 
 The default resolver `targetFor(trigger)` looks up `commandfor` by ID in the
 trigger's document or shadow root. Supply `resolve(trigger)` to validate or
-replace that lookup. An optional idempotent `prepare(trigger, target, command)`
-callback runs directly before `handle`; built-in behaviors use it for
-target-derived semantics. `commandSelector(commands)` builds the matching button
-selector. The returned handle has an idempotent `disconnect()` method for
+replace that lookup. Once a target resolves, the router cancels the click before
+`handle` runs, so the native `command` event is never dispatched for a routed
+command. Names must be a native keyword or start with `--`; anything else
+throws. `commandSelector(commands)` builds the matching button selector. The returned handle has an idempotent `disconnect()` method for
 applications that unload the module owning the command.
 
 ### Dismiss command
@@ -414,10 +415,8 @@ registerEnhancement("autosubmit", (form) => {
 <form data-enhance="validation autosubmit">
 ```
 
-`enhancementSelector(name)` returns the matching `[data-enhance~="name"]`
-selector (names must match `[a-z][a-z0-9-]*`), and `hasEnhancement(el, name)`
-tests it. No core module list is modified — the regression test in
-`tests/enhance.test.js` proves the shape.
+Names must match `[a-z][a-z0-9-]*`. To find opted-in elements from your own
+script, query `[data-enhance~="name"]`; styles keep using presentation classes.
 
 A name is owned once per root: a second `registerEnhancement("autosubmit", …)`
 on the same root throws, and `disconnect()` releases the name so it can be

package/docs/pages/guides/tailwind.md

@@ -17,9 +17,11 @@ If you finish the migration with a new `.mt-4`, `.flex`, `.bg-primary`, and `md:
 
 Tailwind and Actual can temporarily coexist, but some short class names overlap.
 
-Examples include layout and flex-related names such as `.grid`, `.grow`, and `.items-center`.
+The most dangerous is `.outline`: it is an Actual button variant (`.btn.outline`), and Tailwind's `outline` utility draws a real outline on it. Layer order does not save this one — the migration setup above puts Tailwind utilities over Actual on purpose.
 
-For a staged migration, use cascade layers, controlled import order, or a project-side Actual prefix transform where necessary.
+Other overlapping names: `.table`, `.sticky`, `.truncate`, `.prose`, `.sr-only`, plus layout names such as `.grid`, `.grow`, and `.items-center`.
+
+For a staged migration, use cascade layers, controlled import order, or a project-side Actual prefix transform where necessary. The transform lives in the consumer's own pipeline (a build-time rename on the Actual import), not in the Actual CLI, which only bundles. The JavaScript runtime writes state classes (`is-open`, `danger`, …): rename them in `actual-css/js/selectors` too, or flyouts and dialogs never open.
 
 The layered import is the cleanest way to keep both stylesheets during the
 migration:

package/llms.txt

@@ -30,9 +30,10 @@ show supported CSS modules and individual enhancer imports without duplicating
 the full export list here.
 
 Presentation (`class`) and behavior are separate layers. `data-enhance` takes
-four tokens only — `tabs`, `flyout`, `scrollspy`, `validation`; leaf behaviors
-use their own attribute (`data-tooltip`, `data-mask`, `data-filter`,
-`data-context-menu`) and `<dialog>` needs none. See
+five built-in tokens — `tabs`, `flyout`, `range`, `scrollspy`, `validation`.
+Leaf behaviors whose opt-in also carries configuration use their own attribute
+(`data-tooltip`, `data-mask`, `data-filter`, `data-context-menu`), and `<dialog>`
+needs none. See
 [when a token, when a data-*](docs/design-notes/enhancement-contract.md).
 
 Behaviour primitives are independently importable for building custom widgets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.4.2",
@@ -66,6 +66,7 @@
     "./js/mask": "./src/js/mask.js",
     "./js/menu": "./src/js/menu.js",
     "./js/password": "./src/js/password.js",
+    "./js/range": "./src/js/range.js",
     "./js/scrollspy": "./src/js/scrollspy.js",
     "./js/selectors": "./src/js/selectors.js",
     "./js/tab": "./src/js/tab.js",
@@ -130,6 +131,7 @@
     "build:js": "bun scripts/build-js.js",
     "build:themes": "bun scripts/build-themes.js",
     "build:size": "bun scripts/build-size.js",
+    "export:design": "bun scripts/export-design.js",
     "check:enhance": "bun run scripts/check-enhance.js",
     "generate:reserved": "bun scripts/generate-reserved-classes.js",
     "check:reserved": "bun scripts/check-reserved.js",
@@ -138,12 +140,15 @@
     "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",
     "shot:page": "bun scripts/page-shot.js",
+    "shot:states": "bun scripts/shot-states.js",
     "probe": "bun scripts/probe.js",
     "serve": "bun scripts/serve.js",
     "check:sync": "bun scripts/check-sync.js",
+    "release": "bun scripts/release.js",
     "release:notes": "bun scripts/release-notes.js",
     "test": "bun test",
     "test:changed": "bun test --changed=master",

package/reserved-classes.json

@@ -203,6 +203,7 @@
   "separated",
   "shadow-context",
   "shadow-popout-context",
+  "shimmer",
   "sidebar-layout",
   "skeleton",
   "sm",

package/skills/actual-css/references/enhancements.md

@@ -21,6 +21,41 @@ Self-describing leaf behavior should use the feature's own documented attribute,
 
 Native `<dialog>` is semantically self-describing and does not need a generic enhancement token merely to be a dialog.
 
+## Dialog anatomy
+
+Treat `.modal` as the outer surface, not as its content layout. It deliberately
+has no padding. Wrap modal content in a direct `<form>` or `.stack`; do not put
+`.stack` on `dialog.modal` itself.
+
+For a header band, put `<header>` directly under the dialog before the body
+wrapper. Compose a flexible `.media` title region and a trailing `.cluster` of
+controls. Nest `.close` in that cluster so it remains in flow; the title,
+leading `.dialog-icon`, close, and any additional control then share one center
+axis and the title uses the close control's minimum height. A direct
+`dialog > header` is dialog chrome and forms a distinct band; put an ordinary
+content heading in the wrapper's `<header>` instead.
+
+For a corner close button, keep `.close` as a direct child of the dialog and put
+the title in the content wrapper's direct `<header>`. The close button is then
+anchored to the surface, and the header reserves room so the title cannot run
+under it. A `.close` that is a direct child of the chrome header is that same
+corner overlay, and that header reserves room for it too. Put actions in the
+wrapper's `<footer>`.
+
+Use `.bleed` on that direct header when it needs a contrasting full-width band;
+the wrapper relays the modal padding so the band reaches the surface edges while
+its contents keep the normal inset. In `.dialog-confirmation`, keep the icon and
+the text header as the media object's two children; the component centers the
+header's first heading on the icon while following copy stays in that text
+column. For a trailing icon, use the confirmation's direct header as a
+non-wrapping split `.cluster`, with `.grow` on the text group. Do not compensate
+heading alignment with a literal margin.
+
+Do not turn the dialog heading into an `.alert` to obtain icon or surface
+styling. Compose `.dialog-icon` with `.media` for a leading title icon; reserve
+`.alert` for a distinct status message in the dialog body. Inspect
+`docs/pages/components/dialog.md` in the installed package for current recipes.
+
 ## Custom widgets
 
 Before implementing lifecycle, focus, Escape handling, keyboard navigation, input rewriting, or floating-surface policy from scratch, inspect the exported Actual JS primitives.

package/src/cli/actual-css.js

@@ -7,16 +7,23 @@ import { inlineImports, minifyCss } from "../tooling/css-bundle.js";
 function usage() {
   return [
     "actual-css bundle INPUT --out FILE [--minify]",
+    "actual-css design [--theme FILE] [--name NAME] --out DIR",
     "",
-    "  -o, --out FILE   write the bundle to FILE (required)",
+    "  -o, --out FILE   write the bundle to FILE / the export to DIR (required)",
     "      --minify     collapse comments and whitespace",
+    "      --theme FILE export this [data-theme] file instead of the default theme",
+    "      --name NAME  the data-theme name, when the file declares several",
     "  -h, --help       show this message",
     "      --version    print the actual-css version",
     "",
-    "Bundle plain CSS @import chains from relative files and actual-css/css/* subpaths.",
-    "A layer or layer(name) import is flattened into the @layer block it stands for.",
-    "Remote imports are kept and hoisted to the top of the bundle.",
+    "bundle: flatten plain CSS @import chains from relative files and actual-css/css/*",
+    "subpaths. A layer or layer(name) import is flattened into the @layer block it",
+    "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 actual-css design ...).",
   ].join("\n");
 }
 
@@ -36,6 +43,10 @@ function parseArgs(argv) {
     return { version: true };
   }
 
+  if (command === "design") {
+    return parseDesignArgs(rest);
+  }
+
   if (command !== "bundle") {
     throw new Error(`Unknown command: ${command}`);
   }
@@ -87,7 +98,39 @@ function parseArgs(argv) {
     throw new Error("Missing required --out FILE option.");
   }
 
-  return { help: false, input, out, minify };
+  return { help: false, command: "bundle", input, out, minify };
+}
+
+function parseDesignArgs(rest) {
+  const options = { help: false, command: "design", themeFile: null, name: null, out: "" };
+  const valued = { "--theme": "themeFile", "--name": "name", "--out": "out", "-o": "out" };
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    const key = valued[arg];
+    if (!key) throw new Error(`Unknown option: ${arg}`);
+    const value = rest[i + 1];
+    if (!value) throw new Error(`Missing value for ${arg}.`);
+    options[key] = value;
+    i += 1;
+  }
+
+  if (!options.out) throw new Error("Missing required --out DIR option.");
+  return options;
+}
+
+async function design({ themeFile, name, out }) {
+  // Checked before the import: under Node the module does not even parse
+  // (`await using`), and `bundle` must stay usable there.
+  if (typeof Bun === "undefined") {
+    throw new Error(
+      "actual-css design needs Bun: it reads the theme in headless Chrome through Bun.WebView. Run it with bunx.",
+    );
+  }
+  const { exportDesign } = await import("../tooling/design-export.js");
+  const written = await exportDesign({ themeFile, name, out: resolve(out) });
+  console.log(`Exported ${written.length} files to ${resolve(out)}`);
 }
 
 async function bundle({ input, out, minify }) {
@@ -124,7 +167,7 @@ async function main() {
     return;
   }
 
-  await bundle(args);
+  await (args.command === "design" ? design(args) : bundle(args));
 }
 
 main().catch((error) => {

package/src/css/components/avatar.css

@@ -211,7 +211,7 @@ a.avatar[aria-disabled="true"] {
 }
 
 .avatar-stack > .avatar {
-  box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface);
+  box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface-opaque);
 }
 
 .avatar-stack > .avatar + .avatar {

package/src/css/components/bleed.css

@@ -5,9 +5,9 @@
  *
  * A surface that insets its direct children relays that inset to them as
  * --surface-pad; a direct .bleed child cancels it and reaches the surface
- * edge. Card and drawer pad at the container level, so they own the token
- * there; the accordion pads its summary and its panel instead, so the panel
- * owns it and the item does not.
+ * edge. Card and drawer pad at the container level, while modal pads its inner
+ * wrapper; each owns the token where that inset lives. The accordion pads its
+ * summary and panel instead, so the panel owns it and the item does not.
  *
  * Why the token is handed to the children rather than declared on the surface:
  * custom properties inherit, so a surface-level declaration would also reach a
@@ -28,11 +28,11 @@
  * Framework plumbing:
  * --surface-pad (declared by the surface)
  */
-:where(.card, .drawer, .accordion details > summary + *) > * * {
+:where(.card, .drawer, dialog.modal > :is(form, .stack), .accordion details > summary + *) > * * {
   --bleed-pad: initial;
 }
 
-:where(.card, .drawer, .accordion details > summary + *) > * {
+:where(.card, .drawer, dialog.modal > :is(form, .stack), .accordion details > summary + *) > * {
   --bleed-pad: var(--surface-pad);
 }
 

package/src/css/components/button.css

@@ -31,6 +31,7 @@
  * --btn-default-hover-bg
  * --btn-border-block-end-color
  * --btn-border-block-end-width
+ * --btn-border-block
  * --spinner-width
  */
 
@@ -56,6 +57,10 @@
   --btn-default-hover-bg: var(--btn-bg);
   --btn-radius: var(--radius);
   --btn-hover-overlay: var(--hover-overlay, rgb(0 0 0 / 0.08));
+  --btn-border-block: calc(
+    var(--border-width) +
+    var(--btn-border-block-end-width, var(--border-width))
+  );
 
   /* Positioning context for indicators, overlays, and grouped states. */
   position: relative;
@@ -65,7 +70,13 @@
   gap: var(--btn-gap, 0.375em);
   min-block-size: var(--btn-min-size);
   padding-block: var(--space-20);
-  padding-block: max(var(--space-10), calc((var(--btn-min-size) - 1lh) / 2));
+  /* why: centres one line in --btn-min-size and keeps that rhythm when the
+     label wraps. min-block-size is a border-box length, so both borders come
+     out of it; without them .btn stood 2px taller than .input. */
+  padding-block: max(
+    var(--space-10),
+    calc((var(--btn-min-size) - 1lh - var(--btn-border-block)) / 2)
+  );
   padding-inline: var(--btn-pad-x);
   border: var(--border-width) solid var(--btn-border-color, var(--btn-border));
   border-block-end-color: var(
@@ -162,6 +173,8 @@
   --ui-fg: var(--intent, currentColor);
   --ui-border: transparent;
   --btn-radius: var(--radius-sm);
+  /* border: 0 below; the padding must not subtract a border it lacks. */
+  --btn-border-block: 0px;
 
   min-block-size: auto;
   padding-inline: 0;

package/src/css/components/close.css

@@ -16,8 +16,17 @@
  * Public hooks:
  * --close-size
  * --close-icon-size
+ * --close-bg
+ * --close-color
+ * --close-hover-color
+ * --close-hover-overlay
  */
 .close {
+  /* Routes the hover/active wash, as --btn-hover-overlay does for .btn. A
+     context that wants ink-only feedback (the dialog corner) sets it
+     transparent. */
+  --close-hover-overlay: var(--hover-overlay);
+
   display: inline-grid;
   place-items: center;
   flex: none;
@@ -44,12 +53,12 @@
    the control (the dialog corner's --surface-subtle) instead of replacing it. */
 @media (hover: hover) {
   .close:hover {
-    box-shadow: inset 0 0 0 999px var(--hover-overlay);
+    box-shadow: inset 0 0 0 999px var(--close-hover-overlay);
   }
 }
 
 .close:active {
-  box-shadow: inset 0 0 0 999px var(--hover-overlay);
+  box-shadow: inset 0 0 0 999px var(--close-hover-overlay);
 }
 
 .close:focus-visible {
@@ -61,23 +70,25 @@
    surface rather than to the header or a scroll container inside it. Matched
    on the documented positions (the dialog, its form, its header, or a form
    inside that header) so a .close inside content — an alert in the body —
-   keeps its own place. */
+   keeps its own place. The corner drops the wash: only the ink changes. */
 :where(dialog):is(.modal, .drawer) > .close,
 :where(dialog):is(.modal, .drawer) > :is(form, header) > .close,
 :where(dialog):is(.modal, .drawer) > :is(form, header) > :is(form, header) > .close {
+  --close-hover-overlay: transparent;
+
   position: absolute;
   z-index: 1;
   inset-block-start: var(--space-20);
   inset-inline-end: var(--space-20);
-  background: var(--surface-subtle);
-  color: var(--text-muted);
+  background: var(--close-bg, var(--surface-subtle));
+  color: var(--close-color, var(--text-muted));
 }
 
 @media (hover: hover) {
   :where(dialog):is(.modal, .drawer) > .close:hover,
   :where(dialog):is(.modal, .drawer) > :is(form, header) > .close:hover,
   :where(dialog):is(.modal, .drawer) > :is(form, header) > :is(form, header) > .close:hover {
-    color: var(--text);
+    color: var(--close-hover-color, var(--text));
   }
 }
 

package/src/css/components/flyout.css

@@ -14,6 +14,7 @@
  * Public hooks:
  * --flyout-inline-size
  * --flyout-max-inline-size
+ * --flyout-pad
  *
  * Internal:
  * --menu-item-size (derived from --control-size for menu rows)
@@ -66,7 +67,9 @@
   );
   overflow: auto;
   margin: 0;
-  padding: var(--space-10);
+  /* Tight by default for action menus, whose items carry their own padding.
+     Rich panels (forms, pickers) opt into dialog air per instance. */
+  padding: var(--flyout-pad, var(--space-10));
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius);
   background: var(--surface-raised);

package/src/css/components/meter.css

@@ -11,11 +11,14 @@
  * .sm/.lg are deliberately not supported.
  *
  * Public hooks:
+ * --meter-track
  * --meter-value
  * --bar-height
  */
 
 .meter {
+  --meter-track: var(--surface-subtle);
+
   appearance: none;
   -webkit-appearance: none;
   display: block;
@@ -24,7 +27,7 @@
   overflow: hidden;
   border: 0;
   border-radius: var(--radius-full);
-  background: var(--surface-subtle);
+  background: var(--meter-track);
 }
 
 /* A non-native meter is a weighted flex container. The element type keeps the
@@ -43,7 +46,7 @@
 }
 
 .meter:not(meter) > * + * {
-  border-inline-start: var(--border-width) solid var(--surface);
+  border-inline-start: var(--border-width) solid var(--surface-opaque);
 }
 
 .meter::-webkit-meter-bar {
@@ -51,7 +54,7 @@
   block-size: var(--bar-height);
   border: 0;
   border-radius: var(--radius-full);
-  background: var(--surface-subtle);
+  background: var(--meter-track);
 }
 
 .meter::-webkit-meter-optimum-value {