@codenhub/styles 0.5.0 → 0.7.0

package/docs/usage/forms.md

@@ -1,145 +1,230 @@
 ---
 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. |
-| `.textarea`                                                           | Textarea control styling.                                                |
-| `.select`                                                             | Select control styling.                                                  |
-| `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.                                                        |
+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.
 
-## Icons
+## A labeled field
 
-No icon is shipped for text inputs — that's what this section covers. It used to paint one per input type as a `background-image` — a `data:` URI, which cannot read `currentColor` or a custom property, so every glyph shipped a light and a dark copy and a theme selector chose between them. That put icon artwork, and the package's only theme-by-selector branch, inside a CSS-only design system whose glyphs did not fit every aesthetic. Icons for `.input-group` are the consumer's to choose now.
+A field is a label, a control, and an optional hint, stacked:
 
-This is separate from the toggle marks below, which stay small, fixed, built-in glyphs. `.alert`'s icon followed the same path since — see [Feedback → Icon](./feedback.md#example) — the package no longer paints one there either.
+```html
+<div class="field">
+  <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>`.
 
-`.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`.
+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.
+
+## Show a validation error
+
+Mark the control invalid with `aria-invalid="true"` and give the error message `.hint.destructive`:
 
 ```html
-<label class="field">
-  <span class="label">Email</span>
-  <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" />
+<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.
+
+## 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>
-</label>
-<label class="field">
-  <span class="label">Search</span>
+
+  <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.
+
+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="member-search">Find a member</label>
   <div class="input-group">
-    <input class="ipt" type="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>
-</label>
+</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.
+
+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.
 
-Non-icon input types keep the browser's native `date` and `datetime-local` pickers. WebKit's native `search` decorations are still suppressed on `.text-control` to keep them from overlapping the value.
+The group reads intent and presentation the way a lone `.ipt` does: `.input-group.primary` colors the border, and `.input-group.soft.edgeless` is a field sunk into the page. `aria-invalid="true"` or `disabled` on the control inside applies to the whole group, and so does either on the group itself. The focus ring appears when anything inside the group has focus, so unlike a lone field it also shows after a mouse click.
 
-The slot works the same way for a text affix — a URL host, a currency symbol, a unit — not just an icon:
+## 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="input-group">
-  <span>example.com/</span>
-  <input class="ipt" type="text" />
+<div class="field">
+  <label class="label" for="member-filter">Find a member</label>
+  <div class="input-group unadorned">
+    <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 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.
+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
 
-`.checkbox`, `.radio`, and `.switch` accept the same intent classes as buttons to set the checked color:
+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
+<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>
+```
+
+- `.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.
 
-| 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.             |
+### Checked and unchecked colors
 
-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:
+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.
 
-| 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) |
+Presentation changes only the unchecked look. Every toggle rests at `.soft`; once checked, each has one look whatever its presentation:
 
-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.
+| 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 |
 
-## Text controls
+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.
 
