@codenhub/styles 0.0.4 → 0.1.1

package/docs/usage/buttons.md

@@ -0,0 +1,58 @@
+---
+title: Buttons
+description: Button classes, intents, sizes, and states.
+order: 5
+---
+
+# Buttons
+
+Use `.btn` with one optional intent class, one optional fill class, one optional edge class, optional size class, and optional state. See [Composing](./composing.md) for how the intent, presentation, and aesthetic axes combine on any component.
+
+Intent classes map color tokens into button tone slots. [Presentation](./composing.md#presentation) decides how much of that intent reaches background, text, border, and hover.
+
+Intent classes:
+
+| Class                               | Meaning                        |
+| ----------------------------------- | ------------------------------ |
+| `.neutral` _(default)_              | No specific intent.            |
+| `.primary`                          | Primary action.                |
+| `.secondary`                        | Secondary/accent action.       |
+| `.success`                          | Successful or positive action. |
+| `.warning`                          | Warning/caution action.        |
+| `.destructive`, `.danger`, `.error` | Destructive or error action.   |
+| `.info`                             | Informational action.          |
+
+Every component that supports intent accepts the same list and reads the same [intent tokens](./theming.md#intent-tokens), so a custom intent class works everywhere without touching a component.
+
+`.neutral` is the only intent that does not fill all the way. Its color is the page's own text color, so a full fill of it would be a black or white slab — the loudest element on the page, for the intent that means nothing in particular. It stops at `--intent-fill-max`, which is why a `.solid` neutral is a quiet plate a step past `.soft` rather than a block of ink. Set the slot on your own intent classes; see [Theming → Intent tokens](./theming.md#intent-tokens).
+
+Size and shape classes:
+
+| Class                                                                  | Purpose                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.pill`                                                                | Fully rounded button corners (`border-radius: 9999px`).                                                                                                                                                                                                                                                         |
+| `.sm`                                                                  | Smaller button.                                                                                                                                                                                                                                                                                                 |
+| `.lg`                                                                  | Larger button.                                                                                                                                                                                                                                                                                                  |
+| `.p-xs`, `.dense`                                                      | Tightest padding modifier (`px-2 py-0.5`; icon `p-0.5`). Also drops the `--control-height` minimum so a chip-sized button fits a table cell or a dense toolbar; every other size and padding class keeps that floor. An icon-only button at this tier gives up its `min-width` too, so size the glyph yourself. |
+| `.p-sm`, `.compact`                                                    | Compact padding modifier (`px-2.5 py-1`; icon `p-1`).                                                                                                                                                                                                                                                           |
+| `.p-lg`, `.spacious`                                                   | Spacious padding modifier (`px-6 py-3`; icon `p-3`).                                                                                                                                                                                                                                                            |
+| `.icon`                                                                | Square icon button. Use an accessible name in HTML.                                                                                                                                                                                                                                                             |
+| `.loading`                                                             | Loading state. Hides text and shows CSS activity indicator.                                                                                                                                                                                                                                                     |
+| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                                                                                                                                                                                                                                                                               |
+
+Examples:
+
+```html
+<button class="btn primary">Primary</button>
+<button class="btn success ghost edged">Success outline</button>
+<button class="btn warning soft">Warning soft</button>
+<button class="btn destructive ghost edgeless">Danger ghost</button>
+<button class="btn icon primary" aria-label="Create">+</button>
+<button class="btn primary loading" disabled>Saving</button>
+```
+
+`.loading` is a state, not a color or presentation class. Prefer combining it with disabled behavior so users cannot trigger duplicate work. Loading buttons keep only opacity and transform transitions active so spinner and surface colors stay synchronized when theme tokens change.
+
+On the base look a press scales the button down a little (`--ui-active-transform`, `scale(0.97)`). [Aesthetics](./aesthetics.md) swap in their own press gesture, and `prefers-reduced-motion` turns it off.
+
+Use `<button>` for actions or an accessible link for navigation; see [Accessibility](../accessibility.md).

package/docs/usage/composing.md

@@ -0,0 +1,143 @@
+---
+title: Composing
+description: Combining intent, presentation, and aesthetic on a component, and the axis-support matrix.
+order: 1
+---
+
+# Composing the three axes
+
+See [Concepts](../concepts.md#the-three-axes) for what each axis means. This page covers how they combine in markup, what the presentation classes mean in depth, which components support which axis, and elevation.
+
+## Combining axes
+
+```html
+<div class="soft">
+  <button class="btn primary">Soft primary button</button>
+  <span class="badge success">Soft success badge</span>
+  <button class="btn primary ghost edged">Outlined; the element wins</button>
+</div>
+```
+
+A declaration on the element always beats one inherited from a container, so a container sets the default look for its subtree and any element opts out.
+
+Intent classes do not cascade. `.primary` and its siblings stay on the element that shows the intent, because a container silently recoloring every descendant is a trap rather than a feature — see [Theming → Intent tokens](./theming.md#intent-tokens). Use `.neutral` to opt an element back out of an inherited intent context. Presentation and [material tokens](./customizing.md#material-tokens) do cascade, so a container can set the look of its whole subtree while any element overrides it.
+
+## Presentation
+
+Presentation has two independent axes. `.solid`, `.soft`, and `.ghost` decide how much intent fills a component; `.edged` and `.edgeless` decide whether it draws a boundary. They set [presentation tokens](./customizing.md#presentation-tokens) and nothing else, so they work on the component itself or on any ancestor.
+
+| Class       | Look                                                       |
+| ----------- | ---------------------------------------------------------- |
+| `.solid`    | Intent-colored fill with contrast text.                    |
+| `.soft`     | Lightly tinted fill with intent-colored text.              |
+| `.ghost`    | No fill at rest, with intent-colored text.                 |
+| `.edged`    | Intent-colored boundary at the aesthetic's material width. |
+| `.edgeless` | No boundary.                                               |
+
+Values each class ships:
+
+| Class       | `--ui-fill` | `--ui-fg-on-fill` | `--ui-border` |
+| ----------- | ----------- | ----------------- | ------------- |
+| `.solid`    | `100%`      | `100%`            |               |
+| `.soft`     | `12%`       | `0%`              |               |
+| `.ghost`    | `0%`        | `0%`              |               |
+| `.edged`    |             |                   | `100%`        |
+| `.edgeless` |             |                   | `0%`          |
+
+The combinations mean exactly what they spell:
+
+```html
+<button class="btn primary">Solid, the button default</button>
+<button class="btn soft edged">Tinted with a border</button>
+<button class="btn primary ghost edged">Outline</button>
+<button class="btn ghost">Ghost; picks up a tint on hover</button>
+<input class="ipt soft edgeless" />
+<!-- A field sunk into the page -->
+```
+
+A fill class never decides an edge and an edge class never decides a fill. Use `.solid.edgeless` for a filled box with no line — and prefer it on a neutral one, because a capped fill leaves the box translucent and the edge blend then paints a second coat of the same tint rather than disappearing into it (measured 1.53:1 against its own plate in light, 1.82:1 in dark).
+
+The edge is the silhouette and nothing else. Rules _inside_ a component that has an inside are a separate switch — see [Content and layout → Table rules](./content-and-layout.md#table-rules) — because tying them to this axis made them arrive by implication rather than by request.
+
+With no presentation class in scope, each component keeps its own default: buttons are filled, alerts and badges are tinted, surfaces and controls are neutral and bordered.
+
+| Component                                       | Reads                                       |
+| ----------------------------------------------- | ------------------------------------------- |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`   | Fill, text, border, and border width.       |
+| `.kbd`                                          | Fill, text, border, and border width.       |
+| `.data-table`                                   | Header fill and text, border, border width. |
+| `.ipt`, `.textarea`, `.select`, `.text-control` | Border, border width, and a capped fill.    |
+| `.input-group`                                  | Border, border width, and a capped fill.    |
+| `.checkbox`, `.radio`                           | A capped fill, checked and unchecked.       |
+| `.switch`                                       | Border, border width, and a capped fill.    |
+| `.quote`                                        | Fill, text, border, and width.              |
+| `.code`, `.pre`, `.tooltip`                     | Fill, text, border, and material.           |
+| `.loader`, `.skeleton`, `.progress`, `.divider` | Intent only, not presentation.              |
+
+Text controls and toggles cap a **cascaded** fill at `6%`, keeping typed text legible when a `.solid` container reaches a field nobody classed. A fill class written on the control itself names its own cap instead, because that is a consumer describing what they want: `.soft` takes `12%` and `.solid` takes `20%`. A switch caps at `40%`, where its three fills separate far enough to read on a track.
+
+| On a text control | fill |
+| ----------------- | ---- |
+| `.ghost`          | 0%   |
+| cascaded `.solid` | 6%   |
+| `.soft`           | 12%  |
+| `.solid`          | 20%  |
+
+The same split governs the edge: a cascaded `.edgeless` is floored and the element's own is honoured — except on `.checkbox` and `.radio`, which never drop their line at all. See [Forms](./forms.md) for the full toggle and text control reference.
+
+A tooltip bubble is filled, over a tinted ground. An intent fills it with that intent's own color: `.tooltip.primary` is the primary color, black on a light page and white on a dark one, and `.tooltip.destructive` is a red bubble.
+
+With no intent the bubble is `--color-tooltip`, the one plate in the package chosen per theme rather than derived from an intent. Composed like everything else it was `20%` of the page's ink over the surface tone, which steps _lighter_ than the surface on a dark page and _darker_ on a light one — so the dark bubble read as lifted and the light one as a mid-grey slab two steps darker than every card on the screen. The token states each direction instead: near-white over a light page, a mid grey over a dark one. `--color-tooltip-contrast` is its ink.
+
+Near-white is only 1.04:1 against a light page, so the bubble draws a hairline as well, and floors it: a container's `.solid` or `.edgeless` cannot take the boundary away from a bubble nobody classed, while `.tooltip.edgeless` still can. The ground keeps the bubble opaque at every fill, so a cascaded presentation leaves it readable over whatever it floats above. It reads the material tokens too, so an [aesthetic](./aesthetics.md) in scope shapes the bubble like any other component. See [Tooltips](./tooltips.md) for the full tooltip reference.
+
+## Component axis reference
+
+This table is the authoritative axis map for demonstrated components. "Shape" means the component reads applicable radius, border-width, shadow, hover, or clip/edge material tokens; an aesthetic may intentionally affect only the materials that component draws.
+
+Presentation is two independent axes, so they get a column each. A `Yes` means the class changes what the component computes, which `tests/browser/axes.spec.ts` asserts against `registry.json` in both directions: an axis marked `Yes` must move, and an axis marked `No` must not.
+
+| Components                                                | Intent | Fill | Edge | Aesthetic material |
+| --------------------------------------------------------- | ------ | ---- | ---- | ------------------ |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`             | Yes    | Yes  | Yes  | Shape              |
+| `.loader`                                                 | Yes    | No   | No   | No                 |
+| `.kbd`, `.data-table`                                     | Yes    | Yes  | Yes  | Radius and edge    |
+| `.quote`                                                  | Yes    | Yes  | Yes  | Edge width         |
+| `.divider`, `.skeleton`                                   | Yes    | No   | No   | No                 |
+| `.ipt`, `.textarea`, `.select`, `.text-control`           | Yes    | Yes  | Yes  | Shape              |
+| `.input-group`                                            | Yes    | Yes  | Yes  | Shape              |
+| `.surface`                                                | Yes    | Yes  | Yes  | Shape              |
+| `.checkbox`, `.radio`                                     | Yes    | Yes  | No   | Radius and edge    |
+| `.switch`                                                 | Yes    | Yes  | Yes  | Radius and edge    |
+| `.progress`                                               | Yes    | No   | No   | No                 |
+| `.code`, `.pre`                                           | Yes    | Yes  | Yes  | Radius and clip    |
+| `.tooltip`                                                | Yes    | Yes  | Yes  | Shape and overlay  |
+| `.table-wrap`, `.quote-inline`, layout and text utilities | No     | No   | No   | No                 |
+
+`.checkbox` and `.radio` are the only components that read one axis and not the other. Their line is the only thing marking an unchecked box, so it is drawn whatever the edge class says, from a container or from the element itself. `.edgeless` on either is unsupported rather than merely discouraged.
+
+Every other text control floors a _cascaded_ `.edgeless` and honours its own: a `.edgeless` toolbar will not erase the line of a field nobody classed, while `.ipt.edgeless` is a consumer describing what they want and gets it.
+
+Intent aliases such as `.danger` and `.error` occupy the same intent axis as `.destructive`; they do not add component behavior. State and modifier classes such as `.interactive`, `.hoverable`, `.pressable`, `.loading`, `.invalid`, `.compact`, and `.vertical` sit above this map and are documented with their component.
+
+## Elevation
+
+Depth is a modifier, not an axis. Nothing is raised until an [aesthetic](./aesthetics.md) draws depth or one of these classes asks for it.
+
+| Class             | Alias       | Depth                                                                    |
+| ----------------- | ----------- | ------------------------------------------------------------------------ |
+| `.elevation-none` | `.flat`     | Removes part-based elevation; glass surfaces keep their complete shadow. |
+| `.elevation-sm`   | `.raised`   | One unit of the depth in scope. Cards, tiles, popovers that sit close.   |
+| `.elevation-md`   | `.floating` | Twice it, for menus and popovers.                                        |
+
+Both names in a row are equivalent, interchangeable classes — `.elevation-sm` and `.raised` are aliases, not a canonical form and a deprecated one, the way `.destructive` and `.danger` are on the intent axis. The `none`/`sm`/`md` naming matches the raw `--elevation-*` tokens in [Theming](./theming.md#foundation-tokens) for the same weight of depth, even though the two are read from different places.
+
+Each is one unitless multiplier over whatever shadow geometry is in scope, so the same class reads as a soft blur on a plain page and as a hard offset slab under `.neobrutalism` — the aesthetic decides what depth looks like, the class decides how much of it this element takes.
+
+```html
+<article class="card elevation-sm">Lifted</article>
+<div class="elevation-md panel">A menu surface</div>
+<article class="card elevation-none">Flat, whatever the page or container says</article>
+```
+
+The multiplier is a plain number, so it inherits: a container lifts or flattens a whole region and any element inside it still opts out on itself. Spread is deliberately left out of the multiplication, because an aesthetic that draws its edge as an inset ring spends spread on it and scaling that would erase the edge.

package/docs/usage/content-and-layout.md

@@ -0,0 +1,175 @@
+---
+title: Content and layout
+description: Layout helpers, content chips and tables, surfaces, and typography utilities.
+order: 9
+---
+
+# Content and layout
+
+## Layout
+
+Layout helpers use the shared `--layout-gap` token. `.tight` sets it to `0.5rem` and `.loose` sets it to `1.5rem` within a view, stack, cluster, or auto-grid.
+
+- `.view` is a flex container; `.vertical` and `.horizontal` set its direction, and horizontal views wrap with centered cross-axis alignment.
+- `.stack` is a vertical flex stack.
+- `.cluster` is a wrapping horizontal flex row; `.between` adds `space-between` alignment.
+- `.auto-grid` is a responsive auto-fit grid using `--layout-grid-min`.
+- `.tight` and `.loose` set the shared gap to `0.5rem` or `1.5rem` on views, stacks, clusters, and auto-grids.
+- `.section` adds responsive block padding and an inline gutter.
+- `.section-content` centers content at `--container-max`; `.narrow` and `.wide` select the corresponding container tokens.
+- `.divider` is horizontal; `.vertical` makes it self-stretch vertically. It takes intent, but presentation classes do not affect it.
+
+The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no compatibility aliases.
+
+## Content
+
+| Class           | Purpose                                                                                  | Intent affects         |
+| --------------- | ---------------------------------------------------------------------------------------- | ---------------------- |
+| `.table-wrap`   | Full-width horizontal overflow wrapper for wide tables.                                  | Nothing.               |
+| `.data-table`   | Rounded nested table styling for captions, heads, footers, cells, and rows.              | Head, border, hover.   |
+| `.ruled`        | On `.data-table`. Draws a rule between body rows.                                        | Rule color.            |
+| `.ruleless`     | On `.data-table`. Draws no lines inside the table at all.                                | Nothing.               |
+| `.kbd`          | Inline keyboard-input styling.                                                           | Surface, border, text. |
+| `.quote`        | Block quote styling; a nested `cite` is set upright and takes the quotation's own color. | Bar, surface, text.    |
+| `.quote-inline` | Inline quotation styling.                                                                | Nothing.               |
+| `.code`         | Inline code formatting.                                                                  | Surface.               |
+| `.pre`          | Scrollable block code formatting with larger padding.                                    | Surface.               |
+
+### Table rules
+
+A table draws three kinds of line, and `.ruled` and `.ruleless` move all of them together:
+
+| Class       | Head and foot boundaries | Rules between body rows |
+| ----------- | ------------------------ | ----------------------- |
+| `.ruleless` | No                       | No                      |
+| _no class_  | Yes                      | No                      |
+| `.ruled`    | Yes                      | Yes                     |
+
+```html
+<table class="data-table">
+  Head and foot boundaries only
+</table>
+<table class="data-table ruled">
+  Every row separated
+</table>
+<table class="data-table ruleless">
+  No lines inside the table at all
+</table>
+```
+
+The boundaries under a head and above a foot separate the parts of a table from each other, so they are drawn by default where the row rules are not. Rules between body rows used to arrive on their own, because the component's published edge default is `edged` and the edge axis wrote the rules along with the boundary — so whether you got them depended on a registry default rather than on anything in your markup.
+
+`--ui-rule` is the token behind both classes, so a container can set the answer for a whole region without classing each table:
+
+```html
+<section style="--ui-rule: 100%">
+  <table class="data-table">
+    Ruled by the region
+  </table>
+</section>
+```
+
+The frame around the table is the edge axis and is asked for the same way: `.data-table` publishes `edgeless`, so `.edged` draws one. None of the three switches reaches the others — `.data-table.ruleless.edged` is a framed table with no lines inside it, and `.data-table.ruled` is a frameless one with every row separated.
+
+A table's rows deliberately inherit its intent instead of resetting it, so `.data-table.success` tints throughout. A row carrying its own intent still wins:
+
+```html
+<table class="data-table success">
+  <tbody>
+    <tr>
+      <td>Inherits the table intent</td>
+    </tr>
+    <tr class="destructive">
+      <td>Overrides it for this row</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+This is the one place intent cascades, because a table's rows are parts of the table rather than independent components.
+
+`.data-table`, `.kbd`, `.code`, and `.pre` also read [presentation](./composing.md#presentation). A table applies it to its header, its rules and its border; a chip to its whole plate:
+
+```html
+<table class="data-table success soft edged">
+  ...
+</table>
+<table class="data-table">
+  A ghost table: rules and type, no header plate
+</table>
+<kbd class="kbd primary solid">Ctrl</kbd>
+<kbd class="kbd primary soft edged">Shift</kbd>
+```
+
+`.ghost` means two different things on these components, and both are worth knowing before you reach for it.
+
+On `.data-table` it removes the header plate along with the body tint, so `.data-table.ghost` is boundaries and type alone. The component rests at `soft`, so that is something to ask for rather than the default.
+
+On `.kbd`, `.code`, and `.pre` it is **not supported**. All three rest on `--intent-subtle`, and that ground draws the plate whatever the fill says — so `.ghost` took the fill away and changed nothing visible. Worse, the ground alone is a near-page tint: a ghost chip measured the same `#e5e5e5` for neutral and primary on the light page, and `#f5f5f5` at 1.04:1 against it for secondary. All three rest at `.soft` instead, which puts a real `12%` of the intent over the ground and separates them.
+
+Use `.table-wrap` around `.data-table` when table width may exceed its container:
+
+```html
+<div class="table-wrap">
+  <table class="data-table">
+    <thead>
+      <tr>
+        <th>Package</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>styles</td>
+        <td>Ready</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+## Surfaces
+
+| Class                | Purpose                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `.card`              | Bordered container, surface radius, padded. Rests at elevation `1`.                   |
+| `.panel`             | Flush container for sidebars, toolbars, and wells. No elevation.                      |
+| `.interactive`       | On `.card`. Adds pointer cursor, hover and press response, and a focus ring.          |
+| `.hoverable`         | On `.card`. The hover half of `.interactive`: hover response only, no pointer cursor. |
+| `.pressable`         | On `.card`. The press half of `.interactive`: press response and pointer cursor.      |
+| `.p-xs`, `.dense`    | On `.card` or `.panel`. Reduces padding further than `.compact`.                      |
+| `.p-sm`, `.compact`  | On `.card` or `.panel`. Reduces padding.                                              |
+| `.p-lg`, `.spacious` | On `.card` or `.panel`. Increases padding.                                            |
+| `.flush`             | On `.card` or `.panel`. Removes padding, for edge-to-edge content.                    |
+
+Both read intent, [presentation](./composing.md#presentation), and [material tokens](./customizing.md#material-tokens). A plain `.card` is a neutral bordered container; only an explicit presentation tints it. Resting at elevation `1` is not a visible shadow by itself — nothing draws depth until an [aesthetic](./aesthetics.md) supplies shadow geometry or `.elevation-sm`/`.elevation-md` asks for it; see [Composing → Elevation](./composing.md#elevation).
+
+On the base look, `.card.interactive` scales down slightly on press (`--ui-active-transform`, `scale(0.97)`); an [aesthetic](./aesthetics.md) substitutes its own press gesture, and `prefers-reduced-motion` turns it off.
+
+`.interactive` is the pair `.hoverable` (hover response only, no pointer cursor) and `.pressable` (press response and pointer cursor) applied together. Take one half for a card that answers a single gesture: a card that warms on hover but holds its own action in a nested button takes `.hoverable`, so pressing that button does not dip the whole card.
+
+```html
+<article class="card">Neutral card</article>
+<article class="card success soft">Tinted success card</article>
+<article class="card primary ghost edged">Intent border, no fill</article>
+<a class="card interactive" href="/package">Responds to hover and press</a>
+<article class="card hoverable">Warms on hover; the action is a nested button</article>
+<aside class="panel">Flush panel</aside>
+```
+
+`.interactive` and `.pressable` are styling only. Use a real interactive element and give it an accessible name; a `<div class="card interactive">` is not focusable or operable by keyboard.
+
+## Typography utilities
+
+All typography classes and `.selection-contrast` are `@utility` classes.
+
+| Class                 | Purpose                                                      |
+| --------------------- | ------------------------------------------------------------ |
+| `.text-display`       | Large display headings.                                      |
+| `.text-title-lg`      | Large section titles.                                        |
+| `.text-title`         | Default section titles.                                      |
+| `.text-title-sm`      | Smaller titles or card titles.                               |
+| `.text-label-lg`      | Large label text.                                            |
+| `.text-label`         | Default label text.                                          |
+| `.text-body`          | Default body copy.                                           |
+| `.selection-contrast` | Inverts `::selection` colors to primary-contrast background. |

package/docs/usage/customizing.md

@@ -0,0 +1,148 @@
+---
+title: Customizing
+description: Presentation and material token reference, and aesthetic knobs.
+order: 3
+---
+
+# 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.
+
+## 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.                |
+
+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.
+
+No fill class writes `--ui-border` and no edge class writes `--ui-fill`. A filled box with no line is `.solid.edgeless`, which is worth reaching for on a neutral component: neutral caps its fill, so the box stays translucent and a border over it paints a second coat of the same tint instead of blending into it.
+
+```css
+background: color-mix(in oklab, var(--color-primary) var(--ui-fill, 100%), transparent);
+```
+
+Two choices there are deliberate. Mixing toward `transparent` rather than a background token lets a tinted surface adapt to whatever it is placed on. Mixing in `oklab` keeps the wide-gamut token palette intact and blends perceptually, where `srgb` would clip it.
+
+A computed color therefore reaches the page as a resolved `color-mix` result rather than the token's own `oklch` syntax. It is the same color; code that compares computed color strings should compare colors instead.
+
+> **Presentation token contract**: only presentation classes and consumer overrides set these tokens; components only read them. Setting a value that no presentation class produces is supported but unvalidated. See [Composing](./composing.md) for the classes that ship these values.
+
+## Material tokens
+
+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.
+
+| Token                   | Purpose                                                                                                       | Fallback             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `--ui-radius`           | Corner radius for controls.                                                                                   | `--radius-control`   |
+| `--ui-radius-surface`   | Corner radius for surfaces.                                                                                   | `--radius-surface`   |
+| `--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-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`                |
+| `--ui-shadow-blur`      | Shadow blur radius.                                                                                           | `0px`                |
+| `--ui-shadow-spread`    | Shadow spread radius.                                                                                         | `0px`                |
+| `--ui-shadow-inset`     | The `inset` keyword for an inner ring.                                                                        | Empty                |
+| `--ui-hover-shadow-x`   | Shadow horizontal offset while hovered.                                                                       | `--ui-shadow-x`      |
+| `--ui-hover-shadow-y`   | Shadow vertical offset while hovered.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-shadow-x`  | Shadow horizontal offset while pressed.                                                                       | `--ui-shadow-x`      |
+| `--ui-active-shadow-y`  | Shadow vertical offset while pressed.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-transform` | Transform while pressed. `none` under `prefers-reduced-motion`.                                               | `scale(0.97)`        |
+| `--ui-shadow-ink`       | Percentage of shadow color taken from intent ink.                                                             | `0%`                 |
+| `--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-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-hover-transform`  | Transform while an interactive element is hovered.                                                            | `none`               |
+| `--ui-clip`             | Structural component silhouette.                                                                              | `none`               |
+| `--ui-clip-tight`       | Compact component silhouette.                                                                                 | `--ui-clip`          |
+| `--ui-focus-inset`      | Inset focus layer width.                                                                                      | Unset                |
+
+```html
+<section style="--ui-radius: 0; --ui-border-width: 3px">
+  <button class="btn primary">Square and heavy</button>
+  <input class="ipt" placeholder="Matches" />
+</section>
+```
+
+> **Material token contract**: components read these; aesthetic classes and consumer overrides set them.
+
+### 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`.
+
+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.
+
+The token is read for its presence, not its value: declare it empty to switch the ring on, and `initial` to switch it back off in an aesthetic nested inside one that declares it.
+
+```css
+.stepped {
+  --ui-clip: polygon(/* structural silhouette */);
+  --ui-clip-tight: none;
+  --ui-border-max: 0px;
+  --ui-shadow-inset: inset;
+  --ui-shadow-edge: ;
+  --ui-shadow-x: 0px;
+  --ui-shadow-y: 0px;
+  --ui-shadow-blur: 0px;
+  --ui-shadow-spread: 4px;
+  --ui-focus-inset: var(--focus-ring-width);
+}
+```
+
+Variables prefixed `--_` are internal composition outputs — `--_bg`, `--_fg`, `--_edge`, `--_fill`, `--_shadow`, and the `--_d-*` resting slots a component states for `box` to read. Do not set or read them; only the `--ui-*` inputs above are public.
+
+## Aesthetic tokens
+
+The shipped [aesthetic classes](./aesthetics.md) set material tokens for you. Only aesthetics with a token listed below expose an aesthetic-specific token. Tune all other behavior through the shared material tokens above. Listed tokens are available only where that aesthetic's stylesheet is imported.
+
+| 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`                            |
+| `--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`                         |
+| `--tile-lift`            | `.chunky-tile`  | Depth of the seated bar, and how far a press travels.       | `4px`                             |
+| `--font-rounded`         | `.chunky-tile`  | Consumer-supplied rounded font stack.                       | Falls back to the page stack      |
+
+All four aesthetics 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`:
+
+```html
+<section class="pixel" style="--pixel-unit: 6px">
+  <button class="btn primary">Chunkier</button>
+</section>
+```
+
+```html
+<html class="pixel" style="--pixel-unit: 6px">
+  <body>
+    <button class="btn primary">Also chunkier, set from the root</button>
+  </body>
+</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.
+
+Shipped aesthetics set the shared material tokens above. `.neobrutalism` and `.pixel` set `--ui-ink` for their neutral outline; intent classes still override the intent slots on each component.
+
+## Component internals
+
+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.
+
+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%`.
+
+`--layout-gap` replaces the removed `--layout-stack-gap` and `--layout-cluster-gap` tokens. No compatibility aliases are provided.
+
+Next: [Aesthetics](./aesthetics.md) covers each shipped aesthetic's complete look and its documented exceptions.

package/docs/usage/feedback.md

@@ -0,0 +1,79 @@
+---
+title: Feedback
+description: Alert, badge, loader, skeleton, and progress class reference.
+order: 7
+---
+
+# Feedback
+
+| Class            | Purpose                                                                      |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `.alert`         | Inline feedback surface.                                                     |
+| `.icon`          | Subclass of `.alert`. Adds a corresponding intent icon and padding.          |
+| `.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 (`2rem`). |
+| `.sm`    | Small (`1.5rem`). |
+| `.lg`    | Large (`2.5rem`). |
+
+Alerts, badges, progress bars, skeletons, and loaders accept `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, `.danger`, `.error`, and `.info`. Without an intent, they use the text palette, except `.loader`, which keeps `currentColor` so it matches whatever content surrounds it.
+
+Skeletons, loaders, progress bars, and dividers are indicators. They read intent but ignore fill and edge [presentation](./composing.md#presentation).
+
+```html
+<span class="loader success" aria-hidden="true"></span> <span class="skeleton info"></span>
+```
+
+`.icon` is a subclass of `.alert`. When applied as `.alert.icon`, it increases the left padding and adds an embedded SVG. Success, warning, and destructive intents use corresponding symbols; other intents use the information symbol.
+
+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.
+
+## Example
+
+```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 icon" role="status">Review required.</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 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).