@codenhub/styles 0.7.0 → 0.9.0

package/tw/components/index.css

@@ -0,0 +1,16 @@
+/* The layer map, stated before any import uses a layer -- see `theme.css`.
+   Tailwind's utilities are imported into `utilities` the way
+   `tailwindcss/index.css` does it, so every component lands there on this
+   entrypoint and on `/native` too, exactly where `.` already puts them. Without
+   `layer(utilities)` the CLI emitted them unlayered here, and they beat every
+   consumer rule on these two entries alone. */
+@layer theme, base, components, utilities;
+
+/* The theme first, as `native.css` has it: Tailwind writes the theme's
+   variables at the first `@theme` it meets. See docs/internal/model.md
+   (Which files import the theme). */
+@import "../theme.css";
+@import "tailwindcss/utilities.css" layer(utilities);
+/* Everything that is not `src/` -- see the note in `index.css`. Keeps a class
+   name in a docs code fence from shipping as a real rule in `dist/components.css`. */
+@import "./rules.css";

package/tw/components/rules.css

@@ -0,0 +1,41 @@
+/* Every component, with nothing they need to compile: the entry that imports
+   this file brings the theme and Tailwind once. `index.css` beside it is that
+   entry for `/components`; the complete stylesheet and `/native` are the
+   others. See docs/internal/model.md (One route to each utility). */
+@import "../typography.rules.css";
+
+/* `hidden` hides. The user agent says so at user-agent origin, which loses to
+   any author `display`, and every component sets one. The complete stylesheet
+   gets this rule from Tailwind's Preflight; this entry and `/native`, which
+   imports it, ship no Preflight, so a hidden `.btn` or `.card` stayed on the
+   page. Preflight's own rule, in the same layer, so the three entries agree. */
+@layer base {
+  [hidden]:where(:not([hidden="until-found"])) {
+    display: none !important;
+  }
+}
+
+/* `box` and `surface` once each, then every component's rules: the focused
+   entries beside this file each bring their own reference to `box.css`, and
+   importing five of them stacked five copies of every `@apply box`. */
+@import "../box.css";
+@import "../surface.rules.css";
+@import "./button.rules.css";
+@import "./feedback.rules.css";
+@import "./form.rules.css";
+@import "./surface.rules.css";
+@import "./tooltip.rules.css";
+
+/* The composition utilities -- `box`, `box-hover`, `box-active`,
+   `text-control`, `surface`, `input-group` -- are `@utility` rules whose bodies
+   the content scan will not emit on its own. `box` and friends appear only as
+   `@utility` blocks and `@apply` targets; `text-control`, `surface` and
+   `input-group` appear only inside `:is()`/`:where()` argument lists in
+   `intent.css` and `form.css`, never as a selector of their own. Safelisting
+   all six makes the emission deliberate; the composition-body check in
+   `exports.test.ts` fails the build if one is dropped. `text-control` and
+   `surface` are also documented as consumer-usable on their own.
+
+   The list is for the compiled build only. `scripts/build-tw.mjs` strips it
+   from the `tw/` copy, so a `/tw` consumer's Tailwind emits just the classes
+   it finds in their files rather than every one named here. */

package/tw/components/surface.css

@@ -0,0 +1,11 @@
+@reference "tailwindcss";
+@import "../theme.css";
+@import "../surface.css";
+
+/* The focused entry: what the rules in `surface.rules.css` need to compile on their
+   own, then the rules. An aggregate entry imports the rules file directly and
+   supplies those needs once -- Tailwind stacks a `@utility` each time a file
+   that defines it is imported or referenced, so a second route to `box.css`
+   doubles every `@apply box`. See docs/internal/model.md (One route to each
+   utility). */
+@import "./surface.rules.css";

package/tw/components/surface.rules.css

