actual-css 0.9.2 → 0.10.0

package/skills/actual-css/references/review-checklist.md

@@ -0,0 +1,51 @@
+# Consumer review checklist
+
+## Vocabulary and imports
+
+- Every framework-looking class exists in the installed Actual CSS version.
+- Intent/variant composition is used instead of invented compound names.
+- Runtime `is-*` state is not authored as application API.
+- The project imports the family/module that owns the markup it uses.
+- `forms` vs `forms/all` is intentional.
+- JS imports match the behavior actually enabled.
+
+## CSS ownership
+
+- Application CSS is not recreating an existing layout/component/focus behavior unnecessarily.
+- Public hooks were considered before replacement CSS.
+- Palette values remain centralized in theme/token definitions.
+- `--gap` is only rebound when inherited rhythm should change.
+- Component-scoped hooks are not read elsewhere without an intentional fallback.
+
+## Layout
+
+- Primitive choice follows child relationships, not a single mockup's item count.
+- `.app-layout` is used only for its actual shell contract.
+- Exact track needs use the appropriate grid hook before a new generic primitive is invented.
+
+## Forms
+
+- `inputmode` is not treated as validation/filtering.
+- `data-filter` is used only when destructive rewriting is intended.
+- Masks are not mistaken for semantic validity.
+- Server/application validation remains authoritative for domain rules.
+- Help/errors and invalid state are connected accessibly.
+
+## Enhancements
+
+- Presentation, semantics, behavior opt-in, and configuration remain separate.
+- Enhancement tokens and feature attributes are documented by the installed version.
+- Application code does not fight Actual for Popover or positioning ownership.
+- Interactive floating content is not placed in a tooltip.
+
+## Accessibility
+
+- Keyboard focus remains visible.
+- Icon-only controls are named.
+- Disabled/current/selected/expanded semantics match visible state.
+- Keyboard behavior matches claimed ARIA roles.
+- Custom states consider forced colors and reduced motion where relevant.
+
+## Version safety
+
+When uncertain, inspect the installed manifests, package exports, source, and docs instead of extrapolating from this starter skill.

