actual-css 0.10.0 → 0.11.0

package/src/css/components/status-bar.css

@@ -33,8 +33,8 @@
 }
 
 .status-bar {
-  --status-bg: var(--intent, var(--text));
-  --status-fg: var(--intent-fg, var(--surface));
+  --status-bg: var(--intent, var(--surface-solid));
+  --status-fg: var(--intent-fg, var(--surface-solid-fg));
 
   position: fixed;
   /* Fixed positioning tracks the layout viewport, which the mobile software

package/src/css/components/steps.css

@@ -58,7 +58,7 @@
   --step-size: 1.75rem;
   --step-inline-gap: var(--space-20);
   --step-line-size: var(--border-width);
-  --step-marker-bg: var(--surface);
+  --step-marker-bg: var(--surface-opaque);
   --step-marker-border: var(--border);
   --step-marker-fg: var(--text-muted);
   --step-marker-radius: var(--radius-full);
@@ -138,7 +138,7 @@
    connector leaving current goes back to neutral. Declared after
    .step-complete at equal specificity: current wins on every channel. */
 .steps > [aria-current="step"] {
-  --step-marker-bg: var(--surface);
+  --step-marker-bg: var(--surface-opaque);
   --step-marker-border: var(--state-selected);
   --step-marker-fg: var(--state-selected);
   --step-line: var(--border);
@@ -177,7 +177,7 @@
    focus ring's own width and offset. Only this composition scrolls, and only a
    link has a ring to protect. */
 .steps-horizontal:has(a[href]) {
-  padding-block: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+  padding-block: calc(var(--focus-outline-offset) + var(--focus-ring-width));
 }
 
 /* One explicit row, the marker's: a `.step-label` is auto-placed into an

package/src/css/components/tab.css

@@ -76,10 +76,10 @@
 }
 
 /* The ring is square on the edge the tab is attached to, so it reads as part
-   of the strip rather than a floating chip. */
+   of the strip rather than a floating chip. Color and width follow the
+   component ring contract (focus.css); only the geometry is tab-specific. */
 .tab:focus-visible {
-  outline: var(--focus-outline);
-  outline-color: var(--focus);
+  outline: var(--focus-ring-width) solid var(--focus);
   outline-offset: -2px;
   border-radius: var(--radius-sm) var(--radius-sm) 0 0;
 }

package/src/css/components/table.css

@@ -6,6 +6,12 @@
  * .table-wrap provides the scroll container and outer chrome; .table owns row
  * and cell rules. Tokens are sourced from the shared scale.
  *
+ * Responsive strategy is horizontal overflow: the wrap scrolls, the table
+ * keeps its columns. Restructuring rows into cards would destroy the
+ * column scanability tables exist for, and needs data-label duplication
+ * because CSS cannot join a cell to its header — that representation choice
+ * belongs to the application, not the framework.
+ *
  * Public hooks:
  * --table-min
  * --table-cell-pad

package/src/css/components/tooltip.css

@@ -22,7 +22,7 @@
  */
 .tooltip {
   --tooltip-bg: var(--surface-solid);
-  --tooltip-fg: var(--surface);
+  --tooltip-fg: var(--surface-solid-fg);
   --tooltip-arrow-size: 5px;
 
   position: fixed;

package/src/css/core/focus.css

@@ -6,12 +6,22 @@
    for its keyboard focus indicator; forced colors keep outlines and drop
    shadows.
 
-   Component indicators are a solid --focus-ring-width line in --focus: inset
-   on fields (inside their border box), offset by --focus-outline-offset on
-   discrete actions. The color never derives from an intent or a local
+   Two contracts share the job, both --focus-ring-width wide. Text-like
+   elements, whose ink is the thing being focused (links, summary, .nav-link,
+   .menu-item, breadcrumb links, .navbar-brand), declare no outline and take
+   the generic fallback below: a currentColor line that follows whatever the
+   application painted. Boxed components, with a fill or border of their own,
+   draw the themed ring instead — a solid line in --focus: inset on fields
+   (inside their border box), offset by --focus-outline-offset on discrete
+   actions. The color never derives from an intent or a local
    surface — the theme guarantees --focus at 3:1 against both --surface and
    --surface-solid, so one token reads on the page, on a solid band and on
-   any nested surface. */
+   any nested surface.
+
+   Documented exception: an invalid field focuses in --form-invalid-border
+   (danger), so the error stays visible at the point of correction. The border
+   carries the same hook; report:theme-contrast measures that line at 3:1
+   against the field's background alongside --focus. */
 :focus {
   outline: var(--focus-outline);
   outline-offset: var(--focus-outline-offset);

package/src/css/core/theme.css

@@ -7,6 +7,8 @@
  * Shadow color, Focus ring derivation.
  * Derived: "Theme-derived aliases", Tone subsystem, Backdrop fill — reference
  * other tokens; hard-coded overrides on a custom theme will break the intent.
+ * Exception: --surface-opaque and --surface-solid-fg are public; a theme with
+ * translucent surfaces overrides them with opaque values.
  * Internal: --hgroup-gap.
  */
 :root {
@@ -98,6 +100,12 @@
   --heading: var(--text);
   --selection-bg: var(--primary);
   --selection-fg: var(--primary-fg);
+  /* Surface roles that must stay opaque when a theme paints translucent
+     surfaces; both equal --surface on an opaque palette. --surface-opaque
+     hides or separates what is painted beneath a ring, separator or marker —
+     never a fill. --surface-solid-fg is the ink on --surface-solid. */
+  --surface-opaque: var(--surface);
+  --surface-solid-fg: var(--surface);
 }
 
 /* Soft foreground hooks — the soft ink is the intent rebated toward the local

package/src/css/core/tokens.css

@@ -78,9 +78,13 @@
   --ease-enter: cubic-bezier(0.2, 0, 0, 1);
   --ease-exit: cubic-bezier(0.4, 0, 1, 1);
 
-  /* Focus ring — shared by every interactive component's :focus-visible */
+  /* Generic focus fallback — an adaptive currentColor line for elements
+     without a component ring (links, summary, plain items). Components draw
+     the themed ring instead: --focus-ring-width solid --focus. See focus.css
+     for the two contracts. Both share --focus-ring-width: they differ in
+     color only. */
   --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;
 
@@ -143,8 +147,8 @@
   --state-selected-fg: var(--primary-fg);
   --state-disabled: var(--text-subtle);
 
-  /* Status dot ring — follows the island's surface. */
-  --indicator-ring: var(--surface);
+  /* Status dot ring — cuts the dot out of what it overlaps. */
+  --indicator-ring: var(--surface-opaque);
 }
 
 :root {

package/src/css/core/variants.css

@@ -77,7 +77,8 @@
 /* Shared control scale. Wrappers are listed when their descendants form one
    component (field, choice-card, floating-field, input-icon, join, pagination,
    tabs, flyout). A local size declaration beats inherited density because it
-   is declared on the sized component itself. */
+   is declared on the sized component itself. Guarded by check:sync
+   (size-scale-participants): .sm and .lg must list the same components. */
 :where(
   .btn,
   .input,

package/src/css/effects/aura.css

@@ -35,36 +35,55 @@
 
 .aura {
   --aura-color: var(--intent, var(--primary));
-  --aura-width: 2px;
+  --aura-width: 1px;
   --aura-blur: 0.25rem;
-  --aura-intensity: 1;
+  --aura-intensity: 0.4;
   --aura-radius: var(--radius-lg);
   --aura-duration: 6s;
 
   position: relative;
   isolation: isolate;
   display: inline-grid;
-  padding: var(--aura-width);
   border-radius: calc(var(--aura-radius) + var(--aura-width));
-  border: var(--border-width) solid transparent;
+
+  /* The frame is the border itself, so --aura-width is the painted thickness.
+     A transparent border stays for forced colors, where it becomes the visible
+     boundary; a padding frame inside it would paint both, doubling the line. */
+  border: var(--aura-width) solid transparent;
   background: var(--aura-color);
 
   /* A short feathered accent rather than a long wedge with a hard edge, which
      reads as one lit side. Nothing tints the frame outside it: a constant tint
-     across 2px draws an outline, the opposite of the effect. */
+     across the frame draws an outline, the opposite of the effect. `border-box`
+     sizes the gradient to the border box: the default padding-box origin would
+     tile a neighbouring copy of the gradient into the border, which is now the
+     whole frame. */
   background: conic-gradient(
-    from var(--aura-angle),
-    transparent 0 78%,
-    var(--aura-color) 93%,
-    transparent
-  );
+      from var(--aura-angle),
+      transparent 0 78%,
+      var(--aura-color) 93%,
+      transparent
+    )
+    border-box;
+
+  /* Far halo — flat and static. At this blur the rotating detail is no longer
+     legible, so there is nothing to gain from animating a second wide blurred
+     layer. This is the layer that stays lit at all times, so it — not the
+     frame — is what keeps the object present between two passes of the
+     accent. An outer shadow never paints under the box, so it stays out of a
+     translucent child. min() because a color-mix() share above 100% is
+     invalid, where the opacity it replaces clamped. */
+  box-shadow: 0 0 calc(var(--aura-blur) * 8) var(--aura-blur)
+    color-mix(in oklab, var(--aura-color) min(100%, calc(15% * var(--aura-intensity))), transparent);
 }
 
-/* Near halo — inherits the frame gradient, so it tracks the lit accent. */
+/* Near halo — inherits the frame gradient, so it tracks the lit accent. An
+   absolute inset starts at the padding edge, inside the border that is the
+   frame, so the negative inset puts the halo back on the frame. */
 .aura::before {
   position: absolute;
   z-index: -1;
-  inset: 0;
+  inset: calc(-1 * var(--aura-width));
   border-radius: inherit;
   background: inherit;
   filter: blur(var(--aura-blur));
@@ -73,29 +92,22 @@
   content: "";
 }
 
-/* Far halo — flat and static. At this blur the rotating detail is no longer
-   legible, so there is nothing to gain from animating a second wide blurred
-   layer. It outgrows the frame, otherwise the child covers it and the whole
-   effect reads as a drop shadow. This is the layer that stays lit at all
-   times, so it — not the frame — is what keeps the object present between two
-   passes of the accent. */
+/* Occlusion — the frame and the near halo paint across the whole box, and only
+   their edge is meant to show. This mask sits above both, under the child, so
+   a transparent or translucent child (an .outline alert, a glass surface) is
+   framed rather than filled with the frame color. It follows the child's
+   shape through --aura-radius. */
 .aura::after {
   position: absolute;
   z-index: -1;
-  inset: calc(-1 * var(--aura-blur));
-  border-radius: calc(var(--aura-radius) + var(--aura-width) + var(--aura-blur));
-  background: var(--aura-color);
-  filter: blur(calc(var(--aura-blur) * 4));
-  opacity: calc(0.15 * var(--aura-intensity));
+  inset: 0;
+  border-radius: var(--aura-radius);
+  background: var(--surface-opaque);
   pointer-events: none;
   content: "";
 }
 
-/* Lifts the child above both halos. It also has to be opaque: the frame paints
-   across the whole box and only its edge is meant to show, so a transparent
-   child (an .outline alert, a .ghost button) is filled with the frame color
-   rather than framed by it. Documented as a constraint, not worked around —
-   masking a ring would cost more than the case is worth. */
+/* Lifts the child above the halo and the mask. */
 .aura > * {
   position: relative;
 }
@@ -118,7 +130,7 @@
     animation: aura-breathe-near var(--aura-duration) ease-in-out infinite;
   }
 
-  .aura-glow::after {
+  .aura-glow {
     animation: aura-breathe-far var(--aura-duration) ease-in-out infinite;
   }
 }
@@ -130,8 +142,8 @@
 @media (prefers-reduced-motion: reduce) {
   .aura:not(.aura-glow) {
     background:
-      radial-gradient(4rem 4rem at 0% 0%, var(--aura-color), transparent 70%),
-      radial-gradient(4rem 4rem at 100% 100%, var(--aura-color), transparent 70%);
+      radial-gradient(4rem 4rem at 0% 0%, var(--aura-color), transparent 70%) border-box,
+      radial-gradient(4rem 4rem at 100% 100%, var(--aura-color), transparent 70%) border-box;
   }
 }
 
@@ -152,10 +164,16 @@
   }
 }
 
+/* The far halo is the element's own shadow: opening its spread and share
+   breathes it without scaling the child. */
 @keyframes aura-breathe-far {
   50% {
-    opacity: calc(0.28 * var(--aura-intensity));
-    transform: scale(1.07);
+    box-shadow: 0 0 calc(var(--aura-blur) * 10) calc(var(--aura-blur) * 2)
+      color-mix(
+        in oklab,
+        var(--aura-color) min(100%, calc(28% * var(--aura-intensity))),
+        transparent
+      );
   }
 }
 

package/src/css/effects/index.css

@@ -1,2 +1,3 @@
 /* Effects — purely visual enrichments. */
 @import "./aura.css";
+@import "./shimmer.css";

package/src/css/effects/shimmer.css

@@ -0,0 +1,57 @@
+/*
+ * Highlight sweeping across a text label — an activity in progress.
+ *
+ * Docs: docs/pages/components/shimmer.md
+ *
+ * Presentation only: it carries no state and selects no ARIA attribute, so the
+ * label stays whatever the author makes it (a role="status" message, a list
+ * item, a heading).
+ *
+ * Public hooks:
+ * --shimmer-color
+ * --shimmer-highlight
+ */
+.shimmer {
+  --shimmer-color: var(--text-muted);
+  --shimmer-highlight: var(--text);
+
+  color: var(--shimmer-color);
+}
+
+/* The sweep paints the glyphs through a clipped background, which needs the
+   glyph fill transparent. Without background-clip: text that would erase the
+   label, so the transparency lives under the same query as the clip. It is
+   the fill, not `color`: a label class that sets its own color (.muted, a
+   caption style) would otherwise win the cascade and paint opaque glyphs over
+   the sweep. Reduced motion keeps the plain label — a frozen band would read
+   as a random tint. */
+@supports (background-clip: text) {
+  @media (prefers-reduced-motion: no-preference) {
+    .shimmer {
+      -webkit-text-fill-color: transparent;
+      background:
+        linear-gradient(
+          90deg,
+          var(--shimmer-color) 40%,
+          var(--shimmer-highlight) 50%,
+          var(--shimmer-color) 60%
+        )
+        0 0 / 300% 100%;
+      background-clip: text;
+      animation: actual-shimmer var(--duration-shimmer) linear infinite;
+    }
+  }
+}
+
+/* The band occupies the middle third of a background three times the label's
+   width, so each pass leaves the end of the label before the next one enters
+   at the start. */
+@keyframes actual-shimmer {
+  from {
+    background-position: 100% 0;
+  }
+
+  to {
+    background-position: 0% 0;
+  }
+}

package/src/css/forms/choice-card.css

@@ -5,13 +5,15 @@
  *
  * Each .choice-card is a <label> wrapping a native radio or checkbox. When
  * :has() is supported the input is visually hidden and the card mirrors its
- * state: checked border and tint, checkmark badge (round for radio, rounded
- * square for checkbox), focus ring, disabled dimming. Without :has() the
- * native input stays visible so selection state never disappears.
+ * state: an indicator on the leading edge (a ring for radio, a box for
+ * checkbox) that fills with a check, checked border and tint, focus ring,
+ * disabled dimming. Without :has() the native input stays visible in the
+ * indicator's slot, so selection state never disappears.
  *
- * The badge overhangs the top-right corner by 0.375em; ancestors with
- * overflow: hidden will clip it. Pair with grid or flex utilities for group
- * layout.
+ * The card is a two-column grid: the indicator in the first column, level
+ * with the first row, and each child element of the label on its own row in
+ * the second. Wrap loose text in an element. A corner badge for tiles is a
+ * documented recipe on these same layers, not a variant.
  *
  * .chip is the compact pill form (filter chips, selectable tags): control
  * height, and a leading dot that turns into the check in a fixed slot, so
@@ -19,6 +21,7 @@
  *
  * Public hooks:
  * --choice-card-pad
+ * --choice-card-gap
  * --choice-card-radius
  * --choice-card-border
  * --choice-card-bg
@@ -33,19 +36,25 @@
 
 .choice-card {
   --choice-card-pad: var(--density-space, var(--space-40));
+  --choice-card-gap: var(--space-30);
   --choice-card-radius: var(--radius);
   --choice-card-border: var(--border);
   --choice-card-bg: var(--surface);
-  --choice-card-check-size: 1.5em;
+  --choice-card-check-size: 1.25em;
 
   position: relative;
-  display: block;
+  display: grid;
+  grid-template-columns: var(--choice-card-check-size) minmax(0, 1fr);
+  /* why: a card stretched by a taller grid neighbour keeps its rows at the
+     top instead of spreading them. */
+  align-content: start;
+  column-gap: var(--choice-card-gap);
   padding: var(--choice-card-pad);
   border: var(--border-width) solid var(--form-invalid-border, var(--choice-card-border));
   border-radius: var(--choice-card-radius);
   background: var(--choice-card-bg);
   color: var(--text);
-  /* Consumed so .sm/.lg reach the card; the badge's em sizing follows. */
+  /* Consumed so .sm/.lg reach the card; the indicator's em sizing follows. */
   font-size: var(--control-font-size);
   cursor: pointer;
   transition:
@@ -54,6 +63,18 @@
     box-shadow var(--duration);
 }
 
+.choice-card > * {
+  grid-column: 2;
+}
+
+/* The input owns the indicator's cell: visible there without :has(), hidden
+   in it with :has(). */
+.choice-card > :is(input[type="radio"], input[type="checkbox"]) {
+  grid-area: 1 / 1;
+  place-self: center;
+  margin: 0;
+}
+
 /* The native input is visually hidden but stays focusable and participates in
    form submission and keyboard navigation (sr-only pattern). Guarded: without
    :has() the card cannot mirror the input's state, so the visible native
@@ -99,24 +120,31 @@
   }
 }
 
-/* Checkmark badge — always rendered at scale(0) and scaled in on check, so
-   the entrance can transition (a pseudo created on :checked could not). */
+/* Indicator: ::before is the ring or box, ::after the check. Both share the
+   input's cell, centred on the first line — not the first row, which a long
+   label wraps — and stay hidden until :has() can mirror the input. The em
+   margin is the lh-less fallback at the default 1.5 line-height. */
 .choice-card::before,
 .choice-card::after {
   content: "";
-  position: absolute;
-  inset-inline-end: -0.375em;
-  inset-block-start: -0.375em;
+  grid-area: 1 / 1;
+  align-self: start;
+  margin-block-start: calc((1.5em - var(--choice-card-check-size)) / 2);
+  margin-block-start: calc((1lh - var(--choice-card-check-size)) / 2);
   inline-size: var(--choice-card-check-size);
   block-size: var(--choice-card-check-size);
   transform: scale(0);
-  transition: transform var(--duration);
+  transition:
+    transform var(--duration),
+    background-color var(--duration),
+    border-color var(--duration);
 }
 
-/* Badge disc — circle for radio, rounded square for checkbox */
+/* A border, not an inset shadow: forced colors drop shadows, and the resting
+   ring is the only sign of an unchecked option. The invalid border reaches it
+   through the same hook as the card's. */
 .choice-card::before {
-  background: var(--intent, var(--state-selected));
-  box-shadow: 0 0 0 2px var(--surface);
+  border: max(var(--border-width), 1.5px) solid var(--form-invalid-border, var(--text-muted));
   z-index: 1;
 }
 
@@ -138,7 +166,19 @@
   z-index: 2;
 }
 
