actual-css 0.11.0 → 0.12.0

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

@@ -21,6 +21,44 @@ 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>` and compose its row in markup
+(`<footer class="cluster justify-content-end">`); the modal and drawer footers
+have no layout of their own.
+
+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. A confirmation is composition, not a
+variant: a `.media` row with a leading `.dialog-icon` and the text column (its
+first heading centers on the icon, following copy stays in that column), then a
+`<footer class="bleed background-subtle cluster justify-content-space-between">` action
+band with the cancel-style action first. For a trailing icon, use the wrapper'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,30 @@ 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",
+    "actual-css contrast [--theme FILE] [--name NAME]",
     "",
-    "  -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 read 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 --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",
+    "--surface and --surface-solid, the invalid-field focus line, and the inverse",
+    "text. Exits 1 when a pair misses its threshold. Needs Bun (bunx --bun actual-css",
+    "contrast ...).",
   ].join("\n");
 }
 
@@ -36,6 +50,10 @@ function parseArgs(argv) {
     return { version: true };
   }
 
+  if (command === "design" || command === "contrast") {
+    return parseThemeArgs(command, rest);
+  }
+
   if (command !== "bundle") {
     throw new Error(`Unknown command: ${command}`);
   }
@@ -87,7 +105,57 @@ 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 parseThemeArgs(command, rest) {
+  const options = { help: false, command, themeFile: null, name: null, out: "" };
+  const valued = { "--theme": "themeFile", "--name": "name" };
+  if (command === "design") Object.assign(valued, { "--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 (command === "design" && !options.out) throw new Error("Missing required --out DIR option.");
+  return options;
+}
+
+/* Checked before the tooling import: under Node those modules do not even
+   parse (`await using`), and `bundle` must stay usable there. The shebang is
+   Node for that reason, so plain `bunx` honors it and lands here: --bun is
+   what makes Bun run the script. */
+function requireBun(command) {
+  if (typeof Bun === "undefined") {
+    throw new Error(
+      `actual-css ${command} needs Bun: it reads the theme in headless Chrome through Bun.WebView. Run it with bunx --bun actual-css ${command} ...`,
+    );
+  }
+}
+
+async function design({ themeFile, name, out }) {
+  requireBun("design");
+  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 contrast({ themeFile, name }) {
+  requireBun("contrast");
+  const { formatContrast, measureThemeFile } = await import("../tooling/theme-contrast.js");
+  const { text, misses } = formatContrast(await measureThemeFile({ themeFile, name }));
+  console.log(text);
+  if (misses > 0) {
+    console.error(`\n${misses} pair${misses === 1 ? "" : "s"} under threshold.`);
+    process.exitCode = 1;
+  }
 }
 
 async function bundle({ input, out, minify }) {
@@ -124,7 +192,8 @@ async function main() {
     return;
   }
 
-  await bundle(args);
+  const commands = { bundle, contrast, design };
+  await commands[args.command](args);
 }
 
 main().catch((error) => {

package/src/css/components/avatar.css

@@ -198,19 +198,26 @@ a.avatar[aria-disabled="true"] {
   --avatar-stack-font-size: var(--font-size-lg);
 }
 
-@supports selector(:has(> .avatar)) {
-  .avatar-stack:has(> .avatar.sm) {
-    --avatar-stack-size: 1.75rem;
-    --avatar-stack-font-size: var(--font-size-xs);
-  }
+/* Infer the stack scale from its avatars. Progressive: without :has() the
+   explicit .avatar-stack.sm/.lg classes and the default size still size the
+   group, only the inference is lost. */
+.avatar-stack:has(> .avatar.sm) {
+  --avatar-stack-size: 1.75rem;
+  --avatar-stack-font-size: var(--font-size-xs);
+}
 
-  .avatar-stack:has(> .avatar.lg) {
-    --avatar-stack-size: 3rem;
-    --avatar-stack-font-size: var(--font-size-lg);
-  }
+.avatar-stack:has(> .avatar.lg) {
+  --avatar-stack-size: 3rem;
+  --avatar-stack-font-size: var(--font-size-lg);
 }
 
+/* Overlapping avatars hide their neighbour: a translucent fill (--surface-subtle
+   on a glass palette) would show the next avatar's edge through it, most of all
+   when hover raises one above the other. The fill is layered over the opaque
+   role; on an opaque fill the base never shows. */
 .avatar-stack > .avatar {
+  background-color: var(--surface-opaque);
+  background-image: linear-gradient(var(--avatar-bg), var(--avatar-bg));
   box-shadow: 0 0 0 var(--avatar-stack-ring) var(--surface-opaque);
 }
 

package/src/css/components/badge.css

@@ -169,10 +169,6 @@
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  :is(a.badge, button.badge):is(.solid, :empty) {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
-  }
-
   :is(a.badge, button.badge):where(:not(.solid, .outline, :empty)) {
     --badge-default-hover-bg: color-mix(
       in oklab,
@@ -199,7 +195,7 @@
   :where(:disabled, [aria-disabled="true"])
 ):hover {
   /* Huge inset spread paints the overlay over the pill radius (see button.css). */
-  box-shadow: inset 0 0 0 999px var(--hover-overlay);
+  box-shadow: inset 0 0 0 999px var(--hover-overlay-solid, var(--hover-overlay));
 }
 
 button.badge {

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

@@ -28,9 +28,9 @@
  * --btn-bg
  * --btn-fg
  * --btn-border
- * --btn-default-hover-bg
  * --btn-border-block-end-color
  * --btn-border-block-end-width
+ * --btn-border-block
  * --spinner-width
  */
 
@@ -53,9 +53,12 @@
   --btn-bg: var(--ui-bg, var(--btn-default-bg, var(--intent, var(--neutral))));
   --btn-fg: var(--ui-fg, var(--btn-default-fg, var(--intent-fg, var(--neutral-fg))));
   --btn-border: var(--ui-border, var(--btn-default-border, transparent));
-  --btn-default-hover-bg: var(--btn-bg);
   --btn-radius: var(--radius);
-  --btn-hover-overlay: var(--hover-overlay, rgb(0 0 0 / 0.08));
+  --btn-hover-overlay: var(--hover-overlay-solid, var(--hover-overlay));
+  --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 +68,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(
@@ -125,10 +134,6 @@
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  .btn {
-    --btn-default-hover-bg: color-mix(in oklch, var(--btn-bg) 88%, black);
-  }
-
   .btn.soft {
     --ui-hover-bg: color-mix(
       in oklab,
@@ -144,9 +149,9 @@
 }
 
 /* The .soft/.outline/.ghost hover recipe (--ui-hover-bg) is set locally above;
-   the overlay darkening for solid/soft is .btn-specific. */
+   the overlay darkening for solid is .btn-specific. */
 .btn:not(:where(:disabled, [aria-disabled="true"])):hover {
-  background: var(--ui-hover-bg, var(--btn-default-hover-bg));
+  background: var(--ui-hover-bg, var(--btn-bg));
   /* Huge inset spread paints the overlay over any border-radius without a
      pseudo-element; a plain background would replace the fill instead of
      darkening it. */
@@ -162,6 +167,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/card.css

@@ -4,11 +4,11 @@
  * Docs: docs/pages/components/card.md
  *
  * Surface, border, radius, padding, density, and elevation stay local here.
- * Direct header/footer children are structural slots; a direct footer is
- * anchored to the card's bottom edge when extra block space is available (so
- * price/action rows align across equal-height cards in a grid). A bare card
- * owns its direct-child rhythm; a layout primitive on the same element takes
- * over that layout. Page layout remains the job of markup and layout
+ * Direct header/footer children are structural slots with a default split row;
+ * a direct footer is anchored to the card's bottom edge when extra block space
+ * is available (so price/action rows align across equal-height cards in a
+ * grid). A bare card owns its direct-child rhythm and its slot rows; a layout
+ * primitive on the card or on a slot takes over that layout. Page layout remains the job of markup and layout
  * primitives outside the card.
  *
  * Public hooks:
@@ -46,6 +46,9 @@
 
 .card {
   --card-pad: var(--space-40);
+  /* Local anatomy, like the padding. Never var(--gap): that token is
+     inherited, so the --gap of a parent grid became the rhythm inside every
+     card (+79px per card on a 38px grid). */
   --card-gap: var(--space-30);
   --card-radius: var(--radius-lg);
   --card-max-inline-size: none;
@@ -87,7 +90,11 @@
   margin-block: 0;
 }
 
-.card > :where(header, footer) {
+/* The slot row is a convenience default, not anatomy: like the root box it
+   lives at zero specificity, so a primitive, role or utility on the slot
+   (.cluster, .media, .form-actions, .justify-content-*) replaces it instead of
+   losing to components/ on source order. */
+:where(.card > header, .card > footer) {
   display: flex;
   flex-wrap: wrap;
   align-items: var(--items-align, center);
@@ -96,15 +103,15 @@
   min-inline-size: 0;
 }
 
+:where(.card > header) {
+  align-items: var(--items-align, flex-start);
+}
+
 .card > :where(header, footer) > * {
   min-inline-size: 0;
   margin-block: 0;
 }
 
-.card > header {
-  align-items: var(--items-align, flex-start);
-}
-
 /* A direct footer is pinned to the bottom when the card has free space.
    Specificity beats .stack > * so a .card.stack keeps this contract. */
 .card > footer {
@@ -119,6 +126,7 @@
 }
 .card.compact {
   --card-pad: var(--space-20);
+  --card-gap: var(--space-20);
 }
 
 @media print {

package/src/css/components/chat.css

@@ -94,9 +94,8 @@
 }
 
 /* Remove the reserved avatar gutter when a message has no avatar. This is a
-   cosmetic enhancement; the two-column baseline remains fully readable. */
-@supports selector(:has(*)) {
-  .chat:not(:has(> .chat-avatar)) {
-    column-gap: 0;
-  }
+   cosmetic enhancement; the two-column baseline remains fully readable, and a
+   browser without :has() drops only this rule. */
+.chat:not(:has(> .chat-avatar)) {
+  column-gap: 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/drawer.css

@@ -22,6 +22,7 @@
  * Internal:
  * --drawer-closed-translate (side/RTL positioning state)
  * --drawer-focus-bleed
+ * --drawer-close-reserve (header room for a corner close; zero without a close)
  * --drawer-motion-duration (shared by panel and ::backdrop so exit duration
  *   changes in one place; entry state redefines it longer)
  */
@@ -31,6 +32,10 @@
   /* The inset a direct .bleed child cancels (components/bleed.css). */
   --surface-pad: var(--drawer-pad);
   --drawer-closed-translate: -100%;
+  /* Header room for a corner close. Unconditional baseline: without :has()
+     (Degraded tier) a header keeps too much room rather than a title running
+     under the close. Zeroed when the drawer has no close. */
+  --drawer-close-reserve: calc(var(--close-size, var(--control-size)) + var(--space-30));
   /* Exit is shorter than entry so the panel clears quickly; the scrim reads
      the same variable through inheritance and never lags the panel. */
   --drawer-motion-duration: var(--duration);
@@ -210,9 +215,20 @@
   }
 }
 
+/* No close anywhere: reclaim the reserve. Deliberately coarse — a close in
+   the body keeps the reserve, which costs only room, never overlap. */
+:where(dialog).drawer:not(:has(.close)) {
+  --drawer-close-reserve: 0px;
+}
+
 /* The header reserves inline room so the title never runs under the close
-   control. */
+   control. A .bleed header keeps at least its band inset. */
 :where(dialog).drawer > header,
-:where(dialog).drawer > form > header {
-  padding-inline-end: calc(var(--close-size, var(--control-size)) + var(--space-30));
+:where(dialog).drawer > :where(form) > header {
+  padding-inline-end: var(--drawer-close-reserve);
+}
+
+:where(dialog).drawer > header:where(.bleed),
+:where(dialog).drawer > :where(form) > header:where(.bleed) {
+  padding-inline-end: max(var(--bleed-pad, 0px), var(--drawer-close-reserve));
 }

package/src/css/components/flyout.css

@@ -50,6 +50,9 @@
   position: absolute;
   inset-block-start: calc(100% + var(--space-10));
   inset-inline-start: 0;
+  /* Anatomy, not a default to replace: `flyout grid-3` (mega menu) takes its
+     columns from the grid preset and keeps this tight gap, because each
+     section pads itself — the visible gutter is section padding + gap. */
   display: grid;
   gap: var(--space-10);
   inline-size: var(--flyout-inline-size, max-content);

package/src/css/components/index.css

@@ -3,7 +3,6 @@
 @import "./close.css";
 @import "./badge.css";
 @import "./alert.css";
-@import "./actions.css";
 
 /* Surfaces */
 @import "./card.css";

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
@@ -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 {