@codenhub/styles 0.6.0 → 0.8.0

package/tw/surface.rules.css

@@ -0,0 +1,212 @@
+/* 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%;
+
+  /* A surface rests on a ground of its own, so no ink from above passes
+     through it: what is inside sits on this plate. It hands its own down
+     only where its fill is a plate (`--_own-hold`, which `box` steps and
+     which does not inherit). Unfilled, it hands down none, so a neutral
+     button in a soft success alert keeps the page's ink, not the alert's. */
+  --_held-ink: var(--_fg-own);
+  --_held-on: var(--_own-hold);
+
+  /* The neutral reset, carried so `@apply surface` gets it: the reset in
+     `intent.css` names `.surface`, which a consumer's `.my-surface` is not, so
+     a surface inside a `.card.success` took the card's intent. Only for an
+     element that carries neither an intent class nor one of the package's own
+     surface classes; those keep the reset in `components`, where a consumer's
+     own intent class beats it, and `.tooltip-bubble` keeps its own no-intent
+     plate. Zero specificity, so every rule that writes an intent slot on the
+     element wins over it. The values track `.neutral`'s. */
+  /* In `families`, beside the intent classes: applied with an intent --
+     `@apply surface info` -- the reset and the intent land in one layer, where the
+     intent's 0-1-0 beats this. Left in the rule's own layer it would beat
+     every intent applied with it. */
+  @layer families {
+    :where(
+      &:not(
+        .surface,
+        .card,
+        .panel,
+        .alert,
+        .tooltip-bubble,
+        .primary,
+        .secondary,
+        .success,
+        .warning,
+        .destructive,
+        .info
+      )
+    ) {
+      --intent-color: var(--color-text);
+      --intent-contrast: var(--color-text-contrast);
+      --intent-hover: var(--color-text-hover);
+      --intent-strong: var(--color-text-strong);
+      --intent-subtle: var(--color-surface);
+      --intent-border: var(--ui-ink, var(--color-border));
+      --intent-fill-max: 20%;
+    }
+  }
+
+  /* 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)));
+
+  /* Whether this surface rests on a quiet neutral tint, as 0% or 100%: a
+     neutral intent (its fill cap is below 100%) and a resolved fill above
+     nothing and below that cap -- `.soft`, a panel's or an alert's default.
+     12% of the page's near-black ink reads as a grey slab rather than a step,
+     so `.card`, `.panel`, and `.alert` read this to rest such a fill on the
+     quiet foreground instead. Stepped from the resolved fill rather than
+     keyed on a class on the element, because presentation cascades: a
+     container's `.soft` and the surface's own are one request and have to
+     render one plate. Stepped rather than divided, as `box`'s `--_plate` is,
+     because the percentages cannot be divided in every engine yet. Only the
+     components that reinterpret the tint apply it; `surface` alone keeps the
+     plain tint. */
+  --_quiet: min(
+    clamp(0%, calc((100% - var(--intent-fill-max, 100%)) * 1000), 100%),
+    clamp(0%, calc(var(--ui-fill, var(--_d-fill)) * 1000), 100%),
+    clamp(0%, calc((var(--intent-fill-max, 100%) - var(--ui-fill, var(--_d-fill))) * 1000), 100%)
+  );
+
+  /* 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))
+  );
+  /* No silhouette clip, whatever the aesthetic's `--ui-clip`: a clip cuts
+     everything inside the element, and a surface is the box that holds other
+     things. Under `.pixel` a tooltip in a card computed visible and was never
+     painted, and a child's shadow and focus outline were cut with it. A
+     surface is square there, with the ring, as a table is. */
+  clip-path: none;
+  /* 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.
+
+     Cleared under liquid glass, which draws the blur on a layer below instead:
+     a surface with a backdrop filter of its own is a backdrop root, and a layer
+     inside one sees only the surface. */
+  --_layers-clear: var(--_glass-liquid-on) none;
+  -webkit-backdrop-filter: var(--_layers-clear, var(--ui-backdrop, none));
+  backdrop-filter: var(--_layers-clear, var(--ui-backdrop, none));
+
+  /* Liquid glass's two layers, a blur under the content and a lens with its rim
+     and sheen above it. A pseudo-element is not a value a token reaches, so
+     they are drawn here, where `@apply surface` carries them, and glass hands
+     them its values: `--_glass-liquid-on` is the space-toggle flag the nearest
+     liquid region in a glass scope sets on and every other region sets off,
+     and the blur, lens, rim, and sheen are its privates. With no liquid region
+     in scope every declaration below is a no-op, so the surface names no
+     aesthetic's class and changes nothing without one.
+
+     Zero specificity, so anything that writes these on the element beats them:
+     the tooltip bubble's own `absolute`, a consumer's `relative` or `before:`
+     utility. Off, the anchor, the isolation, and the content revert to the
+     layer below, so a surface outside a liquid region keeps every positioning
+     and pseudo-element rule written for it in another layer; the layers' other
+     declarations compute to `unset`, which is what an undeclared one is. Both
+     slots are spent where the flag is on, so a host there carries no
+     `::before` or `::after` of its own. See
+     docs/internal/model.md#glass-liquid. */
+  :where(&) {
+    --_layers-anchor: var(--_glass-liquid-on) relative;
+    --_layers-isolation: var(--_glass-liquid-on) isolate;
+
+    position: var(--_layers-anchor, revert-layer);
+    isolation: var(--_layers-isolation, revert-layer);
+  }
+
+  :where(&)::before,
+  :where(&)::after {
+    --_layers-content: var(--_glass-liquid-on) "";
+
+    position: var(--_glass-liquid-on) absolute;
+    inset: var(--_glass-liquid-on) 0;
+    z-index: var(--_glass-liquid-on) -1;
+    border-radius: var(--_glass-liquid-on) inherit;
+    corner-shape: var(--_glass-liquid-on) inherit;
+    content: var(--_layers-content, revert-layer);
+    pointer-events: var(--_glass-liquid-on) none;
+  }
+
+  /* Prefixed first, for the reason above. */
+  :where(&)::before {
+    -webkit-backdrop-filter: var(--_glass-liquid-on) var(--_glass-liquid-blur);
+    backdrop-filter: var(--_glass-liquid-on) var(--_glass-liquid-blur);
+  }
+
+  :where(&)::after {
+    backdrop-filter: var(--_glass-liquid-on) var(--_glass-liquid-lens);
+    background-image: var(--_glass-liquid-on) var(--_glass-liquid-sheen);
+    box-shadow: var(--_glass-liquid-on) var(--_glass-liquid-rim);
+  }
+
+  /* A `<dialog>`: hidden while closed, centred once open. The user agent
+     promises both, at user-agent origin, which loses to any author rule at
+     all: `display: block` above beats the first, so a closed dialog rendered,
+     and a margin reset beats the second, so an open one pinned to the
+     top-left. Carried here so `@apply surface` keeps both; the package's own
+     surfaces also keep the unlayered hide in `components/surface.css`.
+
+     The hide outranks a display utility on specificity, 0-2-1 against 0-1-0,
+     so a closed `.my-sheet.flex` stays closed; written unlayered, the
+     consumer's own applied rule beats every layered one. The centring is a
+     default at zero specificity, so a consumer's margin -- a utility, or their
+     own CSS in the same layer -- still places the dialog. */
+  &:is(dialog):not([open]) {
+    display: none;
+  }
+
+  /* A closed popover, for the same reason: the user agent's
+     `[popover]:not(:popover-open)` hide loses to `display: block` above, so a
+     `.card.floating` menu rendered before it was ever shown. */
+  &[popover]:not(:popover-open) {
+    display: none;
+  }
+
+  :where(&:is(dialog)[open]) {
+    margin: auto;
+  }
+}

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

