@codenhub/styles 0.1.0 → 0.2.0

package/dist/tw/theme.css

@@ -2,11 +2,8 @@
 @import "./intent.css";
 @import "./presentation.css";
 @import "./elevation.css";
-@source not "../dist";
-@source not "../tests";
-@source not "../dev";
-@source not "../debug";
-@source not "../playground";
+/* 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
@@ -27,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
@@ -50,7 +57,9 @@
   --color-text-secondary: light-dark(var(--color-neutral-700), var(--color-neutral-400));
   --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));
-  --color-text-subtle: light-dark(var(--color-neutral-200), var(--color-neutral-900));
+  /* 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-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
@@ -215,4 +224,33 @@
   color-scheme: dark;
 }
 
-@custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *));
+/* The first arm mirrors the `color-scheme: dark` block above, all three
+   spellings included -- a consumer writing `.theme-dark` for the token theme
+   was otherwise left without the matching `dark:` variant.
+
+   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;
+    }
+  }
+}

package/dist/tw/utilities/content.css

@@ -37,14 +37,17 @@
      ghost table is boundaries and type and nothing else -- which is what `.ghost`
      is for on this component, since the published resting fill is `soft`.
 
-     Any fill at all brings the ground back whole rather than in proportion. A
-     soft head mixed onto the page instead of onto `--intent-subtle` is a
-     different colour from the one this component has always drawn, and the fill
-     is meant to read as a step past the tint rather than as a replacement for
-     it. A saturating ramp says that, because the signal is a percentage and
-     there is no branch to hang off one: the smallest fill any presentation asks
-     for is 12%, so a multiplier of 100 puts every non-zero fill over the top and
-     leaves zero where it is.
+     Zero stays zero, and nothing past it saturates the same way any more. A
+     `* 100` multiplier used to put every non-zero fill over the `min(100%, ...)`
+     ceiling in one step -- `.soft`'s 12% and `.solid`'s 100% both landed on a
+     fully opaque plate, so the only thing left to tell them apart was how much
+     `--intent-color` got mixed onto it after (`--table-fill`, 12% vs 20% capped),
+     a difference too small to read as the volume-level step presentation
+     promises everywhere else in the model. `* 5` keeps zero at zero and a
+     `.solid`'s 100% raw fill still clears the ceiling -- the same fully opaque
+     head it always drew -- but stops `.soft`'s 12% short, at 60%: a visibly
+     lighter, partly-page-showing-through plate instead of a second opaque one,
+     which is what makes the two presentations separate again.
 
      It reads `--ui-fill` rather than `--table-fill` because that is the question
      being asked: what the presentation wanted, not what the intent cap and an
@@ -53,10 +56,48 @@
      the raw class value also keeps the expression a `calc()` over one `var()`
      rather than over `--table-fill`'s own `calc()`/`min()` chain, which matters
      for the reason `--table-rule-plated` below records. */
-  --table-ground: min(100%, calc(var(--ui-fill, var(--_d-fill)) * 100));
+  --table-ground: min(100%, calc(var(--ui-fill, var(--_d-fill)) * 5));
   --table-head-plate: color-mix(in oklab, var(--intent-subtle) var(--table-ground), transparent);
   --table-head-bg: color-mix(in oklab, var(--intent-color) var(--table-fill), var(--table-head-plate));
   --table-head-fg: color-mix(in oklab, var(--intent-contrast) var(--_on-fill), var(--intent-strong));
