actual-css 0.3.0 → 0.3.1

package/docs/pages/layout/stack.md

@@ -15,4 +15,41 @@ Vertical flow with consistent spacing, ideal for forms, card content, and conten
 </section>
 ```
 
-Use stack for forms, card content, modal bodies, side panels, and documentation blocks.
+Use stack for forms, card content, modal bodies, side panels, and documentation blocks.
+
+Like `.cluster`, stack owns its children's block-axis spacing: direct-child
+block margins are reset, so vertical rhythm always comes from `--gap`. Inline
+margins stay free — for example `margin-inline: auto` on a child centers it
+without fighting the primitive.
+
+## Grouping items tightly
+
+Stack spacing is a `--gap` between every direct child; the primitive cannot
+tighten two specific children by itself. To group a few items into one unit
+(a title and its description), nest a `.stack gap-none`:
+
+```html demo
+<div class="stack">
+  <div class="stack gap-none">
+    <strong>Ada Meridian</strong>
+    <span class="muted">Senior designer working on design systems.</span>
+  </div>
+  <span class="badge success soft">Active</span>
+</div>
+```
+
+The outer stack keeps its rhythm between groups; the inner `gap-none` unit owns
+the tight pairing.
+
+For a one-off adjacency — pull a single child closer to its neighbour without
+adding a wrapper — the escape hatch is app CSS. `gap` and `margin-block` are
+additive, so a negative block margin on the child cancels the following gap:
+
+```css
+.stack > .profile-row {
+  margin-block-end: calc(var(--gap) * -1);
+}
+```
+
+The stack resets child block margins to zero, so this re-adds a margin on that
+one child only; the rest of the stack keeps its rhythm.

package/docs/pages/utilities/list.md

@@ -28,4 +28,5 @@ The overline exists because categories, kicker labels, and section markers recur
 
 ## CSS hooks
 
-- `--prose-measure` — the readable measure `.measure` caps at; defaults to `70ch`.
+- `--prose-measure` — the readable measure `.measure` caps at; defaults to `70ch`.
+- `--overline-radius` — the pill chip's corner radius; defaults to `--radius-full`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.3.14",
@@ -101,6 +101,7 @@
     "check:links": "bun scripts/check-doc-links.js",
     "check:templates": "bun scripts/check-templates.js",
     "shot:forced": "bun scripts/forced-colors-shot.js",
+    "shot:multi": "bun scripts/multi-shot.js",
     "shot:page": "bun scripts/page-shot.js",
     "probe": "bun scripts/probe.js",
     "check:sync": "bun scripts/check-sync.js",

package/src/css/actual.css

@@ -3,10 +3,13 @@
 @import "./theme.css";
 @import "./base.css";
 @import "./intents.css";
+/* Prose before layout: layout primitives (.stack, .cluster) reset child
+   margins and must win over .prose's flow margins at equal specificity —
+   source order is the tie-breaker, so prose loads first. */
+@import "./prose.css";
 @import "./layout.css";
 @import "./grid.css";
 @import "./variants.css";
-@import "./prose.css";
 @import "./components/index.css";
 @import "./forms/index.css";
 @import "./utilities.css";

package/src/css/components/alert.css

@@ -15,8 +15,12 @@
  * --alert-radius
  * --alert-icon-size
  * --alert-dismiss-size
+ * --alert-border-inline-start-color
+ * --alert-border-inline-start-width
  *
  * Internal:
+ * --alert-default-bg
+ * --alert-default-border
  * --alert-bg
  * --alert-fg
  * --alert-border
@@ -37,9 +41,11 @@
   --alert-pad-inline: var(--space-40);
   --alert-font-size: var(--font-size-md);
   --alert-icon-size: 1.25rem;
-  --alert-bg: var(--ui-bg, var(--surface-subtle));
+  --alert-default-bg: var(--surface-subtle);
+  --alert-default-border: var(--border);
+  --alert-bg: var(--ui-bg, var(--alert-default-bg));
   --alert-fg: var(--ui-fg, var(--intent, var(--text)));
-  --alert-border: var(--ui-border, var(--border));
+  --alert-border: var(--ui-border, var(--alert-default-border));
 
   padding-block: var(--alert-pad-block);
   padding-inline: var(--alert-pad-inline);
@@ -64,13 +70,17 @@
   margin-block-end: 0;
 }
 
-/* Alerts are soft by default. .solid and .outline need no local rules — the
-   shared variant plumbing in variants.css sets --ui-* that alert consumes. */
+/* Alerts are soft by default. The recipe writes local defaults rather than
+   --ui-* so an explicit shared treatment always wins without exclusions. */
 @supports (color: color-mix(in oklch, red, white)) {
-  .alert:where(:not(.solid, .outline, .callout)) {
+  .alert {
     /* @sync soft-recipe */
-    --ui-bg: color-mix(in oklch, var(--surface) var(--soft-bg-mix), var(--intent, var(--neutral)));
-    --ui-border: color-mix(
+    --alert-default-bg: color-mix(
+      in oklch,
+      var(--surface) var(--soft-bg-mix),
+      var(--intent, var(--neutral))
+    );
+    --alert-default-border: color-mix(
       in oklch,
       var(--surface) var(--soft-border-mix),
       var(--intent, var(--neutral))

package/src/css/components/badge.css

@@ -13,6 +13,10 @@
  * --badge-radius
  *
  * Internal:
+ * --badge-default-bg
+ * --badge-default-fg
+ * --badge-default-border
+ * --badge-default-hover-bg
  * --badge-bg
  * --badge-fg
  * --badge-border
@@ -33,9 +37,13 @@
   --badge-pad-x: 0.55em;
   --badge-font-size: 0.8125rem;
   --badge-dot-size: 0.5rem;
-  --badge-bg: var(--ui-bg, var(--surface-subtle));
-  --badge-fg: var(--ui-fg, var(--intent, var(--text)));
-  --badge-border: var(--ui-border, var(--border));
+  --badge-default-bg: var(--surface-subtle);
+  --badge-default-fg: var(--intent, var(--text));
+  --badge-default-border: var(--border);
+  --badge-default-hover-bg: var(--badge-bg);
+  --badge-bg: var(--ui-bg, var(--badge-default-bg));
+  --badge-fg: var(--ui-fg, var(--badge-default-fg));
+  --badge-border: var(--ui-border, var(--badge-default-border));
   --badge-radius: var(--radius-full);
 
   display: inline-flex;
@@ -62,18 +70,17 @@
     box-shadow var(--duration);
 }
 
-/* Soft by default — duplicated here with @sync markers for check-sync.js
-   to guard, the same way alert.css guards its own soft recipe. */
+/* Soft by default. Local defaults remain behind --ui-* in the resolution
+   chain, so explicit shared treatments compose without selector exclusions. */
 @supports (color: color-mix(in oklch, red, white)) {
-  .badge:where(:not(.solid, .outline)) {
+  .badge {
     /* @sync soft-recipe */
-    --badge-bg: color-mix(
+    --badge-default-bg: color-mix(
       in oklch,
       var(--surface) var(--soft-bg-mix),
       var(--intent, var(--neutral))
     );
-    --badge-fg: var(--intent, var(--text));
-    --badge-border: color-mix(
+    --badge-default-border: color-mix(
       in oklch,
       var(--surface) var(--soft-border-mix),
       var(--intent, var(--neutral))
@@ -119,7 +126,7 @@
 /* Hover recipes — sets --ui-hover-bg consumed by the hover rule below.
    Declared outside :hover like button.css for the same reason. */
 :is(a.badge, button.badge).outline {
-  --ui-hover-bg: var(--surface-subtle);
+  --ui-hover-bg: transparent;
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
@@ -128,7 +135,7 @@
   }
 
   :is(a.badge, button.badge):where(:not(.solid, .outline, :empty)) {
-    --ui-hover-bg: color-mix(
+    --badge-default-hover-bg: color-mix(
       in oklch,
       var(--surface) calc(var(--soft-bg-mix) - var(--soft-hover-alpha)),
       var(--intent, var(--neutral))
@@ -136,12 +143,12 @@
   }
 
   :is(a.badge, button.badge).outline {
-    --ui-hover-bg: color-mix(in oklch, var(--surface-subtle) 92%, var(--intent, var(--neutral)));
+    --ui-hover-bg: color-mix(in oklch, currentColor 10%, transparent);
   }
 }
 
 :where(a.badge, button.badge):not(:where(:disabled, [aria-disabled="true"])):hover {
-  background: var(--ui-hover-bg, var(--badge-bg));
+  background: var(--ui-hover-bg, var(--badge-default-hover-bg));
 }
 
 :where(a.badge, button.badge):not(:where(:disabled, [aria-disabled="true"], .outline)):hover {

package/src/css/components/button.css

@@ -18,11 +18,16 @@
  * --btn-focus-color
  * --btn-gap
  * --btn-hover-overlay
+ * --btn-default-bg
+ * --btn-default-fg
+ * --btn-default-border
+ * --btn-border-color
  *
  * Internal:
  * --btn-bg
  * --btn-fg
  * --btn-border
+ * --btn-default-hover-bg
  * --btn-focus-ring-color
  * --btn-border-block-end-color
  * --btn-border-block-end-width
@@ -47,6 +52,7 @@
   --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-focus-color: var(--intent, var(--focus));
   --btn-hover-overlay: var(--hover-overlay, rgb(0 0 0 / 0.08));
@@ -99,7 +105,7 @@
    fallbacks make .btn solid by default; .ghost/.link are .btn-only variants. */
 .btn.ghost {
   --ui-bg: transparent;
-  --ui-fg: var(--intent, var(--text));
+  --ui-fg: var(--intent, currentColor);
   --ui-border: transparent;
 }
 
@@ -117,12 +123,12 @@
    Declared outside :hover: the variables resolve only when the hover rule
    reads them, so the values are inert until interaction. */
 .btn:is(.outline, .ghost) {
-  --ui-hover-bg: var(--surface-subtle);
+  --ui-hover-bg: transparent;
 }
 
 @supports (color: color-mix(in oklch, red, white)) {
-  .btn:not(:where(.soft, .outline, .ghost, .link)) {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--neutral)) 88%, black);
+  .btn {
+    --btn-default-hover-bg: color-mix(in oklch, var(--btn-bg) 88%, black);
   }
 
   .btn.soft {
@@ -133,19 +139,16 @@
     );
   }
 
-  .btn.outline {
-    --ui-hover-bg: color-mix(in oklch, var(--surface-subtle) 92%, var(--intent, var(--neutral)));
-  }
-
+  .btn.outline,
   .btn.ghost {
-    --ui-hover-bg: color-mix(in oklch, var(--intent, var(--text)) 8%, transparent);
+    --ui-hover-bg: color-mix(in oklch, currentColor 10%, transparent);
   }
 }
 
 /* The .soft/.outline/.ghost hover recipe (--ui-hover-bg) is set locally above;
    the overlay darkening for solid/soft is .btn-specific. */
 .btn:not(:where(:disabled, [aria-disabled="true"])):hover {
-  background: var(--ui-hover-bg, var(--btn-bg));
+  background: var(--ui-hover-bg, var(--btn-default-hover-bg));
   box-shadow: inset 0 0 0 999px var(--btn-hover-overlay);
 }
 
@@ -155,7 +158,7 @@
 
 .btn.link {
   --ui-bg: transparent;
-  --ui-fg: var(--intent, var(--text));
+  --ui-fg: var(--intent, currentColor);
   --ui-border: transparent;
   --btn-radius: var(--radius-sm);
   --btn-border-block-end-color: transparent;
@@ -163,6 +166,8 @@
 
   min-block-size: auto;
   padding-inline: 0;
+  inline-size: fit-content;
+  max-inline-size: 100%;
   border-color: transparent;
   text-decoration: underline;
   text-underline-offset: 0.18em;
@@ -173,7 +178,6 @@
 
 .btn.link:not(:where(:disabled, [aria-disabled="true"])):hover {
   background: transparent;
-  color: var(--intent, var(--text));
   text-decoration-thickness: 0.12em;
 }
 

package/src/css/components/card.css

@@ -15,6 +15,8 @@
  * edge children inherit the card corners. .bleed must be a direct child.
  *
  * Internal:
+ * --card-bg
+ * --card-fg
  * --heading
  * --busy-overlay-bg
  */
@@ -30,11 +32,17 @@
   --card-pad: var(--space-40);
   --card-radius: var(--radius-lg);
   --card-max-inline-size: none;
+  --card-bg: var(--ui-bg, var(--surface-raised));
+  --card-fg: var(--ui-fg, var(--text));
+
+  /* Keep contextual descendants tied to the surface this card actually owns. */
+  --heading: var(--card-fg);
+  --busy-overlay-bg: var(--card-bg);
 
   max-inline-size: var(--card-max-inline-size);
   padding: var(--card-pad);
-  background: var(--ui-bg, var(--surface-raised));
-  color: var(--ui-fg, var(--text));
+  background: var(--card-bg);
+  color: var(--card-fg);
   border: var(--border-width) solid var(--ui-border, var(--border));
   border-radius: var(--card-radius);
 }

package/src/css/components/navbar.css

@@ -8,6 +8,14 @@
  * Internal:
  * --gap (local value for the shared gap token)
  */
+/* Intent boundary — inherited intents do not tint this component.
+   Local intent classes still win because :where() has zero specificity. */
+:where(.navbar) {
+  --ui-bg: initial;
+  --ui-fg: initial;
+  --ui-border: initial;
+}
+
 .navbar {
   display: flex;
   flex-wrap: wrap;
@@ -16,17 +24,17 @@
   gap: var(--gap);
   padding-block: var(--space-30);
   padding-inline: var(--space-40);
-  border: var(--border-width) solid var(--border);
+  border: var(--border-width) solid var(--ui-border, var(--border));
   border-radius: var(--radius-lg);
-  background: var(--surface-raised);
-  color: var(--text);
+  background: var(--ui-bg, var(--surface-raised));
+  color: var(--ui-fg, var(--text));
 }
 
 .navbar-brand {
   display: inline-flex;
   align-items: center;
   gap: var(--space-20);
-  color: var(--text);
+  color: var(--ui-fg, var(--text));
   font-weight: var(--font-weight-bold);
   text-decoration: none;
 }
@@ -51,7 +59,7 @@
   min-block-size: var(--control-size-sm);
   padding-inline: var(--space-20);
   border-radius: var(--radius);
-  color: var(--text-muted);
+  color: var(--ui-fg, var(--text-muted));
   font-weight: var(--font-weight-medium);
   text-decoration: none;
 }

package/src/css/components/overline.css

@@ -4,6 +4,9 @@
  * Base form is unstyled chrome that takes its surrounding color. Add .pill for
  * the bordered rounded shape, and combine with an intent class (.primary,
  * .success, etc.) to tint the text, border, and background.
+ *
+ * Public hooks:
+ * --overline-radius
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
@@ -12,7 +15,6 @@
 }
 
 .overline {
-  align-self: flex-start;
   color: var(--text-muted);
   font-size: var(--font-size-sm);
   font-weight: var(--font-weight-medium);
@@ -21,14 +23,18 @@
 }
 
 .overline.pill {
+  --overline-radius: var(--radius-full);
+
   display: inline-flex;
   align-items: center;
   gap: 0.5em;
   padding-inline: 0.6em;
   padding-block: 0.25em;
+  inline-size: fit-content;
+  max-inline-size: 100%;
   color: var(--intent, var(--text-muted));
   border: var(--border-width) solid var(--border);
-  border-radius: var(--radius-full);
+  border-radius: var(--overline-radius);
   background: var(--surface);
 }
 

package/src/css/forms/control.css

@@ -20,6 +20,8 @@
  * --control-bg
  * --control-fg
  * --control-cursor
+ * --control-border-block-end-color
+ * --control-border-block-end-width
  */
 .input,
 .textarea,

package/src/css/grid.css

@@ -5,6 +5,19 @@
  * --grid-min
  * --grid-columns
  */
+
+/* --grid-columns replaces the intrinsic auto-fit template: once set, the
+   grid no longer collapses on its own — the author owns narrow-container
+   collapse. Prefer .sidebar-layout inside .container-query for content +
+   aside layouts; reserve --grid-columns for genuinely fixed or asymmetric
+   templates. */
+
+/* Recipe:
+   - N equal cards that collapse when narrow -> .grid (auto-fit, tune
+     --grid-min) or .grid-2/3/4/6 inside .container-query
+   - content + aside -> .sidebar-layout inside .container-query
+   - fixed or asymmetric columns -> --grid-columns with an explicit collapse
+     rule of your own */
 .grid {
   display: grid;
   gap: var(--gap);

package/src/css/layout.css

@@ -13,13 +13,26 @@
  * --sidebar-layout-size
  *
  * Child contracts:
- * .stack owns vertical rhythm: direct-child margins are reset, spacing comes
- *   from --gap.
+ * .stack owns vertical rhythm: direct-child block-axis margins are reset,
+ *   spacing comes from --gap, inline margins stay free.
  * .cluster owns inline rhythm: direct-child margins are reset, spacing comes
  *   from --gap.
  * .frame sizes direct media children (img/video/iframe/canvas/svg) to fill the
  *   frame.
  */
+
+/* Responsive recipes:
+   - avatar/icon + flexible content -> .media
+   - inline items that wrap when space runs out -> .cluster (keep wrapping)
+   - content + aside -> .sidebar-layout inside .container-query
+   - row that becomes a column when constrained -> .switcher (optional module)
+
+   Anti-patterns:
+   - viewport breakpoints for ordinary composition
+   - fixed grid templates (--grid-columns) where .grid/.sidebar-layout express
+     the layout
+   - nowrap on page-level compositions; prefer wrapping and container-aware
+     primitives */
 .container-query {
   container-type: inline-size;
 }
@@ -30,8 +43,10 @@
   gap: var(--gap);
 }
 
+/* .stack owns the block axis only: block margins reset, inline margins stay
+   free (self-centering children via margin-inline: auto keep working). */
 .stack > * {
-  margin: 0;
+  margin-block: 0;
 }
 
 .cluster {

package/src/css/themes/index.css

@@ -1,4 +1,8 @@
-/* Opt-in theme bundle. Importing this file pulls in every theme below, each
+/*
+ * Reference theme presets. Shipped for inspection and copying; not public
+ * package entry points (package.json blocks ./css/themes exports).
+ *
+ * Opt-in theme bundle. Importing this file pulls in every theme below, each
  * gated by [data-theme="…"]. The light baseline is :root in src/css/theme.css —
  * there is no light.css here.
  *

package/src/css/variants.css

@@ -2,14 +2,18 @@
  * Cross-cutting variant token mapping.
  *
  * Variant scope: .solid/.soft/.outline set --ui-* for components that opt into
- * shared variants. .inverted is a surface modifier, not a variant: it also
- * paints the element directly (background/color/border-color) so it works on
- * any block, competing with component surface treatments (.card.subtle).
+ * shared variants. .inverted is a surface modifier, not a variant: it paints
+ * the element directly (background/color/border-color) so it works on any bare
+ * block, and remaps the shared --ui-* tokens so participating components
+ * (.card, .navbar, .alert, .badge) invert through their own rules. Loaded
+ * before components, so a component with its own explicit surface (e.g.
+ * .accordion) naturally keeps that surface — .inverted never forces a
+ * non-participant.
  * Component-specific defaults (.btn solid-by-default, .badge
  * soft-by-default, .alert soft-by-default) live with their components:
  *   components/button.css — .btn default solid + .btn.ghost + .btn.link
- *   components/badge.css   — .badge default soft
- *   components/alert.css   — .alert default soft (consumes --ui-* directly)
+ *   components/badge.css   — .badge default soft behind explicit --ui-*
+ *   components/alert.css   — .alert default soft behind explicit --ui-*
  *
  * .sm/.lg set shared density tokens: spacing rhythm and geometry only.
  * Density never changes typography — controls keep their font-size and
@@ -37,18 +41,23 @@
 
 .outline {
   --ui-bg: transparent;
-  --ui-fg: var(--intent, var(--text));
-  --ui-border: var(--intent, var(--border));
+  --ui-fg: var(--intent, currentColor);
+  --ui-border: var(--intent, currentColor);
 }
 
-/* Inverse surface treatment. Components (e.g. .card) compose through --ui-*;
-   the direct background/color/border-color also make .inverted useful on a
-   generic element. --heading is set so global headings (var(--heading, inherit))
-   do not inherit an outside heading color onto the dark surface. */
+/* Inverse surface treatment. Paints the element directly (so it works on any
+   bare block) and remaps the shared --ui-* tokens so opt-in components
+   (.card, .navbar) invert through their own rules. Because this loads before
+   component base surfaces, components with their own explicit surface
+   (e.g. .accordion) keep it — participation is opt-in, never forced. --heading
+   is set so global headings (var(--heading, inherit)) do not inherit an outside
+   heading color onto the dark surface; surface-owning descendants derive
+   their contextual aliases from their own local surface. */
 .inverted {
   --ui-bg: var(--surface-solid);
   --ui-fg: var(--surface);
   --ui-border: transparent;
+  --ui-hover-bg: var(--surface-solid);
 
   --heading: var(--surface);
   --busy-overlay-bg: var(--surface-solid);
@@ -84,6 +93,10 @@
     );
     /* @sync soft-recipe */
   }
+
+  .inverted {
+    --ui-hover-bg: color-mix(in oklch, var(--surface-solid) 88%, black);
+  }
 }
 
 /* Interactive hover recipes live in the components that consume them:

package/src/js/surface.js

@@ -274,7 +274,9 @@ export function retainSurface(panel) {
     released = true;
     entry.count--;
     if (entry.count <= 0) {
-      disconnectSurface(panel, { restore: false });
+      // A released retainer may leave a mounted panel whose original parent
+      // either still needs it back or has disappeared along with the trigger.
+      disconnectSurface(panel);
       surfaceRetainers.delete(panel);
     }
   };