@@ -0,0 +1,225 @@
+/* A ghost, edged container that takes one unit when depth is supplied. */
+@utility card {
+  @layer families {
+    :where(&:not(.p-xs)) {
+      --_m-p-xs: initial;
+    }
+
+    :where(&:not(.p-sm)) {
+      --_m-p-sm: initial;
+    }
+
+    :where(&:not(.p-lg)) {
+      --_m-p-lg: initial;
+    }
+
+    :where(&:not(.flush)) {
+      --_m-flush: initial;
+    }
+  }
+
+  /* The hover flag, raised by `interactive` and `hoverable` below. */
+  @layer families {
+    :where(&:not(.interactive, .hoverable)) {
+      --_m-hover: initial;
+    }
+  }
+
+  @apply surface;
+
+  /* After the `@apply`, not before: `surface` inlines its own resting geometry
+     at that point, so defaults written above it would be overridden by the very
+     utility they are meant to specialise. */
+  --_d-fill: 0%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 100%;
+  --_d-elevation: 1;
+
+  /* The padding steps and `flush`. Each raises a flag (`modifiers.css`) and
+     the lines below compute only while theirs is up, so `@apply card p-xs`
+     carries the step. `--_scale-pad` is the step `box` scales the corner
+     and the depth by; `flush` leaves it alone. */
+  --_xs-pad: var(--_m-p-xs) 0.5rem;
+  --_sm-pad: var(--_m-p-sm) 0.75rem;
+  --_lg-pad: var(--_m-p-lg) 2rem;
+  --_flush-pad: var(--_m-flush) 0px;
+  --_xs-scale: var(--_m-p-xs) 0.5;
+  --_sm-scale: var(--_m-p-sm) 0.75;
+  --_lg-scale: var(--_m-p-lg) 1.25;
+  --_scale-pad: var(--_lg-scale, var(--_sm-scale, var(--_xs-scale)));
+
+  padding: var(--_flush-pad, var(--_lg-pad, var(--_sm-pad, var(--_xs-pad, 1.25rem))));
+
+  /* A quiet neutral tint -- `.soft`, on the card or on a container -- rests
+     untinted instead of mixing its 12%: 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),
+     so swapping the ground token alone does not read as quieter. A resting
+     neutral `.card.soft` is `--color-foreground` with no ink mixed in -- a
+     plain step up from the page that marks a different container without
+     drawing attention to it.
+
+     A named intent keeps its ordinary 12% wash: 12% of an actual hue does not
+     read as a slab the way 12% of near-black ink does (`.card.soft.destructive`
+     is a gentle `249, 225, 225`), and untinting it would silence it rather than
+     quiet it. `.ghost` and `.solid` are not a tint and keep their own plates.
+
+     Which case applies is `surface`'s `--_quiet`, stepped from the resolved
+     fill and the intent's cap rather than keyed on classes on the card, so a
+     container's `.soft` renders the plate the card's own `.soft` does. Keyed
+     on the card's classes, `.soft > .card` drew the grey slab. `--_fill-cap`
+     (box.css's override slot, not `--ui-fill` directly -- see the comment
+     there) drops to 0% only when quiet, and the ground steps to the
+     foreground only then, through `--_d-surface-ground`, the default
+     `surface` reads beneath the public `--ui-surface-ground`, so a consumer's
+     override, or glass's ground, wins.
+
+     Composed with `box-hover`'s formula (`min(100%, resting + 14%)`), the
+     quiet rest reveals the intent on hover with no second fill declaration:
+     resting at 0% means hover lands at exactly the hover step, 14%, in
+     `--intent-hover`, and the ground steps to `--color-surface` at the same
+     moment. Scoped to `.interactive` and `.hoverable`, the two classes that
+     opt a card into `box-hover`. A named intent rests tinted, so the generic
+     formula deepens it on hover (12% to 26%). */
+  --_fill-cap: calc(100% - var(--_quiet));
+  --_d-surface-ground: color-mix(in oklab, var(--color-foreground) var(--_quiet), var(--color-background));
+
+  --_hover-ground: var(--_m-hover) color-mix(in oklab, var(--color-surface) var(--_quiet), var(--color-background));
+
+  /* Behind the query `box-hover` is, so a tapped card keeps its ground. */
+  @media (hover: hover) {
+    &:hover {
+      --_d-surface-ground: var(
+        --_hover-ground,
+        color-mix(in oklab, var(--color-foreground) var(--_quiet), var(--color-background))
+      );
+    }
+  }
+
+  /* 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
+     card-specific about either.
+
+     `.interactive` is the whole opt-in and stays that way; `.hoverable` and
+     `.pressable` are its halves, for a card that answers one gesture and not
+     the other. A card with its own nested controls takes `.hoverable` for the
+     hover warmth without the press-scale that reads as "you activated the
+     card" when the click really landed on a nested button. `.hoverable` alone
+     does not set the pointer cursor: that travels with being a click target,
+     i.e. with `.pressable` / `.interactive`. */
+}
+
+/* The opt-in itself: utilities, so `@apply card interactive` carries the
+   gestures. Each is `box-hover` or `box-active` under the name a card's
+   markup uses, and the hover half raises the flag the card's quiet ground
+   reads. The pointer is 0-1-0 here, below `box`'s disabled cursor, so a
+   disabled interactive card does not invite the click. */
+@utility hoverable {
+  @layer families {
+    --_m-hover: ;
+  }
+
+  @apply box-hover;
+}
+
+@utility pressable {
+  @apply box-active cursor-pointer;
+}
+
+@utility interactive {
+  @layer families {
+    --_m-hover: ;
+  }
+
+  @apply box-hover box-active cursor-pointer;
+}
+
+/* A panel is the flush, unelevated sibling: sidebars, toolbars, and wells that
+   sit flat against the layout rather than floating above it. Soft and edgeless
+   is what makes it read as a well without drawing a line to say so. */
+@utility panel {
+  @layer families {
+    :where(&:not(.p-xs)) {
+      --_m-p-xs: initial;
+    }
+
+    :where(&:not(.p-sm)) {
+      --_m-p-sm: initial;
+    }
+
+    :where(&:not(.p-lg)) {
+      --_m-p-lg: initial;
+    }
+
+    :where(&:not(.flush)) {
+      --_m-flush: initial;
+    }
+  }
+
+  @apply surface;
+
+  --_d-fill: 12%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 0%;
+  --_d-elevation: 0;
+
+  /* The padding steps and `flush`. Each raises a flag (`modifiers.css`) and
+     the lines below compute only while theirs is up, so `@apply card p-xs`
+     carries the step. `--_scale-pad` is the step `box` scales the corner
+     and the depth by; `flush` leaves it alone. */
+  --_xs-pad: var(--_m-p-xs) 0.25rem;
+  --_sm-pad: var(--_m-p-sm) 0.5rem;
+  --_lg-pad: var(--_m-p-lg) 1.5rem;
+  --_flush-pad: var(--_m-flush) 0px;
+  --_xs-scale: var(--_m-p-xs) 0.5;
+  --_sm-scale: var(--_m-p-sm) 0.75;
+  --_lg-scale: var(--_m-p-lg) 1.25;
+  --_scale-pad: var(--_lg-scale, var(--_sm-scale, var(--_xs-scale)));
+
+  padding: var(--_flush-pad, var(--_lg-pad, var(--_sm-pad, var(--_xs-pad, 1rem))));
+
+  /* Neutral panels are the common case -- layout wells, sidebars, toolbars with
+     no named intent -- and 12% of `--color-text` (near-black) mixed onto the
+     page is far more assertive than 12% of a hue (`217, 217, 217` against a
+     `250, 250, 250` page): the same "neutral ink reads louder" effect
+     `.card.soft` answers, and the reason `--intent-fill-max` stops neutral's
+     fill short everywhere else. So a quiet neutral tint rests untinted on
+     `--color-foreground`, through `--_d-surface-ground`, the default
+     `.card.soft` rests on, so a bare `.panel` rests at exactly the plate a
+     `.card.soft` does, and a consumer's `--ui-surface-ground` or glass's
+     translucent ground wins over it: a neutral panel under `.glass` is glass.
+
+     A named intent keeps its wash: a panel 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 (a resting `.panel.destructive` is
+     a gentle `249, 225, 225` wash). `.ghost` and `.solid` keep their own
+     plates. Which case applies is `surface`'s `--_quiet`, stepped from the
+     resolved fill, so a container's `.ghost` or `.solid` renders the panel its
+     own would; keyed on the panel's classes, both landed on the quiet plate.
+     Permanent rather than hover-revealed: a panel has no interaction state to
+     reveal a tint into. */
+  --_fill-cap: calc(100% - var(--_quiet));
+  --_d-surface-ground: color-mix(in oklab, var(--color-foreground) var(--_quiet), var(--color-background));
+}
+
+/* A closed `<dialog>` is hidden, and an open one centred, by `surface` itself,
+   so every element that applies it -- these three, `.alert`, a consumer's
+   `@apply surface` -- gets both (see `surface.css`). That hide is in the
+   layer the surface is applied in. For the three containers a consumer
+   reaches for as a dialog, it is restated here unlayered: hiding a closed
+   dialog is behaviour, so it beats any layered rule whatever its specificity.
+   The centring stays a default in `utilities` at zero specificity, so a
+   consumer's own margin -- a utility, or unlayered CSS -- still places one.
+
+   Here rather than in the reset, so every entrypoint that ships `.card` ships
+   the fix, `/components` included. */
+dialog:is(.card, .panel, .surface):not([open]) {
+  display: none;
+}
+
+/* The popover counterpart, unlayered for the same reason. `.alert` joins the
+   list: a toast is the surface most often given `popover`. */
+:is(.card, .panel, .surface, .alert)[popover]:not(:popover-open) {
+  display: none;
+}