+
+  /* Untinted rather than mixed, the same call `.card.soft` makes: 12% ink onto
+     `--intent-subtle` still reads as `.solid` on neutral, since neutral's ink
+     and ground are both on the same greyscale axis and no ramp over that ground
+     changes it much. A head has no hover or interaction state to reveal a tint
+     into the way a card does on `.interactive`/`.hoverable`, so there is no
+     second state to move a mechanism to -- `.soft` is `--color-foreground`,
+     flat, always, for every intent. That mutes a colored `.success`/`.destructive`
+     head at rest the way it mutes a non-interactive `.card.soft`; accepted for
+     the same reason, not solved a different way.
+
+     The table's own base plate rests the same way, for a reason the head fix
+     alone did not cover: a `.soft` head landing at `--color-foreground` (five
+     units off the page) sitting directly above a body still carrying the
+     ordinary 12% tint (twenty-four units past the head) read backwards -- the
+     seam that should read as one table read as the head belonging to the page
+     and the body being the odd one out. `--_fill-cap` is `box.css`'s override
+     slot (the same one `.card.soft` uses, for the same cascade-layer reason
+     the comment there gives), and `--_d-ground` is box's own private ground
+     slot, unclaimed here until now -- both land on the table's own element,
+     same as `--table-fill`/`--table-head-plate` do, so nothing here fights
+     `.soft` for `--ui-fill` either. `.ghost` is left at box's default
+     (`--_d-ground: transparent`), so it stays the fully bare boundaries-only
+     table it already was -- `.soft` now differs from it by keeping an opaque,
+     untinted plate and a head label strip, not by how much ink is in either.
+
+     `:not(.solid, .ghost)` rather than `.soft`: the published resting fill is
+     `soft`, so a bare `<table class="data-table">` -- the members table in
+     `playground/app-shell/`, with no fill class at all -- is the common case
+     this has to reach, not the edge case. `.soft` alone would miss every table
+     that gets soft by doing nothing. */
+  &:not(.solid, .ghost) {
+    --table-fill: 0%;
+    --table-head-plate: var(--color-foreground);
+    --_fill-cap: 0%;
+    --_d-ground: var(--color-foreground);
+  }
+
   /* How much rule there is between body rows, and none unless asked for. Ruling
      every row is a style choice rather than part of what a table is, and tying it
      to the edge axis made it arrive by implication instead: a table drew rules
@@ -148,14 +189,21 @@
     color: var(--table-head-fg);
   }
 
-  /* Every cell carries the hairline; what varies is whether it is painted. A rule
-     is structure rather than the silhouette, so it stays hairline under an
-     aesthetic that draws a thick edge, and it survives a fill that would
-     otherwise paint over it. */
+  /* Every cell carries the hairline; what varies is whether it is painted. The
+     width tracks the aesthetic's own line weight (`--_width`, the same token
+     `box` uses for the table's outer frame) rather than a fixed `1px`, so a
+     row rule reads as the same material as the boundary around it instead of
+     as a leftover default under an aesthetic whose whole point is thickness --
+     `.chunky-tile`'s 2px frame used to sit over a 1px row rule, which read as
+     unstyled rather than as a deliberate, quieter line. It still survives a
+     fill that would otherwise paint over it, because color and width are
+     independent here: `.ruleless` zeroes the color, not this. */
   & th,
   & td {
-    @apply border-b px-4 py-3 align-top;
+    @apply px-4 py-3 align-top;
 
+    border-bottom-style: solid;
+    border-bottom-width: var(--_width);
     border-color: var(--table-rule);
   }
 
@@ -173,8 +221,8 @@
   }
 
   & tfoot tr:first-child > * {
-    @apply border-t;
-
+    border-top-style: solid;
+    border-top-width: var(--_width);
     border-top-color: var(--table-boundary);
   }
 
@@ -247,6 +295,20 @@
    itself, and amber-600 on amber-100 is a smudge. `box` now mixes toward
    `--intent-strong`, which is what these three were reaching for, so the three
    copies are gone and the ground is the only thing left to declare. */
+/* Neutral, for the same reason `.panel`'s own carve-out is: 12% of
+   `--color-text` mixed onto `--intent-subtle` (`--color-surface` for
+   neutral) reads as an assertive slab rather than a quiet chip -- measured,
+   `199, 199, 199` on a light page whose own `--color-surface` step is
+   `229, 229, 229`, further off than the ground alone already carries a key
+   cap. A named intent keeps its wash unchanged: a colored chip needs it to
+   separate from the others the way `.ghost` being unsupported here already
+   protects (dropping *all* fill collapsed every intent's ghost chip onto the
+   same near-page `--intent-subtle` tone) -- the neutral case has nothing to
+   separate from, so it alone drops the extra ink. The ground itself is not
+   moved the way `.panel`'s is: `--intent-subtle` already resolves to
+   `--color-surface` for neutral, a real, visible step past the page on its
+   own, so only the wash on top of it goes. `:not(.solid)` so an explicit
+   `.solid` chip is never clamped to a cap it did not ask for. */
 @utility kbd {
   @apply box inline-flex items-center px-1.5 py-0.5 font-mono text-xs font-medium;
 
@@ -260,6 +322,10 @@
      cap this small would read as a lozenge. A squaring aesthetic still reaches it. */
   border-radius: min(var(--ui-radius, var(--radius-small)), var(--radius-small));
   clip-path: var(--ui-clip-tight, var(--ui-clip, none));
+
+  &:not(.primary, .secondary, .success, .warning, .destructive, .danger, .error, .info, .solid) {
+    --_fill-cap: 0%;
+  }
 }
 
 /* The same plate with no line around it. */