@@ -2,27 +2,43 @@
    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. */
+   rank the same. Intent, presentation, elevation, corner, and size are
+   `@utility` rules whose bodies sit in `utilities.families`, a sublayer that
+   loses to every rule written straight into `utilities` -- a component's, or
+   a consumer's own utility -- so `@apply` and the variants reach them and an
+   override still beats them. The intent floor and resets, and every
+   aesthetic's token class, stay in `components`. 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);
+/* Unlayered imports: a `@utility` has to be top-level, and each of these files
+   places its own rules -- the class families in `utilities.families`, the
+   intent floor and resets in `components`. */
+@import "./intent.css";
+@import "./presentation.css";
+@import "./elevation.css";
+@import "./corner.css";
+@import "./size.css";
+@import "./modifiers.css";
 /* 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. */
 
 /* Color tokens are declared once with `light-dark()`, which resolves at the
    point of use against the consuming element's computed `color-scheme`. Theme
-   selectors below therefore set `color-scheme` and nothing else. Verified
+   selectors below therefore set `color-scheme`, and the region's own `color`
+   so its text re-resolves too. 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));
@@ -38,8 +54,15 @@
   /* 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));
+     already separates (27 units).
+
+     `--_contrast-border` is set only under `prefers-contrast: more`, below.
+     Read here rather than restating the token there, so a consumer who sets
+     `--color-border` replaces both and keeps their colour. */
+  --color-border: var(--_contrast-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.
@@ -120,22 +143,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;
 }
 