package/tw/components/tooltip.css

@@ -0,0 +1,11 @@
+@reference "tailwindcss";
+@import "../theme.css";
+@reference "../surface.css";
+
+/* The focused entry: what the rules in `tooltip.rules.css` need to compile on their
+   own, then the rules. An aggregate entry imports the rules file directly and
+   supplies those needs once -- Tailwind stacks a `@utility` each time a file
+   that defines it is imported or referenced, so a second route to `box.css`
+   doubles every `@apply box`. See docs/internal/model.md (One route to each
+   utility). */
+@import "./tooltip.rules.css";

package/{dist/tw/components/tooltip.css → tw/components/tooltip.rules.css}

@@ -1,8 +1,3 @@
-@reference "tailwindcss";
-@import "../theme.css";
-@reference "../box.css";
-@reference "../surface.css";
-
 /* 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, so intent, presentation, aesthetic, and
@@ -17,40 +12,45 @@
    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;
-  /* How long the bubble stays after the pointer leaves the trigger: long
-     enough to cross `--tooltip-gap` onto the bubble, which keeps it open
-     (WCAG 1.4.13). */
-  --tooltip-linger: 300ms;
-  --tooltip-top: calc(var(--tooltip-gap) * -1);
-  --tooltip-right: auto;
-  --tooltip-bottom: auto;
-  --tooltip-left: 50%;
-  --tooltip-origin: bottom;
-  --tooltip-transform: translate(-50%, -100%);
+  /* `--tooltip-gap` and `--tooltip-linger` are public, read with their
+     defaults rather than declared, so a value set on any ancestor reaches the
+     tooltip. The linger is how long the bubble stays after the pointer leaves
+     the trigger: long enough to cross the gap onto the bubble, which keeps it
+     open (WCAG 1.4.13). The default is resolved here, so a bubble outside a
+     tooltip keeps no delay unless a linger is set above it. The bubble reads
+     the public one first, so a value set on the bubble itself, as 0.8
+     allowed, still wins. */
+  --_tooltip-gap: var(--tooltip-gap, 0.5rem);
+  --_tooltip-linger: var(--tooltip-linger, 300ms);
+  --_tooltip-top: calc(var(--_tooltip-gap) * -1);
+  --_tooltip-right: auto;
+  --_tooltip-bottom: auto;
+  --_tooltip-left: 50%;
+  --_tooltip-origin: bottom;
+  --_tooltip-transform: translate(-50%, -100%);
 
   @apply relative inline-block;
 
   &[data-tooltip-position="bottom"] {
-    --tooltip-top: auto;
-    --tooltip-bottom: calc(var(--tooltip-gap) * -1);
-    --tooltip-origin: top;
-    --tooltip-transform: translate(-50%, 100%);
+    --_tooltip-top: auto;
+    --_tooltip-bottom: calc(var(--_tooltip-gap) * -1);
+    --_tooltip-origin: top;
+    --_tooltip-transform: translate(-50%, 100%);
   }
 
   &[data-tooltip-position="left"] {
-    --tooltip-top: 50%;
-    --tooltip-left: calc(var(--tooltip-gap) * -1);
-    --tooltip-origin: right;
-    --tooltip-transform: translate(-100%, -50%);
+    --_tooltip-top: 50%;
+    --_tooltip-left: calc(var(--_tooltip-gap) * -1);
+    --_tooltip-origin: right;
+    --_tooltip-transform: translate(-100%, -50%);
   }
 
   &[data-tooltip-position="right"] {
-    --tooltip-top: 50%;
-    --tooltip-left: auto;
-    --tooltip-right: calc(var(--tooltip-gap) * -1);
-    --tooltip-origin: left;
-    --tooltip-transform: translate(100%, -50%);
+    --_tooltip-top: 50%;
+    --_tooltip-left: auto;
+    --_tooltip-right: calc(var(--_tooltip-gap) * -1);
+    --_tooltip-origin: left;
+    --_tooltip-transform: translate(100%, -50%);
   }
 }
 
