@codenhub/styles 0.4.0 → 0.6.0

package/dist/tw/presentation.css

@@ -1,22 +1,17 @@
+/* Imported into the `components` layer by `theme.css`, below every utility, so
+   a consumer's own utility or unlayered CSS beats these classes. See
+   docs/internal/model.md#cascade-layers. */
+
 /* Presentation answers two independent questions, and each is its own closed
    set: how much of the intent color fills the box, and whether the box draws a
    line at its boundary. Exactly one value from each set applies, so the six
    combinations are the whole vocabulary.
 
-   A fill class never decides an edge and an edge class never decides a fill.
-   `.solid` briefly broke that rule, writing `--ui-border: 0%` alongside its fill
-   so that a filled box could not be ringed in another colour. It bought a real
-   fix -- the edge blend runs the line toward the fill, which lands *on* the fill
-   when the fill is opaque and on a second coat of the same tint when it is not,
-   so every capped intent that drew a line drew a visible ring over its own plate
-   -- at the cost of the one property that makes the six combinations readable:
-   that each half means only what it says. Two axes that are independent in two
-   cases out of three are not axes.
-
-   The ring is a fault in the blend rather than in the class, and it is recorded
-   as such: `.solid.edged` on a capped intent measures 1.53:1 against its own
-   plate in light and 1.82:1 in dark. `.solid.edgeless` is how a consumer asks
-   for a filled box with no line.
+   A fill class never decides an edge and an edge class never decides a fill, so
+   each half means only what it says. The line fades toward `transparent` as the
+   fill fills in (`box.css`; docs/internal/model.md#presentation), so
+   `.solid.edged` and `.solid.edgeless` render one box without either class
+   deciding the other's question.
 
    Presentation declares only unitless numbers and percentages. A custom
    property's value is resolved on the element that declares it, so anything
@@ -28,8 +23,8 @@
    container set the look for its subtree while any element still opts out.
 
    Hover is derived from these values rather than declared beside them:
-   `min(100%, resting fill + --hover-step)`, always in `--intent-hover`. There is
-   no hover token and no per-presentation branch. */
+   `min(100%, resting fill + --hover-step)`, always in `--intent-hover`. There
+   is no hover token and no per-presentation branch. */
 
 /* Filled with the intent color. Text is the contrast tone. */
 .solid {
@@ -43,11 +38,9 @@
   --ui-fg-on-fill: 0%;
 }
 
-/* No fill at rest; the derived hover gives it one. Text is the intent color.
-
-   Named `.ghost` rather than `.bare` because `.bare` and `.edgeless` both read
-   as "less of something", so an author wanting no border reached for `.bare`
-   first and got no background instead. `.ghost` says fill and only fill.
+/* No fill at rest; the derived hover gives it one. Text is the intent color. It
+   names a fill and only a fill: `.bare` and `.edgeless` both read as "less of
+   something", so an author wanting no border would reach for the wrong one.
 
    A component that rests on a ground rather than on nothing keeps that ground
    here: `.ghost` is zero fill, not zero paint. `.data-table` is the exception
@@ -57,16 +50,14 @@
   --ui-fg-on-fill: 0%;
 }
 
-/* A line in the intent color, at the aesthetic's material width. The width comes
-   from the aesthetic and nothing else: there is no presentation scale on it, so
-   small components need no ceilings to survive a thick one.
+/* A line in the intent color, at the aesthetic's material width. The width
+   comes from the aesthetic and nothing else: there is no presentation scale on
+   it, so small components need no ceilings to survive a thick one.
 
    The edge is the silhouette and nothing else. Rules *inside* a component that
-   has an inside are a separate decision with its own class -- `.data-table.ruled`
-   -- because tying them here made them arrive by implication: a table drew rules
-   only because its published edge default happened to be `edged`, so whether a
-   consumer got them depended on a default they had not read and could not name.
-   Two questions, two switches. */
+   has an inside are a separate decision with their own class --
+   `.data-table.ruled` -- so a consumer's own markup says whether they asked for
+   them. */
 .edged {
   --ui-border: 100%;
 }

