@codenhub/styles 0.6.0 → 0.8.0

package/docs/usage/forms.md

@@ -1,161 +1,255 @@
 ---
 title: Forms
-description: Field, text control, and toggle class reference.
-order: 6
+description: Labeled fields, hints and errors, icons and fixed prefixes, selects, and checkbox, radio, and switch toggles.
+order: 2
 ---
 
 # Forms
 
-| Class or Selector                                                     | Purpose                                                                                                        |
-| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `.field`                                                              | Vertical field wrapper.                                                                                        |
-| `.label`                                                              | Form label text.                                                                                               |
-| `.hint`                                                               | Secondary helper text.                                                                                         |
-| `.hint.destructive`                                                   | Helper text with destructive intent.                                                                           |
-| `.surface`                                                            | Shared public container composition utility.                                                                   |
-| `.text-control`                                                       | Shared public text-control composition utility.                                                                |
-| `.ipt`                                                                | Input control styling.                                                                                         |
-| `.input-group`                                                        | Wrapper that owns the field box so a control can carry an icon or affix.                                       |
-| `.unadorned`                                                          | Removes the browser's own field decorations, on the control or on its `.input-group`.                          |
-| `.textarea`                                                           | Textarea control styling.                                                                                      |
-| `.select`                                                             | Select control styling. With `multiple` or a `size` above 1 it is a list box: no chevron, as tall as its rows. |
-| `input[type="checkbox"].checkbox`                                     | Custom checkbox control styling.                                                                               |
-| `input[type="radio"].radio`                                           | Custom radio control styling.                                                                                  |
-| `input[type="checkbox"].switch`                                       | Custom switch control styling.                                                                                 |
-| `[aria-invalid="true"]` on controls                                   | Destructive border and focus color.                                                                            |
-| `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` on controls | Disabled styling.                                                                                              |
-
-## Icons
-
-The package ships no icon for text inputs. Icons for `.input-group` are the consumer's to choose: artwork painted as a `data:` URI could not read `currentColor` or a custom property, so it could not follow the theme or fit every aesthetic. The toggle marks below are the exception: small, fixed, built-in glyphs. `.alert` likewise takes a consumer-supplied icon; see [Feedback](./feedback.md#example).
-
-`.input-group` is the wrapper for a control that carries one. It owns the field box — border, radius, fill, focus ring, invalid and disabled state — and the control inside it goes flush, so the boundary is drawn once. Any icon element works, placed before the control for a leading icon or after it for a trailing one: an inline `<svg>`, an `<img>`, or a class from an icon set such as `@codenhub/icons`.
+The profile card has a Save button but nothing to save. This page fills it in: a display name with a hint, an email address that shows a validation error, a profile address with a fixed prefix, a language select, and the toggles for notifications, billing, and profile visibility. The package styles each control; your HTML provides the labels, the validation, and the error messages, and this page shows how to connect them.
+
+## A labeled field
+
+A field is a label, a control, and an optional hint, stacked:
 
 ```html
 <div class="field">
-  <label class="label" for="contact-email">Email</label>
-  <div class="input-group">
-    <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" aria-hidden="true">
-      <rect width="20" height="16" x="2" y="4" rx="2" />
-      <path d="m22 7-8.991 5.727a2 2 0 0 1-2.009 0L2 7" />
-    </svg>
-    <input class="ipt" type="email" id="contact-email" />
+  <label class="label" for="display-name">Display name</label>
+  <input class="ipt" id="display-name" name="display-name" aria-describedby="display-name-hint" />
+  <span class="hint" id="display-name-hint">Shown on invoices and shared projects.</span>
+</div>
+```
+
+- `.field` stacks its children with a small gap (0.35rem) and takes the full width.
+- `.label` sets label text: 1rem, medium weight.
+- `.hint` is smaller, secondary-colored helper text. Keep it outside the `<label>` and point `aria-describedby` at it, so a screen reader announces it as a description instead of reading it as part of the field's name.
+- `.ipt` styles an `<input>`. Use `.textarea` for a `<textarea>` and `.select` for a `<select>`.
+
+A text control is at least 2.5rem tall (`--control-height`), the same height as a default button, so a field and a button line up in a row. Its default look is no fill and a border. A `.textarea` is at least 7rem tall and can be resized vertically.
+
+### Sizes
+
+`.ipt`, `.select`, `.textarea`, and `.input-group` take the button's size classes, so a small field and a small button line up in a row:
+
+| Class   | Height | Side padding | Text      |
+| ------- | ------ | ------------ | --------- |
+| `.sm`   | 2rem   | 0.625rem     | 0.875rem  |
+| default | 2.5rem | 0.75rem      | inherited |
+| `.lg`   | 3rem   | 1rem         | 1.0625rem |
+
+The corners scale with the size, as a button's do. A `.textarea` keeps its 7rem minimum height at every size; the class changes its text, padding, and corners. Size an `.input-group` on the group, not on the control inside it: the control and its adornments take the group's text size.
+
+```html
+<div class="cluster tight">
+  <input class="ipt sm" aria-label="Coupon code" />
+  <button class="btn sm" type="button">Apply</button>
+</div>
+```
+
+## Show a validation error
+
+Mark the control invalid with `aria-invalid="true"` and give the error message `.hint.destructive`:
+
+```html
+<div class="field">
+  <label class="label" for="email">Email</label>
+  <input class="ipt" type="email" id="email" name="email" value="ada@" aria-invalid="true" aria-describedby="email-error" />
+  <span class="hint destructive" id="email-error">Enter a full email address, such as ada@example.com.</span>
+</div>
+```
+
+An invalid control draws its border, focus ring, and typed text in the destructive color, whatever intent class it has. The text uses the readable tone of that color, `--intent-strong`, so it stays legible on the page. The package only paints the state: deciding that the value is invalid, setting and clearing `aria-invalid`, and writing the message are your code. Remove `aria-invalid` once the value is valid again; leaving it set keeps the field red. On a checkbox, radio, or switch, `aria-invalid="true"` draws the toggle exactly as `.destructive` does, checked mark included.
+
+A hint takes any of the six built-in intents, not only `.destructive`: `.hint.success` confirms a value was accepted, and `.hint.warning` flags one that is allowed but unusual. Each prints in its intent's readable tone, `--intent-strong`, which holds 4.5:1 against the page in both themes. A hint with no intent, with `.neutral`, or with an [intent you defined yourself](./theming.md#your-own-intent), stays secondary-colored. Only a class on the hint itself colors it; an intent on the field or a container around it does not.
+
+```html
+<input class="ipt success" id="username" value="ada" aria-describedby="username-hint" /> <span class="hint success" id="username-hint">That username is available.</span>
+```
+
+## Put the profile form together
+
+```html
+<form class="card stack" aria-labelledby="profile-title">
+  <h2 class="text-title-sm" id="profile-title">Profile</h2>
+
+  <div class="field">
+    <label class="label" for="display-name">Display name</label>
+    <input class="ipt" id="display-name" name="display-name" value="Ada Lovelace" aria-describedby="display-name-hint" />
+    <span class="hint" id="display-name-hint">Shown on invoices and shared projects.</span>
+  </div>
+
+  <div class="field">
+    <label class="label" for="email">Email</label>
+    <input class="ipt" type="email" id="email" name="email" value="ada@example.com" />
+  </div>
+
+  <div class="field">
+    <label class="label" for="bio">Bio</label>
+    <textarea class="textarea" id="bio" name="bio" rows="3"></textarea>
+  </div>
+
+  <div class="field">
+    <label class="label" for="language">Language</label>
+    <select class="select" id="language" name="language">
+      <option>English</option>
+      <option>Português</option>
+      <option>Español</option>
+    </select>
+  </div>
+
+  <div class="cluster">
+    <button class="btn primary" type="submit">Save changes</button>
+    <button class="btn ghost" type="reset">Cancel</button>
+  </div>
+</form>
+```
+
+A `.select` draws its own arrow. With `multiple` or a `size` above 1 it becomes a list box instead: no arrow, as tall as the rows it shows. The open list of options is drawn by the browser and the operating system, so it does not take the package's look.
+
+## Add an icon or a fixed prefix
+
+`.input-group` puts an icon or a piece of text inside a field's border. The group draws the border, background, focus ring, and invalid and disabled states; the control inside it gives up its own, so the border is drawn once. Place the adornment before the control to put it at the start, after it to put it at the end. A group is the height of a lone field, so it lines up with the fields and buttons beside it.
+
+The profile address always starts with the same host, so it is a fixed prefix:
+
+```html
+<div class="field">
+  <label class="label" for="profile-url">Profile address</label>
+  <div class="input-group" style="--input-group-gap: 0">
+    <span>app.example.com/u/</span>
+    <input class="ipt" id="profile-url" name="profile-url" value="ada" />
   </div>
 </div>
+```
+
+The gap between the control and its adornment is `--input-group-gap`, 0.5rem by default. That suits an icon, but text meant to read as part of the value looks broken with a space after it, so the example sets it to `0`. Set it on the `.input-group` itself: the group declares its own default, so a value set on a parent element has no effect. It is one of six [public component variables](./customizing.md#component-variables).
+
+A members search, with an icon at the start (the `ic-lucide-*` classes need `@codenhub/icons` loaded; see [Buttons → Loading icons](./buttons.md#loading-icons)):
+
+```html
 <div class="field">
-  <label class="label" for="site-search">Search</label>
+  <label class="label" for="member-search">Find a member</label>
   <div class="input-group">
-    <input class="ipt" type="search" id="site-search" />
-    <i class="ic-search" aria-hidden="true"></i>
+    <i class="ic-lucide-search" aria-hidden="true"></i>
+    <input class="ipt" type="search" id="member-search" name="q" />
   </div>
 </div>
 ```
 
-The group reads intent and both [presentation](./composing.md#presentation) axes the same way a lone `.ipt` does — `.input-group.soft.edgeless` is the sunk variant, `.input-group.primary` colors the boundary — and follows whichever [aesthetic](./aesthetics.md) is in scope. `aria-invalid` or `disabled` on the control inside propagates to the group; so does either on the group itself. Focus is shown with `:focus-within`, so unlike a lone field the ring also appears on a mouse click.
+A `.select` works in a group too. The group removes the control's side padding, except at the end of a single-row select, which keeps 1.75rem so the chosen option's text does not run under the arrow.
 
-Text controls keep the browser's own decorations: the date and time picker button, a number field's spin buttons, and a search field's clear button and magnifier. Each one is also behaviour -- the picker button is the only pointer route to the picker, and the clear button empties the field.
+Any element works as the adornment: an icon class, an inline `<svg>`, an `<img>`, or text. The package ships no icons for fields, because a built-in image could not follow your text color, theme, or aesthetic.
 
-`.unadorned` removes all of them, for a field whose adornments you draw yourself. Put it on the control, or on its `.input-group` to reach the control inside. Removing a decoration removes what it did, so wire the behaviour back to your own adornment: `input.showPicker()` for a picker, `stepUp()`/`stepDown()` for spin buttons, and setting `value` to `""` and dispatching an `input` event for a clear button. Keyboard entry keeps working either way. Firefox exposes no way to remove its date picker button, so it stays there.
+The group reads intent and presentation the way a lone `.ipt` does: `.input-group.primary` colors the border and the typed text, and `.input-group.soft.edgeless` is a field sunk into the page. Put the intent on the group, not on the control inside: the group draws the field, so the control's text takes the group's intent and an intent class on the control has no effect. `aria-invalid="true"` or `disabled` on the control inside applies to the whole group, and so does either on the group itself. The group's focus ring appears when its field has focus, so unlike a lone field it also shows after a mouse click. A button inside the group, such as a clear button, draws its own ring when it has focus, and the group draws none: one ring always marks the one control that has focus.
+
+## Browser decorations
+
+Some input types come with built-in buttons: a date or time field's picker button, a number field's up and down arrows, and a search field's clear button. The package keeps them, because each one also does something: the picker button is the only way to open the picker with a mouse, and the clear button empties the field.
+
+`.unadorned` removes them, for a field where you draw your own. Put it on the control, or on its `.input-group`. Removing a decoration removes what it did, so connect your replacement yourself: `input.showPicker()` opens a picker, `stepUp()` and `stepDown()` replace the arrows, and setting `value` to `""` and dispatching an `input` event replaces a clear button. Typing keeps working either way. Firefox gives no way to remove its date picker button, so it stays there.
 
 ```html
 <div class="field">
-  <label class="label" for="query">Search</label>
+  <label class="label" for="member-filter">Find a member</label>
   <div class="input-group unadorned">
-    <i class="ic-search" aria-hidden="true"></i>
-    <input class="ipt" type="search" id="query" />
-    <button type="button" class="btn icon ghost p-xs" aria-label="Clear search">
-      <i class="ic-x" aria-hidden="true"></i>
+    <i class="ic-lucide-search" aria-hidden="true"></i>
+    <input class="ipt" type="search" id="member-filter" name="q" />
+    <button class="btn icon ghost p-xs" type="button" aria-label="Clear search">
+      <i class="ic-lucide-x" aria-hidden="true"></i>
     </button>
   </div>
 </div>
 ```
 
-The slot works the same way for a text affix — a URL host, a currency symbol, a unit — not just an icon:
+The clear button above is a real `<button>` with an accessible name. A button inside a group keeps its own classes: a `.btn.ghost` has no fill and, like every button by default, no border, so it sits inside the field's border without drawing one of its own.
+
+## Toggles
+
+The settings screen has three kinds of toggle: a checkbox to opt into invoice emails, radio buttons to choose a billing period, and a switch to make the profile public. Each class goes on a native `<input>` of the matching type:
 
 ```html
-<div class="input-group">
-  <span>example.com/</span>
-  <input class="ipt" type="text" />
-</div>
+<fieldset class="stack tight">
+  <legend class="label">Notifications</legend>
+  <label class="cluster tight">
+    <input class="checkbox" type="checkbox" name="invoice-email" checked />
+    Email me when an invoice is ready
+  </label>
+</fieldset>
+
+<fieldset class="stack tight">
+  <legend class="label">Billing period</legend>
+  <label class="cluster tight">
+    <input class="radio" type="radio" name="period" value="monthly" />
+    Monthly
+  </label>
+  <label class="cluster tight">
+    <input class="radio" type="radio" name="period" value="yearly" checked />
+    Yearly, two months free
+  </label>
+</fieldset>
+
+<label class="cluster tight">
+  <input class="switch primary" type="checkbox" role="switch" name="public-profile" />
+  Public profile
+</label>
 ```
 
-The gap between the control and its adornment is `--input-group-gap`, `0.5rem` by default: the right amount of breathing room for a distinct icon glyph, and too much for text meant to read as glued to the value — `example.com/` followed by a gap reads as a stray space breaking the path apart. Set `--input-group-gap: 0` on the group for a flush affix; icon compositions keep the default unchanged.
+- `.checkbox` goes on `type="checkbox"`, `.radio` on `type="radio"`, and `.switch` on `type="checkbox"`. Give a switch `role="switch"` yourself, so it is announced as on or off rather than checked.
+- `.cluster.tight` on the `<label>` lines the control up with its text and leaves a 0.5rem gap.
+- A checkbox whose `indeterminate` property is set, for a group where only some items are checked, shows a dash, and keeps the dash while also `checked`, as the browser's own checkbox does. Set it from script (`input.indeterminate = true`); there is no attribute for it.
 
-## Toggles
+### Checked and unchecked colors
 
-`.checkbox`, `.radio`, and `.switch` accept the same intent classes as buttons to set the checked color:
+An intent class sets the checked color. With no intent, a checked toggle is filled with the text color, and the mark is drawn in the page color: a black box with a white check on a light page. Unlike a neutral button, a neutral toggle fills all the way when checked.
 
-| Class                  | Meaning                 |
-| ---------------------- | ----------------------- |
-| `.neutral` _(default)_ | Text color, capped.     |
-| `.primary`             | Primary color.          |
-| `.secondary`           | Secondary/accent color. |
-| `.success`             | Success color.          |
-| `.warning`             | Warning color.          |
-| `.destructive`         | Destructive color.      |
-| `.info`                | Info color.             |
+Presentation changes only the unchecked look. Every toggle rests at `.soft`; once checked, each has one look whatever its presentation:
 
-All three toggles rest at `.soft`. Presentation decides the _unchecked_ plate; checked is pinned to one look regardless of which class is on the element, so a checkbox, a radio, and a switch each have a single "on" identity rather than one per presentation:
+| Toggle           | Unchecked fill | Checked                                        |
+| ---------------- | -------------- | ---------------------------------------------- |
+| `.ghost`         | 0%             | 100% fill, with the mark in the contrast color |
+| `.soft`, default | 12%            | 100% fill, with the mark in the contrast color |
+| `.solid`         | 40%            | 100% fill, with the mark in the contrast color |
 
-| Toggle           | unchecked | checked                                  |
-| ---------------- | --------- | ---------------------------------------- |
-| `.ghost`         | 0%        | 100%, mark in the contrast tone (pinned) |
-| `.soft`, default | 12%       | 100%, mark in the contrast tone (pinned) |
-| `.solid`         | 40%       | 100%, mark in the contrast tone (pinned) |
+A checked checkbox and a checked switch cut their mark out of the filled plate. A checked radio thickens its ring to twice the resting line width, up to 3px, takes the full intent color on it, and shows a dot. The 3px limit keeps the ring from swallowing the dot under an aesthetic with a thick line.
 
-A checked checkbox and a checked switch cut their mark out of that pinned plate. A checked radio thickens its ring to twice the resting line and takes the intent whole on it, and the dot follows the same pinned plate, so `.radio.soft` and `.radio.solid` render the same filled circle once checked — presentation only changes what the radio looks like before it's picked.
+`.checkbox` and `.radio` always draw their border, even with `.edgeless`, because the border is the only thing that shows an unchecked box. `.switch.ghost` keeps its border too, since with no fill and no border nothing would mark the track. These are listed in [Composing](./composing.md#component-axis-reference).
 
-A checkbox whose `indeterminate` property is set -- a group some of whose items are checked -- takes the same pinned plate with a dash for its mark, and keeps the dash while it is also `checked`, as the browser's own checkbox does. The property is set from script (`input.indeterminate = true`); there is no attribute for it.
+An aesthetic that draws its border as an inner shadow, such as `.pixel`, cannot make that shadow wider than the toggle's border width. A 16px checkbox or a 20px switch has no room for a thicker inner ring without covering the mark. This only matters if you set `--ui-shadow-spread` yourself; see [Customizing → Material tokens](./customizing.md#material-tokens).
 
-## Text controls
+## Fill and border on text controls
 
-Text controls also take intent, which colors the resting border and the focus-visible border, and both [presentation](./composing.md#presentation) axes. `.ghost` fills nothing, `.soft` takes `12%`, and `.solid` takes `20%` — quiet enough that typed text still reads on it, and ordered so the louder name draws the stronger tint. None of them touches the line.
+Text controls take intent, which colors the border, the focus ring, and the typed text, the text in the intent's readable tone (`--intent-strong`). They also take both presentation axes. Their fill is capped low, so typed text stays readable:
 
-The boundary is the edge axis's, and it splits the same way. A container's `.edgeless` is floored, so a toolbar cannot leave a field with no mark of where typing goes. `.edgeless` on the control itself is honoured, which is how the borderless field is spelled — it does not meet WCAG 1.4.11 at rest, so it is opt-in and never a default, and the focus ring still shows.
+| On a text control                               | Fill |
+| ----------------------------------------------- | ---- |
+| `.ghost`, default                               | 0%   |
+| Any fill from a container (`.soft` or `.solid`) | 6%   |
+| `.soft` on the control                          | 12%  |
+| `.solid` on the control                         | 20%  |
+
+A container's fill is meant for the surfaces in it, so a field nobody classed takes only a faint 6% of it. Put the class on the field itself for more.
+
+The border works the same way. An `.edgeless` inherited from a container is ignored, so a toolbar cannot leave a field with no visible edge. `.edgeless` written on the control itself is honored: that is how you ask for a borderless field. A borderless field does not meet the WCAG 1.4.11 contrast requirement for a control's boundary, so it is never a default; its focus ring still shows.
 
 ```html
-<input class="ipt success" placeholder="Valid" />
-<input class="ipt ghost edged" placeholder="Outlined" />
-<input class="ipt soft edged" placeholder="Tinted with a border" />
+<input class="ipt success" placeholder="Matches your current password" />
+<input class="ipt soft edged" placeholder="Tinted, with a border" />
 <input class="ipt soft edgeless" placeholder="Sunk into the page" />
 <div class="soft">
-  <input class="ipt" placeholder="Tinted from the container, capped at 6%" />
-</div>
-<div class="edgeless">
-  <input class="ipt" placeholder="Keeps its line; the floor holds" />
+  <input class="ipt" placeholder="A container's .soft gives a 6% tint" />
 </div>
 ```
 
-`.surface` is a public low-level utility. It is the box every container in the package composes: ghost, edged, surface radius, and the two slots only a surface resolves — the backdrop filter and the complete surface shadow. Use it to paint a container the package does not ship, under whichever aesthetic is in scope. Prefer `.card` or `.panel` when they fit.
+At rest, a field's border is deliberately lighter than 3:1 against the page, so hover and focus have a visible change to make. [Accessibility → Control boundaries](../accessibility.md#control-boundaries) explains the trade-off and how to get a stronger border.
 
-```html
-<div class="surface glass">Blurred, translucent, glass corners</div>
-<div class="surface pixel">Cut corners and an inset ring</div>
-<div class="surface primary solid">Any intent, any presentation</div>
-```
+## Disabled controls
 
-`.text-control` is a public low-level utility from the form entrypoint. It provides the shared control dimensions, border, placeholder, focus-visible, invalid, and disabled styles composed by `ipt`, `textarea`, and `select`. Use it for custom text-like controls; prefer those higher-level utilities when they fit.
+`disabled`, `aria-disabled="true"`, `data-disabled`, or `.disabled` on a control draws it at reduced opacity with a not-allowed cursor. As with buttons, only the `disabled` attribute stops input; the others change the look only.
 
-## Example
+## Building your own control
 
-```html
-<div class="field">
-  <label class="label" for="email">Email</label>
-  <input class="ipt" type="email" id="email" aria-invalid="true" aria-describedby="email-error" />
-  <span class="hint destructive" id="email-error">Enter a valid email.</span>
-</div>
-<label style="display: flex; gap: 0.5rem; align-items: center">
-  <input type="checkbox" class="checkbox success" />
-  <span>Accept terms</span>
-</label>
-<label style="display: flex; gap: 0.5rem; align-items: center">
-  <input type="radio" class="radio secondary" name="plan" />
-  <span>Standard plan</span>
-</label>
-<label style="display: flex; gap: 0.5rem; align-items: center">
-  <input type="checkbox" class="switch destructive" role="switch" />
-  <span>Enable</span>
-</label>
-```
+For a text-like control the package does not ship, `.text-control` gives an element the same border, placeholder, hover, focus, invalid, and disabled styles as `.ipt`, without its height or padding. [Customizing → Composition helpers](./customizing.md#composition-helpers) explains it with the other building blocks.
+
+## Next
 
-Keep a hint or error message outside the `<label>` and point `aria-describedby` at it, so it is announced as a description rather than read as part of the field's name. Give a `.switch` `role="switch"`. Use labels, `type`, validation logic, `aria-describedby`, and error message relationships; see [Accessibility](../accessibility.md).
+The form can be filled in and submitted. [Feedback](./feedback.md) shows what the screen does next: a Save button that says it is saving, a success message, a plan badge, and a storage usage bar.

package/docs/usage/index.md

@@ -1,24 +1,32 @@
 ---
 title: Overview
-description: Guides for composing axes, theming, customizing, aesthetics, and each component family.
+description: The guides that finish the settings screen, then the lookup pages for every class, token, and default.
 group: Usage
-order: 3
+order: 4
 ---
 
 # Usage
 
-These guides assume the [Concepts](../concepts.md) mental model: intent, presentation, and aesthetic as three independent axes, resolved through tokens a component reads.
+These guides finish the settings screen started in [Building a screen](../concepts.md). Read the first seven in order: each one adds a part of the screen and assumes the ones before it. The next three are lookup pages; you will be sent to them when a guide needs the full table, and you can come back whenever you need a default or a rule. The last page, Presets, is for when the screen works and you are tired of typing the same classes.
 
-- [Composing](./composing.md): Combining the three axes on a component, the axis-support matrix, and elevation modifiers.
-- [Theming](./theming.md): The color, intent, and foundation token reference.
-- [Customizing](./customizing.md): The presentation and material token reference, aesthetic knobs, and defining a custom intent.
-- [Aesthetics](./aesthetics.md): Each shipped aesthetic in depth, including its documented exceptions.
-- [Buttons](./buttons.md)
-- [Forms](./forms.md)
-- [Feedback](./feedback.md)
-- [Tooltips](./tooltips.md)
-- [Content and layout](./content-and-layout.md): Layout helpers, tables, quotes, code, surfaces, and typography utilities.
+Guides, in order:
 
-## Supported surface
+1. [Buttons](./buttons.md): the danger zone's destructive action, icon buttons, sizes, link buttons, and disabled states, plus how to load icons.
+2. [Forms](./forms.md): the profile form, with labels, hints, validation errors, an input with an icon or a fixed prefix, a select, and checkbox, radio, and switch toggles.
+3. [Feedback](./feedback.md): what the screen shows while saving and after: a loading button, a success alert, a plan badge, a loading placeholder, and a storage usage bar.
+4. [Tooltips](./tooltips.md): help text beside a form field, how to wire it for keyboard and screen reader users, and where a tooltip can be cut off.
+5. [Theming](./theming.md): light and dark mode, replacing the palette with brand colors, and defining an intent of your own, with the full color and foundation token tables.
+6. [Aesthetics](./aesthetics.md): the six optional looks, what each one changes, and its limits.
+7. [Solo classes](./solo.md): painting an aesthetic onto a component from another library.
 
-A class, component, and axis combination is supported when this documentation describes it and the package playground demonstrates it. Undocumented and undemonstrated combinations may still produce CSS, but are not maintained behavior. Playground variant matrices are the exhaustive demonstrations; small examples elsewhere illustrate usage without widening that contract.
+Lookup pages:
+
+- [Composing](./composing.md): the complete rules for combining intent, presentation, and elevation, every component's defaults, and which axes each component reads.
+- [Customizing](./customizing.md): presentation and material tokens, aesthetic knobs, the six public component variables, the generated palette, and the composition helpers for building your own components.
+- [Content and layout](./content-and-layout.md): every layout helper, the type scale, cards and panels, tables, quotes, code, and keyboard keys.
+
+Once the screen works:
+
+- [Presets](./presets.md): set a look once, with axis classes on a container, theme and material tokens, or your own component classes built with `@apply`.
+
+When you finish, [Accessibility](../accessibility.md) collects what the CSS does for you and what your application still owes its users.

package/docs/usage/presets.md

@@ -0,0 +1,91 @@
+---
+title: Presets
+description: Three ways to set a look once instead of on every element, and when to reach for each.
+order: 11
+---
+
+# Presets
+
+By now the settings screen says `btn primary soft sm` in a dozen places, and changing your mind means changing a dozen places. This page covers the three ways to set a look once: axis classes on a container, theme and material tokens, and your own component classes built with `@apply`. Each fits a different kind of "once".
+
+## Which one to use
+
+| You want                                                              | Reach for                                                   |
+| --------------------------------------------------------------------- | ----------------------------------------------------------- |
+| Every component in one region to share a fill, an edge, or a material | [Axis classes on a container](#axis-classes-on-a-container) |
+| Different colors, corners, borders, or depth for a page or a region   | [Theme and material tokens](#theme-and-material-tokens)     |
+| One name for a recipe you repeat, such as "the save button"           | [Your own component classes](#your-own-component-classes)   |
+
+They combine. A region can set a material token, sit under an aesthetic, and hold your own button class, and each element can still override what it inherits.
+
+## Axis classes on a container
+
+Some classes work on a container as well as on a component, and everything inside takes them:
+
+- The presentation classes: `.solid`, `.soft`, `.ghost`, `.edged`, and `.edgeless`.
+- The corner patterns: `.cut-diagonal` and `.cut-diagonal-reverse`.
+- The [aesthetics](./aesthetics.md), such as `.glass` or `.pixel`.
+
+```html
+<div class="cluster soft edged">
+  <button class="btn primary" type="button">Bold</button>
+  <button class="btn" type="button">Italic</button>
+  <button class="btn destructive solid" type="button">Clear formatting</button>
+</div>
+```
+
+The toolbar's buttons are soft and edged, and the last one asks for its own fill. A class on the element always beats one from a container.
+
+The other axes do not pass down. Intent, elevation (`.flat`, `.raised`, `.floating`), and size (`.sm`, `.lg`) change only the element they are on, so a `.sm` toolbar does not shrink its buttons; [Composing → Combining classes](./composing.md#combining-classes) explains why. An aesthetic class also sets its own corner pattern on its region, so a `.cut-diagonal` above a `.pixel` region does not reach inside it.
+
+Use a container class when the look belongs to the region, such as a quiet sidebar, rather than to the components in it.
+
+## Theme and material tokens
+
+Tokens are CSS custom properties. Set one on `:root` and the whole page follows; set it on an element and only what is inside follows. They reach further than classes, because components read them while they draw:
+
+```css
+.admin {
+  --radius-control: 0.25rem;
+  --radius-surface: 0.5rem;
+  --border-width: 2px;
+}
+```
+
+Every button, field, tooltip bubble, and surface inside `.admin` takes the tighter corners and the heavier border, with no class on any of them. Checkboxes, `.kbd`, and `.code` keep their own smaller corner, `--radius-small`.
+
+The tables live where the tokens are explained, so this page does not repeat them:
+
+- [Theming → Color tokens](./theming.md#color-tokens): brand and status colors, in both themes.
+- [Theming → Foundation tokens](./theming.md#foundation-tokens): corners, border width, control height, focus ring, depth, and motion.
+- [Customizing → Presentation tokens](./customizing.md#presentation-tokens): how much a fill, an edge, or a hover gives.
+- [Customizing → Material tokens](./customizing.md#material-tokens): what an aesthetic sets, which you can set yourself, such as `--ui-radius`.
+- [Customizing → Aesthetic tokens](./customizing.md#aesthetic-tokens): the knobs of each aesthetic, such as `--neo-offset`.
+
+Use tokens when the change is a value, such as a color or a corner, rather than a choice between classes.
+
+## Your own component classes
+
+With the Tailwind source entrypoints, every component, helper, and axis class is a Tailwind utility, so one class of yours can carry the whole recipe:
+
+```css
+@import "@codenhub/styles/tw";
+
+@utility btn-save {
+  @apply btn primary soft sm;
+}
+```
+
+```html
+<button class="btn-save" type="submit">Save changes</button>
+```
+
+`btn-save` behaves like `btn primary soft sm` written out, aesthetics and hover included, and changing the recipe changes every save button. Modifiers that belong to one component, such as `.tight` on `.stack` or `.icon` on `.btn`, are utilities too, so `@apply btn icon` gives you an icon button of your own. [Tailwind CSS v4 → Build your own components with `@apply`](../integrating/tailwind.md#build-your-own-components-with-apply) has the rules, including why `@utility` beats a plain rule.
+
+With the compiled CSS there is no `@apply`. Keep the recipe in one place on the other side instead: a template partial, a component in your framework, or a constant such as `const saveButton = "btn primary soft sm"`.
+
+Use your own class when the same combination names one thing in your design, such as the save button or the plan card.
+
+## Next
+
+[Accessibility](../accessibility.md) lists what the CSS does for your users and what your application still owes them.