@@ -64,13 +64,13 @@
   /* Hidden rather than merely transparent, so a closed bubble is nothing
      under the pointer, and it lingers before it goes: the host stays hovered
      once the pointer is over the bubble, so crossing the gap in
-     `--tooltip-linger` keeps it open. Visibility switches at the end of the
+     `--_tooltip-linger` keeps it open. Visibility switches at the end of the
      fade, so the bubble is there to land on for the whole of it. */
   visibility: hidden;
   transition-property: opacity, transform, visibility;
   transition-duration: var(--motion-duration-normal);
   transition-timing-function: var(--motion-ease);
-  transition-delay: var(--tooltip-linger, 0s);
+  transition-delay: var(--tooltip-linger, var(--_tooltip-linger, 0s));
 
   /* Filled, over a ground of its own. An intent floods the fill
      (`.tooltip-bubble.primary` is the primary colour); with no intent
@@ -86,6 +86,10 @@
   --_d-elevation: 0;
   --_d-ground: var(--ui-surface-ground, var(--intent-subtle));
 
+  /* `surface` refuses the silhouette clip because it holds other things. The
+     bubble holds a line of text, so it takes the aesthetic's shape back. */
+  clip-path: var(--ui-clip, none);
+
   /* 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. */
@@ -93,9 +97,9 @@
 
   /* 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%;
+     is near-white). The element's own `.edgeless` lowers it -- the same
+     `--_own-edge` `text-control` reads. */
+  --_edge-floor: var(--_own-edge);
 
   /* A bubble is a small transient popover, not a modal, so it takes the
      control corner `box` computes rather than the surface one `surface` hands
@@ -105,39 +109,52 @@
     calc(var(--_corner) * var(--ui-corner-tl, 1)) calc(var(--_corner) * var(--ui-corner-tr, 1))
       calc(var(--_corner) * var(--ui-corner-br, 1)) calc(var(--_corner) * var(--ui-corner-bl, 1))
   );
-  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%;
-  }
+  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);
 
   /* The bubble appears without growing under reduced motion, for the entries
      without the reset; see `box.css`. */
   @media (prefers-reduced-motion: reduce) {
     transition-duration: 0.01ms;
   }