package/dist/tw/reset.css

@@ -3,13 +3,12 @@
 @import "./typography.css";
 
 @layer base {
-  /* The package's own components no longer lean on this: `@utility box` sets
+  /* The package's own components do not lean on this: `@utility box` sets
      `box-sizing: border-box` on itself, so a sized control is right in every
      entrypoint including the reset-less `/components` and granular `/tw/*`
-     ones. What is left for the universal rule is the consumer's own markup --
-     a plain `<div>` laid out beside our components under the full reset -- so
-     it stays part of the opinionated baseline the reset already is, rather
-     than a correctness prop the components need. */
+     ones. The universal rule covers the consumer's own markup -- a plain
+     `<div>` laid out beside our components -- as part of the opinionated
+     baseline. */
   *,
   *::before,
   *::after {
@@ -52,12 +51,16 @@
     margin: 0;
   }
 
+  /* The whole font, not only the family: the user agent gives a button and a
+     field their own smaller size, so a `<button>`, a `.btn` link, and the
+     same `.btn` on another entrypoint each printed a different label size.
+     Tailwind's Preflight does the same on the entries that carry it. */
   button,
   input,
   optgroup,
   select,
   textarea {
-    font-family: inherit;
+    font: inherit;
   }
 
   button,
@@ -72,9 +75,20 @@
     color: var(--color-primary-contrast);
   }
 
+  /* Negative, so the ring is drawn over the edge rather than beside it: at a
+     positive offset the outline floats a gap away and reads as a second,
+     detached frame around the control. Pulled in by exactly the line width the
+     aesthetic draws, the ring lands on top of the line and a focused control
+     reads as its own edge thickening -- which is what a focus indicator is
+     meant to look like. Computed here, on the focused element, because that is
+     where an aesthetic's `--ui-border-width` resolves; `--focus-ring-offset`,
+     when a consumer sets it, still wins.
+
+     A component drawing no line at rest loses nothing: the outline moves inward
+     over its own fill by a hairline, which is not a visible change. */
   :focus-visible {
     outline: var(--focus-ring-width) solid var(--focus-ring);
-    outline-offset: var(--focus-ring-offset);
+    outline-offset: var(--focus-ring-offset, calc(-1 * var(--ui-border-width, var(--border-width))));
   }
 
   @media (forced-colors: active) {
@@ -127,24 +141,3 @@
     border-color: CanvasText;
   }
 }
-
-/* The user agent already promises both of these for a native `<dialog>` --
-   `dialog:not([open]) { display: none }` and a centered `margin: auto` on the
-   open box -- but both are user-agent origin, which loses to any author rule
-   at all. `.card`'s own `display: block` (`surface`'s `@apply box block`)
-   beats the first outright, so a `<dialog class="card">` renders open with no
-   `open` attribute and no `.showModal()` call -- the registry has no
-   dialog/modal component of its own, and `.card` is the closest primitive a
-   consumer reaches for. A margin reset on every element -- Tailwind's own
-   Preflight on the entries that carry it -- beats the second, so an opened
-   dialog pins to the top-left instead of centering. Restated here, unlayered like
-   the block above, for the same reason: a behavior override has to win over
-   any layered rule whatever the specificity, and `.card` is layered in the
-   utilities layer regardless of how it composes `box`. */
-dialog:not([open]) {
-  display: none;
-}
-
-dialog[open] {
-  margin: auto;
-}

package/dist/tw/surface.css

