@codenhub/styles 0.5.0 → 0.7.0

package/docs/usage/customizing.md

@@ -1,24 +1,32 @@
 ---
 title: Customizing
-description: Presentation and material token reference, and aesthetic knobs.
-order: 3
+description: Lookup for presentation and material tokens, aesthetic knobs, the six public component variables, the generated palette, and the helpers for building your own components.
+order: 9
 ---
 
 # Customizing
 
-Presentation tokens decide how much of an intent shows. Material tokens decide what a component is made of. Aesthetic tokens are the small set of named knobs a shipped aesthetic exposes to scale its own look.
+This is a lookup page for changing the package beyond its classes. [Theming](./theming.md) covers colors and the foundation tokens; this page covers the rest:
+
+- [Presentation tokens](#presentation-tokens): how much of an intent a component shows.
+- [Material tokens](#material-tokens): what a component is made of.
+- [Aesthetic tokens](#aesthetic-tokens): the knobs each aesthetic exposes.
+- [Component variables](#component-variables): the six variables a single component reads.
+- [Generated palette](#generated-palette): fixed color values for code that cannot load the package.
+- [Composition helpers](#composition-helpers): the classes to build a component of your own from.
 
 ## Presentation tokens
 
 Presentation tokens describe _how much_ of an intent a component shows, never _which_ intent it shows. They are unitless numbers and percentages, so they carry no color and inherit safely: a container sets them once and every component below resolves them against its own intent.
 
-| Token             | Purpose                                                                    |
-| ----------------- | -------------------------------------------------------------------------- |
-| `--ui-fill`       | Percentage of the intent color mixed into the background.                  |
-| `--ui-fg-on-fill` | Percentage blended from the intent readable tone toward its contrast tone. |
-| `--ui-border`     | Percentage of the intent color mixed into the border color.                |
+| Token             | Purpose                                                                                             | Default                             |
+| ----------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `--ui-fill`       | Percentage of the intent color mixed into the background.                                           | The component's default; see below. |
+| `--ui-fg-on-fill` | Percentage blended from the intent's strong tone toward its contrast color.                         | The component's default.            |
+| `--ui-border`     | Percentage of the intent's border color in the border.                                              | The component's default.            |
+| `--hover-step`    | Added to the resting fill under the pointer, in `--intent-hover`. Set it on `:root` or any element. | `14%`                               |
 
-A component resolves them with `color-mix` from its published default. Hover is derived by adding `--hover-step` to the resting fill and using `--intent-hover`; there are no per-presentation hover tokens.
+Unset, each component uses its own default, listed in [Composing → Component defaults](./composing.md#component-defaults). The presentation classes set the first three to the values in [Composing → Presentation](./composing.md#presentation). There are no hover tokens per presentation: hover is always the resting fill plus `--hover-step`, up to 100%.
 
 No fill class writes `--ui-border` and no edge class writes `--ui-fill`. A filled box with no line is `.solid.edgeless`, and `.solid.edged` renders the same box: the line fades out as the fill fills in, so even a neutral fill, capped and translucent, shows through its own border as one coat.
 
@@ -36,7 +44,9 @@ A computed color therefore reaches the page as a resolved `color-mix` result rat
 
 Material tokens describe what a component is _made of_ rather than which intent it shows or how strongly. They control shape, borders, shadows, translucency, filters, and transforms.
 
-Components read each with a fallback, so leaving them unset produces the default look. Setting them on a container restyles the whole subtree. Only shadow geometry is split into colorless parts that inherit safely; color-capable inputs such as `--ui-ink` and `--ui-surface-shadow` may include their own colors.
+Components read each with a fallback, so leaving them unset gives the default look. Set on a container, they restyle everything inside it. The one exception is `--ui-elevation`, which does not inherit, so it reaches only the element it is set on; see [Composing → Elevation](./composing.md#elevation).
+
+Shadow geometry is split into parts with no color in them, so they inherit safely. Tokens that take a color, such as `--ui-ink` and `--ui-surface-shadow`, may include their own.
 
 | Token                     | Purpose                                                                                                                                              | Fallback                                  |
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
@@ -46,14 +56,15 @@ Components read each with a fallback, so leaving them unset produces the default
 | `--ui-radius`             | A complete control radius, used as written: overrides the corner, the step, and the pattern.                                                         | Computed from the corner                  |
 | `--ui-radius-surface`     | A complete surface radius, used as written.                                                                                                          | Computed from the corner                  |
 | `--ui-scale`              | Overrides the size step the size and padding classes set.                                                                                            | The step                                  |
-| `--ui-corner-shape`       | What every corner draws: `round`, or `bevel` for a straight cut. Chromium only today.                                                                | `round`                                   |
+| `--ui-corner-shape`       | What every corner draws: `round`, `bevel` for a straight cut, or `squircle` for a continuous curve. Chromium only today.                             | `round`                                   |
 | `--ui-radius-pill`        | Corner for what is fully round by default: badges, switches, progress, the tooltip icon; `.btn.pill` and `.radio` read it with no fallback but full. | `--ui-radius`, `--ui-corner`, then full   |
-| `--ui-radius-tight`       | Complete radius for chips -- checkbox, `.kbd`, `.code` -- when set; otherwise a small computed default.                                              | `min(--ui-radius or --ui-corner, small)`  |
+| `--ui-radius-tight`       | Complete radius for chips, such as a checkbox, `.kbd`, or `.code`, when set. Unset, a small computed default.                                        | `min(--ui-radius or --ui-corner, small)`  |
 | `--ui-line-style`         | Style of every line a component draws: `solid`, `dashed`, `dotted`, or `double` (3px wide or more).                                                  | `solid`                                   |
 | `--ui-border-width`       | Edge thickness.                                                                                                                                      | `--border-width`                          |
 | `--ui-border-max`         | Ceiling on computed edge width.                                                                                                                      | `100px`                                   |
 | `--ui-ink`                | Neutral line color when no intent is set.                                                                                                            | `--color-border`                          |
 | `--ui-control-ink`        | Neutral line color of fields, selects, checkboxes, radios, and switches when no intent is set.                                                       | `--ui-ink`, then `--color-control-border` |
+| `--ui-rule-ink`           | Neutral line color of a table's frame and rules when no intent is set.                                                                               | `--ui-ink`, then `--color-border`         |
 | `--ui-rule`               | Lines inside a table. Unset draws the head and foot boundaries only; `0%` draws none; `100%` rules every row.                                        | unset                                     |
 | `--ui-shadow-x`           | Shadow horizontal offset.                                                                                                                            | `0px`                                     |
 | `--ui-shadow-y`           | Shadow vertical offset.                                                                                                                              | `0px`                                     |
@@ -68,13 +79,13 @@ Components read each with a fallback, so leaving them unset produces the default
 | `--ui-active-translate-x` | Distance a press travels into the element's depth; `-y` beside it. Scaled like the shadow.                                                           | `0px`                                     |
 | `--ui-shadow-ink`         | Percentage of shadow color taken from intent ink.                                                                                                    | `0%`                                      |
 | `--ui-halo-blur`          | Blur of a halo around the element; `--ui-halo-spread` beside it. Elevation does not scale it.                                                        | `0px`                                     |
-| `--ui-halo-ink`           | The halo's share of the intent colour, over nothing. Unset, there is no halo.                                                                        | Unset                                     |
+| `--ui-halo-ink`           | The halo's share of the intent color, over nothing. Unset, there is no halo.                                                                         | Unset                                     |
 | `--ui-shadow-edge`        | Declared, even empty, when the shadow is the element's edge rather than its depth. Read for presence.                                                | Unset                                     |
-| `--ui-elevation`          | Unitless multiplier over shadow geometry.                                                                                                            | `1`                                       |
+| `--ui-elevation`          | Unitless multiplier over shadow geometry. Does not inherit.                                                                                          | `1`                                       |
 | `--ui-surface-shadow`     | Complete multi-layer shadow accepted by surfaces only.                                                                                               | Unset                                     |
-| `--ui-surface-ground`     | Ground a surface sits on.                                                                                                                            | `--color-background`                      |
-| `--ui-bg-alpha`           | Multiplier over fill for translucent materials.                                                                                                      | `1`                                       |
-| `--ui-backdrop`           | Backdrop filter accepted by surfaces only.                                                                                                           | `none`                                    |
+| `--ui-surface-ground`     | Ground a surface, or a default or `.soft` table, sits on.                                                                                            | `--color-background`                      |
+| `--ui-bg-alpha`           | Multiplier over every fill, `.solid` included. No shipped aesthetic sets it.                                                                         | `1`                                       |
+| `--ui-backdrop`           | Backdrop filter accepted by surfaces, and by a default or `.soft` table, only.                                                                       | `none`                                    |
 | `--ui-surface-image`      | A painted layer over a surface's plate: any `background-image` value. Surfaces only.                                                                 | `none`                                    |
 | `--ui-hover-transform`    | Transform while an interactive element is hovered.                                                                                                   | `none`                                    |
 | `--ui-clip`               | Structural component silhouette.                                                                                                                     | `none`                                    |
@@ -83,7 +94,7 @@ Components read each with a fallback, so leaving them unset produces the default
 | `--ui-label-weight`       | Label weight of `.btn` (and, with `/native`, a bare `<button>`) and `.badge`.                                                                        | Semibold on a button, bold on a badge     |
 | `--ui-label-tracking`     | Label letter spacing. Unset, the label inherits it.                                                                                                  | Unset                                     |
 | `--ui-label-case`         | Label `text-transform`.                                                                                                                              | `none` on a button; inherited on a badge  |
-| `--ui-label-shadow`       | Label `text-shadow`, written without a colour so it takes the label's own.                                                                           | `none` on a button; inherited on a badge  |
+| `--ui-label-shadow`       | Label `text-shadow`, written without a color so it takes the label's own.                                                                            | `none` on a button; inherited on a badge  |
 
 ```html
 <section style="--ui-corner: 0; --ui-border-width: 3px">
@@ -102,23 +113,23 @@ Which corners take the corner is its own choice. `.cut-diagonal` keeps the top-l
 
 ### Lines, layers, and labels
 
-`--ui-line-style` reaches every line a component draws: the box's edge, the progress track, and dividers and table rules. `--ui-rule-style` optionally overrides just dividers and table rules, without changing the box edge; sketch uses it for dashed accents. A dashed or dotted line keeps its colour, so it keeps its contrast; `double` needs a width of 3px or more to draw two lines.
+`--ui-line-style` reaches every line a component draws: the box's edge, the progress track, and dividers and table rules. `--ui-rule-style` optionally overrides just dividers and table rules, without changing the box edge; sketch uses it for dashed accents. A dashed or dotted line keeps its color, so it keeps its contrast. A `double` line needs a width of 3px or more to draw two lines.
 
-`--ui-halo-*` is light rather than depth -- a glow in the element's own intent colour -- so elevation does not scale it and `.flat` leaves it on. It appears only when its ink is set.
+`--ui-halo-*` is light rather than depth: a glow in the element's own intent color. Elevation does not scale it, and `.flat` leaves it on. It appears only when its ink is set.
 
 `--ui-surface-image` lays any `background-image` over a surface's plate: cards, panels, alerts, and tooltips, not controls. Whoever sets it owns the contrast of the text over it, and your own `background-image` on a surface still wins.
 
-`--ui-label-*` treats the label of a button or a badge: weight, tracking, case, and a text shadow. Write the shadow without a colour -- `0 0 6px` -- so it takes the label's own colour and cannot lower its contrast. Your own `font-*`, `tracking-*`, and case utilities still win.
+`--ui-label-*` treats the label of a button or a badge: weight, tracking, case, and a text shadow. Write the shadow without a color, such as `0 0 6px`, so it takes the label's own color and cannot lower its contrast. Your own `font-*`, `tracking-*`, and case utilities still win.
 
-Under forced colours each of these draws its plain version: a solid line, no halo, no painted layer, and no label shadow.
+Under forced colors each of these draws its plain version: a solid line, no halo, no painted layer, and no label shadow. The silhouette and the ring below go too. Forced colors remove every box shadow, so `--ui-clip`, `--ui-clip-tight`, `--ui-border-max`, and `--ui-shadow-edge` are cleared and a component draws its real border at `--ui-border-width`.
 
 ### Shape and ring composition
 
-Clipping removes borders, outlines, and outer shadows. An aesthetic that uses a clip can replace the border with an inset shadow by setting `--ui-shadow-inset` and the four shadow geometry parts. Set `--ui-border-max: 0px` when that ring replaces the component border. Focusable components restore the clipped focus outline through `--ui-focus-inset`.
+Clipping removes borders, outlines, and outer shadows. An aesthetic that uses a clip can replace the border with an inset shadow by setting `--ui-shadow-inset` and the four shadow geometry parts. Set `--ui-border-max: 0px` when that ring replaces the component border. Focusable components restore the clipped focus outline through `--ui-focus-inset`: an inset layer of that width in `--focus-ring`, with a 2px line of `--color-background` inside it so focus still shows on a component filled with the ring's own color.
 
-A clip is not the only way to cut a corner. `--ui-corner-shape: bevel` draws the corner the radius sets as a straight cut instead of an arc, and the border, outer shadow, focus outline, and backdrop all follow it -- so a bevelled element keeps its glow and its line, where a clipped one loses both. `.cyber` uses it. Engines without `corner-shape` ignore it and draw the radius round, so an aesthetic that bevels should square its radius under `@supports not (corner-shape: bevel)`. A bevel on a full radius cuts to points: a radio, a `.btn.pill`, and anything reading `--ui-radius-pill` become diamonds or pointed hexagons.
+A clip is not the only way to cut a corner. `--ui-corner-shape: bevel` draws the corner the radius sets as a straight cut instead of an arc, and the border, outer shadow, focus outline, and backdrop all follow it. A beveled element therefore keeps its glow and its line, where a clipped one loses both. `.cyber` uses it. Engines without `corner-shape` ignore it and draw the radius round, so an aesthetic that bevels should square its radius under `@supports not (corner-shape: bevel)`. A bevel on a full radius cuts to points: a radio, a `.btn.pill`, and anything reading `--ui-radius-pill` become diamonds or pointed hexagons.
 
-`--ui-radius` accepts any `border-radius` value and is used as written, so it can place the corner per side: `10px 0` cuts only top-left and bottom-right. The pill and chip corners are separate tokens. An unset chip corner computes a small default from `--ui-radius`, then `--ui-corner`, capped at `--radius-small`; an explicit `--ui-radius-tight` is used as written, even for a per-corner or elliptical value. Aesthetic and consumer overrides can therefore give a chip a larger or more irregular shape. `.btn.pill` takes `--ui-radius-pill` ahead of the other radii; under sketch it takes organic hand-drawn pill contours avoiding egg distortion, while an explicit `--ui-radius-pill` on that button still wins.
+`--ui-radius` accepts any `border-radius` value and is used as written, so it can place the corner per side: `10px 0` cuts only top-left and bottom-right. The pill and chip corners are separate tokens. An unset chip corner computes a small default from `--ui-radius`, then `--ui-corner`, capped at `--radius-small`; an explicit `--ui-radius-tight` is used as written, even for a per-corner or elliptical value. Aesthetic and consumer overrides can therefore give a chip a larger or more irregular shape. `.btn.pill` takes `--ui-radius-pill` ahead of the other radii; under sketch it takes an uneven hand-drawn pill outline whose ends stay the same size. An explicit `--ui-radius-pill` on that button still wins.
 
 Declare `--ui-shadow-edge` when that ring _is_ the border. The ring then takes the element's edge color, which carries the edge axis as its alpha, so `.edged` draws it and `.edgeless` does not — the same answer a real border gives. Without it the ring paints on every component the aesthetic reaches and the edge classes have no effect. Use `--ui-shadow-ink` instead when the shadow is depth cast in the intent's own ink, such as a hard offset slab, which an `.edgeless` element still gets.
 
@@ -148,8 +159,8 @@ The shipped [aesthetic classes](./aesthetics.md) set material tokens for you. On
 | Token                             | Aesthetic                    | Purpose                                                                                         | Default                                                            |
 | --------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
 | `--neo-offset`                    | `.neobrutalism`              | Hard shadow offset and distance the press travels.                                              | `4px`                                                              |
-| `--glass-radius`                  | `.glass`                     | Control corner radius.                                                                          | `0.75rem`                                                          |
-| `--glass-radius-surface`          | `.glass`                     | Surface corner radius.                                                                          | `1rem`                                                             |
+| `--glass-radius`                  | `.glass`, `.glass-liquid`    | Control corner radius. `1rem` under `.glass-liquid`.                                            | `0.75rem`                                                          |
+| `--glass-radius-surface`          | `.glass`, `.glass-liquid`    | Surface corner radius. `1.5rem` under `.glass-liquid`.                                          | `1rem`                                                             |
 | `--pixel-unit`                    | `.pixel`                     | One pixel of the grid. The corner cut and the ring are one.                                     | `4px`                                                              |
 | `--font-pixel`                    | `.pixel`                     | Consumer-supplied pixel font stack.                                                             | Falls back to the monospace stack                                  |
 | `--tile-radius`                   | `.chunky-tile`               | Corner radius, on controls and surfaces alike.                                                  | `0.75rem`                                                          |
@@ -159,13 +170,13 @@ The shipped [aesthetic classes](./aesthetics.md) set material tokens for you. On
 | `--cyber-shape`                   | `.cyber`                     | Where controls take the cut: any `border-radius` value.                                         | `<cut> 0` (top-left, bottom-right)                                 |
 | `--cyber-shape-surface`           | `.cyber`                     | Where surfaces take the cut: any `border-radius` value.                                         | `0 <cut>` (top-right, bottom-left)                                 |
 | `--cyber-glow`                    | `.cyber`                     | Blur of the glow.                                                                               | `8px`                                                              |
-| `--cyber-ink`                     | `.cyber`                     | Neutral line and glow colour, where no intent sets one.                                         | Theme ink (near-black, near-white)                                 |
+| `--cyber-ink`                     | `.cyber`                     | Neutral line and glow color, where no intent sets one.                                          | Theme ink (near-black, near-white)                                 |
 | `--font-cyber`                    | `.cyber`                     | Consumer-supplied technical font stack.                                                         | Falls back to the monospace stack                                  |
 | `--sketch-radius`                 | `.sketch`                    | Control outline radius: any `border-radius` value.                                              | Irregular box outline with sibling variation                       |
 | `--sketch-radius-surface`         | `.sketch`                    | Surface container outline radius: any `border-radius` value.                                    | Sharp irregular square outline with sibling variation              |
 | `--sketch-radius-rounded`         | `.sketch`, `.sketch-rounded` | Rounded control outline radius: expressive elliptical contour with sibling variation.           | `26px 10px 24px 11px / 12px 23px 11px 20px` with sibling variation |
 | `--sketch-radius-surface-rounded` | `.sketch`, `.sketch-rounded` | Rounded surface container outline radius: expressive elliptical contour with sibling variation. | `38px 16px 36px 17px / 16px 34px 17px 32px` with sibling variation |
-| `--sketch-radius-pill`            | `.sketch`                    | Pill button outline radius: organic hand-drawn pill contour avoiding egg-shaped distortion.     | `24px 16px 23px 17px / 17px 21px 16px 20px` with sibling variation |
+| `--sketch-radius-pill`            | `.sketch`                    | Radius of a pill button's outline: an uneven hand-drawn pill whose ends stay the same size.     | `24px 16px 23px 17px / 17px 21px 16px 20px` with sibling variation |
 | `--font-sketch`                   | `.sketch`                    | Consumer-supplied handwriting font stack.                                                       | Falls back to `cursive`                                            |
 
 Every aesthetic's knobs reach the same way: each knob is _read_ with its default as a `var()` fallback rather than declared, so it resolves once into a private on the aesthetic's own class (`--_pixel-unit`, `--_neo-offset`, `--_tile-radius`, `--_tile-lift`, and so on). Set a knob on the element carrying the aesthetic class, or on any ancestor including `:root`:
@@ -184,15 +195,19 @@ Every aesthetic's knobs reach the same way: each knob is _read_ with its default
 </html>
 ```
 
-Knobs and material tokens reach in opposite directions, and telling them apart matters. A knob resolves once at the aesthetic's own class and inherits down already-resolved, so it reaches the aesthetic **from above**: setting it on the element or any ancestor works, but setting it on a _descendant_ of the aesthetic class changes nothing — the value has already been read. `--ui-radius` and the other material tokens above are read fresh by each component as it draws, so they reach **at or below** the element carrying them, which is how you round one card differently from its neighbours without touching the knob at all.
+Knobs and material tokens reach in opposite directions. A knob is read once, at the element with the aesthetic class, and the result passes down. So set a knob on that element or on one above it; set on an element inside the aesthetic, it changes nothing, because the value has already been read.
+
+`--ui-radius` and the other material tokens are read by each component as it draws. They work on the element they are set on and everything inside it, which is how you round one card differently from its neighbors without touching the knob.
 
-Shipped aesthetics set the shared material tokens above. Every shipped aesthetic sets `--ui-ink` for its neutral line. `.glass` and `.chunky-tile` also set `--ui-control-ink`, so their controls keep a heavier line than their surfaces; the others clear it and their controls take `--ui-ink`. Intent classes still override the intent slots on each component.
+Shipped aesthetics set the shared material tokens above. Every shipped aesthetic sets `--ui-ink` for its neutral line. Every shipped aesthetic also sets `--ui-control-ink`: `.glass` and `.chunky-tile` to a line of their own, heavier than their surfaces', and the others to `--color-control-border`, since their ink is near-black or near-white and a resting checkbox outlined in it would look checked. `.glass` sets `--ui-rule-ink` too, so a table's lines read on its plate; the others clear it. Intent classes still override the intent slots on each component.
 
-The same knobs tune each aesthetic's [solo class](./aesthetics.md#solo-classes), which reads them on its own element.
+The same knobs tune each aesthetic's [solo class](./solo.md), which reads them on its own element.
 
 ## Generated palette
 
-`@codenhub/styles/palette` is a generated, self-contained stylesheet of every `intent x presentation` cell's composed colors, baked to flat `--palette-*` custom properties -- the same values `box.css` composes live, computed once at build time rather than re-derived. It exists for a consumer that cannot take `@codenhub/styles` as a build-time dependency (an optional peer, for example) but still wants to look consistent with it, not as a replacement for the components themselves when Tailwind is available.
+`@codenhub/styles/palette` is a generated stylesheet of fixed colors: for every intent and presentation, the background, text, and border color a component would draw, as flat `--palette-*` custom properties. It is for code that cannot load this package's stylesheet, such as a library that lists `@codenhub/styles` as an optional peer, but wants to match it. Where you can load the stylesheet, use the components instead.
+
+**The values are a snapshot of the shipped colors.** They were computed from the package's default theme when it was built, and they do not change when you override a token. If you set `--color-primary` to your brand color, `--palette-primary-solid-bg` is still the shipped near-black. Code that must follow your theme has to read the `--color-*` tokens, which means loading `@codenhub/styles/theme`.
 
 ```css
 @import "@codenhub/styles/palette";
@@ -206,23 +221,77 @@ The same knobs tune each aesthetic's [solo class](./aesthetics.md#solo-classes),
 }
 ```
 
-Every value is already the composited color -- never a `var(--color-background)` or `var(--intent-subtle)` reference -- so this file never needs `./theme` loaded alongside it to resolve anything.
+Every value is a finished color, never a reference to another variable, so the file needs nothing else loaded.
 
 Naming: `--palette-<intent>-<presentation>-<slot>`, where `<intent>` is one of the seven published intents (`neutral`, `primary`, `secondary`, `success`, `warning`, `destructive`, `info`) and `<presentation>` is `solid`, `soft`, or `ghost`. `<slot>` is `bg`, `fg`, or `edge`. Two qualifiers layer on only where they apply:
 
-- A ground qualifier (`page` or `subtle`) inserted before the slot, present only on `.soft`/`.ghost`'s `bg` and `edge` -- `.solid` is ground-independent at full fill, and `fg` never varies by ground. No qualifier means the `transparent` ground (`.badge`/`.btn`'s ground): `--palette-success-soft-bg`. `page` is `.alert`'s ground (`--color-background`): `--palette-success-soft-page-bg`. `subtle` is `.pre`/`.code`/`.kbd`/`.tooltip-bubble`'s ground (that intent's own `--intent-subtle`): `--palette-success-soft-subtle-bg`.
-- A `-hover` suffix on `bg` and `edge` only -- `fg` never changes on hover: `--palette-success-soft-page-bg-hover`.
+- A ground qualifier, `page` or `subtle`, before the slot. It appears only on the `bg` and `edge` of `.soft` and `.ghost`, because a `.solid` fill covers its ground and the text color never depends on it.
+  - No qualifier is the transparent ground of `.badge` and `.btn`: `--palette-success-soft-bg`.
+  - `page` is the ground of `.alert`, `--color-background`: `--palette-success-soft-page-bg`.
+  - `subtle` is the ground of `.pre`, `.code`, `.kbd`, and `.tooltip-bubble`, the intent's own `--intent-subtle`: `--palette-success-soft-subtle-bg`.
+- A `-hover` suffix, on `bg` and `edge` only, because the text color does not change on hover: `--palette-success-soft-page-bg-hover`.
+
+Light values are set on `:root`. Dark values apply under `.dark`, `.theme-dark`, or `[data-theme="dark"]` on the element or an element above it, the same selectors the package's theme uses. The light values also apply under `.light`, `.theme-light`, and `[data-theme="light"]`, so the nearest explicit theme wins: a light area inside a dark one reads the light values.
+
+The file does not follow `prefers-color-scheme`. Code that uses the palette on its own already switches themes itself, so it sets one of those classes or attributes.
+
+Three more tokens have no intent, presentation, ground, or hover: `--palette-border`, `--palette-surface`, and `--palette-text`, fixed values of `--color-border`, `--color-surface`, and `--color-text`. They are for things that are not intent-colored, such as a container's border, a dialog's background, and its text.
+
+## Component variables
+
+Six variables are read by a single component and are supported inputs. Every other variable a component declares, such as `--surface-padding`, `--field-gap`, `--switch-*`, `--table-*`, or `--quote-*`, is internal and may change in any release.
+
+| Variable             | Element        | Value                        | Default                                                                 | Effect                                                                                                | Where to set it                                                                               |
+| -------------------- | -------------- | ---------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `--progress-value`   | `.progress`    | A percentage, `0%` to `100%` | `0%`                                                                    | Width of the filled part. Not clamped; a value without `%` is invalid and shows empty.                | The bar, or any element around it.                                                            |
+| `--progress-color`   | `.progress`    | A color                      | The intent color                                                        | Color of the filled part and of the `.active` shimmer.                                                | The bar, or any element around it.                                                            |
+| `--progress-surface` | `.progress`    | A color                      | The intent color at the presentation's fill: 12% by default             | Color of the track.                                                                                   | The bar, or any element around it.                                                            |
+| `--progress-edge`    | `.progress`    | A color                      | The intent's border color at the presentation's border: none by default | Color of the track's border. It shows only where the track has a border width, such as with `.edged`. | The bar, or any element around it.                                                            |
+| `--input-group-gap`  | `.input-group` | A length                     | `0.5rem`                                                                | Space between the control and its icon or text.                                                       | The `.input-group` itself. The group declares the default, so a value on a parent is ignored. |
+| `--tooltip-linger`   | `.tooltip`     | A time                       | `300ms`                                                                 | How long the bubble stays after the pointer leaves the trigger.                                       | The `.tooltip` itself. The wrapper declares the default, so a value on a parent is ignored.   |
+
+```html
+<div class="progress" role="meter" aria-label="Storage used" aria-valuemin="0" aria-valuemax="100" aria-valuenow="92" style="--progress-value: 92%; --progress-color: var(--color-warning)"></div>
+
+<div class="input-group" style="--input-group-gap: 0">
+  <span>app.example.com/u/</span>
+  <input class="ipt" id="profile-url" aria-label="Profile address" />
+</div>
+```
+
+The examples in context are in [Feedback → Show progress](./feedback.md#show-progress), [Forms → Add an icon or a fixed prefix](./forms.md#add-an-icon-or-a-fixed-prefix), and [Tooltips → Hover, linger, and Escape](./tooltips.md#hover-linger-and-escape).
+
+## Composition helpers
+
+To build a component the package does not ship, such as a segmented control or a filter chip, compose it from the same classes the package's components are built from. With compiled CSS, write them as classes; with Tailwind source, you can also `@apply` them.
 
-Dark values are scoped the same way `@codenhub/styles`' own explicit theme override is: `.dark`, `.theme-dark`, and `[data-theme="dark"]`, on the element or an ancestor. There is no `prefers-color-scheme` fallback in this file -- a consumer reaching for a standalone palette is already handling its own theme switching, so the OS-preference case is left to `@codenhub/styles`' own `light-dark()`-based tokens when that package is actually in use.
+| Class          | What it gives an element                                                                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `box`          | The painted box: background, text color, border, corner, shadow, the aesthetic's material, the focus ring, and the disabled look. It reads intent, presentation, aesthetic, and elevation. |
+| `box-hover`    | The hover color, for something pressed rather than typed into. Add it with `box`.                                                                                                          |
+| `box-active`   | The press: a slight shrink, or the aesthetic's own press. Add it with `box`.                                                                                                               |
+| `surface`      | `box` with a surface's defaults: no fill and a border, the surface corner, and the aesthetic's surface background, blur, and shadow, as on a card.                                         |
+| `text-control` | `box` with a text field's defaults: no fill and a border, the capped fill and border rules, placeholder color, a border that changes on hover and focus, and the invalid state.            |
+
+Filter chips for the members list, one pressed and one not:
+
+```html
+<button class="box box-hover box-active neutral soft edgeless" type="button" aria-pressed="true" style="padding: 0.25rem 0.75rem; border-radius: 999px">Admins</button>
+
+<button class="box box-hover box-active neutral ghost edgeless" type="button" aria-pressed="false" style="padding: 0.25rem 0.75rem; border-radius: 999px">Owners</button>
+```
 
-Three more tokens sit alongside the intent cells for the same reason, without an intent, presentation, ground, or hover axis of their own: `--palette-border`, `--palette-surface`, and `--palette-text`, flat values for `--color-border`, `--color-surface`, and `--color-text` -- the resting colors anything that is not intent-colored needs (a container's border, a dialog's background, its text), which an optional-peer consumer needs just as much as the intent cells.
+`box` does not read `aria-pressed`, so the pressed chip looks pressed only because it has `.soft`. When your code changes `aria-pressed`, change the presentation class with it: `.soft` when pressed, `.ghost` when not.
 
-## Component internals
+What to give each one:
 
-Component classes may define scoped implementation variables such as `--surface-padding`, `--field-gap`, `--input-group-pad`, `--switch-*`, `--table-*`, `--quote-*`, and `--tooltip-*`. These variables are internal wiring for class composition and are not the public token contract.
+- **`box` needs a fill and an edge class.** It has no defaults of its own, so with no `.solid`, `.soft`, or `.ghost` and no `.edged` or `.edgeless`, on the element or a container, it draws nothing. `surface` and `text-control` have defaults and work alone.
+- **Name the intent.** A `box` element takes the intent of the nearest element around it that has one, unlike the package's components. Put `.neutral` or an intent class on it.
+- **Size and spacing are yours.** None of the helpers sets padding, width, or height; `text-control` does not set the 2.5rem height that `.ipt` adds.
+- **So are behavior and semantics.** Use a real `<button>`, `<input>`, or `<a href>`, or add the role and keyboard handling yourself, and set states such as `aria-pressed` or `aria-invalid`. `box` draws the disabled look for `disabled`, `.disabled`, `aria-disabled="true"`, and `data-disabled`, but only the `disabled` attribute stops input.
 
-Consumers should customize broad behavior through color, foundation, motion, elevation, radius, layout, and focus tokens first. The only supported component-scoped input is `--progress-value` on the `.progress` element, because consumers must provide a value such as `64%`.
+Do not set or read the `--_`-prefixed variables these helpers use internally; they change between releases.
 
-`--layout-gap` replaces the removed `--layout-stack-gap` and `--layout-cluster-gap` tokens. No compatibility aliases are provided.
+## Next
 
-Next: [Aesthetics](./aesthetics.md) covers each shipped aesthetic's complete look and its documented exceptions.
+[Content and layout](./content-and-layout.md) lists the layout helpers, the type scale, surfaces, tables, and content chips.

package/docs/usage/feedback.md

@@ -1,87 +1,152 @@
 ---
 title: Feedback
-description: Alert, badge, loader, skeleton, and progress class reference.
-order: 7
+description: A saving button, alerts, badges, loading placeholders, and progress bars, and what your code must keep in sync with them.
+order: 3
 ---
 
 # Feedback
 
-| Class            | Purpose                                                                      |
-| ---------------- | ---------------------------------------------------------------------------- |
-| `.alert`         | Inline feedback surface.                                                     |
-| `.alert-icon`    | Sizing and alignment for an icon element dropped in as a child of `.alert`.  |
-| `.badge`         | Compact status pill.                                                         |
-| `.loader-mask`   | Low-level activity indicator composition utility. Applies the spinner mask.  |
-| `.loader`        | Standalone inline loader artwork.                                            |
-| `.skeleton`      | Ambient loading placeholder.                                                 |
-| `.progress`      | Progress track. Uses `--progress-value` variable.                            |
-| `.active`        | Optional on `.progress` to add a track shimmer.                              |
-| `.indeterminate` | Optional on `.progress` to animate a moving fill without `--progress-value`. |
-
-Activity indicator modifier classes compose with `.loader`:
-
-| Class                  | Animation style                         |
-| ---------------------- | --------------------------------------- |
-| _(default)_            | Circular spinner (rotating arc).        |
-| `.dots-wave`           | Three dots bouncing up/down in a wave.  |
-| `.dots-fade`           | Three dots fading in and out.           |
-| `.dots-queue`          | Dot queuing from left to right.         |
-| `.dots-rotate`         | Side dots rotating around a center dot. |
-| `.dots-grow`           | Three dots growing and shrinking.       |
-| `.dots-grow-alternate` | Outer dots small, center dot pulses.    |
-| `.dot-bounce`          | Single dot bouncing with squash effect. |
-| `.bars-wave`           | Three vertical bars scaling in a wave.  |
-| `.pulse-ring`          | Two concentric rings pulsing outward.   |
-
-These variants retain their embedded SVG animations normally. Under `prefers-reduced-motion: reduce`, loader CSS substitutes a corresponding static mask. This fallback is part of focused loader, button, and components imports; it does not depend on the global reset. See [Accessibility](../accessibility.md).
-
-Loader size modifiers:
-
-| Class    | Size                 |
-| -------- | -------------------- |
-| _(none)_ | Default (`1.75rem`). |
-| `.sm`    | Small (`1.25rem`).   |
-| `.lg`    | Large (`2.25rem`).   |
-
-Alerts, badges, progress bars, skeletons, and loaders accept `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, and `.info`. Without an intent, they use the text palette, except `.loader`, which keeps `currentColor` so it matches whatever content surrounds it.
-
-Skeletons, loaders, and dividers are indicators: they read intent but ignore fill and edge [presentation](./composing.md#presentation). `.progress` is not one of them — its track reads both, `.soft.edgeless` by default; only the moving value fill stays intent-colored at full strength regardless of presentation. `.solid` is unsupported on the track, and `.ghost.edgeless` renders but is discouraged, since neither leaves the track a visible frame. See [Composing → Component axis reference](./composing.md#component-axis-reference) for the full table.
+The profile form can be submitted, but nothing tells the user what happened. This page adds the screen's feedback: a Save button that shows it is working, an alert when the save succeeds, a badge on the plan card, a placeholder while the profile loads, and bars for storage use and a data export. The package draws each of these; your code decides when they appear, updates their values, and makes sure screen readers hear about them.
+
+## Show that the form is saving
+
+There is no loading class. A saving button is a disabled button with a spinning icon:
+
+```html
+<button class="btn primary" type="submit" disabled>
+  <i class="ic-lucide-loader-circle ic-anim-spin" aria-hidden="true"></i>
+  Saving…
+</button>
+```
+
+The spinner comes from `@codenhub/icons`, which this package does not load. Load it once, as [Buttons → Loading icons](./buttons.md#loading-icons) shows; with compiled CSS that is:
+
+```css
+@import "@codenhub/icons";
+@import "@codenhub/icons/lucide";
+```
+
+`ic-anim-spin` rotates the icon and stops when the user asks the system for reduced motion. The animated `svg-spinners` family in `@codenhub/icons` is different: its artwork keeps moving under that preference. Either icon takes the button's text color.
+
+Disabling the button stops a second click from submitting twice. Whether to keep or replace the label is up to you; the package has no way to hide it. A changing button label is not reliably announced, so tell screen reader users the outcome with a status message, as the next section does.
+
+## Confirm the result with an alert
+
+When the save succeeds, show an alert above the form:
 
 ```html
-<span class="loader success" aria-hidden="true"></span> <span class="skeleton info"></span>
+<div class="alert success" role="status">Profile saved.</div>
 ```
 
-The package ships no icon of its own: `.alert` is already `flex`, so an icon dropped in as a child is spaced from the message by its `gap-3` with nothing to trigger. `.alert-icon` only sizes and aligns whatever icon element you provide — an inline `<svg>`, an `<img>`, or a class from an icon set such as `@codenhub/icons` — the same contract [`.input-group`](./forms.md#icons) documents.
+`role="status"` makes screen readers announce the text politely, after what they are reading. For an error the user must act on, use `role="alert"`, which interrupts:
+
+```html
+<div class="alert destructive" role="alert">Your changes were not saved. Check your connection and try again.</div>
+```
 
-Alerts and badges read the shared [presentation](./composing.md#presentation) classes. Without one they use a tinted surface, intent-colored text, and a mixed intent border -- except a neutral `.alert` (no named intent), which rests untinted instead, the same no-named-intent carve-out `.card.soft` and `.panel` use: a plain `--color-foreground` plate rather than 12% of near-black ink over the page. A named intent (`.alert.success`, `.alert.destructive`, and so on) keeps its ordinary tint. `.badge` is unaffected either way -- it has no border to fall back on at rest, so untinting it would make a neutral badge disappear rather than read quieter.
+Screen readers announce a live region when its content changes, so render the region empty when the page loads and put the message into it, rather than inserting a new alert element with the text already inside. The package adds no role, timing, or dismiss button; those are yours.
 
-## Example
+An alert is a row with a 0.75rem gap, so an icon placed before the message is spaced automatically. `.alert-icon` sizes an icon to 1.25rem and aligns it with the first line of text:
 
 ```html
-<div class="alert success" role="status">Saved successfully.</div>
-<div class="alert primary solid" role="status">Deployment started.</div>
-<div class="alert warning soft" role="status">
-  <svg class="alert-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
-    <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
-    <path d="M12 9v4" />
-    <path d="M12 17h.01" />
-  </svg>
-  Review required.
+<div class="alert warning" role="status">
+  <i class="alert-icon ic-lucide-triangle-alert" aria-hidden="true"></i>
+  Your card expires next month. Update it to keep your plan.
 </div>
-<div class="alert destructive ghost edged" role="alert">Deployment failed.</div>
-<span class="badge warning">Queued</span>
-<span class="badge success solid">Live</span>
-<span class="badge info soft">Draft</span>
-<span class="loader" aria-hidden="true"></span>
-<span class="loader dots-wave" aria-hidden="true"></span>
-<span class="loader dots-fade" aria-hidden="true"></span>
-<span class="loader bars-wave" aria-hidden="true"></span>
-<span class="loader pulse-ring sm" aria-hidden="true"></span>
-<span class="loader dots-grow lg" aria-hidden="true"></span>
-<div class="progress" role="progressbar" aria-label="Upload progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64" style="--progress-value: 64%"></div>
-<div class="progress secondary active" role="progressbar" aria-label="Upload progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64" style="--progress-value: 64%"></div>
-<div class="progress primary ghost edged" role="progressbar" aria-label="Upload progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64" style="--progress-value: 64%"></div>
-<div class="progress info indeterminate" role="progressbar" aria-label="Loading" aria-valuemin="0" aria-valuemax="100"></div>
 ```
 
-Add `role="status"` or `role="alert"` to alerts based on announcement urgency, mark decorative loading visuals with `aria-hidden="true"`, and use semantic progress elements or ARIA values when numeric progress must be announced; see [Accessibility](../accessibility.md).
+Any icon element works: a class from an icon set, an inline `<svg>`, or an `<img>`. `@codenhub/icons` sizes its glyphs in a rule no class can outrank, so `.alert-icon` also sets that set's `--ic-size`. To resize an alert icon, write your own rule that sets `width`, `height`, and, for `@codenhub/icons`, `--ic-size`.
+
+### How alerts look
+
+With no presentation class, an alert is soft and edged: a light tint of its intent, intent-colored text, and a border. Presentation classes change that like on any component, such as `.alert.primary.solid` for a filled banner.
+
+An alert with no intent is an exception. It has no tint at rest; it uses `--color-foreground`, the quiet background tone one step off the page, the same as a neutral `.card.soft` or `.panel`. An alert with `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, or `.info` keeps its tint. Only those six classes count here: an alert with an intent class you defined yourself is treated as having no intent; see [Theming → Your own intent](./theming.md#your-own-intent).
+
+## Label the plan with a badge
+
+A badge is a small pill for a status or a count:
+
+```html
+<section class="card soft primary stack tight" aria-labelledby="plan-title">
+  <div class="cluster between">
+    <h2 class="text-label" id="plan-title">Current plan</h2>
+    <span class="badge success">Active</span>
+  </div>
+  <p class="text-title-sm">Team, billed yearly</p>
+</section>
+```
+
+A badge is soft with no border by default, and takes the same intent and presentation classes as a button: `.badge.warning` for "Payment due", `.badge.info.solid` for a filled "New". Unlike an alert, a badge with no intent keeps its light tint, because it has no border, and without the tint it would disappear into the text around it.
+
+## Show a placeholder while loading
+
+While the profile card waits for data, show gray blocks where the text will be:
+
+```html
+<section class="card stack" aria-busy="true" aria-labelledby="profile-title">
+  <h2 class="text-title-sm" id="profile-title">Profile</h2>
+  <p class="visually-hidden">Loading your profile…</p>
+  <div class="stack tight" aria-hidden="true">
+    <div class="skeleton" style="height: 2.5rem"></div>
+    <div class="skeleton" style="width: 60%"></div>
+  </div>
+</section>
+```
+
+A `.skeleton` fills the width of its container and is at least 1rem tall. It has no size or shape of its own: use a block element such as a `<div>`, and set its width and height to match the content it stands in for. An empty inline element such as `<span class="skeleton">` has no size and does not appear.
+
+A skeleton takes an intent but ignores presentation. With no intent, it is a light gray tinted by the surrounding text color. It shows a moving shimmer that stops when the user asks for reduced motion.
+
+Mark the blocks `aria-hidden="true"`, because they mean nothing to a screen reader. Say that the content is loading in text instead, as the visually hidden paragraph does, and remove `aria-busy` once the content is in place.
+
+## Show progress
+
+The storage card shows how much space is used, and the danger zone's "Export data first" button starts an export that takes a while. Both are `.progress` bars:
+
+```html
+<div class="progress" role="meter" aria-label="Storage used" aria-valuemin="0" aria-valuemax="100" aria-valuenow="48" aria-valuetext="48 GB of 100 GB" style="--progress-value: 48%"></div>
+
+<div class="progress primary" role="progressbar" aria-label="Export progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="20" style="--progress-value: 20%"></div>
+```
+
+`--progress-value` is the width of the filled part, as a percentage of the track. It is 0% when unset.
+
+- **Write it with `%`.** `--progress-value: 48` without a unit is not a valid width, and the bar shows empty.
+- **Nothing is clamped or checked.** Above 100%, the fill is cut off at the end of the track and looks full; a negative value is not a valid width either. Keep the value between 0% and 100% in your code.
+- **The visual value and the announced value are separate.** The bar's width comes from `--progress-value`; what a screen reader announces comes from `aria-valuenow`. The package does not connect them, so update both together.
+
+```js
+function setExportProgress(bar, percent) {
+  const value = Math.min(100, Math.max(0, Math.round(percent)));
+  bar.classList.remove("indeterminate");
+  bar.style.setProperty("--progress-value", `${value}%`);
+  bar.setAttribute("aria-valuenow", String(value));
+}
+```
+
+When you do not know how far along the work is, such as while the export is being prepared, use `.indeterminate`. A bar about a third of the track wide sweeps from start to end, again and again, and `--progress-value` is ignored. Remove `aria-valuenow`, because there is no known value to announce:
+
+```html
+<div class="progress primary indeterminate" role="progressbar" aria-label="Preparing export"></div>
+```
+
+`.active` adds a shimmer over the track of a determinate bar, to show that work is still happening between updates. Both animations stop when the user asks for reduced motion; an indeterminate bar then rests with its fill at the start.
+
+### How progress bars look
+
+The fill is the intent color at full strength, or `currentColor` with no intent. The track is soft and edgeless by default: a light tint with no border.
+
+The default track is faint. Against the page it measures about 1.1:1 to 1.3:1, below the 3:1 that WCAG 1.4.11 asks of the parts of a graphic needed to understand it. When the track's extent matters, use `.ghost.edged` with an intent class, which draws an outline around it in the intent's color. With no intent the outline is a light gray that measures below 3:1; [Accessibility → Progress outlines](../accessibility.md#progress-outlines) has the measurements and what to do for a neutral bar. `.solid` is not supported on the track, because the fill and the track would be the same color. `.ghost.edgeless` renders, but leaves the track with no visible frame.
+
+To change the colors of the fill, the track, or its border without changing the intent, set `--progress-color`, `--progress-surface`, or `--progress-edge` on the bar or any element around it. They and `--progress-value` are listed in [Customizing → Component variables](./customizing.md#component-variables).
+
+## Animation that keeps running
+
+Skeletons, `.active` shimmers, indeterminate bars, and spinners animate for as long as they are on the page. The package stops its own animations when the user asks the system for reduced motion, but that is not the only requirement. WCAG 2.2.2 asks that motion which starts automatically, lasts more than five seconds, and is shown alongside other content can be paused, stopped, or hidden by the user, unless the motion is essential.
+
+A loading indicator shown while the user cannot do anything else, and that would confuse them if it were missing, counts as essential. A shimmer or spinner that keeps moving next to content the user is working with, such as a decorative "live" shimmer on a card, does not. Remove those as soon as their work is done, or give the user a control that stops them.
+
+## Next
+
+The screen now reports what it is doing. [Tooltips](./tooltips.md) adds short help text beside a form field.