@codenhub/styles 0.1.0 → 0.2.0

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

@@ -1,32 +1,26 @@
 ---
 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.
+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.
+- `.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.
+- `.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.
+- `.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.
+- `.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.
+- `.visually-hidden` hides content visually while keeping it in the accessibility tree, using the standard clip-based recipe. Not named `.sr-only`: on a `/tw` entry the consumer's own Tailwind build already ships a real `.sr-only`, and a same-named utility of this package's own would silently collide with it in the cascade — the same reason `.data-table` is not named `.table`.
 
-The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no
-compatibility aliases.
+The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no compatibility aliases.
 
 ## Content
 
@@ -44,8 +38,7 @@ compatibility aliases.
 
 ### Table rules
 
-A table draws three kinds of line, and `.ruled` and `.ruleless` move all of
-them together:
+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 |
 | ----------- | ------------------------ | ----------------------- |
@@ -54,36 +47,32 @@ them together:
 | `.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>
+<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.
+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:
+`--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>
+  <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.
+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:
+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">
@@ -98,37 +87,30 @@ wins:
 </table>
 ```
 
-This is the one place intent cascades, because a table's rows are parts of
-the table rather than independent components.
+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:
+`.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>
+<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.
+`.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 `.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.
+`.soft` rests untinted throughout -- `--color-foreground`, no intent color mixed in, for every intent, including the resting default, on the head plate and the table's own base fill alike. A table has no hover or interaction state to reveal a tint into the way `.card.soft` does on `.interactive`/`.hoverable`, so unlike a card there is no state where a `.data-table.success.soft` reveals green; only the boundary and rule lines still read the intent.
 
-Use `.table-wrap` around `.data-table` when table width may exceed its
-container:
+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. A named intent rests at `.soft` instead, which puts a real `12%` of the intent over the ground and separates it from the others; the no-named-intent case reads no differently from `.ghost` either way, so it rests at the ground alone rather than adding an unmotivated wash of its own.
+
+Use `.table-wrap` around `.data-table` when table width may exceed its container:
 
 ```html
 <div class="table-wrap">
@@ -151,38 +133,38 @@ container:
 
 ## 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. |
-| `.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.
+| 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).
+
+`.card.soft` with no named intent is untinted at rest — a plain `--color-foreground` plate, no ink mixed in, marking a different container without drawing attention to it. The intent tint and a `--color-surface` ground only appear together, on `:hover`, and only on `.card.interactive`/`.card.hoverable`: a plain `.card.soft` with neither has no hover state to reveal into and stays at the quiet rest. A named intent (`.card.soft.success`, `.card.soft.destructive`, and so on) keeps its ordinary tint at rest instead, and deepens further on hover the same way any other filled surface does — only the no-intent case is untinted, since removing an intent's own color would silence it rather than quiet it. `.solid` and `.ghost` are unaffected either way.
+
+`.panel` with no named intent behaves the same way, permanently rather than on hover: a plain `.panel` rests at the same untinted `--color-foreground` plate a neutral `.card.soft` does, because a panel has no hover state to reveal a tint into. `.panel.primary`, `.panel.destructive`, and every other named intent keep their ordinary tint. `.kbd`, `.code`, and `.pre` follow the same no-named-intent rule for their own fill, without moving off their `--intent-subtle` ground.
+
+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 success solid">Filled 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>
+<a class="card success soft interactive" href="/package">Success-tinted at rest; deepens on hover</a>
+<article class="card hoverable">Warms on hover; the action is a nested button</article>
 <aside class="panel">Flush panel</aside>
 ```
 
-`.interactive` is 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.
+`.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
 

package/docs/usage/customizing.md

@@ -1,20 +1,16 @@
 ---
 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 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.
+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                                                                    |
 | ----------------- | -------------------------------------------------------------------------- |
@@ -22,45 +18,25 @@ component below resolves them against its own intent.
 | `--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.
+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.
+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.
+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.
+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.
+> **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.
+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 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             |
 | ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
@@ -99,29 +75,15 @@ include their own colors.
 </section>
 ```
 
-> **Material token contract**: components read these; aesthetic classes and
-> consumer overrides set them.
+> **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.
+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 {
@@ -138,16 +100,11 @@ nested inside one that declares it.
 }
 ```
 
-Variables named `--shape-*` are internal composition outputs. Do not set or
-read them; only the `--ui-*` inputs above are public.
+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.
+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                           |
 | ------------------------ | --------------- | ----------------------------------------------------------- | --------------------------------- |
@@ -160,11 +117,7 @@ imported.
 | `--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`:
+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">
@@ -180,34 +133,16 @@ carrying the aesthetic class, or on any ancestor including `:root`:
 </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, 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.
+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
-`--button-*`, `--surface-*`, `--control-*`, `--feedback-*`, and `--tooltip-*`.
-These variables are internal wiring for class composition and are not the
-public token contract.
+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%`.
+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.
+`--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.
+Next: [Aesthetics](./aesthetics.md) covers each shipped aesthetic's complete look and its documented exceptions.

package/docs/usage/feedback.md

@@ -1,6 +1,7 @@
 ---
 title: Feedback
 description: Alert, badge, loader, skeleton, and progress class reference.
+order: 7
 ---
 
 # Feedback
@@ -8,7 +9,7 @@ description: Alert, badge, loader, skeleton, and progress class reference.
 | Class            | Purpose                                                                      |
 | ---------------- | ---------------------------------------------------------------------------- |
 | `.alert`         | Inline feedback surface.                                                     |
-| `.icon`          | Subclass of `.alert`. Adds a corresponding intent icon and padding.          |
+| `.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.                                            |
@@ -32,48 +33,41 @@ Activity indicator modifier classes compose with `.loader`:
 | `.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).
+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`). |
+| 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`, `.danger`, `.error`,
-and `.info`. Without an intent, they use the text palette, except `.loader`,
-which keeps `currentColor` so it matches whatever content surrounds it.
+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).
+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>
+<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.
+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.
 
-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.
+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.
 
 ## 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 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>
 <div class="alert destructive ghost edged" role="alert">Deployment failed.</div>
 <span class="badge warning">Queued</span>
 <span class="badge success solid">Live</span>
@@ -84,34 +78,9 @@ mixed intent border.
 <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>
+<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).
+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).