@@ -0,0 +1,61 @@
+@reference "./box.css";
+
+/* What every surface shares. Two slots exist here and nowhere else, and that is
+   how an aesthetic reaches surfaces without naming one: only a surface resolves
+   `--ui-backdrop`, so glass blurs cards and panels while controls stay solid,
+   and only a surface resolves `--ui-surface-shadow`, so a two-layer drop shadow
+   does not land under every button on the page.
+
+   A primitive beside `box`, and like `box` it imports neither the theme nor
+   Tailwind: `feedback.css` and `tooltip.css` `@reference` it, and a referenced
+   file that reaches the theme strips its tokens from every entry that pulls it
+   in. See docs/internal/model.md (Which files import the theme). */
+@utility surface {
+  @apply box block;
+
+  /* Bare and edged. `box` reads these three with no fallback, so `surface` --
+     typeable on its own -- owes all three; `card` restates its own. No shadow
+     geometry: depth is asked for (`.raised`/`.floating`, an aesthetic, the
+     registry elevation) rather than carried, so a plain card is flat. */
+  --_d-fill: 0%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 100%;
+
+  /* The public token first, so an aesthetic (glass's translucent ground) or a
+     consumer names the ground outright; then the component's own quiet default,
+     which `.card.soft`, a neutral `.panel`, and a neutral `.alert` write as a
+     private rather than as the public token. Written as the public token, their
+     own declaration would beat glass's inherited one in a glass region, and
+     beat glass on the same element too (`.card.soft.glass` would go opaque).
+     Restated `initial` here so a quiet ground cannot inherit into a surface
+     nested inside one, the way `box` restates `--_d-ground`. See
+     docs/internal/model.md#cascade-layers. */
+  --_d-surface-ground: initial;
+  --_d-ground: var(--ui-surface-ground, var(--_d-surface-ground, var(--color-background)));
+
+  /* The complete-shadow slot for a shadow that is not one layer (glass tucks two
+     under with negative spread). Only `surface` reads it -- through `--ui-shadow`
+     it would land an 18px drop under every button and chip -- like the backdrop. */
+  --_shadow: var(--ui-surface-shadow, var(--_shadow-parts)) var(--_halo-layer,);
+
+  /* The surface pair of `box`'s corner: the aesthetic's surface length, scaled
+     by the padding step and patterned by the same four corner switches. */
+  --_corner-surface: calc(var(--ui-corner-surface, var(--radius-surface)) * var(--_scale));
+  border-radius: var(
+    --ui-radius-surface,
+    calc(var(--_corner-surface) * var(--ui-corner-tl, 1)) calc(var(--_corner-surface) * var(--ui-corner-tr, 1))
+      calc(var(--_corner-surface) * var(--ui-corner-br, 1)) calc(var(--_corner-surface) * var(--ui-corner-bl, 1))
+  );
+  /* The painted layer: a pattern, a texture, or a gradient an aesthetic lays
+     over the plate. Surfaces only, like the backdrop, so a control's label and
+     `.select`'s chevron never sit on one. The aesthetic that sets it owns the
+     contrast of the text over it, and a consumer's own `background-image` still
+     beats this declaration. */
+  background-image: var(--ui-surface-image, none);
+  /* Prefixed property first, deliberately: written second the minifier folds the
+     pair into the prefixed one alone, and the standard property never reaches
+     `dist/` -- which drops the blur in Firefox (the one engine with
+     `backdrop-filter` and not the `-webkit-` alias). Measured on the built CSS. */
+  -webkit-backdrop-filter: var(--ui-backdrop, none);
+  backdrop-filter: var(--ui-backdrop, none);
+}

package/dist/tw/theme.css

@@ -1,7 +1,18 @@
-@import "tailwindcss/theme.css";
-@import "./intent.css";
-@import "./presentation.css";
-@import "./elevation.css";
+/* The package's layer map, declared before anything uses a layer. A browser
+   orders layers by the first time it meets each name, so a sheet that opened
+   `components` first would rank it below `theme` and `base`; stating Tailwind's
+   own order here, and at the top of every entrypoint, makes every load order
+   rank the same. The four class families -- intent, presentation, elevation,
+   and every aesthetic -- sit in `components`, below every utility, so a
+   consumer's own utility or unlayered CSS beats them. Components are
+   `@utility` rules in `utilities`. See docs/internal/model.md#cascade-layers. */
+@layer theme, base, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "./intent.css" layer(components);
+@import "./presentation.css" layer(components);
+@import "./elevation.css" layer(components);
+@import "./corner.css" layer(components);
 /* Everything that is not `src/` -- see the note in `index.css`. Keeps a
    `--color-*` reference in a docs example from shipping as a real theme entry. */
 