-.choice-card:has(:checked)::before,
+/* Guarded with the input's hiding above: a resting ring beside a visible
+   native input would draw the indicator twice. */
+@supports selector(:has(*)) {
+  .choice-card::before {
+    transform: none;
+  }
+}
+
+.choice-card:has(:checked)::before {
+  border-color: var(--intent, var(--state-selected));
+  background: var(--intent, var(--state-selected));
+}
+
 .choice-card:has(:checked)::after {
   transform: scale(1);
 }
@@ -164,11 +204,16 @@
 .choice-card.chip::before {
   --choice-chip-dot: calc(var(--control-pad-x) + var(--choice-card-check-size) / 2) 50%;
 
+  position: absolute;
   inset: 0;
+  /* why: an absolute box honours self-alignment — the card's start would
+     shrink this layer to 0 height and the dot with it. */
+  align-self: auto;
+  margin: 0;
   inline-size: auto;
   block-size: auto;
+  border: 0;
   border-radius: inherit;
-  box-shadow: none;
   background: var(--text-subtle);
   transform: none;
   clip-path: circle(0.1875em at var(--choice-chip-dot));
@@ -182,10 +227,11 @@
 
 /* The check keeps the card's scale-in, in flow ahead of the label. */
 .choice-card.chip::after {
-  position: static;
   order: -1;
   flex: none;
-  margin-inline-end: 0.375em;
+  align-self: center;
+  margin-block: 0;
+  margin-inline: 0 0.375em;
   background: var(--intent, var(--state-selected));
   -webkit-mask-size: contain;
   mask-size: contain;
@@ -195,9 +241,11 @@
    this repair, forced colors pushes disc and check to the same system color
    and the state disappears. Highlight/Canvas/HighlightText are preserved as-is,
    so no forced-color-adjust is needed. The pseudo is not focusable — the
-   outline is a separator against the card, not a focus channel. */
+   outline separates the disc from whatever it overlaps (the card's border,
+   for a corner-badge recipe), not a focus channel. */
 @media (forced-colors: active) {
   .choice-card:has(:checked)::before {
+    border-color: Highlight;
     background: Highlight;
     outline: 2px solid Canvas;
   }

package/src/css/forms/control.css

@@ -53,8 +53,8 @@
   cursor: var(--control-cursor);
   /* No outline: none here — the core :focus fallback must survive for browsers
      without :focus-visible. Pointer focus is hidden by core's
-     :focus:not(:focus-visible); keyboard focus swaps in the transparent
-     outline + ring below. */
+     :focus:not(:focus-visible); keyboard focus draws the inset outline below
+     (invalid fields take --form-invalid-border, the documented exception). */
   transition:
     border-color var(--duration),
     box-shadow var(--duration),

package/src/css/forms/otp.css

@@ -64,7 +64,7 @@
   padding-block: 0;
   padding-inline: calc((var(--otp-cell-size) - 1ch) / 2) 0;
   border: 0;
-  outline: 2px solid transparent;
+  outline: none;
   box-shadow: none;
   background: transparent;
   color: var(--text);
@@ -89,6 +89,14 @@
    character after it: the state rules select the cells as following siblings
    (input:focus ~ span, input:disabled ~ span, …), so that order is part of the
    contract. */
+/* The documented markup puts .input on the native input, so the field ring
+   (.input:focus-visible:not(:disabled), control.css) would outrank the reset
+   above and draw that group ring; this selector must stay one step above it.
+   No transparent outline either: forced colors would paint it as a ring. */
+.otp > input:focus-visible:not(:disabled) {
+  outline: none;
+}
+
 .otp > input:focus ~ span {
   --otp-cell-border: var(--focus);
   --otp-cell-border-width: calc(var(--border-width) * 2);