@codenhub/styles 0.5.0 → 0.7.0

package/dist/tw/palette.css

@@ -7,11 +7,14 @@
 @layer theme, base, components, utilities;
 
 @layer theme {
-  :root {
-    --palette-neutral-solid-bg: oklab(0.145 0 0 / 0.2);
+  :root,
+  .light,
+  .theme-light,
+  [data-theme="light"] {
+    --palette-neutral-solid-bg: oklab(0.817 0 0);
     --palette-neutral-solid-fg: oklab(0.205 0 0);
     --palette-neutral-solid-edge: oklab(0 0 0 / 0);
-    --palette-neutral-solid-bg-hover: oklab(0.371 0 0 / 0.34);
+    --palette-neutral-solid-bg-hover: oklab(0.77624 0 0);
     --palette-neutral-solid-edge-hover: oklab(0 0 0 / 0);
     --palette-neutral-soft-fg: oklab(0.205 0 0);
     --palette-neutral-soft-bg: oklab(0.145 0 0 / 0.12);
@@ -225,18 +228,18 @@
     --palette-info-ghost-subtle-edge: oklab(0.511 0.0317755 -0.260066);
     --palette-info-ghost-subtle-bg-hover: oklab(0.8685 0.00575617 -0.0640304);
     --palette-info-ghost-subtle-edge-hover: oklab(0.490714 0.0309565 -0.24875);
-    --palette-border: oklch(0.708 0 0);
-    --palette-surface: oklch(0.922 0 0);
-    --palette-text: oklch(0.145 0 0);
+    --palette-border: oklch(0.708 0 none);
+    --palette-surface: oklch(0.922 0 none);
+    --palette-text: oklch(0.145 0 none);
   }
 
   .dark,
   .theme-dark,
   [data-theme="dark"] {
-    --palette-neutral-solid-bg: oklab(0.985 0 0 / 0.2);
+    --palette-neutral-solid-bg: oklab(0.313 0 0);
     --palette-neutral-solid-fg: oklab(0.97 0 0);
     --palette-neutral-solid-edge: oklab(0 0 0 / 0);
-    --palette-neutral-solid-bg-hover: oklab(0.922 0 0 / 0.34);
+    --palette-neutral-solid-bg-hover: oklab(0.40918 0 0);
     --palette-neutral-solid-edge-hover: oklab(0 0 0 / 0);
     --palette-neutral-soft-fg: oklab(0.97 0 0);
     --palette-neutral-soft-bg: oklab(0.985 0 0 / 0.12);
@@ -450,8 +453,8 @@
     --palette-info-ghost-subtle-edge: oklab(0.511 0.0317755 -0.260066);
     --palette-info-ghost-subtle-bg-hover: oklab(0.38601 0.0239578 -0.155809);
     --palette-info-ghost-subtle-edge-hover: oklab(0.551929 0.0373722 -0.238521);
-    --palette-border: oklch(0.371 0 0);
-    --palette-surface: oklch(0.269 0 0);
-    --palette-text: oklch(0.985 0 0);
+    --palette-border: oklch(0.371 0 none);
+    --palette-surface: oklch(0.269 0 none);
+    --palette-text: oklch(0.985 0 none);
   }
 }

package/dist/tw/presentation.css

@@ -7,21 +7,11 @@
    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 was a fault in the blend rather than in the class, and it was fixed
-   there: the line fades toward `transparent` as the fill fills in, so a
-   translucent plate shows through its own border as one coat (`box.css`;
-   docs/internal/model.md#presentation). `.solid.edged` and `.solid.edgeless`
-   render one box.
+   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
@@ -33,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 {
@@ -48,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
@@ -62,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,28 +75,39 @@
     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) {
     input:is(
-      [type="text"],
-      [type="email"],
-      [type="password"],
-      [type="url"],
-      [type="tel"],
-      [type="number"],
-      [type="search"],
-      [type="date"],
-      [type="datetime-local"],
-      [type="month"],
-      [type="week"],
-      [type="time"],
-      [type="checkbox"],
-      [type="radio"]
-    ):focus-visible,
+        [type="text"],
+        [type="email"],
+        [type="password"],
+        [type="url"],
+        [type="tel"],
+        [type="number"],
+        [type="search"],
+        [type="date"],
+        [type="datetime-local"],
+        [type="month"],
+        [type="week"],
+        [type="time"],
+        [type="checkbox"],
+        [type="radio"]
+      ):focus-visible,
     textarea:focus-visible,
     select:focus-visible {
       outline: 2px solid Highlight !important;
@@ -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

@@ -22,14 +22,13 @@
   --_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 beat glass's inherited one in a glass region,
-     and once the aesthetics are layered below the components it beats glass
-     on the same element too -- `.card.soft.glass` went opaque. Restated
-     `initial` here so a quiet ground cannot inherit into a surface nested
-     inside one, the way `box` restates `--_d-ground`. See
+     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)));
@@ -47,16 +46,16 @@
     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))
   );