@@ -24,30 +35,22 @@
   --color-accent-hover: light-dark(var(--color-neutral-700), var(--color-neutral-300));
   --color-accent-subtle: light-dark(var(--color-neutral-100), var(--color-neutral-800));
   --color-accent-strong: light-dark(var(--color-neutral-800), var(--color-neutral-200));
-  /* Light was neutral-300 (1.42:1 against the page, already under 3:1 by the
-     text-control comment below) until a `.card.soft.edged` measured its own
-     border against its own fill rather than against the page: 12% of
-     `--intent-color` mixed into the ground and a line resolving to nearly the
-     same tone landed the two 4 RGB units apart, which reads as no boundary at
-     all. Dark's neutral-700 pairing already separated -- 27 units, still under
-     3:1 but at least legible -- so only light moved. Neutral-400 is not a new
-     number: `.chunky-tile` already measured it at 2.48:1 against the light
-     page and picked it for the same reason, "the heaviest grey that still
-     leaves a field legible." Dark is unchanged. */
+  /* Neutral-400 in light: the heaviest grey that still leaves a field legible
+     (2.48:1 against the page). A lighter line lands within a few RGB units of a
+     `.card.soft.edged`'s own fill and reads as no boundary. Dark's neutral-700
+     already separates (27 units). */
   --color-border: light-dark(var(--color-neutral-400), var(--color-neutral-700));
 
   /* A text control's line is the only thing identifying it: the box is
      transparent at rest, so nothing else marks where typing goes.
-     `--color-border` is neutral-300/700 and measures 1.42:1 on the light page,
-     which is a line you can barely see.
+     `--color-border` is the quiet surface line, too light for that.
 
-     One value rather than a `light-dark()` pair, and that is the point: the page
-     is neutral-50 in light and neutral-950 in dark, so a tone halfway between
-     them reads on both grounds at once. A text control draws it at
-     `--_line-rest` rather than whole, which is what keeps the field quiet while
-     leaving the pointer somewhere to go -- so the line as painted lands under
-     the 3:1 WCAG 1.4.11 asks of a control boundary. Recorded in
-     docs/accessibility.md. */
+     One value rather than a `light-dark()` pair: the page is neutral-50 in
+     light and neutral-950 in dark, so a tone halfway between them reads on both
+     grounds at once. A text control draws it at `--_line-rest` rather than
+     whole, which keeps the field quiet while leaving the pointer somewhere to
+     go, so the line as painted lands under the 3:1 WCAG 1.4.11 asks of a
+     control boundary. Recorded in docs/accessibility.md. */
   --color-control-border: var(--color-neutral-500);
   --color-background: light-dark(var(--color-neutral-50), var(--color-neutral-950));
   --color-foreground: light-dark(var(--color-neutral-100), var(--color-neutral-900));
@@ -57,40 +60,30 @@
   --color-text-contrast: light-dark(var(--color-neutral-50), var(--color-neutral-950));
   --color-text-hover: light-dark(var(--color-neutral-700), var(--color-neutral-200));
   /* No `--color-text-subtle`: the neutral intent points `--intent-subtle` at
-     `--color-surface`, not at a text-family tint, so the slot the other families
-     fill had no reader here. */
+     `--color-surface`, not at a text-family tint. */
   --color-text-strong: light-dark(var(--color-neutral-900), var(--color-neutral-100));
 
