@codenhub/styles 0.1.1 → 0.2.0

package/dist/tw/components/surface.css

@@ -67,6 +67,53 @@
     --surface-padding: 0;
   }
 
+  /* `.soft` rests untinted for no named intent, rather than mixing its 12% --
+     measured on a neutral card, 12% of `--color-text` onto any of
+     `--color-background`, `--color-foreground`, or `--color-surface` lands
+     within a few units of the others (a near-black ink dominates the result
+     regardless of which near-white ground it is mixed onto), which is why
+     swapping the ground token alone does not read as quieter. A resting
+     no-intent `.card.soft` is instead `--color-foreground` with no ink mixed
+     in at all -- a plain step up from the page that marks a different
+     container without drawing attention to it, the way a card that is not
+     currently interesting should.
+
+     A named intent keeps its ordinary 12% wash rather than being untinted
+     unconditionally: 12% of an actual hue does not read as a slab the way
+     12% of near-black ink does -- measured, `.card.soft.destructive` at 12%
+     is a gentle `249, 225, 225`, nothing like the `217, 217, 217` a neutral
+     surface mixing the same 12% of its own ink used to read as -- and
+     untinting it anyway would silence a `.card.soft.destructive` at rest
+     rather than merely quiet it, the same reason `.panel`'s own carve-out
+     (below) is scoped the same way. `:not(...)` names every intent class for
+     that reason; a version of this fix that untinted every intent shipped
+     first and was corrected once `.panel` needed the identical, narrower
+     carve-out to keep a resting `.panel.destructive` legible.
+
+     `--_fill-cap: 0%` (box.css's override slot, not `--ui-fill` directly --
+     see the comment there) composed with `box-hover`'s own formula
+     (`min(100%, resting + 14%)`) is what reveals the intent on hover without
+     a second fill declaration, for the no-intent case: resting at 0% means
+     hover lands at exactly the hover step, 14%, in `--intent-hover` as
+     always. The ground steps to `--color-surface` at the same moment,
+     through the public `--ui-surface-ground` escape hatch rather than the
+     private `--_d-ground`, so a consumer's own override still wins over both
+     states the way it always has. Scoped to `.interactive` and `.hoverable`,
+     the two classes that already opt a card into `box-hover` -- a plain
+     `.card.soft` with neither has no hover state to reveal into and stays at
+     the quiet, untinted rest. A named intent needs neither special case: it
+     already rests tinted, so the same generic `box-hover` formula deepens it
+     on hover (12% to 26%) with no ground shift required. */
+  &.soft:not(.primary, .secondary, .success, .warning, .destructive, .danger, .error, .info) {
+    --_fill-cap: 0%;
+    --ui-surface-ground: var(--color-foreground);
+
+    &.interactive:hover,
+    &.hoverable:hover {
+      --ui-surface-ground: var(--color-surface);
+    }
+  }
+
   /* Opt-in, because a card is only sometimes a control. Applications still owe
      it a real interactive element and an accessible name. Hover and press are
      the derived ones every other pressable box gets; there is nothing
@@ -119,4 +166,50 @@
   &.flush {
     --surface-padding: 0;
   }
+
+  /* Neutral panels are the common case -- most are plain layout wells,
+     sidebars, and toolbars with no named intent -- and 12% of `--color-text`
+     (near-black) mixed onto the page is a far more assertive move than 12%
+     of an actual hue: measured, `217, 217, 217` against a `250, 250, 250`
+     page, the same "neutral ink reads louder" effect `.card.soft`'s fix
+     already answered, and the same reason `--intent-fill-max` stops
+     neutral's fill short everywhere else in the model.
+
+     Scoped to no named intent rather than untinted unconditionally the way
+     `data-table` is: a panel is not interactive, so there is no hover to
+     reveal a colored intent back into later, and it is edgeless by default,
+     so the fill is the only channel a `.primary` bulk-actions bar or a
+     `.destructive` danger-zone panel has to say what it is. Untinting those
+     unconditionally would silence them, not just quiet them -- measured, a
+     resting `.panel.destructive` is a gentle `249, 225, 225` warm wash,
+     nothing like the neutral slab above. `.card.soft` carries the identical
+     no-named-intent scoping now, corrected to match once this carve-out
+     shipped -- see the comment on `.card`'s own `&.soft`, above. `:not(...)`
+     names every intent class for that reason, plus `.solid`/`.ghost` so an
+     explicit presentation on the element is never clamped to a cap it did
+     not ask for -- the same guard `data-table`'s own `:not(.solid, .ghost)`
+     uses.
+
+     Grounds on `--color-foreground` through the public `--ui-surface-ground`
+     escape hatch, not the private `--_d-ground`, the same token `.card.soft`
+     steps to -- so a consumer's own override still wins, and a bare `.panel`
+     rests at exactly the plate a `.card.soft` does (measured: `245, 245, 245`
+     light, `23, 23, 23` dark, identical both ways). Permanent rather than
+     hover-revealed: neither a panel nor `data-table` has an interaction
+     state to reveal a tint into, so both rest quiet rather than reveal.
+
+     The one cost, inherited rather than new: an own declaration always beats
+     an inherited one, so this also beats `.glass` setting the same token on
+     an ancestor for its translucent ground -- a neutral panel under `.glass`
+     is quiet but opaque rather than blurred. `.card.soft` has carried this
+     exact trade-off since it shipped; nothing exercised it there because
+     `tests/browser/aesthetics.spec.ts`'s glass coverage tests a default
+     (ghost) card, never a soft one. Accepted rather than solved differently:
+     there is no way to ask "did an ancestor already set this token" in CSS,
+     only which declaration wins, and the quiet neutral rest is the more
+     common case a panel needs to get right. */
+  &:not(.primary, .secondary, .success, .warning, .destructive, .danger, .error, .info, .solid, .ghost) {
+    --_fill-cap: 0%;
+    --ui-surface-ground: var(--color-foreground);
+  }
 }