-  /* 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. */
   /* 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

@@ -21,8 +21,15 @@
    selectors below therefore set `color-scheme` and nothing else. Verified
    across Chromium, Firefox, and WebKit, including resolution through
    `color-mix()` and through Tailwind's `@theme`, which emits theme values as
-   unregistered custom properties rather than `@property` registrations. */
-@theme {
+   unregistered custom properties rather than `@property` registrations.
+
+   `static`, because every token here is documented as public. Tailwind keeps a
+   plain `@theme` value only where it sees the entry read it, and `/theme`
+   carries no reset or component to read `--color-background`,
+   `--color-foreground`, `--color-text-secondary`, or `--font-default`, so it
+   shipped without them. `exports.test.ts` holds every compiled entry to the
+   tokens `docs/usage/theming.md` lists. */
+@theme static {
   --font-default: "Segoe UI", system-ui, sans-serif;
 
   --color-primary: light-dark(var(--color-neutral-950), var(--color-neutral-50));
@@ -35,30 +42,25 @@
   --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));
+  /* Nothing in the package draws a border that darkens on hover; it is a
+     public override point for a consumer's own. */
+  --color-border-hover: light-dark(var(--color-neutral-600), var(--color-neutral-500));
 
   /* 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));
@@ -68,40 +70,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
@@ -110,21 +102,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. */
@@ -143,23 +130,13 @@
   --color-info-hover: light-dark(#4b36e9, #5e4ff9);
   --color-info-subtle: light-dark(var(--color-indigo-100), var(--color-indigo-900));
   --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
-   detects that variable being used somewhere in this package's own source --
-   everything above earns its keep that way, through `intent.css` or a
-   component reading it. `--color-border-hover` is different: `docs/usage/
-   theming.md` documents it as a public override point like every other row
-   in that table, but nothing in this package draws a border that darkens on
-   hover, so nothing here ever references it, and Tailwind quietly dropped it
-   from every compiled stylesheet. `static` forces it to compile regardless,
-   so the token a consumer's docs promise is the token their `var()` actually
-   resolves. */
-@theme static {
-  --color-border-hover: light-dark(var(--color-neutral-600), var(--color-neutral-500));
+/* Not `static`: a breakpoint is a variant for a `/tw` consumer's own build and
+   means nothing as a custom property, since a media query cannot read `var()`.
+   Tailwind keeps the variable only where an `xs:` utility uses it. */
+@theme {
+  --breakpoint-xs: 30rem;
 }
 
 /* The foundation tokens and the colour-scheme selectors, in `theme` so every
@@ -202,15 +179,11 @@
     --elevation-lg: 0 20px 25px -5px var(--elevation-color), 0 8px 10px -6px var(--elevation-color);
 
     --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.
-
-       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-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;
 
     --motion-duration-fast: 120ms;
@@ -254,24 +227,24 @@
 }
 
 /* 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 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.
 
-   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. */
+   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;
@@ -288,9 +261,20 @@
    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. */
+   docs/internal/model.md#material-tokens.
+
+   The border comes back and the clip goes. Forced colours remove every box
+   shadow, so an aesthetic that draws its edge as an inset ring and takes the
+   border out with `--ui-border-max` (`.pixel`) left buttons, fields, and cards
+   with no boundary at all. With the ceiling lifted the border is drawn at the
+   aesthetic's own width and the system colours it; with no clip the corners
+   it would cut are whole and the focus outline shows. */
 @media (forced-colors: active) {
   * {
+    --ui-border-max: initial;
+    --ui-clip: none;
+    --ui-clip-tight: none;
+    --ui-shadow-edge: initial;
     --ui-line-style: solid;
     --ui-rule-style: solid;
     --ui-halo-ink: initial;