actual-css 0.8.0 → 0.9.1

package/src/css/components/modal.css

@@ -1,6 +1,8 @@
 /*
  * Modal shell styling for native dialog elements.
  *
+ * Docs: docs/pages/components/dialog.md
+ *
  * Spacing, radius, transitions, and focus treatment come from shared tokens.
  * Opening behavior and intent-specific decisions stay outside this component.
  *
@@ -12,16 +14,15 @@
  *
  * Internal:
  * --dialog-close-icon-size
+ * --dialog-focus-bleed
  * --dialog-viewport-block
  * --dialog-viewport-gap-default
  * --dialog-viewport-gap-2x
  */
-dialog.modal {
-  /* --dialog-viewport-gap stays fallback-only for the same reason as
-     --modal-size below: declaring the public hook here would give it
-     type+class specificity that a single author class cannot outrank. The
-     responsive default lives in an internal token instead, so a media query
-     can still move it without closing the hook.
+:where(dialog).modal {
+  /* --dialog-viewport-gap stays fallback-only so the responsive default can
+     live in an internal token: a media query moves it without closing the
+     public hook.
 
      calc() multiplication is not in the supported browser range, so the
      doubled gap is spelled out with an additive calc. */
@@ -35,10 +36,8 @@ dialog.modal {
      provides the containing block for the absolutely positioned close button. */
   position: fixed;
 
-  /* --modal-size stays fallback-only: declaring it on dialog.modal gives it
-     type+class specificity, which a single author class cannot outrank, so the
-     public hook would silently keep this default. Same reason choice.css never
-     declares --choice-control-offset. */
+  /* The root is :where(dialog).modal (0-1-0), so a single author class can
+     outrank these defaults — no fallback-only indirection needed here. */
   max-inline-size: min(calc(100% - var(--dialog-viewport-gap-2x)), var(--modal-size, 32rem));
 
   /* Stable viewport cap for the panel: dvh tracks the dynamic browser toolbar
@@ -68,8 +67,8 @@ dialog.modal {
     transform var(--duration) var(--ease-exit);
 }
 
-dialog.modal > form,
-dialog.modal > .stack {
+:where(dialog).modal > form,
+:where(dialog).modal > .stack {
   display: grid;
   gap: var(--space-40);
   max-block-size: calc(var(--dialog-viewport-block) - var(--dialog-viewport-gap-2x));
@@ -79,7 +78,7 @@ dialog.modal > .stack {
 }
 
 @supports (block-size: 100svh) {
-  dialog.modal {
+  :where(dialog).modal {
     --dialog-viewport-block: 100svh;
   }
 }
@@ -87,42 +86,50 @@ dialog.modal > .stack {
 /* Keep the dialog off the viewport edges on small screens. Moves the internal
    default, not the public hook, so an author override still wins here too. */
 @media (max-width: 30rem) {
-  dialog.modal {
+  :where(dialog).modal {
     --dialog-viewport-gap-default: var(--space-30);
   }
 }
 
-dialog.modal.scrollable > form,
-dialog.modal.scrollable > .stack {
+:where(dialog).modal.scrollable > form,
+:where(dialog).modal.scrollable > .stack {
   grid-template-rows: auto minmax(0, 1fr) auto;
   overflow: hidden;
 }
 
-dialog.modal.scrollable > form > :not(:is(header, footer)),
-dialog.modal.scrollable > .stack > :not(:is(header, footer)) {
+:where(dialog).modal.scrollable > form > :not(:is(header, footer)),
+:where(dialog).modal.scrollable > .stack > :not(:is(header, footer)) {
+  --dialog-focus-bleed: calc(var(--focus-outline-offset) + var(--border-width) * 2);
+
   min-block-size: 0;
+  /* Keep focus paint inside the clip without moving the body off the fixed
+     header and footer edges. */
+  margin-inline: calc(var(--dialog-focus-bleed) * -1);
+  padding-inline: var(--dialog-focus-bleed);
   overflow: auto;
   overscroll-behavior: contain;
 }
 
-dialog.modal header > :first-child,
-dialog.modal footer > :first-child {
+/* Anatomy is bounded to the structural slots (direct children of the
+   form/.stack body): a header or footer deeper in the content keeps its own
+   rhythm and is not restyled as the modal's chrome. */
+:where(dialog).modal > :where(form, .stack) > :is(header, footer) > :first-child {
   margin-block-start: 0;
 }
 
-dialog.modal header > :last-child,
-dialog.modal footer > :last-child {
+:where(dialog).modal > :where(form, .stack) > :is(header, footer) > :last-child {
   margin-block-end: 0;
 }
 
 /* The close button is anchored to the dialog at top inline-end, out of the
-   content flow; headers reserve inline room so titles never run under it. */
-dialog.modal > form > header,
-dialog.modal > .stack > header {
+   content flow; headers reserve inline room so titles never run under it.
+   The form/.stack anatomy is structural, so it stays in :where() and never
+   lends .stack's specificity to a bare <form>. */
+:where(dialog).modal > :where(form, .stack) > header {
   padding-inline-end: calc(var(--control-size) + var(--space-30));
 }
 
-dialog.modal footer {
+:where(dialog).modal > :where(form, .stack) > footer {
   display: flex;
   flex-wrap: wrap;
   justify-content: flex-end;
@@ -132,17 +139,17 @@ dialog.modal footer {
 /* Confirmation layout — a focused message followed by a visually distinct
    action band. The media primitive owns icon/content alignment; this variant
    only removes the standard form inset so both regions can own their padding. */
-dialog.modal.dialog-confirmation > form {
+:where(dialog).modal.dialog-confirmation > form {
   gap: 0;
   padding: 0;
 }
 
-dialog.modal.dialog-confirmation > form > .media {
+:where(dialog).modal.dialog-confirmation > form > .media {
   gap: var(--space-40);
   padding: var(--space-50);
 }
 
-dialog.modal.dialog-confirmation > form > footer {
+:where(dialog).modal.dialog-confirmation > form > footer {
   padding: var(--space-40) var(--space-50);
   border-end-start-radius: calc(var(--radius-lg) - var(--border-width));
   border-end-end-radius: calc(var(--radius-lg) - var(--border-width));
@@ -183,13 +190,13 @@ dialog.modal.dialog-confirmation > form > footer {
 }
 
 @media (max-width: 30rem) {
-  dialog.modal.dialog-confirmation > form > .media,
-  dialog.modal.dialog-confirmation > form > footer {
+  :where(dialog).modal.dialog-confirmation > form > .media,
+  :where(dialog).modal.dialog-confirmation > form > footer {
     padding: var(--space-40);
   }
 }
 
-dialog.modal[open] {
+:where(dialog).modal[open] {
   opacity: 1;
   transform: none;
   transition:
@@ -198,13 +205,13 @@ dialog.modal[open] {
 }
 
 @starting-style {
-  dialog.modal[open] {
+  :where(dialog).modal[open] {
     opacity: 0;
     transform: translateY(0.35rem);
   }
 }
 
-dialog.modal::backdrop {
+:where(dialog).modal::backdrop {
   background: var(--backdrop-fill);
   opacity: 0;
   /* Scrim curve stays neutral `ease`; only the panel carries the character
@@ -213,7 +220,7 @@ dialog.modal::backdrop {
 }
 
 @supports (transition-behavior: allow-discrete) {
-  dialog.modal {
+  :where(dialog).modal {
     transition:
       opacity var(--duration) var(--ease-exit),
       transform var(--duration) var(--ease-exit),
@@ -221,7 +228,7 @@ dialog.modal::backdrop {
       display var(--duration) allow-discrete;
   }
 
-  dialog.modal[open] {
+  :where(dialog).modal[open] {
     transition:
       opacity var(--duration) var(--ease-enter),
       transform var(--duration) var(--ease-enter),
@@ -229,7 +236,7 @@ dialog.modal::backdrop {
       display var(--duration) allow-discrete;
   }
 
-  dialog.modal::backdrop {
+  :where(dialog).modal::backdrop {
     transition:
       opacity var(--duration) ease,
       overlay var(--duration) allow-discrete,
@@ -237,7 +244,7 @@ dialog.modal::backdrop {
   }
 }
 
-dialog.modal[open]::backdrop {
+:where(dialog).modal[open]::backdrop {
   opacity: 1;
 }
 
@@ -250,7 +257,7 @@ html.has-modal-open.had-scrollbar {
 }
 
 @starting-style {
-  dialog.modal[open]::backdrop {
+  :where(dialog).modal[open]::backdrop {
     opacity: 0;
   }
 }
@@ -258,7 +265,7 @@ html.has-modal-open.had-scrollbar {
 @media (prefers-reduced-motion: no-preference) {
   /* Wrong-close feedback and view-transition transport are motion quirks, not
      presence enter/exit, so they stay on the plain CSS default easing. */
-  dialog.modal.is-static {
+  :where(dialog).modal.is-static {
     animation: actual-dialog-static var(--duration-slow) ease;
   }
 

package/src/css/components/navbar.css

@@ -1,6 +1,8 @@
 /*
  * Navbar — top-level navigation bar.
  *
+ * Docs: docs/pages/components/navbar.md
+ *
  * .navbar is a horizontal bar; .navbar-brand is the brand link; .navbar-nav is
  * the inline link list using .nav-link items. .nav-list is the vertical nav
  * list shared with .drawer, fed by the shared --gap token.

package/src/css/components/pagination.css

@@ -1,6 +1,8 @@
 /*
  * Pagination — page navigation for paginated lists.
  *
+ * Docs: docs/pages/components/pagination.md
+ *
  * Render .btn elements inside a .pagination list. The active page is marked
  * with aria-current="page"; .btn owns the active state styling.
  *

package/src/css/components/progress.css

@@ -1,6 +1,8 @@
 /*
  * Progress — native progress bar with theme-aware track and value.
  *
+ * Docs: docs/pages/components/progress.md
+ *
  * Consumes the shared --intent/--primary for the value bar and --bar-height
  * for thickness. Indeterminate state animates a shimmer using --duration-shimmer.
  *

package/src/css/components/rating.css

@@ -1,6 +1,8 @@
 /*
  * Rating — integer star rating drawn on native radio inputs.
  *
+ * Docs: docs/pages/components/rating.md
+ *
  * The checked radio remains the functional baseline. :has() progressively
  * fills preceding stars without reversing DOM or keyboard order. Forced
  * colors restores the platform radio presentation.

package/src/css/components/scrollspy.css

@@ -2,6 +2,8 @@
  * Scrollspy — behavior hook for navigation that marks the active section
  * while the page scrolls.
  *
+ * Docs: docs/pages/enhancements/scrollspy.md
+ *
  * Does not add visual styles by itself. scrollspy.js watches
  * <nav class="scrollspy">
  * containing <a href="#section"> links and toggles aria-current="location" on

package/src/css/components/skeleton.css

@@ -1,6 +1,8 @@
 /*
  * Skeleton placeholders for loading states.
  *
+ * Docs: docs/pages/components/skeleton.md
+ *
  * Shows approximate loading structure without implying real content hierarchy.
  * Geometry, animation, and color stay theme-aware.
  *
@@ -11,16 +13,24 @@
  * --skeleton-track
  * --skeleton-highlight
  */
+/* A placeholder fills its container up to --skeleton-width; the preset widths
+   are a cap, never an intrinsic size. Stated the other way round — a rem
+   `inline-size` capped by a percentage `max-inline-size` — the cap is ignored
+   during intrinsic sizing, so every shrink-to-fit ancestor inherits the
+   preset as a min-content floor: a card holding a title placeholder could not
+   go below 18rem and pushed a phone's layout sideways. A percentage
+   `inline-size` contributes nothing intrinsically and a rem cap only lowers
+   the contribution, so the same geometry costs no floor. */
 .skeleton {
   --skeleton-size: 1rem;
-  --skeleton-width: 100%;
+  --skeleton-width: none;
   --skeleton-radius: var(--radius);
   --skeleton-track: var(--surface-subtle);
   --skeleton-highlight: var(--surface-raised);
 
   display: block;
-  inline-size: var(--skeleton-width);
-  max-inline-size: 100%;
+  inline-size: 100%;
+  max-inline-size: var(--skeleton-width);
   block-size: var(--skeleton-size);
   border-radius: var(--skeleton-radius);
   background:
@@ -44,11 +54,14 @@
   --skeleton-width: 18rem;
 }
 
+/* The one preset with a real intrinsic width: a disc is square, so it sizes
+   rather than caps. The floor it does carry is the avatar size, which is small
+   enough never to widen a layout. */
 .skeleton[data-shape="avatar"] {
   --skeleton-size: var(--avatar-size, 2.25rem);
-  --skeleton-width: var(--skeleton-size);
   --skeleton-radius: var(--radius-full);
 
+  inline-size: var(--skeleton-size);
   flex: 0 0 auto;
 }
 

package/src/css/components/spinner.css

@@ -1,6 +1,8 @@
 /*
  * Spinner — compact loading feedback.
  *
+ * Docs: docs/pages/components/spinner.md
+ *
  * Uses currentColor so it adapts to buttons, alerts, badges, and text. The
  * [aria-busy] overlay composition lives in components/busy.css.
  *

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

@@ -1,6 +1,8 @@
 /*
  * Status bar — singleton floating status area.
  *
+ * Docs: docs/pages/enhancements/status-bar.md
+ *
  * One element in the HTML, empty by default. .is-open is the visual state, set
  * by status.js like any other surface: it lands after the message is written
  * and lifts before the bar is cleared, so the bar leaves in the exact state it

package/src/css/components/steps.css

@@ -1,6 +1,8 @@
 /*
  * Steps — semantic ordered-list progression for a multi-step process.
  *
+ * Docs: docs/pages/components/steps.md
+ *
  * One primitive, two explicit compositions. Both classes are required:
  *
  *   <ol class="steps steps-horizontal">  horizontal, 2 to 5 stages

package/src/css/components/tab.css

@@ -1,6 +1,8 @@
 /*
  * Tabs — in-place panel switcher with real tab semantics.
  *
+ * Docs: docs/pages/enhancements/tabs.md
+ *
  * JavaScript owns roving tabindex, aria-selected, panel visibility,
  * and arrow-key navigation. CSS owns the tab strip appearance and
  * active indicator.

package/src/css/components/table.css

@@ -1,6 +1,8 @@
 /*
  * Table — structured tabular data.
  *
+ * Docs: docs/pages/components/table.md
+ *
  * .table-wrap provides the scroll container and outer chrome; .table owns row
  * and cell rules. Tokens are sourced from the shared scale.
  *
@@ -9,6 +11,14 @@
  * --table-cell-pad
  */
 .table-wrap {
+  /* Containing block for anything absolutely positioned inside the table —
+     `.sr-only` on a column header above all. Without it that box resolves
+     against the initial containing block, so it keeps the static position of a
+     cell that may be a thousand pixels along the scrolled row, escapes this
+     scroller, and extends the *document's* scrollable width. The page then
+     scrolls sideways on a phone with nothing painted out there. */
+  position: relative;
+
   inline-size: 100%;
   max-inline-size: 100%;
   min-inline-size: 0;

package/src/css/components/tooltip.css

@@ -1,6 +1,8 @@
 /*
  * Tooltip — supplemental label overlaid near a trigger.
  *
+ * Docs: docs/pages/enhancements/tooltip.md
+ *
  * Position, placement, and arrow position are managed by JavaScript via left,
  * top, data-placement, and --arrow-x. The runtime also owns `position`: it
  * writes `absolute` for a tip whose trigger scrolls with the page, so the

package/src/css/core/print.css

@@ -1,5 +1,8 @@
 @media print {
   :root,
+  /* The doubled attribute intentionally outranks single-attribute preset
+     islands (data-theme="dark", paired themes) loaded after the core. */
+  [data-theme][data-theme],
   body {
     /* Save some ink in dark mode */
     color-scheme: light;

package/src/css/core/variants.css

@@ -92,9 +92,9 @@
 }
 
 /* Shared control scale. Wrappers are listed when their descendants form one
-   component (field, input-icon, join, pagination, tabs, flyout). A local size
-   declaration beats inherited density because it is declared on the sized
-   component itself. */
+   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. */
 :where(
   .btn,
   .input,
@@ -104,7 +104,9 @@
   .file,
   .field,
   .choice,
+  .choice-card,
   .input-icon,
+  .floating-field,
   .otp,
   .join,
   .pagination,
@@ -126,7 +128,9 @@
   .file,
   .field,
   .choice,
+  .choice-card,
   .input-icon,
+  .floating-field,
   .otp,
   .join,
   .pagination,

package/src/css/effects/aura.css

@@ -1,6 +1,8 @@
 /*
  * Decorative intent-colored frame for one direct child.
  *
+ * Docs: docs/pages/components/aura.md
+ *
  * The effect is built from three layers with distinct roles: a frame carrying
  * a short accent of light, a small halo that belongs to the frame and keeps
  * that light attached to the edge, and a wide static halo that belongs to the

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

@@ -1,6 +1,8 @@
 /*
  * Choice cards — card-style radio and checkbox labels.
  *
+ * Docs: docs/pages/forms/choice-cards.md
+ *
  * 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
@@ -37,6 +39,8 @@
   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. */
+  font-size: var(--control-font-size);
   cursor: pointer;
   transition:
     border-color var(--duration),

package/src/css/forms/choice.css

@@ -10,7 +10,7 @@
  * geometry and states. switch.css is imported after this file.
  *
  * Public hooks:
- * --choice-control-offset
+ * --choice-control-nudge
  * --choice-border
  * --choice-bg
  * --choice-mark
@@ -42,45 +42,89 @@
   cursor: pointer;
 }
 
-/* Optical alignment: nudge the control down so it sits visually centered with
-   the first line of label text, not flush with the top of the line-box. Every
-   inline choice runs the same formula — center the control's own block size on
-   the first line box, then drop it 0.0625em so it reads level with the
-   cap-height rather than the em-box. A checkbox and a switch therefore stay
-   level with each other under any line-height or --choice-control-size, which
-   a per-control constant cannot do (a taller switch and a shorter checkbox
-   need different offsets to land on the same optical line).
-
-   The constants are what the formula yields at the default 1.5 line-height:
-   0.25em (4px) for a checkbox, 0.1875em (3px) for the taller switch track.
-   They serve browsers without lh units. Multi-line labels still keep the
-   control at the top thanks to align-items: flex-start.
-
-   --choice-control-offset stays fallback-only rather than declared here, so an
-   override placed anywhere up the tree — :root included — reaches the control
-   instead of losing to a component-level declaration. */
+/* Optical alignment: the control reads level with the first line's cap height,
+   not with the top of its line box. Every inline choice runs the same formula
+   over its own block size, so a checkbox and a taller switch stay level with
+   each other under any line-height or --choice-control-size — something a
+   per-control constant cannot do.
+
+   Three tiers, each the best the engine can express:
+
+   - `cap` unit: exact, and the only font-independent answer. Where the cap
+     center sits inside a line box depends on the font's ascent/descent/cap
+     ratios, so no constant can serve both Segoe UI and Roboto — the same rule
+     was a pixel high on Windows and two pixels low on Android. Baseline
+     alignment puts the control's border-box bottom on the text baseline, and
+     one inset drops it by half the difference between its own height and the
+     cap height. Both classed controls synthesize that baseline from their
+     border box because their mark and knob are out of flow.
+   - `lh` only: center the control on the line box, which is within a pixel of
+     the cap center for the usual UI faces.
+   - neither: the constants that formula yields at the default 1.5
+     line-height, 0.1875em for a checkbox and 0.125em for the switch track.
+
+   --choice-control-nudge adds to whichever tier applies, rather than replacing
+   it: the derived value is exact now, so a design has a correction to make,
+   not a formula to restate — and one number cannot stand in for three
+   different references anyway. It stays fallback-only rather than declared
+   here, so an override placed anywhere up the tree — :root included — reaches
+   the control instead of losing to a component-level declaration. */
 .choice > :is(input[type="checkbox"]:not([role="switch"]), input[type="radio"]) {
   flex: 0 0 auto;
-  margin-block-start: var(--choice-control-offset, 0.25em);
+  margin-block-start: calc(0.1875em + var(--choice-control-nudge, 0px));
 }
 
 .choice > .switch {
   flex: 0 0 auto;
-  margin-block-start: var(--choice-control-offset, 0.1875em);
+  margin-block-start: calc(0.125em + var(--choice-control-nudge, 0px));
 }
 
 @supports (margin-block-start: 1lh) {
   .choice > :is(input[type="checkbox"]:not([role="switch"]), input[type="radio"]) {
-    margin-block-start: var(
-      --choice-control-offset,
-      calc((1lh - var(--choice-control-size)) / 2 + 0.0625em)
+    margin-block-start: calc(
+      (1lh - var(--choice-control-size)) /
+      2 +
+      var(--choice-control-nudge, 0px)
+    );
+  }
+
+  .choice > .switch {
+    margin-block-start: calc(
+      (1lh - var(--switch-block-size)) /
+      2 +
+      var(--choice-control-nudge, 0px)
+    );
+  }
+}
+
+@supports (margin-block-start: 1cap) {
+  .choice {
+    align-items: baseline;
+  }
+
+  /* Baseline alignment owns the block position now; the tier above would only
+     grow the row. An unclassed native input keeps the UA's own baseline, which
+     is already tuned for text — the formula below describes the framework's
+     geometry and would not fit it. */
+  .choice > :is(input[type="checkbox"], input[type="radio"]) {
+    margin-block-start: 0;
+  }
+
+  /* inset-block-start rides the `position: relative` these controls already
+     carry for their mark and knob. */
+  .choice > :is(.check, .radio) {
+    inset-block-start: calc(
+      (var(--choice-control-size) - 1cap) /
+      2 +
+      var(--choice-control-nudge, 0px)
     );
   }
 
   .choice > .switch {
-    margin-block-start: var(
-      --choice-control-offset,
-      calc((1lh - var(--switch-block-size)) / 2 + 0.0625em)
+    inset-block-start: calc(
+      (var(--switch-block-size) - 1cap) /
+      2 +
+      var(--choice-control-nudge, 0px)
     );
   }
 }

package/src/css/forms/control.css

@@ -1,6 +1,8 @@
 /*
  * Text controls — input, textarea, select.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Neutral geometry and interaction states shared across all text-like
  * controls. select shares this base recipe; its chevron/appearance layer
  * lives in select.css. checkbox, radio, range, switch, and file have their

package/src/css/forms/floating-field.css

@@ -2,6 +2,8 @@
  * Floating labels — optional composition over the text controls
  * (.input, .textarea, .select) and .field-label.
  *
+ * Docs: docs/pages/forms/floating-field.md
+ *
  * The cell owns a control plus its label; the label overlays the control and
  * floats to the top when the control is focused or non-empty. Help and error
  * messages stay in the surrounding .field, not inside the cell, so the
@@ -43,7 +45,9 @@
 
 .floating-field > .field-label {
   position: absolute;
-  inset-inline-start: calc(var(--space-30) + var(--border-width));
+  /* Same start edge as the control's text: --control-pad-x owns that shared
+     geometry, so .sm/.lg keep label and value aligned. */
+  inset-inline-start: calc(var(--control-pad-x) + var(--border-width));
   color: var(--text-muted);
   font-size: var(--control-font-size);
   font-weight: var(--font-weight-normal);

package/src/css/forms/form-actions.css

@@ -1,6 +1,8 @@
 /*
  * Form actions — bottom form bar with sticky variant.
  *
+ * Docs: docs/pages/forms/form-actions.md
+ *
  * A flex cluster of buttons/actions that closes a form. The sticky variant
  * docks to the viewport bottom with a translucent blur where supported; at
  * rest it stays visually neutral so it does not double as a separator.

package/src/css/forms/form.css

@@ -1,6 +1,8 @@
 /*
  * Form layout and supporting text.
  *
+ * Docs: docs/pages/forms/overview.md
+ *
  * Individual controls keep their own files; .choice label layout lives in
  * choice.css; .form-actions lives in form-actions.css.
  *