-/* 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
@@ -171,13 +185,25 @@
        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. */
+       shadow parts instead, and are not read from here.
+
+       They resolve `--elevation-color` here, once, so a container's own
+       `--elevation-color` does not reach them. Declaring them on every element
+       instead would re-resolve it, and would also redeclare them under a
+       container that sets its own `--elevation-sm`, which no descendant would
+       then see. A consumer's override wins over a colour that follows the
+       container; docs/usage/theming.md#foundation-tokens says so. */
     --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);
 
-    --focus-ring: color-mix(in srgb, var(--color-primary) 64%, transparent);
+    /* `--focus-ring` is not declared: its default is the brand colour
+       at 64%, and declared here it resolved against `:root`'s
+       `--color-primary` and inherited, so a region that set its own brand
+       colour filled a primary button in it and ringed it in the page's. Every
+       reader falls back to the mix on the focused element instead, and a
+       consumer's `--focus-ring` on any ancestor still inherits. */
     /* `--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
@@ -200,28 +226,29 @@
   /* 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. */
+     this whichever sheet loads first. Reduced motion keeps it and drops only
+     its motion, in `box`. */
   :root {
     --ui-active-transform: scale(0.97);
   }
 
-  @media (prefers-reduced-motion: reduce) {
-    :root {
-      --ui-active-transform: none;
-    }
-  }
-
+  /* A forced theme re-resolves the region's own text as well as its scheme.
+     `color` inherits as a computed colour, already resolved against the scheme
+     above, so a `<p>` in an `<aside class="dark">` on a light page kept the
+     light theme's near-black. No background: a region that wants the theme's
+     ground says so. In `theme`, so every utility and component still wins. */
   .light,
   .theme-light,
   [data-theme="light"] {
     color-scheme: light;
+    color: var(--color-text);
   }
 
   .dark,
   .theme-dark,
   [data-theme="dark"] {
     color-scheme: dark;
+    color: var(--color-text);
   }
 }
 
@@ -231,13 +258,14 @@
    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.
+   `docs/usage/theming.md#light-and-dark`. 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
@@ -256,13 +284,61 @@
   }
 }
 
+/* Paper is the light ground. A browser leaves backgrounds off a printed page
+   unless told otherwise, so a dark page printed its near-white text on no
+   ground at all. Every token resolves through `light-dark()`, so printing in
+   the light scheme re-resolves all of them, a forced-dark region's included.
+   In `theme`, after the selectors above and at their specificity, so it beats
+   them and a consumer's utility still beats it. It does not reach a `dark:`
+   utility, which keys on the class and not on the scheme. */
+@layer theme {
+  @media print {
+    :root,
+    .dark,
+    .theme-dark,
+    [data-theme="dark"] {
+      color-scheme: light;
+    }
+  }
+}
+
+/* More contrast, asked for by the reader. The quiet surface line is 2.48:1
+   against the light page and 1.91:1 against the dark one by choice; here it
+   takes a grey two steps heavier, neutral-600 in light and neutral-400 in
+   dark. The control grey between them is not enough: `box` fades a line by the
+   fill under it, and on a neutral `.badge.soft.edged` neutral-500 lands at
+   2.9:1 against its own tint. One token, so every neutral line that reads it
+   follows: surfaces, dividers, table rules, a neutral button's edge.
+   `--color-border` reads this slot first, so a consumer's own value for the
+   token replaces both and still wins.
+   See docs/accessibility.md. */
+@layer theme {
+  @media (prefers-contrast: more) {
+    :root,
+    :host {
+      --_contrast-border: light-dark(var(--color-neutral-600), var(--color-neutral-400));
+    }
+  }
+}
+
 /* 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. */
+   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;

package/tw/typography.css

@@ -0,0 +1,8 @@
+@reference "tailwindcss";
+@import "./theme.css";
+
+/* The focused entry: Tailwind and the theme, which the rules need to compile
+   on their own, then the rules. An aggregate entry imports the rules file and
+   brings the theme itself, once. See docs/internal/model.md (One route to each
+   utility). */
+@import "./typography.rules.css";

package/{dist/tw/typography.css → tw/typography.rules.css}

@@ -1,6 +1,3 @@
-@reference "tailwindcss";
-@import "./theme.css";
-
 /* `text-6xl` and up bundle `line-height: 1`, which sets a heading's line box to
    the font size exactly: descenders reach the box edge and a wrapped heading's
    lines collide. The two largest steps set an explicit leading that still