-  /* The tooltip bubble is the one component whose plate is chosen rather than
-     derived. Everything else composes its ground from the intent, and for the
-     bubble that produced the same 20% of the page's ink in both themes -- which
-     steps *lighter* than the surface on a dark page and *darker* on a light one.
-     Dark got the conventional reading, a floating thing lifted off its page;
-     light got a mid-grey slab two steps darker than every card on the screen,
-     carrying dark ink. Measured, the light bubble was neutral-400 at 2.01:1
-     against the page while the dark one was 2.27:1 the other way.
+  /* The tooltip bubble's plate is chosen per theme rather than derived: 20% of
+     the page's ink over the surface tone steps lighter than the surface on a
+     dark page and darker on a light one, and one derivation cannot serve both
+     directions. Both ends read as lifted: near-white over a light page, a mid
+     grey over a dark one.
 
-     One derivation cannot serve both directions, so the pair is stated. Both
-     ends read as lifted: near-white over a light page, a mid grey over a dark
-     one. Near-white is only 1.04:1 against the page, so the bubble draws a
-     hairline as well -- see `components/tooltip.css`. */
+     Near-white is only 1.04:1 against the page, so the bubble draws a hairline
+     as well -- see `components/tooltip.css`. */
   --color-tooltip: light-dark(var(--color-white), var(--color-neutral-700));
   --color-tooltip-contrast: light-dark(var(--color-neutral-900), var(--color-neutral-100));
 
-  /* Emerald-700 rather than 600. A filled button's label is normal-size text, so
-     WCAG 1.4.3 asks 4.5:1, and white on emerald-600 measures 3.50:1 -- it passed
-     only as large text, which `.btn` is not. One step darker carries the white
-     label and leaves the hue where it was. */
+  /* Emerald-700 rather than 600: a filled button's label is normal-size text
+     (WCAG 1.4.3 asks 4.5:1), and white on emerald-600 measures 3.50:1. */
   --color-success: var(--color-emerald-700);
   --color-success-contrast: var(--color-neutral-50);
