@codenhub/styles 0.5.0 → 0.7.0

package/docs/usage/aesthetics.md

@@ -1,65 +1,77 @@
 ---
 title: Aesthetics
-description: The six shipped aesthetics in depth, their solo classes, and their documented exceptions.
-order: 4
+description: The six optional looks, what each one changes about a component, its knobs, and its limits.
+order: 6
 ---
 
 # Aesthetics
 
-An aesthetic decides what a component is _made of_: its radius, border thickness, shadow, and shape. Aesthetics ship from opt-in entrypoints, so importing the stylesheet is what makes the classes available:
+The settings screen has your colors. An aesthetic changes what its components are made of: the corners, the thickness of the borders, the shadow, and the shape. Put `.neobrutalism` on the `<main>` of the settings screen and every card, button, field, and badge in it gets square corners, a thick outline in the ink color, and a hard offset shadow, while keeping its colors. This page shows how to add one, then describes each of the six: what it changes, the number you can tune, and where it behaves differently from the default look.
+
+## Add an aesthetic
+
+Aesthetics ship in a separate entrypoint, so load it next to the stylesheet:
 
 ```css
 @import "@codenhub/styles";
 @import "@codenhub/styles/aesthetics";
 ```
 
-Import them after the base stylesheet. `.neobrutalism` and `.pixel` replace the neutral border color, and they do so at zero specificity, so source order is what lets them win.
+Load order does not matter: the aesthetic classes sit in the `components` cascade layer, and every entrypoint declares the layer order before it uses one, so an aesthetic imported before the base stylesheet wins exactly as one imported after it. See [Setup → Cascade layers](../setup.md#cascade-layers).
 
-Like presentation, an aesthetic class cascades to any subtree:
+Then put the class on any element. Unlike intent, an aesthetic passes down: everything inside the element takes it.
 
 ```html
-<section class="neobrutalism">
-  <button class="btn primary">Thick ink and a hard shadow</button>
-  <div class="card destructive">The intent still wins over the aesthetic ink</div>
-</section>
+<main class="neobrutalism stack">
+  <section class="card stack" aria-labelledby="profile-title">…</section>
+  <section class="card soft destructive stack" aria-labelledby="danger-title">
+    …
+    <button class="btn destructive" type="button">Delete account</button>
+  </section>
+</main>
 ```
 
+The danger zone keeps its red: under neobrutalism its outline and shadow are red too, because this aesthetic draws them in the component's own intent. To load one aesthetic instead of all six, import it by name, such as `@codenhub/styles/aesthetics/neobrutalism`; [Setup → All entrypoints](../setup.md#all-entrypoints) lists them.
+
 | Class           | Look                                                                                                                            |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `.neobrutalism` | No radius, a thick ink outline, a hard unblurred offset shadow, and a press that moves the element into it.                     |
 | `.glass`        | Translucent surfaces over a blurred backdrop with a hairline highlight edge.                                                    |
 | `.pixel`        | Corners cut by one grid unit, a chunky outline drawn as an inset ring, and the consumer-supplied `--font-pixel` over monospace. |
-| `.chunky-tile`  | Rounded slabs seated on a darker shade of themselves, with a press that moves the element down into its own bar.                |
-| `.cyber`        | Bevelled corners, a thin bright edge, and a glow in the component's own colour.                                                 |
+| `.chunky-tile`  | Rounded tiles seated on a darker bar of their own color, with a press that moves the element down into its own bar.             |
+| `.cyber`        | Beveled corners, a thin bright edge, and a glow in the component's own color.                                                   |
 | `.sketch`       | Varying elliptical corners, a solid ink line with dashed accents, a small offset shadow, and an optional handwriting face.      |
 
-Aesthetics compose with every supported fill and edge pair. `.ghost.edgeless` intentionally removes the visible material traits from components whose aesthetic is expressed only through their fill, edge, or elevation.
+Aesthetics work with every fill and edge combination. `.ghost.edgeless` removes the fill and the border, so on a component whose aesthetic shows only through those and its shadow, little of the aesthetic is left; that is intended.
 
-An explicit presentation on the element still wins over the aesthetic's defaults. The aesthetic supplies edge thickness; presentation only decides whether that edge is drawn.
+A presentation class on the element still wins over the aesthetic's defaults. The aesthetic sets how thick the border is; presentation decides whether it is drawn.
 
-An aesthetic directly on a component likewise wins over an inherited aesthetic. This includes tooltip bubbles: `.tooltip-bubble.glass` gets the complete glass bubble under a pixel ancestor, and `.tooltip-bubble.pixel` gets the complete stepped bubble under a glass ancestor.
+An aesthetic class on a component wins over one inherited from a container. This includes tooltip bubbles: `.tooltip-bubble.glass` gets the complete glass bubble under a pixel ancestor, and `.tooltip-bubble.pixel` gets the complete stepped bubble under a glass ancestor.
 
-Your own CSS wins over an aesthetic. The aesthetic classes sit in the `components` cascade layer, so a Tailwind utility on the same element -- `font-mono` on a `.pixel` region, `[--ui-radius:0]` on a `.cyber` one -- or a rule in your own unlayered stylesheet beats them. See [Setup → Cascade layers](../setup.md#cascade-layers).
+Your own CSS wins over an aesthetic. The aesthetic classes sit in the `components` cascade layer, so a rule in your own unlayered stylesheet beats them, and so does a Tailwind utility on the same element, such as `font-mono` on a `.pixel` region or `[--ui-radius:0]` on a `.cyber` one. See [Setup → Cascade layers](../setup.md#cascade-layers).
 
-Each aesthetic that scales from one number publishes it as a knob — see [Customizing → Aesthetic tokens](./customizing.md#aesthetic-tokens) for how knobs resolve and where they can be set. This page covers what each aesthetic looks like and where it makes documented exceptions.
+Most aesthetics scale from one number you can set, such as the offset of the neobrutalism shadow or the size of a pixel. These are the aesthetic's knobs, and each section below names its own. [Customizing → Aesthetic tokens](./customizing.md#aesthetic-tokens) explains where they can be set.
+
+To paint an aesthetic onto an element from another library, such as a toast or a dialog, use its [solo class](./solo.md).
 
 ## Neobrutalism
 
-The shadow is cast in the component's own intent, so a success button throws a green shadow and a destructive card a red one. With no intent, both the outline and the shadow use the ink, which follows the theme rather than the palette.
+The shadow is cast in the component's own intent, so a success button throws a green shadow and a destructive card a red one. With no intent, the outline and the shadow are the ink: near-black on a light page and near-white on a dark one. Fields and toggles are the exception. They draw the theme's control border, as they do with no aesthetic, because a resting checkbox outlined in near-black would look as loud as a checked one. The same holds under pixel, cyber, and sketch.
 
 `--neo-offset` is the knob: the shadow offset and the distance the press travels are the same number, so scaling the look scales both at once.
 
 ```html
 <section class="neobrutalism" style="--neo-offset: 6px">
-  <button class="btn primary">A longer throw</button>
+  <button class="btn primary">A deeper shadow</button>
 </section>
 ```
 
 **Exceptions:**
 
-- Content chips are left alone. A `.kbd`, `.code`, or `.pre` is content rather than structure, and an ink edge on one reads as a defect: a key cap keeps the quiet border color and a code chip keeps no border at all.
+- Content chips take the aesthetic too. A `.kbd` key cap's border changes from the quiet border gray to the ink, and from 1px to 2px, like every other border. A `.code` or `.pre` has no border by default, so it gets none; add `.edged` to give one an ink border.
 - Only `.btn` and an opted-in `.card` respond to hover and press. A card opts in with `.interactive`, or with one of its halves — `.hoverable` for the hover response alone, `.pressable` for the press alone; a plain card, an alert, or a panel is a container and stays put.
-- An alert rests on the slab under this aesthetic and nowhere else. Here the slab is a second ink line rather than depth, and an alert is the only container the package rests flat, so without it a neobrutalist alert is the one box on the page that reads as unfinished. It is a resting default, so `.flat` still takes it off and `.floating` still doubles it.
+- An alert sits on the offset shadow under this aesthetic, and under no other. An alert is otherwise flat, but here the shadow is a second outline rather than depth, and an alert without it looks unfinished next to everything else. This includes an alert inside a nested `.neobrutalism` region. `.flat` still removes it and `.floating` still doubles it.
+- The tooltip trigger takes the zero corner like everything else and draws square; `.radio` keeps its circle.
 
 ## Glass
 
@@ -76,9 +88,55 @@ The shadow is cast in the component's own intent, so a success button throws a g
 **Exceptions:**
 
 - Every surface in a glass region is glass, a neutral `.card.soft`, `.panel`, and `.alert` included.
-- The blur applies to `.card`, `.panel`, `.alert`, and the tooltip bubble only. Controls stay solid and sit on the glass: a blur under every control of a dense cluster costs a composited layer apiece and reads as noise. Controls still take the aesthetic's radius, border, and shadow.
+- The glass is the ground, not the fill. A presentation keeps its whole fill, so a `.solid` button, a checked toggle, and a `.solid` card or table are opaque; the default, `.soft`, and `.ghost` panes are the frosted ones.
+- The blur applies to `.card`, `.panel`, `.alert`, the tooltip bubble, and a default or `.soft` `.data-table` only. Controls stay solid and sit on the glass: a blur under every control of a dense cluster costs a composited layer apiece and reads as noise. Controls still take the aesthetic's radius, border, and shadow.
 - Under `prefers-reduced-transparency: reduce`, glass surfaces drop the blur and become opaque.
-- Controls draw their line in the page's ink at 55% rather than the white hairline, which would erase an unchecked checkbox on a light page. It is `--ui-control-ink`; set it on the region to choose another.
+- Buttons and an opted-in `.card` press with the plain `scale(0.97)`; reduced motion turns it off.
+- Text controls and toggles draw their line in the page's ink at 55% rather than the white hairline, which would erase an unchecked checkbox on a light page. It is `--ui-control-ink`; set it on the region to choose another.
+- A table's frame and rules draw the page's ink at 20%, because the hairline vanishes on the table's plate. It is `--ui-rule-ink`.
+- A table with a `<caption>` blurs behind the caption as well as its rows in Chromium and Safari, whose table box includes the caption, and under `.glass-liquid` the rim and sheen frame the caption too. Firefox keeps the caption off the pane. Label the table from a heading outside it with `aria-labelledby` where that matters.
+
+### Liquid glass
+
+`.glass-liquid` is a modifier of glass, after Apple's Liquid Glass: continuous corners, a bright rim where light catches the pane, a lighter blur, a clearer ground, and a lens that bends what is behind a surface at its edges. Put it beside `.glass` on the region, or on one surface inside a glass region.
+
+```html
+<section class="glass glass-liquid">
+  <div class="card">A pane that bends the page behind it</div>
+</section>
+```
+
+The lens is drawn by an SVG filter in `backdrop-filter`, which Chromium renders and Firefox and Safari do not yet. Elsewhere the pane keeps everything but the lens: the rim, the blur, the ground, and the corners, round rather than continuous where `corner-shape` is not drawn. Nothing needs to be in your markup: the filter ships inside the stylesheet.
+
+**Exceptions:**
+
+- It reaches `.card`, `.panel`, `.alert`, the tooltip bubble, and a default or `.soft` `.data-table`. Controls stay solid, as they do under glass, except a button that asks: see [Liquid buttons](#liquid-buttons).
+- It draws its blur and lens on each surface's `::before` and `::after`, so a surface inside a liquid region cannot carry a `::before` or `::after` of your own. Each surface also becomes a positioned stacking context; a surface you position yourself keeps your placement.
+- Anything else that frosts under glass keeps liquid's light blur and its clearer ground, without the lens or the rim: a bare `<table>` under `/native`, or a component of your own built with `@apply surface`.
+- The lens is 8px of erosion blurred over 10px on every surface, and 3px blurred over 3.5px on a button; its strength is fixed. A filter cannot read a custom property, so neither is a knob. The corners are, through `--glass-radius` and `--glass-radius-surface`, with larger defaults: a continuous corner reads smaller than a round one of the same radius.
+- A region of another aesthetic nested inside a liquid region, or of plain `.glass`, keeps its own material and takes no layers.
+- Without `.glass` in scope it changes the corners and nothing else.
+- Under `prefers-reduced-transparency: reduce` the blur and the lens go and the surface is opaque, as under glass. In forced colors the layers draw nothing.
+- Text sits over a clearer pane than under glass. Over busy content, check that your text still reads: the ground is 30% of the page color, where glass's is 45%.
+
+#### Liquid buttons
+
+A button is a liquid pane when it carries `.glass-liquid` itself, inside a glass region. The modifier on the region alone leaves every button solid: a blur and a lens under each control of a dense toolbar cost two composited layers apiece and read as noise, so the one button that is meant to be glass says so.
+
+```html
+<section class="glass glass-liquid">
+  <button class="btn primary">Solid, like every control</button>
+  <button class="btn ghost glass-liquid">A clear pane</button>
+  <button class="btn soft success glass-liquid">A tinted pane</button>
+</section>
+```
+
+- The fill is still [presentation's](./composing.md#presentation). `.ghost` is the clear pane and `.soft` the tinted one; a `.solid` button keeps its opaque plate and takes the rim and sheen over it. Intent, size, `.pill`, `.icon`, hover, and press all work as on any button.
+- It works in a plain `.glass` region too, and on a button inside a liquid card.
+- It spends the button's `::before` and `::after`, so a liquid button cannot carry one of your own.
+- A disabled liquid button keeps the ground and the rim and loses the blur and the lens: it is dimmed with `opacity`, which cuts its layers off from the page behind it.
+- The label sits over whatever is behind the button. Over busy content, check that it still reads, or use `.solid`.
+- It reaches `.btn`, and a bare `<button>` only through its `.btn` class: the layers are a list of classes, which `/native`'s element mapping does not join.
 
 ## Pixel
 
@@ -92,15 +150,19 @@ The shadow is cast in the component's own intent, so a success button throws a g
 
 **Exceptions:**
 
-- Corners are one unit or nothing. Chips square instead of stepping — badges, key caps, code, checkboxes, and switches all read `--ui-clip-tight`, which this aesthetic sets to none, because one unit off each corner of a 24px badge is a bite rather than a corner. Tables, progress bars, and skeletons square too, each for its own reason: a table's `overflow: hidden` fights the clip and the corners square off where the two meet, and progress and skeleton never read a clip at all — a squaring aesthetic reaches them through `border-radius` alone. `.pre` is the one exception that steps: it carries no clip override, so it inherits the same polygon a button or a card gets, and with no border by default the cut shows with no ring around it.
+- Corners are one unit or nothing. Small chips are square instead of stepped: badges, key caps, inline code, checkboxes, and switches. One unit off each corner of a 24px badge would look like a bite, not a corner.
+- Tables, progress bars, and skeletons are square too. A table takes no cut because in Chromium and WebKit its box includes its caption, and the cut would land on the caption instead of the rows. Progress bars and skeletons take only the square corner.
+- A `.pre` code block is stepped like a card. It has no border by default, so the cut shows with no outline around it.
 - The outline is an inset ring, because a clip removes a real border — and the focus ring, for the same reason, is a second inset layer rather than an outline. Both are the element's own edge rather than a shadow, so the border answers `.edged` and `.edgeless` the way a border does: a `.edgeless` badge and a `.solid` button draw none, a `.edged` card draws one, and a field keeps one whatever a container asks for.
-- The tooltip trigger and `.radio` are hardcoded past the clip rather than reached by it. `.tooltip-icon` forces `clip-path: none` because the docs call it a circular fixed identity, the same reason `.radio` forces it: the circle is the only thing telling it from a checkbox at a glance, and a stepped polygon would square either one.
+- The inset focus ring carries a 2px line of the page color inside it. The ring is the primary color, so on a `.solid.primary` button it would be drawn over its own color; the line is what shows there.
+- In forced colors the ring and the cut both go, because the system removes every box shadow: components draw a real 2px border and square corners, and `.pixel-solo` an inward outline.
+- `.radio` and `.tooltip-icon` are never stepped. The circle is what tells a radio from a checkbox at a glance, so a radio stays round. A stepped 20px tooltip trigger would look bitten, so it is a plain square.
 - `--font-pixel` is yours to supply. The package ships no font binary, so the aesthetic has no network side effect and falls back to the monospace stack.
-- Numeral legibility depends on the face you pick. At UI sizes -- pagination, counters, small badges -- some pixel/bitmap faces render lookalike digits such as `2`/`8` or `3`/`9` closely enough to misread at a glance; this is a property of the font, not something the aesthetic's CSS can correct. Prefer a face with clearly distinct digit shapes wherever small numeric text matters.
+- Whether digits are easy to read depends on the font you pick. At small sizes, such as page numbers, counters, and badges, some pixel fonts draw `2` and `8`, or `3` and `9`, so alike that they are misread. The CSS cannot fix that. Where small numbers matter, choose a font with clearly different digits.
 
 ## Chunky tile
 
-Rounded slabs sitting on a darker shade of themselves, pressed flat on click. The look mobile learning and game apps use; it is named for what it is made of rather than for any one product.
+Rounded tiles seated on a darker bar of their own color, pressed flat on click. The look mobile learning and game apps use; it is named for what it is made of rather than for any one product.
 
 `--tile-lift` is how deep the bar is and how far a press travels, `4px` by default. One number drives both, so the top edge drops by exactly the bar's depth and the bottom edge does not move. `--tile-radius` is the corner, `0.75rem`, and it is one value rather than a control/surface pair on purpose — the shared corner is what makes a button and the card it sits in read as the same object.
 
@@ -110,7 +172,7 @@ Rounded slabs sitting on a darker shade of themselves, pressed flat on click. Th
 </section>
 ```
 
-The bar is a darker shade of the element's own colour rather than a shadow under it, so it follows every intent: a success button sits on a dark green edge, a destructive one on a dark red edge, and a plain card on a grey edge that matches the line it already draws. Measured on the light palette, `.btn.success` is `#007a55` on `#004c34`. On a dark page a near-black surface cannot go darker, so its bar lands lighter and reads as a rim.
+The bar is a darker shade of the element's own color rather than a shadow under it, so it follows every intent: a success button sits on a dark green edge, a destructive one on a dark red edge, and a plain card on a gray edge that matches the line it already draws. Measured on the light palette, `.btn.success` is `#007a55` on `#004c34`. On a dark page a near-black surface cannot go darker, so its bar lands lighter and reads as a rim.
 
 **Exceptions:**
 
@@ -123,21 +185,21 @@ The bar is a darker shade of the element's own colour rather than a shadow under
 - `--font-rounded` is yours to supply. A heavy rounded grotesque is most of this look and the package ships no font binary, so with nothing supplied the page's own stack is used.
 - Labels are drawn heavier and slightly tracked, through `--ui-label-weight` and `--ui-label-tracking`, so your own `font-*` or `tracking-*` utility still wins. It reaches `.btn` and `.badge`, and a bare `<button>` only where `/native` styles it. Casing is left alone: how a label is worded is the application's decision, so if you want uppercase buttons, write that rule in your own stylesheet.
 - `.card.interactive` presses like a `.btn`, so a chunky answer tile drops onto its bar on click; `.card.pressable` gets the same press on its own. A plain `.card` stays put.
-- The shipped `.primary` is a near-black-or-near-white monochrome depending on theme, and the bar mixes toward a fixed black regardless of theme. In light theme this leaves a primary button's bar almost invisible against its own near-black plate (measured `1.04:1`, 10 units of sRGB distance); in dark theme the near-white plate against the same black-anchored bar reads fine (`2.48:1`, 154 units). Give `.primary` a hue of its own if it is the call to action and needs the depth cue in both themes.
+- The shipped `.primary` is near-black on a light page and near-white on a dark one, and the bar is always mixed toward black. On a light page, a primary button's bar is almost invisible against its near-black face (measured `1.04:1`). On a dark page, the near-white face against the same bar reads well (`2.48:1`). Give `.primary` a hue of its own if it is the call to action and needs the depth cue in both themes.
 - Depth in this aesthetic is the bar, never a blurred drop shadow. Anything the registry rests flat sits flush on the page.
-- Controls draw a heavier grey than the tiles around them -- `neutral-600` in light, `neutral-400` in dark -- through `--ui-control-ink`, so a field reads as a field inside a tile.
+- Controls draw a heavier gray than the tiles around them, `neutral-600` in light and `neutral-400` in dark, through `--ui-control-ink`, so a field reads as a field inside a tile.
 
 ## Cyber
 
-Bevelled corners, a 1px edge, and a glow in the component's own colour: a success button glows green, a destructive card red. The bevel is drawn with `corner-shape`, so the border, the glow, and the focus outline all follow the cut rather than being clipped by it.
+Beveled corners, a 1px edge, and a glow in the component's own color: a success button glows green, a destructive card red. The bevel is drawn with `corner-shape`, so the border, the glow, and the focus outline all follow the cut rather than being clipped by it.
 
-Controls and surfaces take the cut on opposite diagonals, so a button and the card around it read as the same material and as different things: buttons and fields cut top-left and bottom-right, cards, panels, and alerts top-right and bottom-left. Anything fully round cuts to points -- a radio, a switch knob, and the tooltip icon become diamonds, a pill button or a badge a pointed hexagon -- and chips square, so the checkbox reads as a plain square beside the diamond radio.
+Controls and surfaces take the cut on opposite diagonals, so a button and the card around it read as the same material and as different things: buttons and fields cut top-left and bottom-right, cards, panels, and alerts top-right and bottom-left. Anything fully round cuts to points: a radio, a switch knob, and the tooltip icon become diamonds, and a pill button or a badge becomes a pointed hexagon. Chips go square, so the checkbox reads as a plain square beside the diamond radio.
 
-`--cyber-cut` is the cut at the default size, `0.625rem`. Controls scale it with their size step, so a `.p-xs` icon button takes half of it and keeps its corners, and it stays a true 45 degrees. `--cyber-shape` and `--cyber-shape-surface` replace the default placement with any `border-radius` value, used as written. `--cyber-glow` is the glow's blur, `8px`. `--cyber-ink` is the neutral line and glow colour, which follows the theme by default -- near-black on light, near-white on dark -- and is where a neon neutral goes if you want one.
+`--cyber-cut` is the cut at the default size, `0.625rem`. Controls scale it with their size step, so a `.p-xs` icon button takes half of it and keeps its corners, and it stays a true 45 degrees. `--cyber-shape` and `--cyber-shape-surface` replace the default placement with any `border-radius` value, used as written. `--cyber-glow` is the glow's blur, `8px`. `--cyber-ink` is the neutral line and glow color. By default it follows the theme, near-black on a light page and near-white on a dark one; set it for a neon neutral.
 
 ```html
 <section class="cyber" style="--cyber-ink: rgb(0 229 255); --cyber-cut: 0.75rem">
-  <button class="btn">Jack in</button>
+  <button class="btn">Open terminal</button>
 </section>
 ```
 
@@ -162,7 +224,7 @@ A parallelogram slants its sides into the content, so give a surface that takes
 **Exceptions:**
 
 - The bevel is Chromium-only today. Firefox and Safari do not draw `corner-shape` yet, and there the aesthetic squares its cut corners instead of rounding them, and what is fully round stays round, so the look degrades to square, lined, and glowing. It picks up the bevel with no change once an engine ships it.
-- The glow is a halo, not depth, so every component takes it -- fields, badges, and alerts included -- and `.flat` does not take it off. `.raised` and `.floating` add no shadow under this aesthetic.
+- The glow is a halo, not depth, so every component takes it, fields, badges, and alerts included, and `.flat` does not take it off. `.raised` and `.floating` add no shadow under this aesthetic.
 - In the light theme the glow of a neutral or `.primary` component is its near-black ink, which reads as a soft shadow rather than as light. The look is at its strongest on a dark page, or with a hued `--cyber-ink`.
 - A plain `.btn.icon` is a square control, so it takes the control diagonal; a `.btn.icon.pill` is round, so it becomes a diamond.
 - `--font-cyber` is yours to supply. The package ships no font binary, so the aesthetic falls back to the monospace stack.
@@ -170,7 +232,7 @@ A parallelogram slants its sides into the content, so give a surface that takes
 
 ## Sketch
 
-Hand-drawn outlines: controls take long, uneven elliptical corners, and cards, panels, and alerts take sharper ones that stay clear of their padding. Siblings rotate through four outlines by position, and a field's control takes its field's position, so a row of buttons or a stacked form does not repeat one shape. The rotation is stable for a given DOM order, not random on each render. Every outline is a complete `border-radius`, used as written rather than scaled by the size step or placed by `.cut-diagonal`.
+Hand-drawn outlines: controls take long, uneven elliptical corners, and cards, panels, alerts, and tables take sharper ones that stay clear of their padding. Siblings rotate through four outlines by position, and a field's control takes its field's position, so a row of buttons or a stacked form does not repeat one shape. The rotation is stable for a given DOM order, not random on each render. Every outline is a complete `border-radius`, used as written rather than scaled by the size step or placed by `.cut-diagonal`.
 
 The 1px ink line is solid; checkboxes, dividers, and table rules are dashed. `--ui-line-style: dashed` dashes any other component, and `--ui-rule-style: solid` puts a divider or table back to solid. The 2px hard shadow is a small neutral depth cue.
 
@@ -198,41 +260,16 @@ The dashed button is `ghost edged` because a filled button has no separate line
 **Exceptions:**
 
 - Sketch names components to rotate their outlines, so its outlines reach only this package's components; a region of another aesthetic nested inside a sketch region keeps that aesthetic's corners.
-- Chips -- checkboxes, key caps, code, badges, switches, and progress bars -- rotate through small uneven outlines through `--ui-radius-tight`. Set that token on a chip to choose its shape.
+- Chips, such as checkboxes, key caps, code, badges, switches, and progress bars, rotate through small uneven outlines set in `--ui-radius-tight`. Set that token on a chip to choose its shape.
 - A `.btn.pill` takes a rounded pill bounded to its own height, so a wide one does not become an oval. Badges, progress bars, and switches take their chip outline. Radios and the tooltip icon stay circles, slightly uneven, so a radio is never mistaken for a checkbox. An explicit `--ui-radius-pill` on an element still wins.
 - `--font-sketch` is yours to supply. The package ships no handwriting font and falls back to the platform `cursive` family.
 - Buttons press with the plain `scale(0.97)`; reduced motion turns it off.
-- Forced-colours mode draws the dashed accents solid, like every other material line.
+- Forced-colors mode draws the dashed accents solid, like every other material line.
 
 ## Solo classes
 
-An aesthetic class sets material tokens and nothing paints until a component reads them, so `.glass` on an element this package does not style -- a toast from another library, a dialog, a plain `<div>` on a page without the base stylesheet -- changes nothing. Each aesthetic also ships a solo class that paints its look directly onto the one element carrying it:
-
-| Aesthetic       | Solo class           | Paints                                                                                                                                                                                                                               |
-| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `.glass`        | `.glass-solo`        | Translucent ground, hairline edge, blur, the tucked two-layer shadow, the surface corner.                                                                                                                                            |
-| `.neobrutalism` | `.neobrutalism-solo` | 2px ink edge, square corners, the hard offset slab.                                                                                                                                                                                  |
-| `.pixel`        | `.pixel-solo`        | The stepped silhouette, the inset ring in place of a border, the pixel font.                                                                                                                                                         |
-| `.chunky-tile`  | `.chunky-tile-solo`  | The tile corner, 2px edge, the bar under it, the rounded font.                                                                                                                                                                       |
-| `.cyber`        | `.cyber-solo`        | The surface diagonal (the control one on an action), 1px edge, the glow, the font.                                                                                                                                                   |
-| `.sketch`       | `.sketch-solo`       | Uneven elliptical corners (sharp surface outline on a pane, expressive control outline on an action; subtle rounded contours when paired with `.sketch-rounded`), a 1px solid ink line, the 2px offset shadow, the handwriting face. |
-
-```css
-/* The only stylesheet from this package on the page. */
-@import "@codenhub/styles/aesthetics/glass";
-```
-
-```html
-<div class="toast glass-solo">A pane over whatever is behind it.</div>
-```
-
-A solo class ships in the same entrypoint as its aesthetic, and needs nothing else loaded:
+An aesthetic class changes nothing on an element this package does not style, such as a toast from another library. Each aesthetic also ships a solo class, such as `.glass-solo`, that paints its look onto that one element. [Solo classes](./solo.md) covers them.
 
-- **It paints material, not colour.** Edge, corner, depth, silhouette, backdrop, font, and press. No intent, no fill amount, no hover tint -- the element has no presentation to compose. Glass's translucent ground is the one fill, because it is glass's material.
-- **It reads its aesthetic's knobs and the theme's tokens, with the shipped values as fallbacks.** `--glass-radius-surface`, `--neo-offset`, `--pixel-unit`, `--tile-lift`, `--tile-radius`, `--cyber-cut`, `--cyber-shape`, `--cyber-shape-surface`, `--cyber-glow`, `--cyber-ink`, `--sketch-radius`, `--sketch-radius-surface`, `--sketch-radius-rounded`, `--sketch-radius-surface-rounded`, and the font knobs (including `--font-sketch`) all work, set on the element or any ancestor. With the theme loaded it follows it; without it, it renders the shipped look.
-- **It ignores the aesthetic around it.** It reads no `--ui-*` or `--elevation-color`, so a `.glass-solo` inside a `.pixel` region keeps its corners. The elevation modifiers do not reach it either.
-- **It beats a foreign component's own styles.** The rules are unlayered and one class deep, so they win over a component's zero-specificity or layered rules wherever the two load. The flip side is that a Tailwind utility on the same element (`rounded-none`) loses to it: tune a solo class through its knobs.
-- **It presses only an action.** Neobrutalism, chunky tile, and cyber press a `button`, `a[href]`, `[role="button"]`, `summary`, or button-type `input` that is not disabled; a container stays put, so a toast does not sink when clicked. Reduced motion drops the movement. Chunky tile's heavier label follows the same rule.
-- **Dark values need a colour scheme.** Light and dark pairs are `light-dark()`, which follows the element's `color-scheme`. The package theme sets it; a page without it gets the light values.
+## Next
 
-Do not put a solo class on this package's own components. On a `.card` it would replace the composed fill, edge, and intent with material alone; use the aesthetic class there.
+[Solo classes](./solo.md) applies these looks to components from other libraries. If every component on your screen comes from this package, the guides end here: [Composing](./composing.md), [Customizing](./customizing.md), and [Content and layout](./content-and-layout.md) are the lookup pages, and [Accessibility](../accessibility.md) lists what your application still owes its users.

package/docs/usage/buttons.md

@@ -1,62 +1,130 @@
 ---
 title: Buttons
-description: Button classes, intents, sizes, and states.
-order: 5
+description: Destructive and secondary actions, icon buttons, sizes, link buttons, disabled states, and loading icons.
+order: 1
 ---
 
 # 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.
+The settings screen has a Save button and a Cancel button. This page adds the rest of its actions: a danger zone with a destructive Delete button, an icon button that copies an API key, and smaller buttons for a dense row. It also covers disabled buttons and how to load the icons used here and on later pages.
 
-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.
+## Add a danger zone
 
-Intent classes:
+A destructive action goes in its own card at the bottom of the screen. The card is soft and destructive so it reads as a warning; the button is solid so it is the loudest thing in that card:
 
-| Class                  | Meaning                        |
-| ---------------------- | ------------------------------ |
-| `.neutral` _(default)_ | No specific intent.            |
-| `.primary`             | Primary action.                |
-| `.secondary`           | Secondary/accent action.       |
-| `.success`             | Successful or positive action. |
-| `.warning`             | Warning/caution action.        |
-| `.destructive`         | Destructive or error action.   |
-| `.info`                | Informational action.          |
+```html
+<section class="card soft destructive stack" aria-labelledby="danger-title">
+  <h2 class="text-title-sm" id="danger-title">Delete account</h2>
+  <p>This removes your projects, invoices, and API keys. It cannot be undone.</p>
+  <div class="cluster">
+    <button class="btn destructive" type="button">Delete account</button>
+    <button class="btn ghost" type="button">Export data first</button>
+  </div>
+</section>
+```
+
+The card and the button each name `.destructive`, because [intent does not pass down](../concepts.md#intent-which-color). The Export button keeps its neutral color inside the red card for the same reason.
+
+## Choose a fill and an edge
+
+A button accepts one intent, one fill class, and one edge class, all optional. With none, a button is solid and edgeless:
+
+```html
+<button class="btn primary">Save changes</button>
+<button class="btn secondary">Preview</button>
+<button class="btn primary soft">Invite member</button>
+<button class="btn destructive ghost edged">Revoke key</button>
+<button class="btn ghost">Cancel</button>
+```
+
+A **neutral** button never fills completely. Its color is the page's own text color, so a full fill would be a black or white block, the loudest thing on the page for the intent that means nothing in particular. A neutral `.solid` button stops at a 20% fill instead, a quiet gray a step darker than `.soft`. Every named intent fills to 100%.
+
+On hover, a button's fill deepens by `--hover-step` (14%), so a `.ghost` button picks up a tint and a `.solid` one changes to its intent's hover color. On press it scales down slightly (`scale(0.97)`); an [aesthetic](./aesthetics.md) can replace that with its own press, and a user's reduced-motion preference turns it off.
 
-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.
+## Sizes and shapes
 
-`.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).
+| Class   | Effect                                                                                                                                       |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| _none_  | At least 2.5rem tall (`--control-height`), 1rem side padding, and the same font size as the surrounding text.                                |
+| `.sm`   | At least 2rem tall, 0.75rem side padding, 0.875rem text.                                                                                     |
+| `.lg`   | At least 3rem tall, 1.25rem side padding, 1.0625rem text.                                                                                    |
+| `.pill` | Fully rounded ends.                                                                                                                          |
+| `.icon` | Square. At least 2.5rem on each side, 2rem with `.sm`, 3rem with `.lg`.                                                                      |
+| `.p-xs` | Tightest padding (0.5rem sides, 0.125rem top and bottom). Also removes the minimum height, so a button fits a table cell or a dense toolbar. |
+| `.p-sm` | Compact padding (0.625rem sides, 0.25rem top and bottom).                                                                                    |
+| `.p-lg` | Roomy padding (1.5rem sides, 0.75rem top and bottom).                                                                                        |
 
-Size and shape classes:
+A size class and a padding class can be combined. Only `.p-xs` removes the minimum height of a labeled button; every other combination keeps it. On an icon button, any `.p-*` class removes the minimum size and the button sizes to its icon plus that padding: 0.125rem, 0.25rem, or 0.75rem around it.
 
-| Class                                                                  | Purpose                                                                                                                                                                                                                                   |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.pill`                                                                | Fully rounded button corners by default; under sketch it takes organic hand-drawn pill contours avoiding egg-shaped distortion.                                                                                                           |
-| `.sm`                                                                  | Smaller button.                                                                                                                                                                                                                           |
-| `.lg`                                                                  | Larger button.                                                                                                                                                                                                                            |
-| `.p-xs`                                                                | 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 for a labeled button. |
-| `.p-sm`                                                                | Compact padding modifier (`px-2.5 py-1`; icon `p-1`).                                                                                                                                                                                     |
-| `.p-lg`                                                                | Spacious padding modifier (`px-6 py-3`; icon `p-3`).                                                                                                                                                                                      |
-| `.icon`                                                                | Square icon button, sized to its own padding rather than to `--control-height`. Use an accessible name in HTML.                                                                                                                           |
-| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                                                                                                                                                                                                         |
+The base look draws corners that scale with the size: a `.sm` or `.p-sm` button has slightly smaller corners than a default one, and `.lg` slightly larger.
 
-Examples:
+## Icon buttons
+
+The API keys list on the settings screen has a copy button beside each key. An icon-only button needs an accessible name, because the icon has no text a screen reader can read:
 
 ```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" disabled>
-  <span class="loader sm" aria-hidden="true"></span>
-  Saving
+<button class="btn icon ghost" type="button" aria-label="Copy API key">
+  <i class="ic-lucide-copy" aria-hidden="true"></i>
+</button>
+<button class="btn ghost sm" type="button">
+  <i class="ic-lucide-download" aria-hidden="true"></i>
+  Download invoice
 </button>
 ```
 
-## Loading
+A button is a flex row with a 0.5rem gap, so an icon next to a label is spaced without extra markup.
+
+### Loading icons
+
+This package ships no icons. The examples in these docs use `@codenhub/icons` with the Lucide family, and its class names are always written with the family, as `ic-lucide-copy`. Install it and load it once, next to this package:
+
+```sh
+pnpm add @codenhub/icons
+```
+
+With compiled CSS, import the base rules and each family you use:
+
+```css
+@import "@codenhub/styles";
+@import "@codenhub/icons";
+@import "@codenhub/icons/lucide";
+```
+
+With Tailwind source, import its Tailwind entrypoint after this package's:
+
+```css
+@import "@codenhub/styles/tw";
+@import "@codenhub/icons/tw";
+```
+
+Any other icon works too: an inline `<svg>` with `stroke="currentColor"` or `fill="currentColor"` takes the button's text color the same way.
+
+## Links that look like buttons
+
+A link that navigates, such as "View billing history", is still a link. Write it as `<a href>` with `.btn`, and it gets the same look:
+
+```html
+<a class="btn secondary ghost edged" href="/settings/billing">View billing history</a>
+```
+
+Do not use `<div class="btn">` or `<span class="btn">`: they look like buttons but cannot be focused or activated from a keyboard. Use `<button>` for actions and `<a href>` for navigation.
+
+## Disabled buttons
+
+Any of these makes a button look disabled: the `disabled` attribute, `.disabled`, `aria-disabled="true"`, or `data-disabled`. A disabled button is drawn at 58% opacity with a not-allowed cursor, and does not change on hover or press.
+
+```html
+<button class="btn primary" type="submit" disabled>Save changes</button>
+
+<a class="btn ghost" aria-disabled="true">Download invoice</a>
+```
+
+Only the `disabled` attribute stops the button from working. `.disabled`, `aria-disabled`, and `data-disabled` change the look only: a click or the Enter key still activates it, so your code has to ignore it. `aria-disabled` is the right choice when the button should stay focusable, for example so a tooltip can explain why it is disabled. A link has no `disabled` attribute, so remove its `href` as well when it should not navigate.
+
+## Loading state
 
-The package ships no loading state of its own: a loading button is a disabled `.btn` composed with a real [`.loader`](./feedback.md) child, the same activity indicator every other component uses. Disable the button so users cannot trigger duplicate work, and drop a `.loader` in beside the label — any of its variants (`.dots-wave`, `.bars-wave`, and so on) work the same way. Whether to also hide the label is your call; the package has no built-in mechanism for that.
+There is no loading class. A loading button is a disabled button with a spinner icon you bring, which [Feedback](./feedback.md#show-that-the-form-is-saving) builds for the Save button. Disable it so a second click cannot submit twice.
 
-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.
+## Next
 
-Use `<button>` for actions or an accessible link for navigation; see [Accessibility](../accessibility.md).
+The buttons are ready; the card they save has nothing to save yet. [Forms](./forms.md) adds the profile fields.