actual-css 0.3.0 → 0.4.0

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;
+}

package/src/css/layout/frame.css

@@ -0,0 +1,19 @@
+/*
+ * Media frame with a fixed ratio.
+ *
+ * Public hooks:
+ * --frame-ratio
+ *
+ * Child contract: direct media children (img/video/iframe/canvas/svg) are
+ * sized to fill the frame.
+ */
+.frame {
+  overflow: hidden;
+  aspect-ratio: var(--frame-ratio, 16 / 9);
+}
+
+.frame > :where(img, video, iframe, canvas, svg) {
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+}

package/src/css/layout/grid.css

@@ -0,0 +1,141 @@
+/*
+ * Responsive equal-width grids.
+ *
+ * .grid is space-driven: it fits as many tracks as --grid-min allows.
+ * .grid-N is count-driven: it declares a structural density of N and collapses
+ * through natural divisors of N (see the subdivision block below).
+ *
+ * Public hooks:
+ * --grid-min
+ * --grid-columns
+ *
+ * Internal:
+ * --grid-count
+ *
+ * Child contract: each direct child is a grid item placed in the tracks the
+ * recipe generates.
+ */
+
+/* --grid-columns replaces the intrinsic auto-fit template: once set, the
+   grid no longer collapses on its own — the author owns narrow-container
+   collapse. Prefer .sidebar-layout for content + aside layouts; reserve
+   --grid-columns for exact custom track templates. */
+
+/* Recipe:
+   - collection whose item width is the contract -> .grid, tune --grid-min
+   - collection whose column density is the contract -> .grid-2/3/4/6
+   - balanced subdivision of that density -> wrap it in .container-query
+   - peer regions that switch as a group -> .switcher
+   - content + aside -> .sidebar-layout
+   - exact custom track templates -> --grid-columns with an explicit collapse
+     rule of your own */
+.grid {
+  display: grid;
+  gap: var(--gap);
+  grid-template-columns: var(
+      --grid-columns,
+      repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr))
+    );
+}
+
+/* Structural density presets. The baseline is an auto-fill grid bounded at N
+   tracks: responsive and overflow-safe on its own, so a preset used without a
+   query container is never a trap — it simply reaches its balanced states less
+   precisely. auto-fill rather than auto-fit keeps item width stable when a
+   partial final page holds fewer items than the grid's capacity.
+
+   --grid-min is deliberately NOT read here. The subdivision below runs on
+   @container thresholds, which cannot resolve a custom property, so a hook
+   honored in the baseline would fall silent the moment a query container is
+   added. Item width is .grid's contract; column density is .grid-N's. */
+:where(.grid-2, .grid-3, .grid-4, .grid-6) {
+  display: grid;
+  gap: var(--gap);
+  grid-template-columns: repeat(
+      auto-fill,
+      minmax(
+        min(
+          100%,
+          max(16rem, calc((100% - (var(--grid-count) - 1) * var(--gap)) / var(--grid-count)))
+        ),
+        1fr
+      )
+    );
+}
+
+.grid-2 {
+  --grid-count: 2;
+}
+.grid-3 {
+  --grid-count: 3;
+}
+.grid-4 {
+  --grid-count: 4;
+}
+.grid-6 {
+  --grid-count: 6;
+}
+
+/* Grid items keep an automatic minimum inline size (min-content), which can
+   overflow a track sized minmax(0, 1fr). Layout primitives remove that
+   intrinsic floor so their overflow-safe track sizing holds; authors only
+   need .min-inline-size-0 outside primitives that do not already remove this
+   floor. */
+:where(.grid, .grid-2, .grid-3, .grid-4, .grid-6) > * {
+  min-inline-size: 0;
+}
+
+/* Balanced subdivision, opted into by an ancestor query container.
+ *
+ *   .grid-2   2 -> 1
+ *   .grid-3   3 -> 1
+ *   .grid-4   4 -> 2 -> 1
+ *   .grid-6   6 -> 3 -> 2 -> 1
+ *
+ * Every state is a divisor of N, so all items keep the same width and no
+ * state produces a visibly uneven split such as 5 + 1 or 4 + 2. Intermediate
+ * counts are skipped on purpose: do not "complete" these chains with the
+ * missing integers, and do not replace them with an unbounded auto-fit.
+ *
+ * The query container must be an ancestor. An element cannot query its own
+ * size without taking inline-size containment, which destroys its intrinsic
+ * inline contribution and collapses it inside .cluster, .topbar, floats, and
+ * any shrink-to-fit box. See docs/design-notes/grid.md.
+ *
+ * Three shared thresholds, not one calibrated per preset: 28rem opens the
+ * first horizontal density, 48rem opens three columns, 64rem opens the dense
+ * 4 and 6. N already carries the author's statement about item size, so
+ * tuning every step to land the same item width would erase that signal —
+ * .grid-6 at 64rem gives ~161px per tile, which is the point of choosing it.
+ * Probed with the content each preset targets: large cards for .grid-2 down
+ * to stats, avatars, and thumbnails for .grid-6.
+ *
+ * Ascending min-width only: the last matching step wins by cascade order.
+ */
+@supports (container-type: inline-size) {
+  .container-query :where(.grid-2, .grid-3, .grid-4, .grid-6) {
+    grid-template-columns: 1fr;
+  }
+
+  @container (min-width: 28rem) {
+    .container-query :where(.grid-2, .grid-4, .grid-6) {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+
+  @container (min-width: 48rem) {
+    .container-query :where(.grid-3, .grid-6) {
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+  }
+
+  @container (min-width: 64rem) {
+    .container-query :where(.grid-4) {
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+
+    .container-query :where(.grid-6) {
+      grid-template-columns: repeat(6, minmax(0, 1fr));
+    }
+  }
+}

package/src/css/layout/index.css

@@ -0,0 +1,42 @@
+/*
+ * Layout — composition primitives. Readable cascade order: container-query
+ * first (a local opt-in, unrelated to the primitives), then the primitives.
+ *
+ * Selection:
+ * .stack          vertical flow
+ * .cluster        wrapping inline group
+ * .center         centered content column
+ * .frame          fixed-ratio media frame
+ * .app-shell      full-height application shell
+ * .media          fixed media + flexible content
+ * .switcher       peer regions: all horizontal or all stacked
+ * .sidebar-layout main content + secondary aside
+ * .grid           responsive collection; item width is the contract
+ * .grid-N         structural density of N; wrap in .container-query for
+ *                 balanced subdivision (in grid.css)
+ * .column-layout  explicit 12-column region composition; the author owns
+ *                 narrow-container recomposition
+ * .scroller       theme-aware scrollbar density and colour
+ * .scroll-snap    snap rails
+ * .scroll-target  anchor scroll offset for sticky headers
+ * .topbar         sticky app-shell top bar
+ * .measure        readable content measure cap
+ *
+ * Prefer these compositions over viewport breakpoint utilities.
+ */
+@import "./container-query.css";
+@import "./stack.css";
+@import "./cluster.css";
+@import "./center.css";
+@import "./frame.css";
+@import "./app-shell.css";
+@import "./media.css";
+@import "./switcher.css";
+@import "./sidebar-layout.css";
+@import "./grid.css";
+@import "./column-layout.css";
+@import "./scroller.css";
+@import "./scroll-snap.css";
+@import "./scroll-target.css";
+@import "./topbar.css";
+@import "./measure.css";

package/src/css/layout/measure.css

@@ -0,0 +1,9 @@
+/* Readable content measure. Composes with .center for centering or with
+   margin-inline: auto for a one-off centered block.
+ *
+ * Public hooks:
+ * --measure
+ */
+.measure {
+  max-inline-size: var(--measure, 70ch);
+}

package/src/css/layout/media.css

@@ -0,0 +1,10 @@
+/* Media object: fixed-width leading element (avatar, icon, image) + flexible
+   trailing content. Replaces the repeated "auto minmax(0, 1fr)" pattern in
+   author cards, comments, meta rows, and similar compositions.
+   Child contract: exactly two direct children (leading media + content). */
+.media {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: var(--gap);
+  align-items: start;
+}

package/src/css/layout/scroll-target.css

@@ -0,0 +1,15 @@
+/* Anchor scroll offset. A #hash link or scrollIntoView() places the target
+ * flush at the scroll container's start edge, which hides it behind a sticky
+ * header (.topbar) or underlaps it; scroll-margin reserves space on the
+ * target itself so the browser stops early.
+ *
+ * Apply to the elements that are link targets: <section id="...">, headings,
+ * etc. The scrollspy enhancer only reads ids — this offset is what actually
+ * shapes where the page lands, and the two are independent.
+ *
+ * Public hooks:
+ * --scroll-target-offset
+ */
+.scroll-target {
+  scroll-margin-block-start: var(--scroll-target-offset, var(--space-60));
+}

package/src/css/layout/scroller.css

@@ -0,0 +1,41 @@
+/*
+ * Scroller — optional scrollbar treatment for overflow regions.
+ *
+ * Apply to any scroll container (.overflow-auto, sidebars, long tables). Only
+ * the standard properties are used: the engine keeps drawing the scrollbar,
+ * this hands it the theme's density and colour. No ::-webkit-scrollbar chrome —
+ * rebuilding a thumb by hand means re-implementing the hover, the corner and
+ * the light/dark adaptation that color-scheme already gives for free, and the
+ * two never match anyway.
+ *
+ * Above the capability floor: scrollbar-color lands in Chromium 121 and
+ * Safari 18.2, the floor is Chromium 99 / Safari 15.4. Older engines ignore
+ * both declarations and draw their native scrollbar — the intended fallback,
+ * not a broken state.
+ *
+ * Styles the scrollbar only; it does not create the overflow. Pair it with
+ * .overflow-auto or a component that already scrolls.
+ *
+ * Public hooks:
+ * --scroller-track
+ * --scroller-thumb
+ */
+.scroller {
+  --scroller-track: transparent;
+  --scroller-thumb: var(--border);
+
+  scrollbar-color: var(--scroller-thumb) var(--scroller-track);
+  scrollbar-width: thin;
+}
+
+/* Opt-in gutter: reserves space so the layout does not shift when
+   the scrollbar appears. Use alongside a known-overflow container. */
+.scroller.stable-gutter {
+  scrollbar-gutter: stable;
+}
+
+@supports (color: color-mix(in oklch, red, white)) {
+  .scroller {
+    --scroller-thumb: color-mix(in oklch, var(--text-muted), transparent 55%);
+  }
+}

package/src/css/layout/sidebar-layout.css

@@ -0,0 +1,31 @@
+/*
+ * Main content + secondary region.
+ *
+ * The children wrap according to the space allocated to this layout, without
+ * an ancestor opt-in or viewport threshold. The large growth ratio lets the
+ * main region reclaim the full row when the aside wraps instead of remaining
+ * at its minimum viable width.
+ *
+ * Public hooks:
+ * --sidebar-content-min
+ * --sidebar-layout-size
+ *
+ * Child contract: the first and last direct children carry the sizing roles.
+ */
+.sidebar-layout {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gap);
+  align-items: flex-start;
+}
+
+.sidebar-layout > :first-child {
+  flex-basis: 0;
+  flex-grow: 999;
+  min-inline-size: min(100%, var(--sidebar-content-min, 30rem));
+}
+
+.sidebar-layout > :last-child {
+  flex-basis: var(--sidebar-layout-size, 18rem);
+  flex-grow: 1;
+}

package/src/css/layout/stack.css

@@ -0,0 +1,21 @@
+/* Vertical flow. .stack owns the block axis only: block margins reset, inline
+   margins stay free (self-centering children via margin-inline: auto keep
+   working).
+   Child contract: direct children become flex items; margins reset, spacing
+   comes from --gap.
+
+   --gap is inherited, so a container that composes other primitives sets its
+   own rhythm on the `gap` property, not on the token: setting --gap on a
+   region re-spaces every nested stack, cluster and grid at any depth. Setting
+   the token stays correct on the element that consumes it, and .sm/.lg set it
+   deliberately so a density context reaches nested layouts. See
+   docs/pages/layout/stack.md. */
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap);
+}
+
+.stack > * {
+  margin-block: 0;
+}

package/src/css/layout/switcher.css

@@ -0,0 +1,23 @@
+/*
+ * Peer regions that switch as a group.
+ *
+ * All children sit side by side when they all fit; otherwise every child
+ * stacks. Unlike .grid, this recipe cannot create a partial row such as two
+ * items plus one orphan.
+ *
+ * Public hooks:
+ * --switcher-threshold
+ *
+ * Child contract: every direct child is a peer; the flex-basis applies to all.
+ */
+.switcher {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--gap);
+}
+
+.switcher > * {
+  flex-basis: calc((var(--switcher-threshold, 40rem) - 100%) * 999);
+  flex-grow: 1;
+  min-inline-size: 0;
+}

package/src/css/{optional/layout-extra.css → layout/topbar.css}

@@ -1,23 +1,3 @@
-/*
- * Additional layout primitives not included in the core bundle.
- *
- * Import this file explicitly when a project needs these patterns.
- *
- * Public hooks:
- * --switcher-threshold
- */
-.switcher {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--gap);
-}
-
-.switcher > * {
-  flex-basis: calc((var(--switcher-threshold, 40rem) - 100%) * 999);
-  flex-grow: 1;
-  min-inline-size: 0;
-}
-
 /*
  * Sticky, frosted top bar shell for app/dashboard shells (persistent
  * sidebar + topbar layouts). Owns positioning, stacking, and the frosted