package/skills/actual-css/scripts/inspect-actual-css.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function exists(file) {
+  try {
+    return fs.existsSync(file);
+  } catch {
+    return false;
+  }
+}
+
+function detectRoot(start = process.cwd()) {
+  const explicit = process.env.ACTUAL_CSS_ROOT;
+  if (explicit) {
+    const root = path.resolve(explicit);
+    if (!exists(path.join(root, "package.json"))) {
+      throw new Error(`ACTUAL_CSS_ROOT does not contain package.json: ${root}`);
+    }
+    return root;
+  }
+
+  let dir = path.resolve(start);
+  while (true) {
+    const localPkg = path.join(dir, "package.json");
+    if (exists(localPkg)) {
+      try {
+        const pkg = readJson(localPkg);
+        if (pkg.name === "actual-css" && exists(path.join(dir, "components.json"))) {
+          return dir;
+        }
+      } catch {
+        // Ignore malformed unrelated package.json files while walking.
+      }
+    }
+
+    const installed = path.join(dir, "node_modules", "actual-css");
+    if (exists(path.join(installed, "package.json"))) {
+      return installed;
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function usage() {
+  process.stdout.write(`Actual CSS inspector\n\n`);
+  process.stdout.write(`Usage:\n`);
+  process.stdout.write(`  inspect-actual-css.mjs --source\n`);
+  process.stdout.write(`  inspect-actual-css.mjs <component>\n`);
+  process.stdout.write(`  inspect-actual-css.mjs --class <class>\n`);
+  process.stdout.write(`  inspect-actual-css.mjs --exports\n`);
+  process.stdout.write(`  inspect-actual-css.mjs --enhancements\n`);
+  process.stdout.write(`  inspect-actual-css.mjs --list\n\n`);
+  process.stdout.write(`Set ACTUAL_CSS_ROOT to inspect a specific checkout/package.\n`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+const root = detectRoot();
+if (!root) {
+  fail("Could not find Actual CSS. Run inside its repository/a consuming project or set ACTUAL_CSS_ROOT.");
+  process.exit(1);
+}
+
+const pkg = readJson(path.join(root, "package.json"));
+const componentsPath = path.join(root, "components.json");
+const reservedPath = path.join(root, "reserved-classes.json");
+const components = exists(componentsPath) ? readJson(componentsPath) : [];
+const reservedRaw = exists(reservedPath) ? readJson(reservedPath) : [];
+const reserved = Array.isArray(reservedRaw)
+  ? reservedRaw
+  : Array.isArray(reservedRaw.classes)
+    ? reservedRaw.classes
+    : Object.keys(reservedRaw);
+
+if (args.length === 0 || args[0] === "--list") {
+  print({
+    version: pkg.version,
+    root,
+    components: components.map((item) => item.name),
+  });
+  process.exit(0);
+}
+
+if (args[0] === "--source") {
+  print({
+    name: pkg.name,
+    version: pkg.version,
+    root,
+    packageJson: path.join(root, "package.json"),
+    componentsJson: exists(componentsPath) ? componentsPath : null,
+    reservedClassesJson: exists(reservedPath) ? reservedPath : null,
+  });
+  process.exit(0);
+}
+
+if (args[0] === "--exports") {
+  print({ version: pkg.version, exports: pkg.exports ?? {} });
+  process.exit(0);
+}
+
+if (args[0] === "--enhancements") {
+  const matches = components
+    .filter((item) => item.jsImport || (item.enhancements && item.enhancements.length))
+    .map((item) => ({
+      name: item.name,
+      jsImport: item.jsImport ?? null,
+      enhancements: item.enhancements ?? [],
+      states: item.states ?? [],
+    }));
+  print({ version: pkg.version, components: matches });
+  process.exit(0);
+}
+
+if (args[0] === "--class") {
+  const className = (args[1] ?? "").replace(/^\./, "");
+  if (!className) {
+    fail("--class requires a class name");
+    process.exit(1);
+  }
+  const owners = components
+    .filter((item) => (item.classes ?? []).includes(className))
+    .map((item) => item.name);
+  print({
+    version: pkg.version,
+    class: className,
+    reserved: reserved.includes(className),
+    owners,
+  });
+  process.exit(0);
+}
+
+const name = args[0];
+const exact = components.find((item) => item.name === name);
+if (exact) {
+  print({ version: pkg.version, component: exact });
+  process.exit(0);
+}
+
+const byClass = components.filter((item) => (item.classes ?? []).includes(name));
+if (byClass.length) {
+  print({ version: pkg.version, query: name, matchedByClass: byClass });
+  process.exit(0);
+}
+
+fail(`No component or owned class matched: ${name}`);
+process.exit(1);

package/src/css/components/accordion.css

@@ -15,11 +15,15 @@
  *
  * Public hooks:
  * --accordion-radius
+ * --accordion-pad
  * --accordion-marker-color
+ * --accordion-marker-size
  */
 .accordion {
   --accordion-radius: var(--radius);
+  --accordion-pad: var(--space-40);
   --accordion-marker-color: var(--text-muted);
+  --accordion-marker-size: 1rem;
 
   border: var(--border-width) solid var(--border);
   border-radius: var(--accordion-radius);
@@ -36,7 +40,7 @@
   gap: var(--space-30);
   cursor: pointer;
   list-style: none;
-  padding: var(--space-40);
+  padding: var(--accordion-pad);
   color: var(--text);
   font-weight: var(--font-weight-medium);
 }
@@ -52,12 +56,17 @@
   display: none;
 }
 
+/* The marker is the chevron itself: the box is filled with
+   --accordion-marker-color and then clipped to the glyph by the mask. Anything
+   painted on this pseudo-element — a background, a ring, a shadow — is clipped
+   with it, so a decorated marker (a chevron in a pill) needs a real element;
+   see the accordion docs for the opt-out. */
 .accordion summary::after {
   content: "";
   flex: 0 0 auto;
   margin-inline-start: auto;
-  inline-size: 1rem;
-  block-size: 1rem;
+  inline-size: var(--accordion-marker-size);
+  block-size: var(--accordion-marker-size);
   background-color: var(--accordion-marker-color);
   -webkit-mask: var(--icon-chevron) center / contain no-repeat;
   mask: var(--icon-chevron) center / contain no-repeat;
@@ -68,9 +77,14 @@
   transform: rotate(180deg);
 }
 
+/* The panel, not the item, owns the inset here — .separated paints a card on
+   <details> but leaves it unpadded — so the panel is what a .bleed child
+   escapes (components/bleed.css). */
 .accordion details > summary + * {
-  padding-block: 0 var(--space-40);
-  padding-inline: var(--space-40);
+  --surface-pad: var(--accordion-pad);
+
+  padding-block: 0 var(--accordion-pad);
+  padding-inline: var(--accordion-pad);
   color: var(--text-muted);
   margin-block: 0;
 }
@@ -79,6 +93,9 @@
   padding-block-start: var(--space-10);
 }
 
+/* Also cancels the lift of a first .bleed child (bleed.css, lower
+   specificity): the panel's top edge is the summary, not the item edge, so a
+   bleed reaches only the sides and the bottom. */
 .accordion details > summary + * > :first-child {
   margin-block-start: 0;
 }
@@ -103,6 +120,12 @@
   padding-inline: 0;
 }
 
+/* Flush already sits at the embedding surface's edge, so there is no inline
+   inset left for a .bleed child to cancel. */
+.accordion.flush details > summary + * {
+  --surface-pad: 0px;
+}
+
 /* Separated — each item owns a full card. The item's own border beats the
    shared details + details separator on specificity alone, so nothing needs
    undoing for the second item onwards. */
@@ -119,8 +142,22 @@
   background: var(--surface-raised);
 }
 
+/* A last .bleed child inherits its bottom corners from the panel, but the
+   rounded box is the item (.separated) or the group (last item) — relay the
+   radius to the panel. Explicit rather than inherit: in browsers with
+   ::details-content the panel's flat-tree parent is that slot, not
+   <details>. */
+.accordion.separated > details > summary + *,
+.accordion:not(.flush) > details:last-child > summary + * {
+  border-end-start-radius: var(--accordion-radius);
+  border-end-end-radius: var(--accordion-radius);
+}
+
 @media (forced-colors: active) {
-  .accordion {
-    --accordion-marker-color: CanvasText;
+  /* Written on the property, not the hook: an application hook override at
+    the same specificity loads after this file and would win the variable,
+    leaving a Canvas-remapped fill. The property keeps CanvasText. */
+  .accordion summary::after {
+    background-color: CanvasText;
   }
 }

package/src/css/components/alert.css

@@ -16,7 +16,6 @@
  * --alert-font-size
  * --alert-radius
  * --alert-icon-size
- * --alert-dismiss-size
  * --alert-border-inline-start-color
  * --alert-border-inline-start-width
  *
@@ -27,7 +26,6 @@
  * --alert-bg
  * --alert-fg
  * --alert-border
- * --alert-dismiss-icon-size
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
@@ -76,13 +74,13 @@
    The slots are excluded because they are anatomy, not content: an
    admonition's title bar has to stay flush against its body. The list follows
    the anatomy, so it grows with it. */
-.alert > :not(:where(.alert-icon, .alert-dismiss, .alert-title, .alert-body)) {
+.alert > :not(:where(.alert-icon, .close, .alert-title, .alert-body)) {
   margin-block: 0;
 }
 
 .alert
-  > :not(:where(.alert-icon, .alert-dismiss, .alert-title, .alert-body))
-  + :not(:where(.alert-icon, .alert-dismiss, .alert-title, .alert-body)) {
+  > :not(:where(.alert-icon, .close, .alert-title, .alert-body))
+  + :not(:where(.alert-icon, .close, .alert-title, .alert-body)) {
   margin-block-start: var(--space-10);
 }
 
@@ -120,42 +118,24 @@
   vertical-align: -0.125em;
 }
 
-/* Dismiss — compact close button for inline alerts. Transparent at rest with
-   a reduced opacity glyph so it stays secondary inside an already-colored
-   alert; hover reinforces it via the shared overlay. Uses the shared
-   --icon-close mask, so no icon font or text glyph is required in the markup.
-   Standard alerts place it as a direct trailing child; admonitions place it
-   inside .alert-title (see below). */
-.alert-dismiss {
-  --alert-dismiss-size: 1.75rem;
-  --alert-dismiss-icon-size: 0.875rem;
-
-  display: inline-grid;
-  place-items: center;
-  inline-size: var(--alert-dismiss-size);
-  block-size: var(--alert-dismiss-size);
-  flex: none;
-  padding: 0;
-  border: 0;
-  border-radius: var(--radius);
-  background: transparent;
-  color: currentColor;
-  opacity: 0.65;
-  cursor: pointer;
+/* Close (components/close.css) — compact, and at reduced opacity so it stays
+   secondary inside an already-colored alert. Standard alerts place it as a
+   direct trailing child; admonitions place it inside .alert-title (see
+   below). The sizes are declared on the alert so an author can still set
+   them on the alert or on the button. */
+.alert {
+  --close-size: 1.75rem;
+  --close-icon-size: 0.875rem;
 }
 
-.alert-dismiss::before {
-  content: "";
-  inline-size: var(--alert-dismiss-icon-size);
-  block-size: var(--alert-dismiss-icon-size);
-  background: currentColor;
-  -webkit-mask: var(--icon-close) center / contain no-repeat;
-  mask: var(--icon-close) center / contain no-repeat;
+.alert > .close,
+.alert > .alert-title > .close {
+  opacity: 0.65;
 }
 
 @media (hover: hover) {
-  .alert-dismiss:hover {
-    background: var(--hover-overlay);
+  .alert > .close:hover,
+  .alert > .alert-title > .close:hover {
     opacity: 1;
   }
 }
@@ -164,7 +144,7 @@
    both. Icon and dismiss are pinned to the outer columns; anything else (the
    message content) flows into the remaining text column. */
 @supports selector(.alert:has(> *)) {
-  .alert:has(> .alert-icon, > .alert-dismiss) {
+  .alert:has(> .alert-icon, > .close) {
     display: grid;
     grid-template-columns: minmax(0, 1fr);
     align-items: var(--items-align, start);
@@ -183,19 +163,19 @@
     margin-block-start: 0.125em;
   }
 
-  .alert:has(> .alert-icon) > :not(.alert-icon, .alert-dismiss) {
+  .alert:has(> .alert-icon) > :not(.alert-icon, .close) {
     grid-column: 2;
   }
 
-  .alert:has(> .alert-dismiss) {
+  .alert:has(> .close) {
     grid-template-columns: minmax(0, 1fr) auto;
   }
 
-  .alert:has(> .alert-icon):has(> .alert-dismiss) {
+  .alert:has(> .alert-icon):has(> .close) {
     grid-template-columns: auto minmax(0, 1fr) auto;
   }
 
-  .alert:has(> .alert-dismiss) > .alert-dismiss {
+  .alert:has(> .close) > .close {
     grid-column: -2 / -1;
     grid-row: 1;
   }
@@ -243,8 +223,8 @@
   border-start-end-radius: calc(var(--alert-radius, var(--radius-lg)) - var(--border-width));
 }
 
-/* Dismiss inside an admonition title bar rides the inline end. */
-.alert.admonition > .alert-title > .alert-dismiss {
+/* Close inside an admonition title bar rides the inline end. */
+.alert.admonition > .alert-title > .close {
   margin-inline-start: auto;
 }
 

package/src/css/components/app-nav.css

@@ -70,6 +70,15 @@
   color: var(--text);
 }
 
+/* Same contextual hover as .nav-link (navbar.css): a tint of the tile's ink
+   reads on any --ui-* bar; the baseline keeps a legible light chip. */
+@supports (color: color-mix(in oklch, red, white)) {
+  .app-nav > a:hover {
+    background: color-mix(in oklch, currentColor 10%, transparent);
+    color: var(--ui-fg, var(--text));
+  }
+}
+
 /* Current tile is already a full selected surface. Selection never changes
    text metrics: the shared medium weight is kept, no permanent indicator is
    added here. */

package/src/css/components/badge.css

@@ -14,7 +14,6 @@
  * --badge-icon-size
  * --badge-dot-size
  * --badge-radius
- * --badge-dismiss-icon-size
  *
  * Internal:
  * --badge-default-bg
@@ -45,7 +44,10 @@
   --badge-font-size: var(--font-size-sm);
   --badge-icon-size: 1em;
   --badge-dot-size: 0.5rem;
-  --badge-dismiss-icon-size: 0.875em;
+  /* Declared on the badge, not the button, so an author can still set them
+     on either. Same element as --badge-size, so .sm/.lg carry through. */
+  --close-size: max(var(--badge-size), 24px);
+  --close-icon-size: 0.875em;
   --badge-default-bg: var(--surface-subtle);
   --badge-default-fg: var(--intent, var(--text));
   --badge-default-border: var(--border);
@@ -95,8 +97,8 @@
   --badge-dot-size: 0.625rem;
 }
 
-/* Decorative children follow the badge's optical size. Text and interactive
-   dismiss buttons retain their own boxes. */
+/* Decorative children follow the badge's optical size. Text and the .close
+   button retain their own boxes. */
 .badge > :where(svg, img, [aria-hidden="true"]:not(.dot)) {
   flex: none;
   /* The shared rule maps --badge-icon-size onto font-size. One em is therefore
@@ -149,45 +151,15 @@
   background-color: currentColor;
 }
 
-.badge > button {
-  display: inline-grid;
-  place-items: center;
-  flex: 0 0 auto;
-  /* WCAG 2.5.8 floors pointer targets at 24 CSS px. Density and local size may
-     keep the badge visually compact through the negative margins, but never
-     shrink its action target below that literal floor. */
-  min-inline-size: max(var(--badge-size), 24px);
-  min-block-size: max(var(--badge-size), 24px);
+/* Removable tag — a .close (components/close.css) inside the pill. WCAG 2.5.8
+   floors pointer targets at 24 CSS px: density and local size may keep the
+   badge visually compact through the negative margins, but never shrink the
+   target below that literal floor. */
+.badge > .close {
   margin-block: -0.25rem;
   margin-inline-start: -0.15em;
   margin-inline-end: -0.45em;
-  padding: 0.25rem;
-  border: 0;
   border-radius: var(--radius-full);
-  background: transparent;
-  color: inherit;
-  font: inherit;
-  line-height: 1;
-  cursor: pointer;
-}
-
-/* Dismiss mark — an empty dismiss button paints its own X from the shared
-   --icon-close mask, so no icon font or text glyph is required in the markup
-   (same contract as .alert-dismiss and .dialog-close). A mask box is a block
-   box, so place-items centers the ink itself; a text glyph would only center
-   its line box and land the ink low, because a lowercase x has no descender
-   and only x-height of ascent. A button with its own content keeps it. */
-.badge > button:empty::before {
-  content: "";
-  inline-size: var(--badge-dismiss-icon-size);
-  block-size: var(--badge-dismiss-icon-size);
-  background: currentColor;
-  -webkit-mask: var(--icon-close) center / contain no-repeat;
-  mask: var(--icon-close) center / contain no-repeat;
-}
-
-.badge > button:not(:disabled):hover {
-  background: var(--hover-overlay);
 }
 
 /* Hover recipes — sets --ui-hover-bg consumed by the hover rule below.

package/src/css/components/bleed.css

@@ -0,0 +1,79 @@
+/*
+ * Full-bleed children — the shared escape hatch for a padded surface.
+ *
+ * Docs: docs/pages/components/bleed.md
+ *
+ * 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.
+ *
+ * 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
+ * grandchild, which sits at its wrapper's edge rather than the surface's and
+ * would pull a negative margin out of the wrong box. Relaying it one level and
+ * clearing it below keeps the child combinator's guarantee while leaving the
+ * .bleed rules themselves free of the surface list.
+ *
+ * Why the clearing rule comes first: both rules are zero-specificity, so
+ * source order decides where they overlap, and they overlap on exactly one
+ * element — a direct child of a surface nested inside another surface. That
+ * child must keep the inner surface's inset, so the relay has to win.
+ *
+ * Public hooks:
+ * --bleed-pad (read-only: the inset relayed to a surface's direct children;
+ *   pad a band that is not a header/footer/figure with it)
+ *
+ * Framework plumbing:
+ * --surface-pad (declared by the surface)
+ */
+:where(.card, .drawer, .accordion details > summary + *) > * * {
+  --bleed-pad: initial;
+}
+
+:where(.card, .drawer, .accordion details > summary + *) > * {
+  --bleed-pad: var(--surface-pad);
+}
+
+/* Inert without a surface: the fallback resolves the negative margin to zero
+   rather than dropping the declaration and inheriting a stray inset. */
+.bleed {
+  margin-inline: calc(var(--bleed-pad, 0px) * -1);
+  max-inline-size: none;
+}
+
+.bleed:first-child {
+  margin-block-start: calc(var(--bleed-pad, 0px) * -1);
+  border-start-start-radius: inherit;
+  border-start-end-radius: inherit;
+}
+
+.bleed:last-child {
+  margin-block-end: calc(var(--bleed-pad, 0px) * -1);
+  border-end-start-radius: inherit;
+  border-end-end-radius: inherit;
+}
+
+/* Media bleed */
+:where(img, picture, video, canvas, svg).bleed {
+  display: block;
+  inline-size: calc(100% + var(--bleed-pad, 0px) * 2);
+  max-inline-size: none;
+}
+
+picture.bleed {
+  overflow: hidden;
+}
+
+picture.bleed > img {
+  display: block;
+  inline-size: 100%;
+  block-size: auto;
+}
+
+/* Padded structural bleed — the band keeps the surface's own rhythm while its
+   background reaches the edge. */
+:where(header, footer, figure).bleed {
+  padding: var(--bleed-pad, 0px);
+}