@@ -274,6 +340,10 @@
 
   border-radius: min(var(--ui-radius, var(--radius-small)), var(--radius-small));
   clip-path: var(--ui-clip-tight, var(--ui-clip, none));
+
+  &:not(.primary, .secondary, .success, .warning, .destructive, .danger, .error, .info, .solid) {
+    --_fill-cap: 0%;
+  }
 }
 
 /* And at block scale, where the radius is a control's rather than a chip's. */
@@ -285,6 +355,10 @@
   --_d-border: 0%;
   --_d-elevation: 0;
   --_d-ground: var(--intent-subtle);
+
+  &:not(.primary, .secondary, .success, .warning, .destructive, .danger, .error, .info, .solid) {
+    --_fill-cap: 0%;
+  }
 }
 
 /* Typography wearing a component's name, so it composes none of `box`: `box`
@@ -306,7 +380,11 @@
   --_d-fg-on-fill: 0%;
   --_d-border: 100%;
   --_d-elevation: 0;
-  --quote-fill: calc(min(var(--ui-fill, var(--_d-fill)), var(--intent-fill-max, 100%)) * var(--ui-bg-alpha, 1));
+  /* Presentation capped by the intent, the same `--_capped` `box` composes, kept
+     separate from `--quote-fill` because the ink ramp below reads it before
+     `--ui-bg-alpha` thins it. */
+  --quote-capped: min(var(--ui-fill, var(--_d-fill)), var(--intent-fill-max, 100%));
+  --quote-fill: calc(var(--quote-capped) * var(--ui-bg-alpha, 1));
   --quote-bg: color-mix(in oklab, var(--intent-color) var(--quote-fill), transparent);
   /* The same edge blend `box` draws, in the same order and for the same reason:
      the blend is the line's colour, and how much line there is comes after it.
@@ -327,9 +405,17 @@
   background-color: var(--quote-bg);
   border-inline-start-color: var(--quote-edge);
   border-inline-start-width: var(--quote-width);
+  /* The ink is gated by the plate, not tied to the fill: `--ui-fg-on-fill` is the
+     ceiling, and the contrast tone only ramps in past a half fill, reaching full
+     at a full fill. Below that the ink stays `--intent-strong`, the tone chosen
+     to read on the page. This is `box`'s `--_on-fill` exactly -- `min(asked,
+     --intent-fill-max)` read plausibly and was wrong at the bottom of the range,
+     printing a capped-neutral `.solid` quote at ~6.6:1 where the ramp gives
+     ~11:1, and this renderer has to agree with `box`. */
   color: color-mix(
     in oklab,
-    var(--intent-contrast) min(var(--ui-fg-on-fill, var(--_d-fg-on-fill)), var(--intent-fill-max, 100%)),
+    var(--intent-contrast)
+      min(var(--ui-fg-on-fill, var(--_d-fg-on-fill)), max(0%, calc(var(--quote-capped) * 2 - 100%))),
     var(--intent-strong)
   );
 

package/dist/tw/utilities/index.css

@@ -3,4 +3,4 @@
 @import "./layout.css";
 @import "./content.css";
 
-@source inline("view vertical horizontal stack tight loose cluster between auto-grid section section-content narrow wide divider selection-contrast table-wrap data-table kbd quote quote-inline code pre");
+@source inline("view vertical horizontal stack tight loose cluster between auto-grid section section-content narrow wide divider selection-contrast visually-hidden table-wrap data-table kbd quote quote-inline code pre");

package/dist/tw/utilities/layout.css

@@ -105,3 +105,36 @@
     color: var(--color-primary);
   }
 }
+
+/* The gap this closes: `sr-only` is Tailwind's own name and the one a consumer
+   reaches for out of habit, but on the vanilla, ready-to-import entries (`.`,
+   `/native`) there is no Tailwind utility layer to reach -- those compile real
+   CSS from a scan of `src/` alone, which used the class nowhere, so `sr-only`
+   silently did nothing there. It worked fine on a `/tw` entry, where the
+   consumer's own Tailwind build supplies it, and that split made the gap easy
+   to miss: it read as a package decision rather than a hole in one build and
+   not the other.
+
+   Not published as `.sr-only` itself. `.table` already did that once --
+   shadowing Tailwind's own `display: table` utility until a consumer needed
+   the one this package ate -- and `registry.test.ts`'s collision check exists
+   because of it (see `data-table`'s `renamedFrom` in `registry.json`). Naming
+   this `sr-only` would trip the same trap from the other direction: on a `/tw`
+   entry a real Tailwind build runs too, and two same-named utilities in the
+   same cascade is exactly the silent collision that test polices.
+   `.visually-hidden` says the same thing under a name nothing else claims,
+   using the standard clip-based recipe. `@source inline("visually-hidden")` in
+   `utilities/index.css` force-emits it on the entries with no scannable markup
+   of their own, the same mechanism that file's inline list already uses for
+   every layout and content utility name in it. */
+@utility visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}

