actual-css 0.3.1 → 0.4.0

package/src/css/forms/choice.css

@@ -14,6 +14,10 @@
  * --choice-border
  * --choice-bg
  * --choice-mark
+ *
+ * --choice-control-size (tokens.css) is the shared typographic size for every
+ * inline choice; switch.css derives its track from it so a checkbox and a
+ * switch on the same line stay proportionate.
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
@@ -30,8 +34,6 @@
 }
 
 .choice {
-  --choice-control-offset: 0.25em;
-
   display: inline-flex;
   align-items: flex-start;
   gap: var(--space-20);
@@ -40,17 +42,47 @@
   cursor: pointer;
 }
 
-/* Optical alignment: nudge the control down so the checkbox/radio sits
-   visually centered with the first line of label text, not flush with the
-   top of the line-box. Default 0.25em (~4px at 16px) places the control just
-   below the cap-height, matching what Bootstrap, Material, and most polished
-   form libraries ship. Multi-line labels still keep the control at the top
-   thanks to align-items: flex-start. Override per-instance via
-   --choice-control-offset for themes with a different line-height or control
-   size. */
+/* 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. */
 .choice > :is(input[type="checkbox"]:not([role="switch"]), input[type="radio"]) {
   flex: 0 0 auto;
-  margin-block-start: var(--choice-control-offset);
+  margin-block-start: var(--choice-control-offset, 0.25em);
+}
+
+.choice > .switch {
+  flex: 0 0 auto;
+  margin-block-start: var(--choice-control-offset, 0.1875em);
+}
+
+@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)
+    );
+  }
+
+  .choice > .switch {
+    margin-block-start: var(
+      --choice-control-offset,
+      calc((1lh - var(--switch-block-size)) / 2 + 0.0625em)
+    );
+  }
 }
 
 .choice > span > .field-help {
@@ -76,8 +108,8 @@
   vertical-align: middle;
   display: inline-grid;
   place-content: center;
-  inline-size: 1.125em;
-  block-size: 1.125em;
+  inline-size: var(--choice-control-size);
+  block-size: var(--choice-control-size);
   margin: 0;
   border: var(--border-width) solid var(--form-invalid-border, var(--choice-border));
   background: var(--choice-bg);
@@ -163,27 +195,7 @@
   opacity: 1;
 }
 
-@media (forced-colors: active) {
-  .check,
-  .radio {
-    --choice-border: ButtonText;
-    --choice-bg: Canvas;
-    --choice-mark: ButtonText;
-  }
-
-  .check:checked,
-  .radio:checked,
-  .check:indeterminate {
-    --choice-border: Highlight;
-    --choice-bg: Highlight;
-    --choice-mark: HighlightText;
-    forced-color-adjust: none;
-  }
-
-  .check:disabled,
-  .radio:disabled {
-    --choice-border: GrayText;
-    --choice-bg: Canvas;
-    --choice-mark: GrayText;
-  }
-}
+/* Forced colors intentionally stay under UA control: the visible check/dot
+   carries state while native remapping preserves platform contrast and focus.
+   If real HCM testing ever loses a mark, opt out on that pseudo only—never on
+   the interactive input host. */

package/src/css/forms/control.css

@@ -46,7 +46,10 @@
   color: var(--control-fg);
   font-size: var(--control-font-size);
   cursor: var(--control-cursor);
-  outline: none;
+  /* 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. */
   transition:
     border-color var(--duration),
     box-shadow var(--duration),

package/src/css/forms/custom-select.css

@@ -12,6 +12,8 @@
  * --control-border
  * --control-bg
  */
