@codenhub/styles 0.5.0 → 0.7.0

package/dist/tw/utilities/layout.css

@@ -1,5 +1,13 @@
+/* The gap is a private each layout declares from `--layout-gap`, and the
+   density modifiers write the private. A container's `--layout-gap` still
+   reaches every layout inside it, because each one reads the token afresh; a
+   `.tight` or `.loose` stays on its own element, the way `.p-xs` stays on a
+   card, because the layout inside declares its own private over the one it
+   would inherit. */
 @utility view {
-  @apply flex gap-(--layout-gap);
+  @apply flex gap-(--_gap);
+
+  --_gap: var(--layout-gap);
 
   &.vertical {
     @apply flex-col;
@@ -10,53 +18,59 @@
   }
 
   &.tight {
-    --layout-gap: 0.5rem;
+    --_gap: 0.5rem;
   }
 
   &.loose {
-    --layout-gap: 1.5rem;
+    --_gap: 1.5rem;
   }
 }
 
 @utility stack {
-  @apply flex flex-col gap-(--layout-gap);
+  @apply flex flex-col gap-(--_gap);
+
+  --_gap: var(--layout-gap);
 
   &.tight {
-    --layout-gap: 0.5rem;
+    --_gap: 0.5rem;
   }
 
   &.loose {
-    --layout-gap: 1.5rem;
+    --_gap: 1.5rem;
   }
 }
 
 @utility cluster {
-  @apply flex flex-wrap items-center gap-(--layout-gap);
+  @apply flex flex-wrap items-center gap-(--_gap);
+
+  --_gap: var(--layout-gap);
 
   &.between {
     @apply justify-between;
   }
 
   &.tight {
-    --layout-gap: 0.5rem;
+    --_gap: 0.5rem;
   }
 
   &.loose {
-    --layout-gap: 1.5rem;
+    --_gap: 1.5rem;
   }
 }
 
 @utility auto-grid {
-  @apply grid gap-(--layout-gap);
+  @apply grid gap-(--_gap);
+
+  --_gap: var(--layout-gap);
 
   grid-template-columns: repeat(auto-fit, minmax(min(var(--layout-grid-min), 100%), 1fr));
 
   &.tight {
-    --layout-gap: 0.5rem;
+    --_gap: 0.5rem;
   }
 
   &.loose {
-    --layout-gap: 1.5rem;
+    --_gap: 1.5rem;
   }
 }
 
@@ -76,10 +90,10 @@
   }
 }
 
-/* An indicator: intent only, and no presentation token at all. A rule is a line,
-   and neither a fill class nor an edge class has anything to say about one -- while
-   reading both used to mean a container's `.ghost.edgeless` made every `<hr>`
-   inside it invisible. The width is the aesthetic's line width, unscaled. */
+/* An indicator: intent only, and no presentation token at all. A rule is a
+   line, and neither a fill class nor an edge class has anything to say about
+   one -- a container's `.ghost.edgeless` must not make every `<hr>` inside it
+   invisible. The width is the aesthetic's line width, unscaled. */
 @utility divider {
   --divider-color: var(--intent-color);
   --divider-width: var(--ui-border-width, var(--border-width));
@@ -106,27 +120,17 @@
   }
 }
 