package/docs/accessibility.md

@@ -1,54 +1,72 @@
 ---
 title: Accessibility
+order: 5
 ---
 
 # Accessibility responsibilities
 
 This package provides CSS hooks for accessible states. It does not provide semantic HTML, ARIA attributes, keyboard behavior, focus management, validation, announcement timing, or JavaScript behavior.
 
-## Provided By CSS
-
-| Feature                 | Behavior                                                                                                                   |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `:focus-visible`        | Global focus-visible outline using `--focus-ring`, `--focus-ring-width`, and `--focus-ring-offset`.                        |
-| Form control focus      | `.ipt`, `.textarea`, and `.select` draw the global focus ring and move their line to the intent color.                     |
-| Control boundaries      | Text controls rest at `--_line-rest` of their intent, under 3:1 by choice; hover and focus take the tone whole.            |
-| Toggle boundaries       | `.checkbox`, `.radio`, and `.switch` draw their line whole, because it is the only thing marking an unchecked box.         |
-| Cascaded `.edgeless`    | Floored on every text control: a container cannot erase the line of a field or toggle nobody classed.                      |
-| Own `.edgeless`         | On the element, `.ipt`, `.textarea`, `.select`, and `.switch` do drop their line and do not meet 1.4.11 at rest.           |
-| `.checkbox`/`.radio`    | Never drop their line, on the element or from a container. `.edgeless` on them is unsupported, not merely discouraged.     |
-| Invalid controls        | `[aria-invalid="true"]` applies destructive border/focus color on form controls.                                           |
-| Disabled controls       | `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]`, and `.disabled` apply disabled cursor/opacity where supported.  |
-| Current page            | `[aria-current="page"]` applies primary color and stronger font weight.                                                    |
-| Open state              | `[data-state="open"]` styles supported surfaces and tooltips.                                                              |
-| Reduced-motion loaders  | Loader variants use animated embedded SVGs normally and static masks when `prefers-reduced-motion: reduce` matches.        |
-| Reduced-motion document | The reset additionally shortens document animations and transitions when `prefers-reduced-motion: reduce` matches.         |
-| Reduced transparency    | `.glass` drops its blur and becomes an opaque surface when `prefers-reduced-transparency: reduce` matches.                 |
-| Filled labels           | Every intent's `.solid` label meets 1.4.3 (4.5:1) as normal text, in both themes. Lowest is success at 5.14:1.             |
-| Warning ink             | `--color-warning-contrast` is the near-black tone, not the page tone. Amber dark enough to carry white is not amber.       |
-| Partial fills           | Contrast ink appears only past a half fill, so a capped plate keeps `--intent-strong` rather than walking toward the page. |
-| Intent hue in dark      | `--intent-strong` is the `-300` shade in dark, so a soft or ghost label keeps its own hue instead of reading white.        |
-| Toggle marks            | A checked mark meets 3:1 as a state indicator on every plate its fill class can paint, in both themes.                     |
-| Forced colors           | `forced-colors: active` preserves visible borders and checked states using system colors.                                  |
-| Text direction          | Quote bar, alert icon, progress fill, vertical divider, and switch knob mirror under `dir="rtl"`. No class needed.         |
-
-The loader fallback is embedded in loader CSS, so focused imports that include
-loaders honor reduced motion without the reset. This includes
-`@codenhub/styles/components`, `@codenhub/styles/tw/components`,
-`@codenhub/styles/tw/button`, and `@codenhub/styles/tw/loader`. The complete and
-native entrypoints include both that fallback and the reset's broader animation
-and transition shortening.
-
-In forced colors, class-based form controls including `.text-control` receive a
-2px `Highlight` system-color focus outline. The native entrypoint provides the
-same visible system outline for unclassed text inputs, selects, textareas,
-checkboxes, and radios.
-
-Custom checkboxes and radios use the system `Canvas`, `CanvasText`, `Highlight`,
-and `HighlightText` colors in forced-colors mode so checked and unchecked states
-remain distinct. Shape, size, and spacing remain unchanged.
-
-## Required Outside CSS
+## Provided by CSS
+
+### Focus and state
+
+| Feature            | Behavior                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`   | Global focus-visible outline using `--focus-ring`, `--focus-ring-width`, and `--focus-ring-offset`.                                                                                                                                                                                                                             |
+| Form control focus | `.ipt`, `.textarea`, and `.select` draw the global focus ring and move their line to the intent color.                                                                                                                                                                                                                          |
+| Invalid controls   | `[aria-invalid="true"]` applies destructive border/focus color on form controls.                                                                                                                                                                                                                                                |
+| Disabled controls  | `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]`, and `.disabled` apply disabled cursor/opacity where supported.                                                                                                                                                                                                       |
+| Open state         | `[data-state="open"]` styles supported surfaces and tooltips.                                                                                                                                                                                                                                                                   |
+| Native `<dialog>`  | `dialog:not([open])` and a centered `dialog[open]` are restored in author origin, so `.card` composed onto a `<dialog>` (the closest primitive the package ships) does not render open on load or lose its centering to another rule. Focus trapping, escape handling, and inert-background behavior stay outside this package. |
+
+### Visually hidden content
+
+`.visually-hidden` hides content from sighted users while keeping it in the accessibility tree, using the standard clip-based recipe. It ships wherever the layout utilities do -- `.`, `./native`, `./tw`, `./tw/native`, and `./tw/utilities` -- including the vanilla entries with no Tailwind utility layer of their own; it is not part of `./components` or the narrower `./tw/components`/`./tw/*` component slices. See [Content and layout](./usage/content-and-layout.md).
+
+### Control boundaries
+
+| Feature              | Behavior                                                                                                                                                                                                                                                                                 |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Control boundaries   | Text controls rest at `--_line-rest` of their intent, under 3:1 by choice; hover and focus take the tone whole.                                                                                                                                                                          |
+| Toggle boundaries    | `.checkbox`, `.radio`, and `.switch` draw their line whole, because it is the only thing marking an unchecked box.                                                                                                                                                                       |
+| Cascaded `.edgeless` | Floored on every text control: a container cannot erase the line of a field or toggle nobody classed.                                                                                                                                                                                    |
+| Own `.edgeless`      | On the element, `.ipt`, `.textarea`, `.select`, and `.switch` do drop their line and do not meet 1.4.11 at rest, except `.switch.ghost`: `.ghost` already asks for zero fill, so dropping the line too would leave no boundary at all, and `.switch.ghost.edgeless` keeps it up instead. |
+| `.checkbox`/`.radio` | Never drop their line, on the element or from a container. `.edgeless` on them is unsupported, not merely discouraged.                                                                                                                                                                   |
+
+### Motion and transparency
+
+| Feature                 | Behavior                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| Reduced-motion loaders  | Loader variants use animated embedded SVGs normally and static masks when `prefers-reduced-motion: reduce` matches. |
+| Reduced-motion document | The reset additionally shortens document animations and transitions when `prefers-reduced-motion: reduce` matches.  |
+| Reduced transparency    | `.glass` drops its blur and becomes an opaque surface when `prefers-reduced-transparency: reduce` matches.          |
+
+The loader fallback is embedded in loader CSS, so focused imports that include loaders honor reduced motion without the reset. This includes `@codenhub/styles/components`, `@codenhub/styles/tw/components`, and `@codenhub/styles/tw/loader`. The complete and native entrypoints include both that fallback and the reset's broader animation and transition shortening.
+
+### Color and contrast
+
+| Feature            | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Filled labels      | Every intent's `.solid` label meets 1.4.3 (4.5:1) as normal text, in both themes. Lowest is success at 5.14:1.                                                                                                                                                                                                                                                                                                                            |
+| Warning ink        | `--color-warning-contrast` is the near-black tone, not the page tone. Amber dark enough to carry white is not amber.                                                                                                                                                                                                                                                                                                                      |
+| Partial fills      | Contrast ink appears only past a half fill, so a capped plate keeps `--intent-strong` rather than walking toward the page.                                                                                                                                                                                                                                                                                                                |
+| Intent hue in dark | `--intent-strong` is the `-300` shade in dark, so a soft or ghost label keeps its own hue instead of reading white.                                                                                                                                                                                                                                                                                                                       |
+| Toggle marks       | A checked mark meets 3:1 as a state indicator on every plate its fill class can paint, in both themes.                                                                                                                                                                                                                                                                                                                                    |
+| Soft-edged border  | `.alert`, `.panel`, `.badge`, `.kbd`, and `.code`/`.pre`'s `.edged` border blends toward the component's own fill; at `.soft`'s 12% fill this misses 3:1 against the fill for some intents, and which ones misses depends on the theme. Known, not fixed -- `--color-border`/`--intent-border` is a shared blend seam every one of them reads, so a targeted fix would need to touch it for one component without moving it for the rest. |
+
+### Forced colors and direction
+
+| Feature        | Behavior                                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Forced colors  | `forced-colors: active` preserves visible borders and checked states using system colors.                          |
+| Text direction | Quote bar, alert icon, progress fill, vertical divider, and switch knob mirror under `dir="rtl"`. No class needed. |
+
+In forced colors, class-based form controls including `.text-control` receive a 2px `Highlight` system-color focus outline. The native entrypoint provides the same visible system outline for unclassed text inputs, selects, textareas, checkboxes, and radios.
+
+Custom checkboxes and radios use the system `Canvas`, `CanvasText`, `Highlight`, and `HighlightText` colors in forced-colors mode so checked and unchecked states remain distinct. Shape, size, and spacing remain unchanged.
+
+## Required outside CSS
 
 Use semantic HTML and behavior appropriate for the component.
 
@@ -58,25 +76,27 @@ Use semantic HTML and behavior appropriate for the component.
 | Forms             | Use labels, `type`, validation logic, `aria-describedby`, and error message relationships.                      |
 | Alerts            | Add `role="status"` or `role="alert"` based on announcement urgency.                                            |
 | Toasts            | Add live-region behavior, dismissal behavior, focus rules, and pause/timeout logic when needed.                 |
-| Tooltips          | Provide accessible names/descriptions. CSS pseudo-element content is not enough for all assistive tech.         |
+| Tooltips          | Give the bubble a real `id` and `role="tooltip"`, and reference it from the trigger's `aria-describedby`.       |
 | Progress          | Use semantic progress elements or ARIA values when numeric progress must be announced.                          |
 | Skeletons/loaders | Mark decorative loading visuals with `aria-hidden="true"` and expose loading state elsewhere when needed.       |
 | Popovers/modals   | Provide focus trapping, escape handling, inert background behavior, labels, and roles outside this CSS package. |
 
-## State Attribute Guidance
+## State attribute guidance
 
 Prefer native attributes first:
 
 ```html
-<button class="btn primary" disabled>Saving</button>
-<input class="ipt" aria-invalid="true" aria-describedby="email-error" />
+<button class="btn primary" disabled>Saving</button> <input class="ipt" aria-invalid="true" aria-describedby="email-error" />
 ```
 
 Use ARIA or data attributes when native attributes are not available for the element or library:
 
 ```html
 <a class="btn secondary" aria-disabled="true">Unavailable</a>
-<button class="tooltip tooltip-icon" data-state="open" data-tooltip="More details" aria-label="More details">?</button>
+<span class="tooltip" data-state="open">
+  <span class="tooltip-icon" tabindex="0" aria-label="More details" aria-describedby="more-details-bubble">?</span>
+  <span class="tooltip-bubble" role="tooltip" id="more-details-bubble">More details</span>
+</span>
 ```
 
 `aria-disabled="true"` communicates disabled state but does not prevent activation. JavaScript or element choice must prevent activation when required.

package/docs/changelog/0.1.0.md

@@ -0,0 +1,37 @@
+---
+title: 0.1.0
+date: 2026-08-31
+description: The three-axis styling model, split presentation, opt-in aesthetics, and Tailwind v4 source entrypoints.
+---
+
+# 0.1.0
+
+`0.1.0` replaces the model published in `0.0.4` wholesale. The old model had three orthogonal axes with per-component clamps and no chosen default: a plain element got whatever `var()` fallback each component happened to declare. This release makes each decision explicitly and is the baseline the `0.x` line builds on. Nearly everything below is breaking against `0.0.4`; there are no compatibility aliases.
+
+## Changed
+
+- **Every element now composes from three named axes.** _Intent_ (`.primary`, `.success`, `.destructive`, …) sets hue only. _Presentation_ sets how much of that hue fills the element and whether it draws an edge. _Aesthetic_ sets the material — radius, edge width, shadow, silhouette, type. Intent is redeclared per component; presentation and aesthetic cascade, so a container can set the look of a subtree while any element opts out. [Concepts](../concepts.md) and [Composing](../usage/composing.md) describe the full model.
+- **Presentation is two independent questions.** Fill is `.solid` / `.soft` / `.ghost`; edge is `.edged` / `.edgeless`. Exactly one of each applies, and they never decide each other. The common web button — a subtle fill with a border — is `.soft.edged`, which had no spelling before.
+- **`.bare` is renamed `.ghost`.** `.bare` and `.edgeless` both read as "less of something", so the name is now a fill and only a fill: no fill at rest, a tint on hover.
+- **Hover is derived, not declared.** A hovered element takes its resting fill plus one published step and its `--intent-hover` colour. There are no hover tokens to set. An outline button therefore tints on hover rather than filling completely.
+- **A sunk text field is `.soft.edgeless`.** Two classes saying two things, where `.soft` alone used to silently suppress the field's border.
+- **Table row rules are opt-in via `.ruled`.** Rules no longer arrive by implication from a component's edge default. The head and foot separators stay at every presentation.
+- **Depth is a modifier, not part of a component.** `surface` no longer carries a structural shadow, so cards, buttons, and chips on a plain page rest flat. Use `.raised` / `.floating` (or `.elevation-sm` / `.elevation-md`) to add depth, and `.flat` to remove an aesthetic's.
+- **The Tailwind v4 entrypoint moved from `/overrides` to `/native`.**
+
+## Added
+
+- **Opt-in aesthetics.** `.neobrutalism`, `.glass`, `.pixel`, and `.chunky-tile`, each shipped as its own entrypoint (`@codenhub/styles/aesthetics/pixel`, …) and as an aggregate (`@codenhub/styles/aesthetics`). An aesthetic sets material tokens only; it never repaints hue. See [Aesthetics](../usage/aesthetics.md).
+- **An elevation modifier.** `.flat` / `.raised` / `.floating` (and the `.elevation-none` / `-sm` / `-md` names) multiply an aesthetic's shadow geometry. Unitless, so a container can flatten a whole toolbar and any element can opt back in.
+- **Granular Tailwind v4 source entrypoints.** `@codenhub/styles/tw` and per-family subpaths (`/tw/button`, `/tw/form`, `/tw/feedback`, `/tw/tooltip`, `/tw/utilities`, `/tw/aesthetics/*`, …) for consumers compiling their own build. `package.json` is also exported.
+- **`.input-group`.** A wrapper that draws one box and lets the control inside give up its own paint, so an icon can sit alongside a field. The package ships no icons — any element works in the slot.
+- **`registry.json`.** A machine-readable record of every supported class, each component's default fill/edge/elevation, the axes it reads, and every bound and exception with its reason.
+- **`--intent-strong`**, the intent tone chosen to be read on a page, used wherever a fill is partial.
+
+## Removed
+
+- **`.out` and `.fill`.** Outline is now `.ghost.edged`; there is no class that makes an outline button fill completely on hover.
+- **`--ui-border-scale` / `.out`'s doubled border.** The edge width comes from the aesthetic and nothing else, which removed the per-component border ceilings small components needed.
+- **`--color-text-subtle`**, which nothing read.
+- **`--layout-stack-gap` and `--layout-cluster-gap`**, replaced by a single `--layout-gap`.
+- **The bundled input-field icons.** Icons were a `background-image` data URI with a light and a dark copy per glyph; they are gone, and `.input-group` carries a consumer-supplied icon instead.

package/docs/changelog/0.1.1.md

@@ -0,0 +1,10 @@
+---
+title: 0.1.1
+date: 2026-09-10
+---
+
+# 0.1.1
+
+## Fixed
+
+- `.p-xs` and its alias `.dense` now clear a button's `--control-height` minimum, so a chip-sized button fits inside a table cell or a dense toolbar. Before this, every button kept the full control-height floor even at the tightest padding, so a button that small could not be built. Every other size and padding class still keeps the floor, so a plain button is unchanged. An icon-only `.p-xs`/`.dense` button also gives up its `min-width`; size the glyph yourself, as the package sizes no icons.

package/docs/changelog/0.2.0.md

@@ -0,0 +1,41 @@
+---
+title: 0.2.0
+date: 2026-09-14
+---
+
+# 0.2.0
+
+Fixes from a stress-test pass composing real screens (`app-shell`, `form`, `settings`) against the published `0.1.x` model. Several change default token values rather than adding new surface, so this lands as one minor rather than a run of patches -- see [Changed](#changed) for what an upgrader needs to check.
+
+## Added
+
+- `.visually-hidden`, a utility that hides content from sighted users while keeping it in the accessibility tree. Ships wherever the layout utilities do (`.`, `/native`, `/tw`, `/tw/native`, `/tw/utilities`), including the vanilla entries that have no Tailwind utility layer of their own; not part of `/components` or the narrower `/tw/*` component slices.
+- `.tooltip-bubble`, a real element for a tooltip's message that can carry its own `id` and be referenced by `aria-describedby`.
+- `.alert-icon`, sizing and alignment for a consumer-supplied icon element dropped into `.alert` -- any inline SVG, `<img>`, or icon-set class works, not just a built-in glyph.
+- `dialog:not([open])`/`dialog[open]` restated in author origin, so `.card` composed onto a `<dialog>` hides until opened and centers when shown, without a dialog primitive of its own.
+- `.icon` added to `registry.json` under `modifiers.shape`. The button shape modifier was already shipped and documented; it was missing only from the machine-readable contract.
+- `.switch.ghost.edgeless` now renders a track instead of disappearing.
+
+## Changed
+
+- **Tooltips are composition, not a single class.** `.tooltip` now wraps a trigger and a `.tooltip-bubble`, one more DOM node than before. Intent, presentation, aesthetic, and elevation classes move to `.tooltip-bubble`, the element that actually paints.
+- **`.checkbox`, `.radio`, and `.switch` default to `.soft` instead of `.solid`, and their checked state now composes one plate regardless of presentation.** Unchecked, `.ghost` (0% fill), `.soft` (12%), and `.solid` now read as three distinct plates instead of three shades of one wash; `.ghost` is a supported look on every toggle for the first time.
+- **A neutral (no named intent) `.card.soft`, `data-table`, `.panel`, or `.alert` rests untinted instead of mixing a 12% ink wash.** A named intent (`.card.soft.destructive`, `.alert.success`, and so on) is unaffected and keeps its ordinary tint; `.badge` is unaffected either way, since it has no border to fall back on if untinted.
+- **Elevation no longer cascades onto descendants.** `--ui-elevation`, `--elevation-y`, and `--elevation-blur` are registered non-inheriting, so an elevation class lifts only the element it is written on. A container that used to lift a whole unclassed subtree in one class now needs an elevation class on each element that wants depth.
+- `--input-group-gap` replaces a hardcoded gap in `.input-group`; unchanged by default for icon compositions, and settable to `0` on a text affix for a flush look.
+- `.loader`'s sizes step down from 24/32/40px to 20/28/36px for `.sm`/default/`.lg`.
+- A `/tw` consumer's own `dark:` utilities now also fire under `prefers-color-scheme: dark` when no explicit theme selector is present, matching how the token palette already follows the OS default.
+
+## Removed
+
+- **`.btn.loading`.** A loading button is now a disabled `.btn` composed with a real `.loader` child instead of a hardcoded `::after` spinner -- any loader variant works, not just one circular spinner.
+- **`.alert.icon`'s hardcoded per-intent SVG mask.** Replaced by `.alert-icon` (above), sized for a consumer-supplied icon element.
+
+## Fixed
+
+- `.icon` buttons kept the wrong `min-width` floor under `.compact`/`.spacious`; all three padding tiers now size `.icon` to its own padding.
+- `.chunky-tile`'s offset shadow read as a solid fill behind a small `.icon.ghost` button; halved for that combination.
+- Table row and boundary rules stayed a 1px hairline under `.chunky-tile`'s 2px frame; both now track the same width token the frame uses.
+- `.progress`'s track failed WCAG 1.4.11 in both themes; `--progress-surface` now mixes enough ink to clear 3:1.
+- `.card.soft.edged`'s border was nearly invisible against its own fill in light theme; `--color-border`'s light value moved one step darker.
+- A badge nested inside an untinted `data-table` lost its own fill; box now restates its fill cap on every element that uses it, so a nested badge, button, or chip no longer inherits its container's cap.

package/docs/changelog/index.md

@@ -0,0 +1,11 @@
+---
+title: Changelog
+curated: true
+group: Changelog
+---
+
+# Changelog
+
+- [0.2.0](0.2.0.md)
+- [0.1.1](0.1.1.md)
+- [0.1.0](0.1.0.md)