package/dist/tw/components/tooltip.css

@@ -3,16 +3,20 @@
 @reference "../box.css";
 @reference "./surface.css";
 
-/* The host is a positioning wrapper and nothing else. Its bubble is a
-   pseudo-element placed outside the host's own box, so painting the host would
-   draw a box around the trigger rather than around the message -- which is
-   exactly what a blanket surface membership did to this component once already.
-
-   The bubble is the component. It is a surface, so an aesthetic that blurs
-   surfaces blurs it too, and it rests on a ground of its own, edged, and flat.
-   Depth is opt-in through `.raised` and `.floating` like every other component;
-   its boundary against arbitrary content is the floored edge below, not a
-   shadow. See model.md#elevation. */
+/* The host is a positioning wrapper and nothing else -- it paints no fill, no
+   edge, no material of its own. The bubble is a real element beside the
+   trigger rather than a pseudo-element attached to it, so intent,
+   presentation, aesthetic, and elevation classes go on `.tooltip-bubble`, the
+   thing actually shown, not on the wrapper -- the same rule every other
+   component in this package follows (theming.md: "Intent does not cascade").
+
+   Composing the bubble as a real element fixes a real gap, not just a styling
+   one: `content: attr(data-tooltip)` text is not reliably exposed to
+   assistive tech and cannot be the target of an `aria-describedby`, since that
+   needs a real element with a real `id`. A real bubble can carry
+   `role="tooltip"` and be referenced by the trigger's own `aria-describedby`;
+   wiring that association is the consumer's, this package only styles the
+   bubble. See docs/usage/tooltips.md. */
 @utility tooltip {
   --tooltip-gap: 0.5rem;
   --tooltip-top: calc(var(--tooltip-gap) * -1);
@@ -22,34 +26,7 @@
   --tooltip-origin: bottom;
   --tooltip-transform: translate(-50%, -100%);
 
-  @apply relative;
-
-  /* The trigger badge, for a page with no element to hang the message on. Quiet
-     -- ghost, edged, on `--intent-subtle`, a key cap's resting shape -- because
-     it marks that there is a message, it is not one. The line earns its keep:
-     `--intent-subtle` is a near-page tint that reads the same across families,
-     so a plate alone left three of eight intents indistinguishable;
-     `--intent-border` is the slot that differs. Painting the host is right only
-     here -- everywhere else the bubble is outside the host's box, so painting it
-     boxes the trigger. `.tooltip-icon` is the opt-in that says the host *is* the
-     badge. */
-  &.tooltip-icon {
-    @apply box inline-flex size-5 cursor-default items-center justify-center text-sm font-bold;
-
-    --_d-fill: 0%;
-    --_d-fg-on-fill: 0%;
-    --_d-border: 100%;
-    --_d-elevation: 0;
-    --_d-ground: var(--intent-subtle);
-
-    border-radius: var(--ui-radius, calc(infinity * 1px));
-    /* The one thing `box` hands it that it must refuse. An aesthetic's `clip-path`
-       clips a host's pseudo-elements along with the host, and this host's
-       pseudo-element is the bubble, positioned outside its box -- so a stepped
-       badge under `.pixel` would clip the message away entirely. The bubble
-       carries the stepped shape itself; the badge stays round. */
-    clip-path: none;
-  }
+  @apply relative inline-block;
 
   &[data-tooltip-position="bottom"] {
     --tooltip-top: auto;
@@ -72,61 +49,95 @@
     --tooltip-origin: left;
     --tooltip-transform: translate(100%, -50%);
   }
+}
 