-/* 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. */
+/* `.visually-hidden`, the standard clip-based recipe. Tailwind's `sr-only` does
+   nothing on the vanilla entries (`.`, `/native`), which compile real CSS from
+   a scan of `src/` alone with no Tailwind utility layer to reach, so the
+   package publishes its own.
+
+   It is not named `.sr-only`: on a `/tw` entry the consumer's own Tailwind
+   build supplies that utility, and two same-named utilities in one cascade
+   collide silently -- the collision `registry.test.ts` polices (see
+   `data-table`'s `renamedFrom` in `registry.json`). `@source
+   inline("visually-hidden")` in `utilities/index.css` force-emits it on the
+   entries with no scannable markup of their own. */
 @utility visually-hidden {
   position: absolute;
   width: 1px;

package/docs/accessibility.md

@@ -1,103 +1,149 @@
 ---
 title: Accessibility
+description: What the CSS does for focus, states, motion, contrast, forced colors, and right-to-left text, and what your application still owes its users.
 order: 5
 ---
 
-# Accessibility responsibilities
+# Accessibility
 
-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.
+The settings screen is built, and the CSS has done its part along the way: every field shows where focus is, an invalid email turns red, and the spinner stops for users who ask for less motion. The rest is up to your HTML and JavaScript. This package styles states; it does not provide semantic elements, ARIA attributes, keyboard behavior, focus management, validation, or the timing of announcements.
+
+This page lists both halves: what the CSS provides, and what your application has to add.
 
 ## 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. |
+| Feature            | Behavior                                                                                                                                                                                                                                                                                                                                 |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`   | A focus outline on every element, drawn with `--focus-ring`, `--focus-ring-width`, and `--focus-ring-offset`.                                                                                                                                                                                                                            |
+| Form control focus | `.ipt`, `.textarea`, and `.select` draw the focus outline and change their border to the intent color. Typed text in a field with an intent class is in the intent's readable tone, `--intent-strong`.                                                                                                                                   |
+| Invalid controls   | `aria-invalid="true"` on a form control turns its border, focus color, and typed text destructive, the text in the destructive readable tone.                                                                                                                                                                                            |
+| Disabled controls  | `disabled`, `aria-disabled="true"`, `data-disabled`, and `.disabled` show the disabled cursor and opacity, and a disabled control does not react to hover, including inside an `.input-group`.                                                                                                                                           |
+| Open state         | `data-state="open"` on a `.tooltip` shows its bubble without hover or focus, and `data-state="closed"` hides it while hovered or focused. No other component reads either.                                                                                                                                                               |
+| Native `<dialog>`  | A `<dialog>` with `.card`, `.panel`, or `.surface` stays hidden until it is opened, and opens centered. A margin you set on the dialog, as a utility or in your own CSS, still overrides the centering. Other dialogs are left alone. Trapping focus, closing on Escape, and making the page behind it inert are up to your application. |
 
 ### 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).
+`.visually-hidden` hides content on screen and keeps it for screen readers, as the API keys table's `<caption>` does in [Content and layout → Tables](./usage/content-and-layout.md#tables). It ships with the layout utilities: in `.`, `./native`, `./tw`, `./tw/native`, and `./tw/utilities`. It is not in `./components` or the `./tw/components` and `./tw/*` component entrypoints.
 
 ### Control boundaries
 
-| Feature              | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Control boundaries   | Text controls rest at `--_line-rest` of their intent, under 3:1 by choice, so hover and focus have a whole tone to move the line to.                                                                                                                                                                                                                                                                                                                                |
-| 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.                                                                                                                                                                                                                                                                                                                                              |
-| Progress track       | By choice, the value carries the reading and the track is a quiet secondary cue. `.progress`'s registered default, `.soft.edgeless`, rests its track at ~1.1-1.3:1 against the page; the value clears 3:1 against that track for every intent but warning in light (~2.7:1) and info in dark (~2.9:1). `.ghost.edged` clears 3:1 for both the track's outline and the value, for every intent, in both themes -- choose it where the track itself must meet 1.4.11. |
+WCAG 1.4.11 asks that the boundary of a control you need to see to use it measures at least 3:1 against what is next to it.
+
+| Feature                      | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Text controls at rest        | A text control's border rests lighter than its intent's full border, below 3:1 by choice, so hover and focus have a stronger tone to change to.                                                                                                                                                                                                                                                                                                             |
+| Toggles                      | `.checkbox`, `.radio`, and `.switch` draw their full border, because the border is the only thing that shows an unchecked box. A `.switch` with its own `.edgeless` is the exception, below.                                                                                                                                                                                                                                                                |
+| `.edgeless` from a container | Ignored by every text control and toggle: a container cannot remove the border of a field or toggle inside it.                                                                                                                                                                                                                                                                                                                                              |
+| `.edgeless` on the control   | `.ipt`, `.textarea`, `.select`, and `.switch` drop their border and no longer meet 1.4.11 at rest. `.switch.ghost` keeps its border even then, because with no fill and no border nothing would show the track.                                                                                                                                                                                                                                             |
+| `.checkbox`, `.radio`        | Always draw their border, from a container or with their own `.edgeless`. `.edgeless` on them is not supported.                                                                                                                                                                                                                                                                                                                                             |
+| Progress track               | By choice, the filled part carries the value and the track is a quiet background. The default track, `.soft.edgeless`, measures about 1.1:1 to 1.3:1 against the page. The filled part measures at least 3:1 against that track for every intent except warning in light (about 2.7:1) and info in dark (about 2.9:1). Where the track itself must meet 1.4.11, use `.ghost.edged` with an intent class; see [Progress outlines](#progress-outlines) below. |
+
+### Progress outlines
+
+On a `.progress.ghost.edged`, the track is the page, and its outline and the filled part are both drawn in the intent's color. Measured against the page, with no aesthetic:
+
+| Intent         | Light page | Dark page | Meets 3:1                                                                |
+| -------------- | ---------- | --------- | ------------------------------------------------------------------------ |
+| `.primary`     | 18.96:1    | 18.96:1   | Yes                                                                      |
+| `.secondary`   | 7.47:1     | 7.63:1    | Yes                                                                      |
+| `.success`     | 5.14:1     | 3.69:1    | Yes                                                                      |
+| `.warning`     | 3.06:1     | 6.20:1    | Yes                                                                      |
+| `.destructive` | 5.80:1     | 3.27:1    | Yes                                                                      |
+| `.info`        | 6.17:1     | 3.07:1    | Yes                                                                      |
+| No intent      | 2.48:1     | 1.91:1    | No: the outline fails, though the filled part, in the text color, passes |
+
+With no intent class, the outline is the quiet border gray, `--color-border`. To make a neutral track meet 1.4.11, give the bar an intent class, or set `--progress-edge` to a stronger color, such as `var(--color-accent)`, which measures 7.47:1 on a light page and 7.63:1 on a dark one. Warning on a light page and info on a dark one clear 3:1 by a small margin, so measure again if you change those colors.
 
 ### 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.          |
+| Feature                    | Behavior                                                                                                                                                                                                 |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Reduced motion, components | With `prefers-reduced-motion: reduce`, every component stops its own transitions and animations: the skeleton and progress shimmer, the indeterminate bar, the tooltip, the toggle marks, and the press. |
+| Reduced motion, whole page | The reset also shortens every other animation and transition on the page.                                                                                                                                |
+| Reduced transparency       | With `prefers-reduced-transparency: reduce`, `.glass` and `.glass-liquid` drop their blur and lens and become opaque.                                                                                    |
+
+Each component's reduced-motion rule ships with the component, so every entrypoint that includes it respects reduced motion without the reset, including `@codenhub/styles/components`, `@codenhub/styles/tw/components`, and each `/tw/*` component entrypoint. The complete and native entrypoints add the reset's page-wide rule.
 
-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.
+The reset's rule is `!important` inside the `base` layer, and a layered `!important` beats an unlayered one, so your own `!important` cannot turn an animation back on. To keep one running for users who ask for reduced motion, such as an upload spinner you consider essential, declare it `!important` in a layer ordered before `base`. The first `@layer` statement the browser reads sets the order, so yours goes before the package:
+
+```css
+@layer essential-motion, theme, base, components, utilities;
+@import "@codenhub/styles";
+
+@layer essential-motion {
+  @media (prefers-reduced-motion: reduce) {
+    .upload-spinner {
+      animation-duration: 1s !important;
+      animation-iteration-count: infinite !important;
+    }
+  }
+}
+```
+
+Respecting reduced motion is not the whole requirement. Motion that keeps going next to content, such as a shimmer left on a card after it has loaded, needs a way to stop it for every user; see [Feedback → Animation that keeps running](./usage/feedback.md#animation-that-keeps-running).
 
 ### 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 fades out by the component's fill amount; 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. |
+The measurements below are for the shipped colors. Once you change a color token, measure your own pairs again; [Theming → Change the brand color](./usage/theming.md#change-the-brand-color) shows which pairs to check.
+
+| Feature                 | Behavior                                                                                                                                                                                                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Filled labels           | Every intent's `.solid` label meets 4.5:1 (WCAG 1.4.3) as normal text, in both themes. The lowest is success, at 5.14:1.                                                                                                                                                |
+| Warning text            | `--color-warning-contrast` is near-black, not the page color, because an amber dark enough to carry white text no longer looks amber.                                                                                                                                   |
+| Partial fills           | The contrast text color appears only on fills above half strength, so a text control's capped fill keeps the intent's own text color.                                                                                                                                   |
+| Intent color in dark    | In dark mode a `.soft` or `.ghost` label uses the `-300` shade of its intent, so it keeps its hue instead of turning white.                                                                                                                                             |
+| Toggle marks            | A checked mark measures at least 3:1 against every fill its presentation can give it, in both themes.                                                                                                                                                                   |
+| Soft fills with borders | `.edged` on a `.soft` `.alert`, `.panel`, `.badge`, `.kbd`, `.code`, or `.pre` draws a border that measures below 3:1 against the 12% fill for some intents, which ones depending on the theme. Measure the pair before relying on that border as a control's boundary. |
 
 ### 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. |
+| Feature        | Behavior                                                                                                                                                                                                                                            |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Forced colors  | With `forced-colors: active`, borders, checked states, and a `.select`'s chevron stay visible, drawn in system colors, under every aesthetic. An aesthetic that draws its border as an inner shadow, such as `.pixel`, draws a real border instead. |
+| Text direction | Under `dir="rtl"`, the quote bar, the alert icon, the progress fill, the vertical divider, the switch knob, table alignment, and a select's chevron all switch sides. No class is 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.
+In forced colors, `.text-control`, `.ipt`, `.textarea`, `.select`, and the toggles show a 2px `Highlight` focus outline. The native entrypoint gives unclassed text inputs, selects, textareas, checkboxes, and radios the same outline.
 
-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.
+Checkboxes, radios, and switches use the system colors `Canvas`, `CanvasText`, `Highlight`, and `HighlightText`, so checked and unchecked stay distinct: a checked toggle is filled with `Highlight` and its mark is `HighlightText`, on the classes and in the native entrypoint alike. Shape, size, and spacing do not change.
 
 ## Required outside CSS
 
-Use semantic HTML and behavior appropriate for the component.
+Use the HTML element that matches what the component does, and add the behavior the CSS cannot.
 
-| UI                | Required outside CSS                                                                                            |
-| ----------------- | --------------------------------------------------------------------------------------------------------------- |
-| Buttons           | Use `<button>` for actions or accessible links for navigation. Add accessible names for `.btn.icon`.            |
-| 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          | 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. |
+| UI               | What your application adds                                                                                                                                                                                                                              |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Buttons          | `<button>` for actions and `<a href>` for navigation. An accessible name, such as `aria-label`, on every `.btn.icon`.                                                                                                                                   |
+| Forms            | A `<label>` for each control, the right `type`, validation, and `aria-describedby` linking hints and errors. Keep hints and errors outside the `<label>`, and give a `.switch` `role="switch"`.                                                         |
+| Alerts           | `role="status"` for a confirmation such as "Profile saved", or `role="alert"` for an error that needs attention now.                                                                                                                                    |
+| Toasts           | A live region, a way to dismiss it, focus rules, and a pause on any timeout.                                                                                                                                                                            |
+| Tooltips         | A real `id` and `role="tooltip"` on the bubble, referenced from the trigger's `aria-describedby`. Dismissal on Escape by writing `data-state="closed"`; see [Tooltips](./usage/tooltips.md#hover-linger-and-escape). The bubble can already be hovered. |
+| Progress         | A `<progress>` element, or `role="progressbar"` or `role="meter"` with ARIA values, when the value must be announced.                                                                                                                                   |
+| Skeletons        | `aria-hidden="true"` on loading visuals, including a spinner you bring, and the loading state announced some other way when needed.                                                                                                                     |
+| Ongoing motion   | A way to pause, stop, or hide motion that is not essential; see [Feedback → Animation that keeps running](./usage/feedback.md#animation-that-keeps-running).                                                                                            |
+| Popovers, modals | Focus trapping, closing on Escape, an inert background, labels, and roles.                                                                                                                                                                              |
 
-## State attribute guidance
+## State attributes
 
-Prefer native attributes first:
+Prefer native attributes:
 
 ```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" type="email" aria-invalid="true" aria-describedby="email-error" />
 ```
 
-Use ARIA or data attributes when native attributes are not available for the element or library:
+Use ARIA or data attributes where the element or your component library has no native one:
 
 ```html
-<a class="btn secondary" aria-disabled="true">Unavailable</a>
+<a class="btn secondary" aria-disabled="true">Export data</a>
 <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>
+  <button type="button" class="tooltip-icon" aria-label="About public profiles" aria-describedby="public-profile-help">?</button>
+  <span class="tooltip-bubble" role="tooltip" id="public-profile-help">Anyone with the link can see your name and photo.</span>
 </span>
 ```
 
-`aria-disabled="true"` communicates disabled state but does not prevent activation. JavaScript or element choice must prevent activation when required.
+`aria-disabled="true"` tells assistive technology the control is disabled, but it does not stop a click or a key press. Use the `disabled` attribute, or stop the action in JavaScript.
+
+## Next
+
+That completes the reading path. The [Introduction](./index.md) links every page, and [Composing](./usage/composing.md), [Customizing](./usage/customizing.md), and [Content and layout](./usage/content-and-layout.md) are the lookup pages for later.

package/docs/changelog/0.1.1.md

@@ -1,6 +1,7 @@
 ---
 title: 0.1.1
 date: 2026-09-10
+description: Chip-sized buttons, with .p-xs and .dense clearing the control-height minimum.
 ---
 
 # 0.1.1

package/docs/changelog/0.2.0.md

@@ -1,6 +1,7 @@
 ---
 title: 0.2.0
 date: 2026-09-14
+description: Fixes from composing real screens, with composed tooltips, soft toggles by default, untinted neutral surfaces, and elevation that no longer cascades.
 ---
 
 # 0.2.0

package/docs/changelog/0.3.0.md

@@ -1,6 +1,7 @@
 ---
 title: 0.3.0
 date: 2026-09-17
+description: A generated palette stylesheet for consumers that cannot build against the package, and a progress track that reads presentation.
 ---
 
 # 0.3.0

package/docs/changelog/0.4.0.md

@@ -1,6 +1,7 @@
 ---
 title: 0.4.0
 date: 2026-09-23
+description: The cyber aesthetic, a solo class for every aesthetic, and three material tokens for corner shape and radius.
 ---
 
 # 0.4.0

package/docs/changelog/0.5.0.md

@@ -1,20 +1,25 @@
 ---
 title: 0.5.0
+date: 2026-09-27
+description: Named cascade layers, corners that scale with size, the sketch aesthetic, and new material tokens. Breaks several 0.4.0 names and defaults, each listed under Changed and Removed.
 ---
 
 # 0.5.0
 
-A foundation update with an opt-in sketch aesthetic and rounded sketch variant.
+A foundation update with an opt-in sketch aesthetic and rounded sketch variant. Everything under [Changed](#changed) and [Removed](#removed) breaks against `0.4.0`.
 
-## Breaking
+## Changed
 
 - **The package sits in named cascade layers.** Every entrypoint declares Tailwind's layer order first and places everything in it: foundation tokens and the palette in `theme`, resets in `base`, the intent, presentation, elevation, and aesthetic classes in `components`, and every component in `utilities` -- including on `/components` and `/native`, which emitted them unlayered. Your own utility or unlayered CSS now beats all four class families on the same element, and an aesthetic on `<html>` keeps its tokens over the theme's in any load order. CSS that relied on a package class beating it now loses to it, and a rule of yours in `@layer components` contests the class families by specificity instead of losing outright. See [Setup](../setup.md).
 - **Aesthetics set `--ui-corner`, not `--ui-radius`.** The corner is now a length at the default size that scales with the element (below); `--ui-radius` and `--ui-radius-surface` take a complete radius used as written, and every shipped aesthetic sets `--ui-corner` and `--ui-corner-surface` instead. If you set `--ui-radius` yourself, nothing changes for you. An aesthetic of your own moves to `--ui-corner` to get the scale and the corner pattern. `--ui-radius-pill` and `--ui-radius-tight` fall back through `--ui-radius`, then `--ui-corner`.
 - **`--ui-button-weight` and `--ui-button-tracking` are `--ui-label-weight` and `--ui-label-tracking`**, read by `.badge` as well as `.btn`. The old names are removed without an alias. Under `.chunky-tile`, badges now take the heavier label too.
 - **Explicit chip radii are no longer capped.** Checkbox, `.kbd`, and `.code` keep a small default radius when `--ui-radius-tight` is unset, but a supplied value now applies as a complete `border-radius`, including elliptical shapes. A consumer setting a large value now gets the large corner it asked for instead of the previous `--radius-small` ceiling.
-- **Alias classes removed**, each a second name for a class that already had one: `.dense`, `.compact`, and `.spacious` (use `.p-xs`, `.p-sm`, and `.p-lg`); `.danger` and `.error` (use `.destructive`, and `.hint.destructive` for `.hint.error`); and `.elevation-none`, `.elevation-sm`, and `.elevation-md` (use `.flat`, `.raised`, and `.floating`). `.theme-light` and `.theme-dark` stay.
 - **`.cyber` glows everything, flat or not.** Its glow moved from depth onto the new halo, so fields, chips, badges, and alerts glow too, `.flat` no longer puts the glow out, and `.raised` and `.floating` add no shadow under it.
 
+## Removed
+
+- **Alias classes removed**, each a second name for a class that already had one: `.dense`, `.compact`, and `.spacious` (use `.p-xs`, `.p-sm`, and `.p-lg`); `.danger` and `.error` (use `.destructive`, and `.hint.destructive` for `.hint.error`); and `.elevation-none`, `.elevation-sm`, and `.elevation-md` (use `.flat`, `.raised`, and `.floating`). `.theme-light` and `.theme-dark` stay.
+
 ## Added
 
 - **`.sketch`, `.sketch-rounded`, and `.sketch-solo`**: a hand-drawn treatment with uneven elliptical corners, a solid ink line (dashed checkboxes and rules under `.sketch`), a small offset shadow, and an optional consumer-supplied handwriting font. Sibling components rotate between four stable outlines; pill buttons take organic hand-drawn rounded pill contours without oval distortion; switch tracks, knobs, and chips take compact irregular box outlines, and radios stay subtly circular. The opt-in `.sketch-rounded` modifier class provides subtle, organic hand-drawn rounded contours across controls, surfaces, chips, and solo elements with 4-step sibling rotation and no egg-shaped distortion on wide elements. The solo class paints an unstyled element directly; the cascading class restyles package components. Both ship in the aesthetic aggregate and dedicated compiled and Tailwind CSS entrypoints. See [Aesthetics](../usage/aesthetics.md#sketch).

package/docs/changelog/0.6.0.md

@@ -0,0 +1,53 @@
+---
+title: 0.6.0
+date: 2026-09-29
+description: Liquid glass, hoverable tooltips, native field decorations, indeterminate checkboxes and list-box selects, and a round of fixes on every entrypoint.
+---
+
+# 0.6.0
+
+A liquid-glass modifier, glass that keeps every presentation's fill whole, hoverable tooltips, native field decorations with an `.unadorned` opt-out, indeterminate checkboxes and list-box selects, and a round of fixes to tables, controls, the focus ring, right-to-left layout, and reduced motion on every entrypoint.
+
+## Added
+
+- **`.glass-liquid`**, a modifier of `.glass`: continuous corners, a bright rim, a lighter blur, a clearer ground, and a lens that bends what is behind a surface at its edges (Chromium today; Firefox and Safari keep the rim, blur, and ground). Put it beside `.glass` on the region, or on one surface inside a glass region; `.glass-solo.glass-liquid` paints the same pane on an element the package does not style. Without `.glass` in scope it changes the corners and nothing else. See [Aesthetics → Liquid glass](../usage/aesthetics.md#liquid-glass).
+- **`.unadorned`** removes the browser's own field decorations -- the date picker button, number spin buttons, and search clear button and magnifier -- on a control or on its `.input-group`, for a field whose adornments you draw yourself. See [Forms → Browser decorations](../usage/forms.md#browser-decorations).
+- **`[data-state="closed"]` on `.tooltip`** hides the bubble while it is hovered or focused, for an Escape handler, and **`--tooltip-linger`** (300ms) sets how long a bubble stays after the pointer leaves its trigger. See [Tooltips](../usage/tooltips.md).
+- **An indeterminate `.checkbox`** (and a native one under `/native`) draws the checked plate with a dash for its mark, and a Highlight plate in forced colors. See [Forms → Toggles](../usage/forms.md#toggles).
+- **A multi-row `.select`** -- `multiple`, or a `size` above 1 -- draws as a list box: no chevron, as tall as its rows, with the chevron's room given back. It used to keep the chevron and a one-row height.
+- **`--ui-rule-ink`**, the neutral line color of a table's frame and rules, read ahead of `--ui-ink`. Glass sets it so a table's lines read on its plate; every other aesthetic clears it.
+
+## Changed
+
+- **Glass no longer thins fills.** It stopped setting `--ui-bg-alpha: 0.8`, so a `.solid` button, a checked toggle, and a `.solid` card are opaque under glass like everywhere else. Translucency comes from the surface ground alone. Glass buttons also take the base `scale(0.97)` press (it was `none`).
+- **A neutral `.solid` rests on the page background.** Its capped 20% fill was painted over nothing and showed whatever was behind it; it is now an opaque grey. The generated `--palette-neutral-solid-bg` and `-bg-hover` values changed to match, in both themes.
+- **Tables frost under glass and keep their lines.** A default or `.soft` `.data-table` blurs like a surface, its frame and rules read `--ui-rule-ink`, and a bare `<table>` under `/native` reads it too.
+- **A table takes the surface corner and is never clipped.** The four corner cells round instead of an `overflow` clip, so a `<caption>` is untouched in every engine; a cell spanning rows into a bottom corner leaves that corner square. `.table-wrap` makes room for an aesthetic's halo (cyber's glow) inside its scroll box, so put the aesthetic class on the wrapper or an ancestor.
+- **Table rules draw at the aesthetic's line width**, uncapped, so `.chunky-tile`'s 2px frame no longer sits over a 1px row rule and `.pixel` draws them at all.
+- **The focus ring is pulled in by the focused element's line width.** `--focus-ring-offset` is no longer declared at `:root`; its default is computed on the element, so it lands on the edge under every aesthetic. Setting `--focus-ring-offset` yourself still wins, but reading `var(--focus-ring-offset)` in your own CSS now needs a fallback.
+- **Ink aesthetics draw controls in the control border.** Under `.neobrutalism`, `.pixel`, `.cyber`, and `.sketch`, a resting neutral field or toggle uses `--color-control-border` instead of the near-primary ink. A bare native checkbox or radio under `/native` takes the control ink too, and a `.neutral` field under glass takes it like an unclassed one.
+- **Text controls keep the browser's own decorations.** The date picker button, number spin buttons, and search clear button were hidden on every text control, which also removed what they do. They are back by default; add `.unadorned` to remove them.
+- **Buttons and fields take the surrounding font on every entrypoint.** `<button>` under `/native`, and every `.btn` and text control under `/components`, used the user agent's smaller control font (13.33px), so the same label printed at three sizes across elements and entrypoints. They inherit the page's font now, as they already did on `.`.
+- **A default `.btn` is `--control-height` tall**, 40px, the same as `.ipt` beside it; it was 42px, and 44px under a 2px aesthetic line. Its vertical padding gives back the line width.
+- **`/tw` keeps Tailwind's `2xl` breakpoint.** It redefined `--breakpoint-2xl` as 90rem, which moved every `2xl:` utility in a consumer's own Tailwind build from 96rem. `--breakpoint-xs` (30rem) is still added. Nothing in the package used the override, so the compiled entrypoints are unchanged.
+- **Components honour reduced motion and fix `<dialog>` on every entrypoint.** `/components` and the focused `/tw/*` entries carry no reset, so the skeleton and progress shimmer, the indeterminate sweep, and the tooltip, toggle, and press transitions kept moving under `prefers-reduced-motion: reduce`, and a `<dialog class="card">` rendered open on load. Each component now stops its own motion, and the `<dialog>` fix ships beside `.card`. The fix now reaches only a dialog carrying `.card`, `.panel`, or `.surface`, so a dialog the package does not style keeps its own margin.
+- **A tooltip bubble is hoverable.** It lingers for `--tooltip-linger` after the pointer leaves the trigger and stays open while the pointer is over it, as WCAG 1.4.13 asks; it used to vanish on the way. A closed bubble is `visibility: hidden` rather than only transparent, so a bubble no `aria-describedby` points at is no longer read in place while closed.
+- **`.alert-icon` sizes without `!important`.** It set its 1.25rem size `!important`, which no consumer rule could override. It sets `--ic-size` for `@codenhub/icons` glyphs and a plain size for any other icon now, so your own rule resizes it. An icon set that sizes itself in an unlayered rule under another knob keeps its own size.
+- **The Tailwind CSS peer range is `>=4.3.2 <5`.** It claimed `>=4.0.0`, but the `/tw` source needs `@source not` and `@source inline()` (Tailwind 4.1) and is tested against 4.3.2. The peer is still optional, and only `/tw` needs it.
+- **Browser floor is Firefox 128.** Non-inheriting elevation relies on `@property`; the documented floor was Firefox 121.
+
+## Fixed
+
+- **A switch's knob sits inside `.pixel`'s inset ring** instead of covering it, so an unchecked and a checked switch no longer read as two halves.
+- **The sketch solo shadow is cast in the depth colour** rather than full ink.
+- **No stray `.contents` rule.** The compiled `.`, `/native`, and `/components` stylesheets shipped Tailwind's `.contents{display:contents}`, picked up from the license text; the build no longer scans the package's root files.
+- **Links under `/native` keep the size of their text.** `a` was mapped to body copy, so a link inside a heading printed at 14px and regular weight.
+- **The Tailwind guide no longer imports Tailwind twice.** `/tw` imports Tailwind itself, so it replaces your own `@import "tailwindcss"`; with both, an unminified build carried two copies of Preflight. The focused `/tw/*` entrypoints and `/tw/native` still expect your import first.
+- **`.tooltip-icon` keeps its size on a `<button>`.** The docs now use a real `<button type="button">` as the trigger, since `aria-label` on a role-less `<span>` is not reliably announced; the chip resets the padding and minimum size a button brings under `/native` and `/components`. The docs also no longer call it circular under every aesthetic: it is square under `.neobrutalism` and `.pixel`.
+- **A wrapped `.hint` has room between its lines.** Its line height equalled its 14px size, so wrapped lines touched; it takes `text-sm`'s 20px leading now.
+- **`/palette` follows a light subtree nested in a dark one.** Its light values sat on `:root` alone, so a `.light` region inside `.dark` kept the dark values. They answer the explicit light selectors too now.
+- **An unchecked switch's knob is `CanvasText` in forced colors.** The switch opts out of forced colors to keep its states apart, and its unchecked knob kept the package grey on the system `Canvas`.
+- **A select's chevron mirrors under `dir="rtl"`.** It and the padding kept for it stayed on the right, so a right-to-left value started beside the chevron.
+- **`.btn.icon` follows the size step.** `.sm` left an icon button at the default 40px, and under WebKit a `.lg` one was 40px wide and 48px tall. They are square at 32px and 48px now.
+- **Tables align to the inline start.** `.data-table` cells and its caption used `text-left`, so a right-to-left table stayed left-aligned.
+- **A region of one aesthetic nested inside another keeps its own material.** Every aesthetic now restates the depth colour and clears the focus inset, hover transform, and shadow tokens it does not use, so glass inside `.chunky-tile` no longer casts a black slab under every card, glass inside `.cyber` casts its shadow again, and a region inside `.pixel` no longer inherits pixel's inset focus layer.