-  /* Baked rather than mixed live. `box-hover` nests this token two `color-mix()`
-     levels deeper to compose the fill and the edge, and three levels of
-     `color-mix()` over a `light-dark()` crashes the WebKit renderer outright on
-     hover. Confirmed on all four semantic intents, not only this one. Each
-     pinned pair below is
-     `color-mix(in srgb, <base> 82%, <strong>)`, resolved once per theme and
-     screenshotted back so the blend stays exact; re-bake it if the base or
-     strong tone it was mixed from changes. */
+  /* Baked rather than mixed live: `box-hover` nests this token two
+     `color-mix()` levels deeper to compose the fill and the edge, and three
+     levels of `color-mix()` over a `light-dark()` crash the WebKit renderer on
+     hover. Each pinned pair below is `color-mix(in srgb, <base> 82%,
+     <strong>)`, resolved once per theme; re-bake it if the base or strong tone
+     it was mixed from changes. */
   --color-success-hover: light-dark(#007552, #008e66);
   /* The dark ground is `-900` to make room for the `-300` ink above it. `-subtle`
      is what `kbd`, `code`, `pre` and the tooltip bubble rest on, and those are the
@@ -99,21 +92,16 @@
      WCAG 1.4.3 asks of normal text -- and the other three sat at 4.9 to 5.0 with
      no headroom. One step darker puts all four past 9:1. */
   --color-success-subtle: light-dark(var(--color-emerald-100), var(--color-emerald-900));
-  /* The dark tone is `-300`, not `-100`. `-strong` is what a partial fill prints
-     -- the label of a soft badge, the dot of a soft radio -- and on a dark page
-     the `-100` shade of every hue is a pale tint that reads white at small
-     sizes. The intent's colour survived only in the fill and the border, so a
-     soft success badge and a soft destructive one had the same white label and a
-     radio's dot stopped matching its own ring. `-300` keeps the hue and stays
-     far above the contrast a mark or a label needs. Light keeps `-800`, which
-     was never the problem: it is saturated and dark against a light page. */
+  /* The dark tone is `-300`, not `-100`: `-strong` is what a partial fill
+     prints -- the label of a soft badge, the dot of a soft radio -- and on a
+     dark page the `-100` shade of every hue is a pale tint that reads white at
+     small sizes. `-300` keeps the hue. Light keeps `-800`, which is saturated
+     and dark against a light page. */
   --color-success-strong: light-dark(var(--color-emerald-800), var(--color-emerald-300));
-  /* Amber is the one family that cannot solve this by darkening. White on
-     amber-600 measures 3.07:1, and the amber dark enough to carry white has
-     stopped being amber -- it reads brown, which is not the colour a warning is
-     supposed to be. So the ink moves instead of the hue: dark ink on amber is
-     what a warning looks like nearly everywhere, and it is the only intent whose
-     contrast tone is not the page colour. */
+  /* Amber cannot solve contrast by darkening: white on amber-600 measures
+     3.07:1, and amber dark enough to carry white reads brown. So the ink moves
+     instead of the hue: dark ink on amber is what a warning looks like, and
+     warning is the only intent whose contrast tone is not the page colour. */
   --color-warning: var(--color-amber-600);
   --color-warning-contrast: var(--color-neutral-950);
   /* Same crash, same fix as `--color-success-hover` above. */
@@ -134,7 +122,6 @@
   --color-info-strong: light-dark(var(--color-indigo-800), var(--color-indigo-300));
 
   --breakpoint-xs: 30rem;
-  --breakpoint-2xl: 90rem;
 }
 
 /* Tailwind only keeps a `@theme` variable in the compiled output when it
@@ -151,111 +138,112 @@
   --color-border-hover: light-dark(var(--color-neutral-600), var(--color-neutral-500));
 }
 
-:root {
-  /* Both keywords: the system preference decides, and the explicit theme
-     selectors below override it at any depth because `color-scheme` inherits. */
-  color-scheme: light dark;
-
-  --container-narrow: 48rem;
-  --container-max: 80rem;
-  --container-wide: 90rem;
-  --layout-gutter: clamp(1rem, 4vw, 2rem);
-  --layout-section-block: clamp(4rem, 9vw, 7rem);
-  --layout-gap: 1rem;
-  --layout-grid-min: 16rem;
-
-  --radius-small: 0.25rem;
-  --radius-control: 0.5rem;
-  --radius-surface: 0.875rem;
-  --control-height: 2.5rem;
-  --border-width: 1px;
+/* The foundation tokens and the colour-scheme selectors, in `theme` so every
+   class family in `components` beats them on the element both land on -- an
+   aesthetic on `<html>` keeps its own press and depth colour over `:root`'s,
+   whatever order the sheets load in. */
+@layer theme {
+  :root {
+    /* Both keywords: the system preference decides, and the explicit theme
+       selectors below override it at any depth because `color-scheme` inherits. */
+    color-scheme: light dark;
 
-  /* `light-dark()` takes colors only, so the shadow color is the token and the
-     three elevations compose from it. Dark themes need a much heavier color to
-     read at all against a dark background. */
-  --elevation-color: light-dark(rgb(15 23 42 / 0.08), rgb(0 0 0 / 0.55));
-  /* Four rungs: no shadow, then a Tailwind-style sm/md/lg progression, so a
-     consumer unsure which step to reach for has a named "no depth" value
-     instead of inferring it by omitting a shadow declaration. The elevation
-     modifier classes (`.elevation-none`/`.elevation-sm`/`.elevation-md` in
-     elevation.css) share this naming on purpose -- same weight, same word --
-     though they multiply an aesthetic's shadow parts rather than declaring a
-     fixed value, so the two are not read from the same place. */
-  --elevation-none: none;
-  --elevation-sm: 0 1px 2px var(--elevation-color), 0 1px 3px var(--elevation-color);
-  --elevation-md: 0 4px 6px -1px var(--elevation-color), 0 2px 4px -2px var(--elevation-color);
-  --elevation-lg: 0 20px 25px -5px var(--elevation-color), 0 8px 10px -6px var(--elevation-color);
+    --container-narrow: 48rem;
+    --container-max: 80rem;
+    --container-wide: 90rem;
+    --layout-gutter: clamp(1rem, 4vw, 2rem);
+    --layout-section-block: clamp(4rem, 9vw, 7rem);
+    --layout-gap: 1rem;
+    --layout-grid-min: 16rem;
 
-  --focus-ring: color-mix(in srgb, var(--color-primary) 64%, transparent);
-  /* Negative, so the ring is drawn over the edge rather than beside it: at a
-     positive offset the outline floats a gap away and reads as a second, detached
-     frame around the control. Pulled in by exactly the material line width, the
-     ring lands on top of the line and a focused control reads as its own edge
-     thickening -- which is what a focus indicator is meant to look like.
+    --radius-small: 0.25rem;
+    --radius-control: 0.5rem;
+    --radius-surface: 0.875rem;
+    --control-height: 2.5rem;
+    --border-width: 1px;
 
-     A component drawing no line at rest loses nothing: the outline moves one
-     pixel inward over its own fill, which at a hairline is not a visible change. */
-  --focus-ring-offset: calc(-1 * var(--border-width));
-  --focus-ring-width: 3px;
+    /* `light-dark()` takes colors only, so the shadow color is the token and the
+       three elevations compose from it. Dark themes need a much heavier color to
+       read at all against a dark background. */
+    --elevation-color: light-dark(rgb(15 23 42 / 0.08), rgb(0 0 0 / 0.55));
+    /* Four rungs: no shadow, then a Tailwind-style sm/md/lg progression, so a
+       consumer unsure which step to reach for has a named "no depth" value
+       instead of inferring it by omitting a shadow declaration. These are raw
+       shadows for elements a consumer styles; the elevation modifier classes
+       (`.flat`/`.raised`/`.floating` in elevation.css) multiply an aesthetic's
+       shadow parts instead, and are not read from here. */
+    --elevation-none: none;
+    --elevation-sm: 0 1px 2px var(--elevation-color), 0 1px 3px var(--elevation-color);
+    --elevation-md: 0 4px 6px -1px var(--elevation-color), 0 2px 4px -2px var(--elevation-color);
+    --elevation-lg: 0 20px 25px -5px var(--elevation-color), 0 8px 10px -6px var(--elevation-color);
 
-  --motion-duration-fast: 120ms;
-  --motion-duration-normal: 200ms;
-  --motion-duration-slow: 400ms;
-  --motion-ease: cubic-bezier(0.2, 0, 0, 1);
+    --focus-ring: color-mix(in srgb, var(--color-primary) 64%, transparent);
+    /* `--focus-ring-offset` is not declared: its default is the negative of the
+       line width of whatever is focused, which only the focused element knows,
+       so the outline computes it there -- see `reset.css`. Declared here it
+       resolved against the base 1px once and inherited, and under a 2px
+       aesthetic the ring covered half the edge and left a stripe of it inside. */
+    --focus-ring-width: 3px;
 
-  --z-popover: 40;
+    --motion-duration-fast: 120ms;
+    --motion-duration-normal: 200ms;
+    --motion-duration-slow: 400ms;
+    --motion-ease: cubic-bezier(0.2, 0, 0, 1);
 
-  /* The one number the derived-hover formula spends: how much fill a hover adds
-     on top of whatever the element rests at. */
-  --hover-step: 14%;
-}
+    --z-popover: 40;
 
-/* The base look answers a press with a small scale-in. `box-active` applies it on
-   `.btn` and `.card.interactive`; every aesthetic sets its own
-   `--ui-active-transform` on its class, loaded after this file, so those win.
-   Reduced motion opts out. Kept outside `@theme` because a media query cannot go
-   inside it. */
-:root {
-  --ui-active-transform: scale(0.97);
-}
+    /* The one number the derived-hover formula spends: how much fill a hover adds
+       on top of whatever the element rests at. */
+    --hover-step: 14%;
+  }
 