-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.
+`.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).
 
-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.
+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).
+
+## Fill and border on text controls
+
+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:
+
+| 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
-<label class="field">
-  <span class="label">Email</span>
-  <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
-  <span class="hint destructive" id="email-error">Enter a valid email.</span>
-</label>
-<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" />
-  <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
 
-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,28 @@
 ---
 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 last 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.
 
-- [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.
+
+When you finish, [Accessibility](../accessibility.md) collects what the CSS does for you and what your application still owes its users.

package/docs/usage/solo.md

@@ -0,0 +1,83 @@
+---
+title: Solo classes
+description: Painting an aesthetic onto one element from another library, such as a toast or a dialog, and what a solo class reads and ignores.
+order: 7
+---
+
+# Solo classes
+
+Suppose the settings screen shows "Profile saved" in a toast from a notification library, not in this package's alert. Under `.neobrutalism`, every card and button has the thick outline and the hard shadow, and the toast does not: an aesthetic class only sets values that this package's components read, so it changes nothing on an element the package does not style. A solo class paints the aesthetic directly onto the one element that carries it:
+
+```html
+<div class="toast neobrutalism-solo success" role="status">Profile saved.</div>
+```
+
+## The six solo classes
+
+Each aesthetic ships its solo class in the same entrypoint, and a solo class needs nothing else loaded:
+
+```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>
+```
+
+| Aesthetic       | Solo class           | Paints                                                                                                                                                                                                           |
+| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.glass`        | `.glass-solo`        | A translucent background, a thin light edge, the blur, a soft two-layer shadow, and the surface corner. With `.glass-liquid`, the liquid pane, drawn on its `::before` and `::after`.                            |
+| `.neobrutalism` | `.neobrutalism-solo` | A 2px ink edge, square corners, and the hard offset shadow.                                                                                                                                                      |
+| `.pixel`        | `.pixel-solo`        | The stepped outline, the inner ring in place of a border, and the pixel font.                                                                                                                                    |
+| `.chunky-tile`  | `.chunky-tile-solo`  | The tile corner, a 2px edge, the bar under it, and the rounded font.                                                                                                                                             |
+| `.cyber`        | `.cyber-solo`        | The surface diagonal (the control diagonal on a button or link), a 1px edge, the glow, and the font.                                                                                                             |
+| `.sketch`       | `.sketch-solo`       | Uneven elliptical corners (a sharper outline on a pane, a looser one on a button or link, and small rounded ones with `.sketch-rounded`), a 1px solid ink line, the 2px offset shadow, and the handwriting font. |
+
+Do not put a solo class on this package's own components. A `.card` already draws its fill, edge, and intent, and a solo class would paint a second edge and fill over them. Use the aesthetic class there; it also works on a single element: `<button class="btn pixel">`.
+
+## What a solo class reads
+
+A solo element takes the same presentation, intent, and elevation classes a `.card` would:
+
+```html
+<div class="toast pixel-solo edgeless">No ring</div>
+<div class="toast glass-solo solid success">An opaque green pane</div>
+<div class="toast neobrutalism-solo flat">No offset shadow</div>
+
+<section class="soft edged">
+  <div class="toast chunky-tile-solo info">Soft and edged from the container, info from itself</div>
+</section>
+```
+
+| What                                  | Read from                                                                                           |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Fill and edge (`.solid`, `.edged`, …) | The element, or any container: presentation passes down, as it does to components.                  |
+| Intent (`.success`, …)                | The element only, as on components. A `.success` container leaves a solo element inside it neutral. |
+| Elevation (`.flat`, `.raised`, …)     | The element only, as on components. It scales the offset shadow, the bar, and sketch's shadow.      |
+| The aesthetic around it (`.pixel`, …) | Never. See [What a solo class ignores](#what-a-solo-class-ignores).                                 |
+
+With none of those classes, a solo class paints the material alone (edge, corner, depth, outline, blur, font, and press) and leaves the element's own background and text color as they were.
+
+- **Only the six built-in intents.** A solo class takes an intent from `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, and `.info` only. An intent class you defined yourself, as in [Theming → Your own intent](./theming.md#your-own-intent), is not read, and the element is drawn neutral. To give a solo element a custom color, retheme one of the built-in intents on it or a container, as that section describes.
+- **The fill is a layer over the element's own background.** Five of the six paint the fill as an inner shadow and do not set `background`, so a `.soft` solo toast is a tint over whatever the toast already was, and a `.solid` one with a colored intent is opaque. Glass sets its own background, because the translucent background is its material, and mixes the fill over it. A neutral `.solid` is a 20% tint, not the opaque gray a component draws.
+- **The text color assumes the theme.** It is set only where a fill or an intent is asked for, and it is the color the theme uses on the page or on the fill. On an element whose own background does not follow the theme, such as a white toast on a dark page, a `.soft` or `.ghost` intent can put light text on a light background; use `.solid`, or leave the intent off.
+- **There is no hover tint.** A solo element is not known to be clickable, so it does not get the hover color a `.btn` gets.
+- **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 tokens such as `--font-sketch` all work, set on the element or any ancestor. With the theme loaded, it follows the theme; without it, it renders the shipped look.
+- **Dark values need a color scheme.** Light and dark pairs use `light-dark()`, which follows the element's `color-scheme`. The package's theme sets it; a page without the theme gets the light values.
+- **The classes it reads come from the theme.** `.solid`, `.edgeless`, `.success`, `.flat`, and the rest ship in the base stylesheet and in `@codenhub/styles/theme`. With an aesthetic entrypoint alone on the page, those classes do nothing, and the solo class paints its unclassed look.
+
+## What a solo class ignores
+
+- **The aesthetic around it.** It reads none of the values an aesthetic class sets, and not `--elevation-color`. A `.glass-solo` inside a `.pixel` region keeps its own corners, and `--ui-radius` or `--ui-border-width` set on it or above it do nothing. Tune it through its knobs.
+- **Its own children.** A solo element is not an aesthetic region. A component inside it keeps the look of the page around it, even with `.glass-liquid` or `.sketch-rounded` beside the solo class. It passes down only what any container does: the solo class's font, and the fill or edge of a presentation class on it, so a `.card` inside a `.glass-solo.solid` pane is solid, as inside any `.solid` container.
+- **Glass's shadow and `.flat`.** `.flat` does not remove the shadow from `.glass-solo`, as it does not under `.glass`.
+
+## How it wins and when it moves
+
+- **It beats the other library's styles.** The rules are unlayered and one class deep, so they win over a component's layered rules, and over its zero-specificity ones, wherever the two load. An unlayered foreign rule that is more specific, or as specific and later in the page, still wins. The other side of this is that a Tailwind utility on the same element, such as `rounded-none`, loses to the solo class: tune it through its knobs instead.
+- **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. Anything else stays put, so a toast does not sink when clicked. Reduced motion removes the movement. Chunky tile's heavier label follows the same rule.
+
+## Next
+
+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 the CSS does for your users and what your application still owes them.