actual-css 0.3.1 → 0.4.1

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-layout.css

@@ -0,0 +1,102 @@
+/*
+ * Specialized application shell recipe: one exact DOM structure uses a
+ * bottom navigation bar when narrow and a labelled side navigation when space
+ * permits. The main region owns scrolling, keeping both pieces of application
+ * chrome available without fixed offsets. This is not a generic page wrapper
+ * or a public-site layout; all three direct regions are part of the contract.
+ *
+ * Public hook:
+ * --app-nav-side-size
+ */
+.app-layout {
+  --app-nav-side-size: 12rem;
+
+  display: grid;
+  grid-template:
+    "topbar" auto
+    "main" minmax(0, 1fr)
+    "nav" auto
+    / minmax(0, 1fr);
+  block-size: var(--viewport-block);
+  min-inline-size: 0;
+  overflow: hidden;
+}
+
+.app-layout > .topbar {
+  grid-area: topbar;
+  padding-block-start: calc(var(--space-30) + env(safe-area-inset-top));
+}
+
+.app-layout > .app-main {
+  grid-area: main;
+  min-inline-size: 0;
+  min-block-size: 0;
+  overflow: auto;
+}
+
+.app-layout > .app-nav {
+  grid-area: nav;
+}
+
+/* The main grid area keeps the FAB clear of bottom navigation without making
+   either component copy the other's geometry. */
+.app-layout > .fab {
+  position: relative;
+  grid-area: main;
+  place-self: end;
+  inset: auto;
+  margin: var(--fab-offset);
+}
+
+@media (min-width: 48rem) {
+  .app-layout {
+    grid-template:
+      "nav topbar" auto
+      "nav main" minmax(0, 1fr)
+      / var(--app-nav-side-size) minmax(0, 1fr);
+  }
+
+  .app-layout > .app-nav {
+    position: sticky;
+    inset-block: 0;
+    grid-auto-flow: row;
+    grid-auto-rows: minmax(var(--control-size-lg), auto);
+    grid-auto-columns: auto;
+    align-content: start;
+    gap: var(--space-20);
+    min-block-size: 0;
+    padding-block: max(var(--space-20), env(safe-area-inset-top))
+      max(var(--space-20), env(safe-area-inset-bottom));
+    padding-inline: var(--space-20);
+    border-block-start: 0;
+    border-inline-end: var(--border-width) solid var(--ui-border, var(--border));
+  }
+
+  .app-layout > .app-nav > a {
+    grid-template-rows: auto;
+    grid-template-columns: 1.5rem minmax(0, 1fr);
+    place-content: center start;
+    align-items: center;
+    justify-items: start;
+    gap: var(--space-30);
+    padding-inline: var(--space-30);
+    text-align: start;
+  }
+
+  /* Side navigation no longer occupies the viewport's bottom safe area. */
+  .app-layout > .fab {
+    margin-block-end: max(var(--fab-offset), env(safe-area-inset-bottom));
+  }
+}
+
+@media print {
+  .app-layout {
+    display: block;
+    block-size: auto;
+    overflow: visible;
+  }
+
+  .app-layout > .app-main {
+    overflow: visible;
+  }
+}

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

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

package/src/css/layout/center.css

@@ -0,0 +1,14 @@
+/*
+ * Centered content column with a maximum measure.
+ *
+ * Public hooks:
+ * --center-size
+ * --center-pad
+ */
+.center {
+  box-sizing: content-box;
+  inline-size: calc(100% - var(--center-pad, 1rem) * 2);
+  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,15 @@
+/* Convenience helper: establishes a query container named actual-grid for
+   descendants. Use it for a component that changes representation according
+   to its allocated inline size, and to give .grid-N the named context it needs
+   for balanced subdivision (see grid.css). The name matters: grids only respond
+   to an explicitly actual-grid-named container, never to an incidental
+   query container. 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: actual-grid / 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,155 @@
+/*
+ * 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 -> place it inside any size query
+     container (.container-query is the convenience helper for that context)
+   - 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, activated by an ancestor container named actual-grid.
+ * A .grid-N inside such a container enters only divisor states of N. The name
+ * is deliberate: a grid must not key off the nearest anonymous query container,
+ * or a region that sets container-type: inline-size for an unrelated reason
+ * would silently change the grid. The author opts the grid in by naming the
+ * context — .container-query is the official helper, or declare
+ * container: actual-grid / inline-size on your own region.
+ *
+ *   .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.
+ *
+ * Without an actual-grid ancestor none of these @container rules resolve, so
+ * the auto-fill baseline above stays. The min-width: 0 rule is the lowest
+ * step: it pins the grid to one column inside a container before any larger
+ * threshold fires (a bare grid would otherwise show a 2 + 1 orphan at 28-48rem).
+ *
+ * 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 actual-grid (min-width: 0px) {
+    :where(.grid-2, .grid-3, .grid-4, .grid-6) {
+      grid-template-columns: 1fr;
+    }
+  }
+
+  @container actual-grid (min-width: 28rem) {
+    :where(.grid-2, .grid-4, .grid-6) {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+
+  @container actual-grid (min-width: 48rem) {
+    :where(.grid-3, .grid-6) {
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+  }
+
+  @container actual-grid (min-width: 64rem) {
+    :where(.grid-4) {
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+
+    :where(.grid-6) {
+      grid-template-columns: repeat(6, minmax(0, 1fr));
+    }
+  }
+}

package/src/css/layout/index.css

@@ -0,0 +1,44 @@
+/*
+ * 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
+ * .app-layout     topbar + scrolling main + bottom/side app navigation
+ * .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; balanced inside a container named
+ *                  actual-grid (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 "./app-layout.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));
+}