-@media (prefers-reduced-motion: reduce) {
+  /* The base look answers a press with a small scale-in. `box-active` applies it on
+     `.btn` and `.card.interactive`; every aesthetic sets its own
+     `--ui-active-transform` on its class, in `components`, so those win over
+     this whichever sheet loads first. Reduced motion opts out. Kept outside `@theme` because a media query cannot go
+     inside it. */
   :root {
-    --ui-active-transform: none;
+    --ui-active-transform: scale(0.97);
   }
-}
 
-.light,
-.theme-light,
-[data-theme="light"] {
-  color-scheme: light;
-}
+  @media (prefers-reduced-motion: reduce) {
+    :root {
+      --ui-active-transform: none;
+    }
+  }
 
-.dark,
-.theme-dark,
-[data-theme="dark"] {
-  color-scheme: dark;
+  .light,
+  .theme-light,
+  [data-theme="light"] {
+    color-scheme: light;
+  }
+
+  .dark,
+  .theme-dark,
+  [data-theme="dark"] {
+    color-scheme: dark;
+  }
 }
 
 /* The first arm mirrors the `color-scheme: dark` block above, all three
-   spellings included -- a consumer writing `.theme-dark` for the token theme
-   was otherwise left without the matching `dark:` variant.
+   spellings included.
 
-   The second arm closes the gap that left open: `--color-*` tokens resolve
-   through `light-dark()` against the computed `color-scheme`, so with no
-   explicit selector at all `:root`'s `color-scheme: light dark` already
-   follows the OS preference -- see `concepts.md#theme-selection`. A selector
-   list cannot query computed style the way `light-dark()` does, but it can
-   still match "OS prefers dark, and not under a forced-light subtree" with a
-   plain descendant exclusion: `:not(:where(.light, .light *, ...))` matches
-   only when no ancestor (or the element itself) carries one of the three
-   light spellings. That is the one case the exclusion cannot see -- a
-   subtree forced light through some means other than these three selectors,
-   where `light-dark()` would still honor it but this variant could not
-   detect it. Out of contract: those three spellings are the only supported
-   way to force a theme, so nothing else is expected to set `color-scheme`
-   directly. Each arm is independent, so an explicit selector still wins at
-   any depth even inside a subtree the other arm would otherwise match. */
+   The second arm follows the OS preference. `--color-*` tokens resolve through
+   `light-dark()` against the computed `color-scheme`, so with no explicit
+   selector `:root`'s `color-scheme: light dark` already follows it -- see
+   `concepts.md#theme-selection`. A selector list cannot query computed style,
+   but it can match "OS prefers dark, and not under a forced-light subtree" with
+   a plain descendant exclusion: `:not(:where(.light, .light *, ...))` matches
+   only when no ancestor (or the element itself) carries one of the three light
+   spellings. The exclusion cannot see a subtree forced light by other means,
+   where `light-dark()` would still honor it; that is out of contract, since
+   those three spellings are the only supported way to force a theme.
+
+   Each arm is independent, so an explicit selector wins over the OS preference
+   at any depth. It does not win over an explicit selector of the opposite
+   theme further up: `.dark *` matches every descendant of a `.dark` element,
+   including one inside a nested `.light`, so a `dark:` utility still fires
+   there although its tokens are light. `setup.md#dark-variant` documents it. */
 @custom-variant dark {
   &:where(.dark, .dark *, .theme-dark, .theme-dark *, [data-theme="dark"], [data-theme="dark"] *) {
     @slot;
@@ -267,3 +255,18 @@
     }
   }
 }
+
+/* Forced colours draw the plain version of every structural part: a solid line
+   and nothing an aesthetic layers on top. Unlayered, so it beats every layered
+   declaration of these tokens -- an aesthetic's and a consumer's utility alike --
+   the way the other `forced-colors` blocks do. See
+   docs/internal/model.md#material-tokens. */
+@media (forced-colors: active) {
+  * {
+    --ui-line-style: solid;
+    --ui-rule-style: solid;
+    --ui-halo-ink: initial;
+    --ui-surface-image: none;
+    --ui-label-shadow: none;
+  }
+}