-  &::after {
-    @apply surface pointer-events-none absolute z-(--z-popover) w-max max-w-72 px-2.5 py-2 text-sm font-normal whitespace-normal opacity-0 transition-[opacity,transform] duration-(--motion-duration-normal) ease-(--motion-ease);
-
-    /* Filled, over a ground of its own. An intent floods the fill
-       (`.tooltip.primary` is the primary colour); with no intent `intent.css`
-       resolves the bubble onto `--color-tooltip` and lifts the neutral cap, a
-       plate stated per theme because the derived version was a mid-grey slab in
-       light and lifted in dark. The ground stays the surface tone, not the
-       plate -- pointed at both, the fill axis went inert and `axes.spec.ts`
-       caught it. An opaque ground is also what keeps a cascaded `.ghost` from
-       leaving the bubble boundaryless, retiring the old pinned-fill bound.
-       `--ui-surface-ground` is read first so a glass tooltip stays glass. */
-    --_d-fill: 100%;
-    --_d-fg-on-fill: 100%;
-    --_d-border: 100%;
-    /* Flat, and stated rather than left to `box`'s fallback of 1: the bubble is
-       a surface, so an aesthetic's part-based depth would otherwise reach it
-       unasked -- `.neobrutalism`'s slab in particular. `.raised`/`.floating`
-       opt back in. */
-    --_d-elevation: 0;
-    --_d-ground: var(--ui-surface-ground, var(--intent-subtle));
-
-    /* The bubble's line is a boundary against content nobody chose, so `box`'s
-       edge blend is wrong here: at a full fill the line *is* the plate. Restate
-       the colour only; how much line comes from `--_edge-amount`, floored below. */
-    --_line: var(--intent-border);
-
-    /* Floored, for the same reason the ground is opaque: a cascade must not take
-       the boundary from a bubble nobody classed (worst in light, where the plate
-       is near-white). The element's own `.edgeless` lowers it -- same
-       element-vs-cascade idiom `text-control` uses -- and `axes.spec.ts` still
-       sees the edge move because it probes with the class on the element. */
-    --_edge-floor: 100%;
-
-    /* A bubble is a small transient popover, not a modal, so it takes the
-       control radius rather than the surface one `surface` hands it. */
-    border-radius: var(--ui-radius, var(--radius-control));
-    content: attr(data-tooltip);
-    left: var(--tooltip-left);
-    right: var(--tooltip-right);
-    top: var(--tooltip-top);
-    bottom: var(--tooltip-bottom);
-    transform: var(--tooltip-transform) scale(0);
-    transform-origin: var(--tooltip-origin);
-  }
-
-  &.edgeless::after {
+/* The bubble. It is a surface, so an aesthetic that blurs surfaces blurs it
+   too, and it rests on a ground of its own, edged, and flat -- depth is
+   opt-in through its own `.raised`/`.floating`, like any other component, now
+   that it is one. No proxy inheritance is needed to carry elevation across a
+   host-to-pseudo-element gap: there is no gap, `.tooltip-bubble.raised` reads
+   `--ui-elevation` the ordinary way every other component does. See
+   model.md#elevation. */
+@utility tooltip-bubble {
+  @apply surface pointer-events-none absolute z-(--z-popover) w-max max-w-72 px-2.5 py-2 text-sm font-normal whitespace-normal opacity-0 transition-[opacity,transform] duration-(--motion-duration-normal) ease-(--motion-ease);
+
+  /* Filled, over a ground of its own. An intent floods the fill
+     (`.tooltip-bubble.primary` is the primary colour); with no intent
+     `intent.css` resolves the bubble onto `--color-tooltip` and lifts the
+     neutral cap, a plate stated per theme because the derived version was a
+     mid-grey slab in light and lifted in dark. The ground stays the surface
+     tone, not the plate -- pointed at both, the fill axis went inert and
+     `axes.spec.ts` caught it. An opaque ground is also what keeps a cascaded
+     `.ghost` from leaving the bubble boundaryless. `--ui-surface-ground` is
+     read first so a glass tooltip stays glass. */
+  --_d-fill: 100%;
+  --_d-fg-on-fill: 100%;
+  --_d-border: 100%;
+  --_d-elevation: 0;
+  --_d-ground: var(--ui-surface-ground, var(--intent-subtle));
+
+  /* The bubble's line is a boundary against content nobody chose, so `box`'s
+     edge blend is wrong here: at a full fill the line *is* the plate. Restate
+     the colour only; how much line comes from `--_edge-amount`, floored below. */
+  --_line: var(--intent-border);
+
+  /* Floored, for the same reason the ground is opaque: a cascade must not take
+     the boundary from a bubble nobody classed (worst in light, where the plate
+     is near-white). The element's own `.edgeless` lowers it -- same
+     element-vs-cascade idiom `text-control` uses. */
+  --_edge-floor: 100%;
+
+  /* A bubble is a small transient popover, not a modal, so it takes the
+     control radius rather than the surface one `surface` hands it. */
+  border-radius: var(--ui-radius, var(--radius-control));
+  left: var(--tooltip-left);
+  right: var(--tooltip-right);
+  top: var(--tooltip-top);
+  bottom: var(--tooltip-bottom);
+  transform: var(--tooltip-transform) scale(0);
+  transform-origin: var(--tooltip-origin);
+
+  &.edgeless {
     --_edge-floor: 0%;
   }
+}
 
-  &:hover::after,
-  &:focus-visible::after,
-  &[data-state="open"]::after {
-    opacity: 1;
-    transform: var(--tooltip-transform) scale(1);
-  }
+/* Shown on hover or focus anywhere in the host, or pinned open with
+   `data-state="open"`. `:focus-within` rather than the trigger's own
+   `:focus-visible`, the same substitution `.input-group` makes for the
+   identical reason: the bubble is a sibling, not a pseudo-element, of the
+   trigger, so nothing but the shared ancestor can see both at once. The cost
+   is the one `.input-group` already accepts -- the bubble also shows on a
+   mouse click, which the old `:focus-visible`-only version did not. */
+.tooltip:hover .tooltip-bubble,
+.tooltip:focus-within .tooltip-bubble,
+.tooltip[data-state="open"] .tooltip-bubble {
+  opacity: 1;
+  transform: var(--tooltip-transform) scale(1);
+}
+
+/* The trigger badge, for a message with no other element to hang it on. Quiet
+   -- ghost, edged, on `--intent-subtle`, a key cap's resting shape -- because
+   it marks that there is a message, it is not one. The line earns its keep:
+   `--intent-subtle` is a near-page tint that reads the same across families,
+   so a plate alone left three of eight intents indistinguishable;
+   `--intent-border` is the slot that differs.
+
+   `clip-path: none` used to exist to protect the bubble, a pseudo-element of
+   this same host, from being clipped away along with it under an aesthetic
+   like `.pixel`. The bubble is independent now, so that reason is gone, but
+   the declaration stays: the docs call this a circular fixed identity, not a
+   shape a container's aesthetic reaches, the same way `.radio` keeps its own
+   circle instead of taking `.pixel`'s stepped silhouette. */
+@utility tooltip-icon {
+  @apply box inline-flex size-5 cursor-default items-center justify-center text-sm font-bold;
+
+  --_d-fill: 0%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 100%;
+  --_d-elevation: 0;
+  --_d-ground: var(--intent-subtle);
+
+  border-radius: var(--ui-radius, calc(infinity * 1px));
+  clip-path: none;
 }

package/dist/tw/elevation.css

@@ -1,18 +1,54 @@
 /* Elevation is a modifier, not an axis: depth is a per-element decision (raised
    tiles beside a flat panel in one aesthetic), so one unitless number multiplies
-   the aesthetic's shadow geometry where the component composes it. Unitless so
-   it inherits -- a container flattens a region, an element opts back in -- and
-   so `.flat` removes a part-based slab or blur without a conditional (complete
-   surface shadows like glass remain). The two classes that ask for depth carry
-   the geometry themselves; on a component it would inherit into everything
-   nested and a plain page would have a shadow under every card. See
-   model.md#elevation.
+   the aesthetic's shadow geometry where the component composes it. `.flat`
+   removes a part-based slab or blur without a conditional (complete surface
+   shadows like glass remain). See model.md#elevation.
+
+   `--ui-elevation`, and the plain-page fallback geometry (`--elevation-y`,
+   `--elevation-blur`) below, are registered non-inheriting: a class sets them
+   on the element it is written on and nothing else picks them up. They used to
+   be ordinary inherited custom properties, on the reasoning that a container
+   could flatten or lift a whole region in one class and any element inside
+   could opt back out -- but the same mechanism let a `.floating` dialog's
+   ambient ×2 reach its own unclassed "Cancel"/"Remove" buttons, doubling their
+   shadow with nothing in the markup asking for that. Depth is not the same
+   kind of thing as color or material: a button inside a raised card is not
+   itself more raised, it is just resting normally inside an already-raised
+   surface. `--ui-shadow-*` -- what an aesthetic supplies -- is unaffected and
+   still cascades normally; that is a different mechanism (the material tokens
+   in `src/aesthetics/*.css`), and an aesthetic still has to reach every nested
+   component uniformly the way it always did. Registering these three is what
+   scopes the change to the elevation modifier alone.
 
    `.flat`/`.raised`/`.floating` and `.elevation-none`/`-sm`/`-md` are
    interchangeable aliases, the second borrowing the raw `--elevation-*` scale's
    naming. Bare `sm`/`md`/`lg` would collide with the size modifier;
    `.elevation-lg` is reserved, not shipped. */
 
+/* `syntax: "*"` with no `initial-value` is deliberate: a numeric syntax would
+   require one (CSS Properties and Values API), and any initial-value at all
+   would mean the property is never actually unset on an element that does not
+   write it -- which is exactly the state `var(--ui-elevation, var(--_d-elevation,
+   1))` in `box.css` needs to fall through to a component's own default. With
+   no initial-value and `inherits: false`, an element that does not set the
+   property directly computes it as guaranteed-invalid, the same as if it had
+   never been registered at all -- `var()` takes its fallback precisely where
+   inheritance used to hand it an ambient value instead. */
+@property --ui-elevation {
+  syntax: "*";
+  inherits: false;
+}
+
+@property --elevation-y {
+  syntax: "*";
+  inherits: false;
+}
+
+@property --elevation-blur {
+  syntax: "*";
+  inherits: false;
+}
+
 /* No part-based depth. Complete surface shadow values, such as glass, are not
    reached by the elevation multiplier. */
 .elevation-none,

package/dist/tw/index.css

@@ -4,10 +4,13 @@
    sees only this package's own files. The `src/` scan is load-bearing -- it is
    how the composition utilities (`box`, `surface`, `text-control`,
    `input-group`, `loader-mask`) get emitted as standalone rules, since nothing
-   `@source inline`s them -- so `source(none)` is not an option. The cost is that
-   a handful of Tailwind utilities whose names collide with a CSS property or a
-   word in a comment (`.backdrop-filter`, `.filter`, `.transition`, `.container`,
-   ...) are emitted unused. They are inert and small; left as-is deliberately.
+   `@source inline`s them -- so `source(none)` is not an option. A handful of
+   Tailwind utility names also collide with a CSS property or a word this
+   file's own comments use (`backdrop-filter`, `filter`, `transition`,
+   `transform`, `container`), which reads like a risk of the same scan --
+   verified against Tailwind 4.3.2, none of them emit.
+   `tests/integration/exports.test.ts` guards it, so a scanner change that
+   starts emitting one is caught rather than shipping silently.
 
    The `@source not` lines below keep everything that is not `src/` out of that
    scan: the sibling app and fixture directories, the `docs/` tree, the build