+/* This enhancement is excluded from forced-colors, where the native/shared
+   outline remains the focus fallback. */
 @media (forced-colors: none) and (prefers-contrast: no-preference) and (hover: hover) and (
     pointer: fine
   ) {

package/src/css/{optional → forms}/floating-field.css

@@ -16,9 +16,13 @@
  * and the reserved headroom with it, leaving typography untouched.
  *
  * Public hooks:
+ * --floating-label-top
+ * --floating-label-opacity
  * --floating-pad-block-start
  */
 .floating-field {
+  --floating-label-top: var(--space-10);
+  --floating-label-opacity: 0.8;
   --floating-pad-block-start: calc(var(--control-size) / 2 + var(--space-20));
 
   /* Grid blockifies the control, removing the inline descender gap a textarea
@@ -37,24 +41,30 @@
 
 .floating-field > .field-label {
   position: absolute;
-  inset-block-start: 50%;
   inset-inline-start: calc(var(--space-30) + var(--border-width));
-  transform: translateY(-50%);
   color: var(--text-muted);
   font-size: var(--control-font-size);
   font-weight: var(--font-weight);
+  opacity: var(--floating-label-opacity);
   pointer-events: none;
   transition:
     inset-block-start var(--duration),
     transform var(--duration),
     font-size var(--duration),
+    opacity var(--duration),
     color var(--duration);
 }
 
-/* A textarea's resting label aligns with the first text line instead of
-   centering in the (tall) control. */
+/* Single-line controls rest in the middle until they receive a value. */
+.floating-field > :is(.input, .select) + .field-label {
+  inset-block-start: 50%;
+  transform: translateY(-50%);
+}
+
+/* An empty textarea label follows the control's normal first-line position;
+   the control itself keeps the extra headroom reserved for its floated state. */
 .floating-field > .textarea + .field-label {
-  inset-block-start: var(--floating-pad-block-start);
+  inset-block-start: calc(1em + var(--border-width));
   transform: none;
 }
 
@@ -63,9 +73,10 @@
 .floating-field
   > :is(.input, .textarea):is(:focus, :autofill, :not(:placeholder-shown))
   + .field-label {
-  inset-block-start: var(--space-10);
+  inset-block-start: var(--floating-label-top);
   transform: none;
   font-size: var(--font-size-xs);
+  opacity: 1;
 }
 
 /* Controls without a dependable :placeholder-shown empty state stay floated:
@@ -81,7 +92,14 @@
     .input[type="week"]
   )
   + .field-label {
-  inset-block-start: var(--space-10);
+  inset-block-start: var(--floating-label-top);
   transform: none;
   font-size: var(--font-size-xs);
+  opacity: 1;
+}
+
+@media (forced-colors: active) {
+  .floating-field > .field-label {
+    opacity: 1;
+  }
 }

package/src/css/forms/index.css

@@ -1,16 +1,13 @@
-/* Forms — import order matters: switch.css follows choice.css so its rules
-   land after the shared choice recipe. validation.css is part of the default
-   forms bundle, but custom builds may omit it when validation styling is
-   app-owned. */
-@import "./form.css";
-@import "./control.css";
+/* Forms — the complete Forms family. base covers the ordinary native
+   controls; the leaves below add opt-in control skins. switch.css follows
+   choice.css (via base) so its rules land after the shared choice recipe.
+   validation.css stays part of base, but custom builds may omit it when
+   validation styling is app-owned. */
+@import "./base.css";
 @import "./input-icon.css";
-@import "./choice.css";
+@import "./switch.css";
+@import "./range.css";
 @import "./choice-card.css";
-@import "./select.css";
 @import "./custom-select.css";
-@import "./native.css";
-@import "./range.css";
-@import "./switch.css";
-@import "./validation.css";
-@import "./form-actions.css";
+@import "./floating-field.css";
+@import "./otp.css";

package/src/css/forms/native.css

@@ -41,11 +41,13 @@
   box-shadow: var(--focus-ring-shadow);
 }
 
-/* Native color picker — keep the browser's dialog and selected-color UI. */
+/* Native color picker — keep the browser's dialog and selected-color UI. The
+   swatch fills almost the whole control so it reads as a color, not as a tiny
+   square inside a button; the 1px padding keeps a hair of --surface around it. */
 .color {
   inline-size: var(--control-size);
   block-size: var(--control-size);
-  padding: var(--space-10);
+  padding: var(--border-width);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius);
   background: var(--surface);
@@ -58,10 +60,12 @@
 
 .color::-webkit-color-swatch {
   border: 0;
+  border-radius: calc(var(--radius) - var(--border-width));
 }
 
 .color::-moz-color-swatch {
   border: 0;
+  border-radius: calc(var(--radius) - var(--border-width));
 }
 
 .color:disabled {
@@ -78,6 +82,15 @@
   .color {
     border-color: ButtonText;
     background: ButtonFace;
+  }
+
+  /* The swatch color is content, so preserve it without disabling the host's
+     native forced-color focus treatment. Vendor pseudos cannot share a rule. */
+  .color::-webkit-color-swatch {
+    forced-color-adjust: none;
+  }
+
+  .color::-moz-color-swatch {
     forced-color-adjust: none;
   }
 }

package/src/css/{optional → forms}/otp.css

@@ -11,7 +11,9 @@
  *
  * Internal:
  * --otp-cell-border
+ * --otp-cell-border-width
  * --otp-cell-bg
+ * --otp-caret-space
  */
 .otp {
   --otp-cell-size: var(--control-size);
@@ -19,6 +21,7 @@
   --otp-font-size: 1.5rem;
   --otp-cell-border: var(--border);
   --otp-cell-bg: var(--surface);
+  --otp-caret-space: calc((var(--otp-cell-size) - 1ch) / 2 + var(--otp-gap) + 1px);
 
   position: relative;
   display: inline-grid;
@@ -28,31 +31,35 @@
   max-inline-size: 100%;
   gap: var(--otp-gap);
   border-radius: var(--radius);
+  /* Unlike hidden, clip cannot become a scroll container when the caret moves
+     into the input extension. */
+  overflow: clip;
   direction: ltr;
 }
 
 .otp > span {
   inline-size: var(--otp-cell-size);
   block-size: var(--otp-cell-size);
-  border: var(--border-width) solid var(--otp-cell-border);
+  border: var(--otp-cell-border-width, var(--border-width)) solid var(--otp-cell-border);
   border-radius: var(--radius);
   background: var(--otp-cell-bg);
   transition:
     border-color var(--duration),
-    background-color var(--duration),
-    box-shadow var(--duration);
+    background-color var(--duration);
 }
 
 /* The native input owns focus, selection, autofill, paste, and one-time-code
-   integration. Its spacing aligns monospace glyphs with the visual cells. */
+   integration. Its clipped extension accommodates the trailing letter-space
+   and final caret so the browser never scrolls the glyphs out of alignment. */
 .otp > input {
   position: absolute;
   z-index: 1;
   inset: 0;
-  inline-size: 100%;
+  inline-size: calc(100% + var(--otp-caret-space));
   block-size: 100%;
   margin: 0;
-  padding: 0 calc((var(--otp-cell-size) - 1ch) / 2);
+  padding-block: 0;
+  padding-inline: calc((var(--otp-cell-size) - 1ch) / 2) 0;
   border: 0;
   outline: 2px solid transparent;
   box-shadow: none;
@@ -67,12 +74,15 @@
   appearance: none;
 }
 
-.otp:focus-within {
-  box-shadow: var(--focus-ring-shadow);
-}
-
+/* Deliberately no group ring: a box around all the cells reads as a second
+   component. The caret already carries focus while the code is being typed,
+   but it sits in the clipped input extension once every cell is filled, so
+   the focused edge must be unambiguous on its own — hence the doubled width,
+   not only the color swap. Width is safe to change: box-sizing is border-box
+   and the cells have a fixed inline/block size, so nothing reflows. */
 .otp > input:focus ~ span {
   --otp-cell-border: var(--focus);
+  --otp-cell-border-width: calc(var(--border-width) * 2);
 }
 
 .otp > input[aria-invalid="true"] ~ span,
@@ -98,12 +108,6 @@
 }
 
 @media (forced-colors: active) {
-  .otp:focus-within {
-    outline: var(--focus-outline);
-    outline-offset: var(--focus-outline-offset);
-    box-shadow: none;
-  }
-
   .otp > input:focus ~ span {
     --otp-cell-border: Highlight;
   }

package/src/css/forms/switch.css

@@ -13,6 +13,10 @@
  * --switch-knob-margin
  * --switch-knob-size
  * --switch-travel
+ *
+ * The track is sized from --choice-control-size (tokens.css), not
+ * --control-size: a switch sits on a line of text next to a checkbox, so it
+ * follows the control typography rather than field density.
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
@@ -25,10 +29,22 @@
   --switch-bg: var(--border);
   --switch-border: var(--border);
   --switch-knob: var(--surface-raised);
-  --switch-width: calc(var(--control-size) * 1.16);
-  --switch-block-size: calc(var(--control-size) * 0.63);
-  --switch-knob-margin: calc(var(--switch-block-size) * 0.12);
-  --switch-knob-size: calc(var(--switch-block-size) - 2 * var(--switch-knob-margin));
+  --switch-block-size: calc(var(--choice-control-size) + 0.125em);
+  --switch-width: calc(var(--switch-block-size) * 1.8);
+  --switch-knob-margin: calc(var(--switch-block-size) * 0.08);
+
+  /* The knob is concentric in the track: --switch-block-size is a border-box
+     height, so the borders have to come out before the inset is applied on
+     both axes. Deriving from the outer height instead leaves the knob
+     --border-width closer to the rails than to the ends — a 1px error on a
+     ~1.6px inset, which reads as a knob squeezed against the track. */
+  --switch-knob-size: calc(
+    var(--switch-block-size) -
+    2 *
+    var(--border-width) -
+    2 *
+    var(--switch-knob-margin)
+  );
   --switch-travel: calc(
     var(--switch-width) -
     var(--switch-knob-size) -
@@ -52,6 +68,11 @@
   cursor: pointer;
 }
 
+/* No elevation on the knob: --shadow is a surface elevation (card, modal,
+   drawer, fab), and at this size its 12px blur reads as a smudge that spills
+   past the rail while carrying no state. The range thumb — the same kind of
+   small moving part — stays flat for the same reason. The concentric inset
+   against the track is what makes the knob legible. */
 .switch::before {
   content: "";
   inline-size: var(--switch-knob-size);
@@ -59,11 +80,9 @@
   margin-inline: var(--switch-knob-margin);
   border-radius: var(--radius-full);
   background: var(--switch-knob);
-  box-shadow: var(--shadow);
   transition:
     transform var(--duration),
-    background-color var(--duration),
-    box-shadow var(--duration);
+    background-color var(--duration);
 }
 
 .switch:hover:not(:disabled) {
@@ -101,28 +120,11 @@
 }
 
 @media (forced-colors: active) {
-  /* --switch-knob must be set on the element, not on ::before: a custom
-     property declared on the pseudo would shadow the :checked override. */
-  .switch {
-    --switch-border: ButtonText;
-    --switch-knob: ButtonText;
-  }
-
+  /* The host intentionally stays under UA control for platform contrast and
+     focus. The custom knob has no native edge, so this system-color border
+     keeps it distinct from the remapped track. If real HCM testing ever needs
+     an opt-out, scope it to ::before—never to the interactive input host. */
   .switch::before {
-    box-shadow: none;
-  }
-
-  .switch:checked {
-    --switch-bg: Highlight;
-    --switch-border: Highlight;
-    --switch-knob: HighlightText;
-    forced-color-adjust: none;
-  }
-
-  .switch:disabled {
-    --switch-bg: Canvas;
-    --switch-border: GrayText;
-    --switch-knob: GrayText;
-    forced-color-adjust: auto;
+    border: var(--border-width) solid ButtonText;
   }
 }

package/src/css/layout/app-shell.css

@@ -0,0 +1,6 @@
+/* Full-height application shell. */
+.app-shell {
+  min-block-size: var(--viewport-block);
+  display: flex;
+  flex-direction: column;
+}

package/src/css/layout/center.css

@@ -0,0 +1,13 @@
+/*
+ * Centered content column with a maximum measure.
+ *
+ * Public hooks:
+ * --center-size
+ * --center-pad
+ */
+.center {
+  box-sizing: content-box;
+  max-inline-size: var(--center-size, 72rem);
+  margin-inline: auto;
+  padding-inline: var(--center-pad, 1rem);
+}

package/src/css/layout/cluster.css

@@ -0,0 +1,21 @@
+/*
+ * Inline group that wraps when space runs out.
+ *
+ * Public hooks:
+ * --cluster-align
+ * --cluster-justify
+ * --cluster-wrap
+ *
+ * Child contract: direct-child margins are reset, spacing comes from --gap.
+ */
+.cluster {
+  display: flex;
+  flex-wrap: var(--cluster-wrap, wrap);
+  align-items: var(--cluster-align, center);
+  justify-content: var(--cluster-justify, flex-start);
+  gap: var(--gap);
+}
+
+.cluster > * {
+  margin: 0;
+}

package/src/css/layout/column-layout.css

@@ -0,0 +1,144 @@
+/*
+ * Explicit 12-column composition canvas.
+ *
+ * Neither space-driven like .grid nor count-driven like .grid-N: this is a
+ * coordinate system. The author places regions with .column-span-N /
+ * .column-start-N and owns narrow-container recomposition. There is
+ * deliberately no automatic collapse — no threshold, no hidden
+ * .container-query behavior, no breakpoint variants. A single framework
+ * threshold cannot be right for arbitrary per-region compositions, and a
+ * hidden default would have to be undone rather than extended.
+ *
+ * See docs/design-notes/column-layout.md.
+ *
+ * Selection — reach for this only when placement is part of the design:
+ *   independent repeated items      -> .grid
+ *   a known peer density            -> .grid-N
+ *   peers switching together        -> .switcher
+ *   content + secondary region      -> .sidebar-layout
+ *   media + flexible content        -> .media
+ *   exact custom track templates    -> --grid-columns on .grid
+ *
+ * Child contract: each direct child is placed on the canvas via its own
+ * .column-span-N / .column-start-N.
+ *
+ * Unlike .grid-N, the track template does not read --gap, so the gap
+ * utilities are exact here at every width.
+ */
+.column-layout {
+  display: grid;
+  gap: var(--gap);
+  grid-template-columns: repeat(12, minmax(0, 1fr));
+}
+
+/* Three zero-specificity tiers, applied in this order and only ever separated
+ * by source order. ORDER IS LOAD-BEARING:
+ *
+ *   1. the child reset       auto-placed, spanning the whole canvas
+ *   2. .column-start-*       a definite start line, running to the canvas end
+ *   3. .column-span-*        the end only, so it refines either of the above
+ *
+ * Moving tier 3 above tier 2 makes every start+span pair run to column 12;
+ * moving either above tier 1 makes every placement full-span. Both failures
+ * are silent. tests/css-audit.test.js locks the order and
+ * tests/browser/column-layout.test.js locks the resulting geometry.
+ *
+ * Zero specificity is the point: an application's own container-query rules
+ * override placement additively, with a single-class selector and without
+ * having to undo framework specificity first.
+ */
+
+/* Tier 1. A child with no placement class stays a readable full-width region
+ * instead of collapsing to one twelfth. Expressed as a span, not as
+ * `1 / -1`: a definite start line would give every child a definite column
+ * position and disable auto-placement, so `.column-span-8` next to
+ * `.column-span-4` would stack instead of composing 8 + 4.
+ *
+ * min-inline-size: 0 keeps the item box inside its track so the canvas never
+ * grows past its container. It does not stop content from painting outside a
+ * narrow track — that distinction is the primitive's contract, not a bug. */
+:where(.column-layout) > * {
+  grid-column-end: span 12;
+  min-inline-size: 0;
+}
+
+/* Tier 2. A definite start line, running to the end of the canvas unless a
+ * .column-span-* refines the end. `column-start-9` alone is therefore the
+ * last four columns rather than an implicit 21-line overflow. */
+:where(.column-start-1) {
+  grid-column: 1 / -1;
+}
+:where(.column-start-2) {
+  grid-column: 2 / -1;
+}
+:where(.column-start-3) {
+  grid-column: 3 / -1;
+}
+:where(.column-start-4) {
+  grid-column: 4 / -1;
+}
+:where(.column-start-5) {
+  grid-column: 5 / -1;
+}
+:where(.column-start-6) {
+  grid-column: 6 / -1;
+}
+:where(.column-start-7) {
+  grid-column: 7 / -1;
+}
+:where(.column-start-8) {
+  grid-column: 8 / -1;
+}
+:where(.column-start-9) {
+  grid-column: 9 / -1;
+}
+:where(.column-start-10) {
+  grid-column: 10 / -1;
+}
+:where(.column-start-11) {
+  grid-column: 11 / -1;
+}
+:where(.column-start-12) {
+  grid-column: 12 / -1;
+}
+
+/* Tier 3. The end only. Combined with a start, keep the placement inside the
+ * canvas: S + N - 1 <= 12. Exceeding it adds an auto-sized implicit column,
+ * which reshapes every 1fr track — the whole canvas loses its alignment, not
+ * just the offending region. */
+:where(.column-span-1) {
+  grid-column-end: span 1;
+}
+:where(.column-span-2) {
+  grid-column-end: span 2;
+}
+:where(.column-span-3) {
+  grid-column-end: span 3;
+}
+:where(.column-span-4) {
+  grid-column-end: span 4;
+}
+:where(.column-span-5) {
+  grid-column-end: span 5;
+}
+:where(.column-span-6) {
+  grid-column-end: span 6;
+}
+:where(.column-span-7) {
+  grid-column-end: span 7;
+}
+:where(.column-span-8) {
+  grid-column-end: span 8;
+}
+:where(.column-span-9) {
+  grid-column-end: span 9;
+}
+:where(.column-span-10) {
+  grid-column-end: span 10;
+}
+:where(.column-span-11) {
+  grid-column-end: span 11;
+}
+:where(.column-span-12) {
+  grid-column-end: span 12;
+}

package/src/css/layout/container-query.css

@@ -0,0 +1,13 @@
+/* Local container-query opt-in: establishes an inline-size query context for
+   descendants. Use it for a component that changes representation according
+   to its allocated inline size, and to opt .grid-N into balanced subdivision
+   (see grid.css). Layout primitives are responsive without it — this adds
+   precision, it is never a prerequisite.
+
+   The element takes inline-size containment, so put it on a normal
+   block-level wrapper, never on a shrink-to-fit item (a .cluster child, a
+   float, an inline-block): its contents would stop contributing to its own
+   inline size and it would collapse. */
+.container-query {
+  container-type: inline-size;
+}