-}
 
-/* 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: the bubble is a
-   sibling of the trigger, so only the shared ancestor can see both at once. The
-   cost is the one `.input-group` accepts -- the bubble also shows on a mouse
-   click.
-
-   In `utilities`, where the bubble's own `@utility` is, winning on specificity
-   -- see the seams note in `form.css`. */
-@layer utilities {
-  .tooltip:hover .tooltip-bubble,
-  .tooltip:focus-within .tooltip-bubble,
-  .tooltip[data-state="open"] .tooltip-bubble {
+  /* The no-intent plate, carried so `@apply tooltip-bubble` gets it: the rule
+     in `intent.css` names `.tooltip-bubble`, which a consumer's `.my-tip` is
+     not, so an applied bubble took `surface`'s neutral reset and drew the
+     page's ink at a fifth. In `families` after that reset, which `surface`
+     carries at the same zero specificity, so this one wins and an intent
+     applied with it still beats both. Never on `.tooltip-bubble` itself,
+     which keeps the rule in `components`. */
+  @layer families {
+    :where(&:not(.tooltip-bubble, .primary, .secondary, .success, .warning, .destructive, .info)) {
+      --intent-color: var(--color-tooltip);
+      --intent-contrast: var(--color-tooltip-contrast);
+      --intent-hover: var(--color-tooltip);
+      --intent-strong: var(--color-tooltip-contrast);
+      --intent-subtle: var(--color-surface);
+      --intent-border: var(--ui-ink, var(--color-border));
+      --intent-fill-max: 100%;
+    }
+  }
+
+  /* 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: the bubble
+     is a sibling of the trigger, so only the shared ancestor can see both at
+     once. The cost is the one `.input-group` accepts -- the bubble also shows
+     on a mouse click.
+
+     In the body, so an applied bubble opens in a `.tooltip` as the class
+     does; they win over the resting values above on specificity. */
+  .tooltip:hover &,
+  .tooltip:focus-within &,
+  .tooltip[data-state="open"] & {
     opacity: 1;
-    transform: var(--tooltip-transform) scale(1);
+    transform: var(--_tooltip-transform) scale(1);
     visibility: visible;
     transition-delay: 0s;
   }
@@ -147,9 +164,9 @@
      writes `data-state="closed"` and clears it when the pointer and focus
      leave. Later and as specific as the rule above, so it wins over hover and
      focus alike. */
-  .tooltip[data-state="closed"] .tooltip-bubble {
+  .tooltip[data-state="closed"] & {
     opacity: 0;
-    transform: var(--tooltip-transform) scale(0);
+    transform: var(--_tooltip-transform) scale(0);
     visibility: hidden;
     transition-delay: 0s;
   }
@@ -176,6 +193,10 @@
   --_d-elevation: 0;
   --_d-ground: var(--intent-subtle);
 
+  /* A ground of its own, so no ink from above passes through, as on `surface`. */
+  --_held-ink: var(--_fg-own);
+  --_held-on: var(--_own-hold);
+
   /* The trigger is best a real `<button>`, which is a `.btn` under `/native`
      and carries the user agent's padding under `/components`; either would
      stretch the chip past its own size. */

package/{dist/tw → tw}/corner.css

@@ -1,5 +1,7 @@
-/* Imported into the `components` layer by `theme.css`, below every utility, so
-   a consumer's own utility or unlayered CSS beats these classes. See
+/* Each class here is a `@utility` whose body sits in `utilities.families`: a
+   utility, so `@apply` and Tailwind's variants reach it, and in a sublayer, so
+   it still loses to every rule written straight into `utilities` -- a
+   component's, or a consumer's own utility. See
    docs/internal/model.md#cascade-layers.
 
    The corner pattern: which corners take the corner the aesthetic draws. `box`
@@ -10,17 +12,21 @@
    is taken as written and ignores the pattern. See docs/internal/model.md#material-tokens. */
 
 /* Top-left and bottom-right. */
-.cut-diagonal {
-  --ui-corner-tl: 1;
-  --ui-corner-tr: 0;
-  --ui-corner-br: 1;
-  --ui-corner-bl: 0;
+@utility cut-diagonal {
+  @layer families {
+    --ui-corner-tl: 1;
+    --ui-corner-tr: 0;
+    --ui-corner-br: 1;
+    --ui-corner-bl: 0;
+  }
 }
 
 /* Top-right and bottom-left. */
-.cut-diagonal-reverse {
-  --ui-corner-tl: 0;
-  --ui-corner-tr: 1;
-  --ui-corner-br: 0;
-  --ui-corner-bl: 1;
+@utility cut-diagonal-reverse {
+  @layer families {
+    --ui-corner-tl: 0;
+    --ui-corner-tr: 1;
+    --ui-corner-br: 0;
+    --ui-corner-bl: 1;
+  }
 }

package/{dist/tw → tw}/elevation.css

@@ -1,5 +1,7 @@
-/* Imported into the `components` layer by `theme.css`, below every utility, so
-   a consumer's own utility or unlayered CSS beats these classes. See
+/* Each class here is a `@utility` whose body sits in `utilities.families`: a
+   utility, so `@apply` and Tailwind's variants reach it, and in a sublayer, so
+   it still loses to every rule written straight into `utilities` -- a
+   component's, or a consumer's own utility. See
    docs/internal/model.md#cascade-layers. */
 
 /* Elevation is a modifier, not an axis: depth is a per-element decision (raised
@@ -8,8 +10,8 @@
    `.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
+   `--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. Inherited, a
    `.floating` dialog's ambient x2 would reach its own unclassed buttons and
    double their shadow with nothing in the markup asking for it. Depth is not
@@ -35,39 +37,43 @@
   inherits: false;
 }
 
-@property --elevation-y {
+@property --_elevation-y {
   syntax: "*";
   inherits: false;
 }
 
-@property --elevation-blur {
+@property --_elevation-blur {
   syntax: "*";
   inherits: false;
 }
 
 /* No part-based depth. Complete surface shadow values, such as glass, are not
    reached by the elevation multiplier. */
-.flat {
-  --ui-elevation: 0;
+@utility flat {
+  @layer families {
+    --ui-elevation: 0;
+  }
 }
 
-/* The plain-step geometry both rungs multiply, declared once so the two cannot
-   drift. It is the fallback for a page with no aesthetic in scope; an aesthetic
+/* The plain-step geometry both rungs multiply. Each utility restates it so
+   `@apply raised` carries it, so the two copies must stay identical. It is the fallback for a page with no aesthetic in scope; an aesthetic
    that declares its own shadow parts overrides it, and the elevation multiplier
    scales whichever one lands. `.floating` takes its extra depth from the
-   multiplier below, not a second copy of these parts. */
-.raised,
-.floating {
-  --elevation-y: 1px;
-  --elevation-blur: 3px;
-}
-
+   multiplier, not from different parts. */
 /* The aesthetic's depth as authored, said explicitly. */
-.raised {
-  --ui-elevation: 1;
+@utility raised {
+  @layer families {
+    --_elevation-y: 1px;
+    --_elevation-blur: 3px;
+    --ui-elevation: 1;
+  }
 }
 
 /* Twice it, for menus and popovers. */
-.floating {
-  --ui-elevation: 2;
+@utility floating {
+  @layer families {
+    --_elevation-y: 1px;
+    --_elevation-blur: 3px;
+    --ui-elevation: 2;
+  }
 }