package/dist/tw/intent.css

@@ -133,7 +133,8 @@
   .data-table,
   .pre,
   .quote,
-  .tooltip,
+  .tooltip-bubble,
+  .tooltip-icon,
   .badge,
   .kbd,
   .code,
@@ -168,8 +169,8 @@
 }
 
 /* The bubble a tooltip draws is the one plate in the package that is chosen
-   rather than composed, so the tooltip resolves the no-intent case onto its own
-   pair instead of onto the shared neutral. Composed, it was 20% of the page's
+   rather than composed, so it resolves the no-intent case onto its own pair
+   instead of onto the shared neutral. Composed, it was 20% of the page's
    ink over `--color-surface`, which lifts off a dark page and sinks into a light
    one -- see `--color-tooltip` in `theme.css` for the measurements.
 
@@ -178,17 +179,20 @@
    rather than an ink, so a full fill of it is the plate and there is nothing to
    stop short of.
 
-   `--intent-subtle` stays the surface token. It is what the trigger badge rests
-   on, and a badge is a quiet marker on the page rather than the message, so it
-   keeps the tone every other unclassed component sits on.
+   `--intent-subtle` stays the surface token, the same tone every other
+   unclassed component sits on. `.tooltip-icon`, the trigger badge, is a
+   separate element now and does not read this block at all -- it never fills
+   past `0%`, so the generic neutral reset above it is enough, and it keeps its
+   own resting ground and line independent of whatever intent the bubble shows.
 
    Two selectors, because `none` and `neutral` have to agree here. `:where()`
-   loses to any intent class, so `.tooltip.primary` still floods with primary;
-   `.tooltip.neutral` carries 0-2-0 and beats `.neutral`, so writing the intent
-   out gives the same bubble as writing nothing. Without the second selector the
-   two would differ on a component where they mean the same thing. */
-:where(.tooltip),
-.tooltip.neutral {
+   loses to any intent class, so `.tooltip-bubble.primary` still floods with
+   primary; `.tooltip-bubble.neutral` carries 0-2-0 and beats `.neutral`, so
+   writing the intent out gives the same bubble as writing nothing. Without the
+   second selector the two would differ on a component where they mean the
+   same thing. */
+:where(.tooltip-bubble),
+.tooltip-bubble.neutral {
   --intent-color: var(--color-tooltip);
   --intent-contrast: var(--color-tooltip-contrast);
   --intent-hover: var(--color-tooltip);

package/dist/tw/reset.css

@@ -127,3 +127,24 @@
     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/theme.css

@@ -24,7 +24,17 @@
   --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));
-  --color-border: light-dark(var(--color-neutral-300), var(--color-neutral-700));
+  /* 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. */
+  --color-border: light-dark(var(--color-neutral-400), var(--color-neutral-700));
   --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
@@ -214,10 +224,33 @@
   color-scheme: dark;
 }
 
-/* The selector list mirrors the `color-scheme: dark` block above, all three
+/* 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. System preference is
-   deliberately out: the variant follows an explicit theme selector, the same
-   rule the rest of the theme model states, so `dark:` utilities track the theme
-   a subtree was actually put in rather than the OS default. */
-@custom-variant dark (&:where(.dark, .dark *, .theme-dark, .theme-dark *, [data-theme="dark"], [data-theme="dark"] *));
+   was otherwise left without the matching `dark:` variant.
+
+   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. */
+@custom-variant dark {
+  &:where(.dark, .dark *, .theme-dark, .theme-dark *, [data-theme="dark"], [data-theme="dark"] *) {
+    @slot;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    &:not(:where(.light, .light *, .theme-light, .theme-light *, [data-theme="light"], [data-theme="light"] *)) {
+      @slot;
+    }
+  }
+}