@codenhub/styles 0.6.0 → 0.8.0

package/docs/usage/solo.md

@@ -0,0 +1,85 @@
+---
+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. Chunky tile's heavier label follows the same rule.
+- **It leaves a container's motion alone.** Only an action takes the press's `transition`, and the press moves the element through the `translate` and `scale` properties, not `transform`. A toast keeps its own transitions and its own `transform`. On an action, the press's `transition` replaces any the element had.
+- **Reduced motion keeps the press and drops its motion.** Under `prefers-reduced-motion: reduce`, neobrutalism, chunky tile, and cyber still press, but at once: the element lands in its shadow or bar, or shrinks, without travelling there.
+
+## 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.

package/docs/usage/theming.md

@@ -1,153 +1,308 @@
 ---
 title: Theming
-description: The color, intent, and foundation token reference.
-order: 2
+description: Light and dark mode, replacing the palette with brand colors, defining an intent of your own, and every color, intent, foundation, and font token with its default.
+order: 5
 ---
 
 # Theming
 
-Color tokens are how you restyle the palette; see [Concepts → Theme selection](../concepts.md#theme-selection) for how a theme is chosen. Intent tokens are how a component reads that palette once an intent class is applied. Foundation tokens are the shared layout, shape, and motion defaults underneath everything.
+The settings screen works and looks like the package's defaults: near-black actions on a near-white page. This page makes it yours. It covers light and dark mode, then replaces the primary color with a brand color in both modes, then defines an intent the package does not ship. The second half is the lookup reference: every color, intent, foundation, and font token, with its default.
 
-## Color tokens
+## Light and dark
 
-Each color token holds both of its theme values at once through `light-dark()`, and the element's `color-scheme` picks one.
+Out of the box, the page follows the operating system: light when the user's system is light, dark when it is dark. You do nothing for that.
 
-Every row is an override point: set it on `:root` to retheme globally, or on any element to retheme that subtree. The `-hover`, `-subtle`, `-strong`, and `-contrast` rows are companion tones wired into the intent slots, so overriding a base color such as `--color-primary` on its own does not shift its companions — retheme the whole family. The `text` family has no `-subtle` row: the neutral intent draws its subtle tone from `--color-surface`.
+To let the user choose, put a theme selector on the root element:
 
 ```html
-<section data-theme="dark">
-  <article>Dark token subtree</article>
-</section>
+<html data-theme="dark">
+  …
+</html>
 ```
 
-| Token                          | Purpose                                                                                                           |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `--color-primary`              | Primary action/content color.                                                                                     |
-| `--color-primary-contrast`     | Text/icon color on primary filled surface.                                                                        |
-| `--color-primary-hover`        | Primary hover state.                                                                                              |
-| `--color-primary-subtle`       | Low-emphasis companion tone for primary. Use as soft surface or subtle background.                                |
-| `--color-primary-strong`       | High-emphasis companion tone for primary. Use as readable text, icon, or border on subtle surfaces.               |
-| `--color-accent`               | Secondary/accent surface.                                                                                         |
-| `--color-accent-contrast`      | Text/icon color on accent filled surface.                                                                         |
-| `--color-accent-hover`         | Accent hover state.                                                                                               |
-| `--color-accent-subtle`        | Low-emphasis companion tone for accent. Use as soft surface or subtle background.                                 |
-| `--color-accent-strong`        | High-emphasis companion tone for accent. Use as readable text, icon, or border on subtle surfaces.                |
-| `--color-border`               | Default border color.                                                                                             |
-| `--color-border-hover`         | Interactive border color.                                                                                         |
-| `--color-control-border`       | Resting line on the six text controls; one value, drawn at a fraction on text inputs.                             |
-| `--color-background`           | Page and default raised surface background.                                                                       |
-| `--color-foreground`           | Subtle raised foreground surface.                                                                                 |
-| `--color-surface`              | Nested or muted surface.                                                                                          |
-| `--color-text`                 | Primary text color.                                                                                               |
-| `--color-text-secondary`       | Secondary text color.                                                                                             |
-| `--color-text-contrast`        | Readable color on top of a full fill of `--color-text`. A checked toggle prints it.                               |
-| `--color-text-hover`           | Text hover state.                                                                                                 |
-| `--color-text-strong`          | High-emphasis companion tone for text. Use as readable text, icon, or border on subtle surfaces.                  |
-| `--color-tooltip`              | Tooltip bubble plate with no intent. Chosen per theme rather than derived: near-white in light, mid grey in dark. |
-| `--color-tooltip-contrast`     | Ink on `--color-tooltip`.                                                                                         |
-| `--color-success`              | Success state color.                                                                                              |
-| `--color-success-contrast`     | Text/icon color on success filled surface. Meets 4.5:1 as normal text on `--color-success` (5.14:1).              |
-| `--color-success-hover`        | Success hover tone.                                                                                               |
-| `--color-success-subtle`       | Low-emphasis companion tone for success.                                                                          |
-| `--color-success-strong`       | High-emphasis companion tone for success.                                                                         |
-| `--color-warning`              | Warning state color.                                                                                              |
-| `--color-warning-contrast`     | The near-black tone, not the page tone. Meets 4.5:1 as normal text on `--color-warning` (6.19:1).                 |
-| `--color-warning-hover`        | Warning hover tone.                                                                                               |
-| `--color-warning-subtle`       | Low-emphasis companion tone for warning.                                                                          |
-| `--color-warning-strong`       | High-emphasis companion tone for warning.                                                                         |
-| `--color-destructive`          | Destructive/error state color.                                                                                    |
-| `--color-destructive-contrast` | Text/icon color on destructive filled surface. Meets 4.5:1 as normal text on `--color-destructive` (5.78:1).      |
-| `--color-destructive-hover`    | Destructive hover tone.                                                                                           |
-| `--color-destructive-subtle`   | Low-emphasis companion tone for destructive.                                                                      |
-| `--color-destructive-strong`   | High-emphasis companion tone for destructive.                                                                     |
-| `--color-info`                 | Informational state color.                                                                                        |
-| `--color-info-contrast`        | Text/icon color on info filled surface. Meets 4.5:1 as normal text on `--color-info` (6.19:1).                    |
-| `--color-info-hover`           | Info hover tone.                                                                                                  |
-| `--color-info-subtle`          | Low-emphasis companion tone for info.                                                                             |
-| `--color-info-strong`          | High-emphasis companion tone for info.                                                                            |
-
-> **Intent token contract**: color intent tokens own meaning and tone variants. Intent classes map one family onto the shared intent slots below, and presentation classes decide how much of it a component shows. Theme changes belong in token values, not broad component-level theme checks. Component-level theme handling should exist only when a component has an internal structure that cannot be expressed through the token palette alone.
+| Theme | Equivalent selectors                             |
+| ----- | ------------------------------------------------ |
+| Light | `.light`, `.theme-light`, `[data-theme="light"]` |
+| Dark  | `.dark`, `.theme-dark`, `[data-theme="dark"]`    |
 
-## Intent tokens
+A settings screen with a "System / Light / Dark" choice removes the attribute for System and sets it for the other two.
+
+How it resolves:
+
+- A theme selector sets the CSS `color-scheme` property, and the element's text color to `--color-text`. Every color token holds its light and its dark value at once, through `light-dark()`, and the element's `color-scheme` picks one.
+- `color-scheme` inherits, so a selector themes everything inside it. A selector on any element themes that part of the page: a dark sidebar on a light page is `<aside class="dark">`, and the text inside it takes the dark theme's text color.
+- A selector sets no background. Give the region its ground yourself, such as `background: var(--color-background)`. Any utility or component class on the same element overrides the selector's text color.
+- The nearest selector wins, at any depth. A `.light` card inside a `.dark` page is light.
+- With no selector, the root has `color-scheme: light dark`, which follows the system.
+- Put one theme on an element. If an element carries both a light and a dark selector, dark wins, but do not rely on that.
+- Setting `color-scheme` yourself on an element themes the tokens the same way, because it is the only thing the palette reads. It also themes native parts such as scrollbars and the inside of form controls. Plain text inside keeps the color it inherited until you also set `color: var(--color-text)`.
+
+Every component color comes from a token or from `currentColor`, so components follow the theme with no dark-mode rules of their own. The marks the package draws, such as the checkbox tick and the select arrow, use `currentColor` too. Icons and images you add are yours to theme.
 
-Intent classes set these seven slots; components read them. Because every supporting component reads the same seven names, an intent works on every component that supports intent, and a custom intent needs no component changes.
+`light-dark()` works from Chrome 123, Safari 17.5, and Firefox 120. The package as a whole needs Firefox 128; see [Setup → Requirements](../setup.md#requirements).
 
-| Token               | Purpose                                                                                                                                                                                                                                |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--intent-color`    | The intent's base color. What a fill is made of.                                                                                                                                                                                       |
-| `--intent-contrast` | Readable color on top of a filled `--intent-color`.                                                                                                                                                                                    |
-| `--intent-hover`    | The intent's hovered base color.                                                                                                                                                                                                       |
-| `--intent-strong`   | The intent printed on a page. Text, icon, or border wherever the fill is not full.                                                                                                                                                     |
-| `--intent-subtle`   | Low-emphasis tone. Tinted surfaces and tracks. Neutral resolves to `--color-surface`.                                                                                                                                                  |
-| `--intent-border`   | Line color. With no intent it resolves to the aesthetic's `--ui-ink`, then `--color-border`; text controls and toggles read `--ui-control-ink`, then `--ui-ink`, then `--color-control-border`, and tables read `--ui-rule-ink` first. |
-| `--intent-fill-max` | How far a fill of this intent is allowed to go. `100%` for every intent but neutral.                                                                                                                                                   |
+### Printing
 
-`--intent-color` and `--intent-strong` are two ends of the same family and not interchangeable. The base is a ground, chosen to be filled with; the strong tone is chosen to be read against a page. A `.soft` or `.ghost` component prints the strong one, which is why an unfilled warning reads in amber-800 rather than the amber-600 its solid sibling is filled with.
+A page prints in the light theme, whatever theme it shows on screen. Under `@media print`, the root and every dark selector set `color-scheme: light`, so every token resolves to its light value, a forced-dark sidebar's included. Paper is light, and dark text on it costs less ink than a printed dark page.
 
-The strong tone has to stay recognisably its own hue, not just readable. On a dark page the `-100` shade of every family is a pale tint that carries almost no chroma at small sizes: a soft success badge and a soft destructive one printed labels that both read white, and a soft radio's dot stopped matching the ring around it. The dark tones are `-300` for that reason, and the tinted grounds under them are `-900` so there is room — measured at 5.0:1 or better everywhere a partial fill prints text, and past 9:1 on the page.
+Filled components print their background. A browser drops backgrounds from a printed page by default, which leaves a solid button's contrast text on nothing, so every component sets `print-color-adjust: exact`. The property inherits, so the content inside a component keeps its colors too.
 
-`--intent-border` exists because a neutral border must stay the quiet border gray rather than the text color. Everything that draws a line reads it: control borders, table rules, dividers, key caps, and quote bars.
+One limit: a `dark:` utility still applies in print. It matches by selector, not by `color-scheme`, so `<html class="dark">` with `dark:bg-black` on an element prints that background black. Write a `print:` utility beside it if the printed page matters.
+
+### The `dark:` variant
+
+With the Tailwind source entrypoints (`/tw`), the package replaces Tailwind's `dark:` variant so your own utilities follow the same theme as the tokens. A `dark:` utility applies under an explicit dark selector on the element or an ancestor, or under a dark system preference when no ancestor sets a theme:
+
+```html
+<html>
+  <body>
+    <p class="dark:text-white">Follows the system preference</p>
+    <div class="light">
+      <p class="dark:text-white">Stays light: this part of the page chose a theme</p>
+    </div>
+  </body>
+</html>
+```
 
-`--intent-fill-max` exists for the neutral intent, whose color is the page's own ink. Every other intent is a hue, legible pale at 12% and saturated at 100%; a grey filled to 100% is a black or white slab, which is the loudest thing on the page and the wrong look for the intent that means _nothing in particular_. Neutral stops at `20%`, so `.solid` gives it a quiet plate that still reads as a step past `.soft`. Hover adds its step on top of the cap, so a capped fill still deepens under the pointer.
+It differs from the tokens in one case: an explicit theme nested inside the opposite one. A `.light` element inside a `.dark` one has light tokens, because the nearest `color-scheme` wins. But `dark:` matches by selector, and `.dark *` matches every element inside `.dark`, so a `dark:` utility inside that `.light` element still applies. If a page uses both tokens and `dark:` utilities, do not nest opposite themes.
 
-The foreground is gated by the plate rather than tied to the fill. `--intent-contrast` is the ink for a _full_ fill, so printing it at full strength on a fifth of one puts white on light grey. Contrast ink therefore appears only once the fill is past halfway and reaches full at a full fill; below that a component prints `--intent-strong`, the tone chosen to be read.
+The compiled entrypoints do not define a `dark:` variant; they have no Tailwind build to define it in.
 
-So a capped neutral takes the strong tone whole rather than a fraction of the way toward the page. A state that lifts the cap on purpose — a checked checkbox is filled with its own intent by definition — reaches a full fill and gets the contrast whole.
+## Change the brand color
 
-Set them directly to define an intent this package does not ship. **State every slot**, including `--intent-fill-max`: components reset all seven to the neutral values, so a slot your intent leaves out keeps neutral's — and an intent that omits the cap fills to 20% of its color instead of 100%.
+The primary color is near-black on a light page and near-white on a dark one. To make it a brand color, replace the whole primary family: the base color and its four companions. Each holds a light and a dark value:
 
 ```css
-.brand {
-  --intent-color: var(--color-violet-600);
-  --intent-contrast: var(--color-neutral-50);
-  --intent-hover: var(--color-violet-700);
-  --intent-strong: var(--color-violet-800);
-  --intent-subtle: var(--color-violet-100);
-  --intent-border: var(--color-violet-600);
+:root {
+  --color-primary: light-dark(#0f766e, #2dd4bf);
+  --color-primary-contrast: light-dark(#ffffff, #042f2e);
+  --color-primary-hover: light-dark(#115e59, #5eead4);
+  --color-primary-subtle: light-dark(#ccfbf1, #134e4a);
+  --color-primary-strong: light-dark(#115e59, #5eead4);
+}
+```
+
+What each one is for:
+
+| Token                      | Role                                                                   | Check                                          |
+| -------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------- |
+| `--color-primary`          | The fill of a solid primary button, a checked toggle, a progress fill. | Text in `-contrast` on it reaches 4.5:1.       |
+| `--color-primary-contrast` | Text and icons on a full primary fill.                                 | See above.                                     |
+| `--color-primary-hover`    | The fill under the pointer.                                            | Text in `-contrast` on it still reaches 4.5:1. |
+| `--color-primary-subtle`   | The light tint behind soft components.                                 | Text in `-strong` on it reaches 4.5:1.         |
+| `--color-primary-strong`   | Text, icons, and borders where the fill is not full: soft and ghost.   | Reaches 4.5:1 on the page and on `-subtle`.    |
+
+The teal values above measure, in light and dark mode: 5.47:1 and 7.77:1 for the fill and its text, 7.27:1 and 13.38:1 for the strong tone on the page, and 6.73:1 and 6.41:1 for the strong tone on the subtle tint.
+
+Replace the whole family. Changing only `--color-primary` leaves its companions on the old near-black, so a soft primary badge keeps gray text and a hovered button flashes black. The focus ring is drawn from `--color-primary` at 64% opacity, so it follows the brand color without a change of its own.
+
+The same pattern works for every family in [Color tokens](#color-tokens): `--color-accent` is what `.secondary` reads, and the four status families are `success`, `warning`, `destructive`, and `info`. Set them on `:root` for the whole page, or on any element to retheme only what is inside it.
+
+The values must be complete colors: hex, `rgb()`, `oklch()`, or a variable you declared yourself. Tailwind palette variables such as `--color-teal-700` exist in a `/tw` build, from your Tailwind theme, but the compiled CSS declares only the palette colors the package itself uses. With compiled CSS, a reference to any other palette variable is empty, and the color it feeds is lost.
+
+With `/tw`, you can drop the Tailwind hues your design does not use, so `bg-red-500` and its siblings stop being classes. Keep the ones the theme reads, `neutral`, `emerald`, `amber`, `rose`, `indigo`, and `white`: cleared, the colors built from them are lost without an error. [Tailwind CSS v4 → Drop Tailwind's palette](../integrating/tailwind.md#drop-tailwinds-palette) has the block to copy.
+
+## Your own intent
+
+The package ships six intents: `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, and `.info`, and the default, `.neutral`. To add one, such as a "Beta" color for features in preview, write a class that sets the seven intent slots. Use complete colors, with `light-dark()` for anything that changes between themes:
+
+```css
+.beta {
+  --intent-color: #7c3aed;
+  --intent-contrast: #ffffff;
+  --intent-hover: #6d28d9;
+  --intent-strong: light-dark(#5b21b6, #c4b5fd);
+  --intent-subtle: light-dark(#ede9fe, #4c1d95);
+  --intent-border: light-dark(#7c3aed, #a78bfa);
   --intent-fill-max: 100%;
 }
 ```
 
 ```html
-<button class="btn brand">Custom intent</button> <span class="badge brand soft">Works everywhere</span>
+<span class="badge beta">Beta</span> <button class="btn beta" type="button">Try the new editor</button>
 ```
 
-> **Intent does not cascade.** Components reset these slots to the text palette at their own root, so a `.success` container never recolors a nested destructive button. Put the intent class on the element that shows the intent.
+These values measure 5.7:1 for white on the fill, 7.1:1 for white on the hover color, 8.61:1 (light) and 10.72:1 (dark) for the strong tone on the page, and 7.57:1 and 5.93:1 for the strong tone on the subtle tint.
+
+**Set every slot**, including `--intent-fill-max`. Each component resets all seven slots to the neutral values at its own root, so a slot you leave out keeps neutral's value, and without `--intent-fill-max: 100%` your intent fills only to 20%, like neutral. What each slot does is in [Intent tokens](#intent-tokens).
+
+The class works on everything that takes an intent: buttons, badges, fields and toggles, solid and ghost cards, progress bars, skeletons, tooltip bubbles, and the rest. A few behaviors are written for the six built-in names, and a custom intent does not get them:
+
+- **A quiet, untinted rest.** A neutral `.card.soft`, `.panel`, and `.alert` rest on the quiet background tone, and they recognize an intent only by the six built-in classes. `.card.soft.beta`, `.panel.beta`, and `.alert.beta` are drawn like the neutral one: the quiet background tone instead of a violet tint. Your intent still colors their text and border.
+- **The chip tint.** A `.beta` key cap or code block shows your `--intent-subtle` tint, but not the extra 12% of `--intent-color` a built-in intent adds over it.
+- **Solo classes.** A [solo class](./solo.md) such as `.neobrutalism-solo` takes an intent only from the six built-in classes, so `.neobrutalism-solo.beta` is drawn neutral.
+- **Hint text.** A [`.hint`](./forms.md#show-a-validation-error) prints in an intent's readable tone only for the six built-in classes, so `.hint.beta` stays secondary-colored.
+- **Table rows.** A body row recolors its text, line, and hover only for the built-in intent classes. `<tr class="beta">` looks like the rest of its table.
+
+If you need those, there are two ways:
+
+- **Retheme a built-in intent instead.** Set the `--color-info` family (or another one) to your colors, as in [Change the brand color](#change-the-brand-color), and write `.info`. Everything, including the cases above, then works. The cost is that the change reaches every `.info` inside the element you set it on, so set it on the narrowest element that works, and do not do it with an intent the page already uses for its own meaning.
+- **Paint it yourself.** Write your own CSS for that one component, such as a `background-color` on `.panel.beta`.
+
+> **Intent does not pass down.** Each component resets the intent slots at its own root, so a `.success` container does not recolor a destructive button inside it. Put the intent class on the element that shows the color.
+
+## Color tokens
+
+Every color token holds a light and a dark value through `light-dark()`; one value means both themes use it. Palette names such as `neutral-950` are Tailwind's default palette, which the package's compiled CSS declares for the colors it uses.
+
+Each row is an override point: set it on `:root` to retheme the page, or on any element to retheme what is inside it. The `-hover`, `-subtle`, `-strong`, and `-contrast` rows are companions of their family's base color and do not follow it, so retheme the whole family. The `text` family has no `-subtle` row: the neutral intent takes its subtle tone from `--color-surface`.
+
+| Token                          | Light, dark                  | Purpose                                                                                        |
+| ------------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| `--color-primary`              | `neutral-950`, `neutral-50`  | Fill of `.primary`.                                                                            |
+| `--color-primary-contrast`     | `neutral-50`, `neutral-950`  | Text and icons on a full primary fill.                                                         |
+| `--color-primary-hover`        | `neutral-700`, `neutral-200` | Primary fill under the pointer.                                                                |
+| `--color-primary-subtle`       | `neutral-200`, `neutral-900` | Primary tint behind soft components.                                                           |
+| `--color-primary-strong`       | `neutral-900`, `neutral-100` | Primary text, icons, and borders where the fill is not full.                                   |
+| `--color-accent`               | `neutral-600`, `neutral-400` | Fill of `.secondary`.                                                                          |
+| `--color-accent-contrast`      | `neutral-50`, `neutral-950`  | Text and icons on a full secondary fill.                                                       |
+| `--color-accent-hover`         | `neutral-700`, `neutral-300` | Secondary fill under the pointer.                                                              |
+| `--color-accent-subtle`        | `neutral-100`, `neutral-800` | Secondary tint behind soft components.                                                         |
+| `--color-accent-strong`        | `neutral-800`, `neutral-200` | Secondary text, icons, and borders where the fill is not full.                                 |
+| `--color-border`               | `neutral-400`, `neutral-700` | Border of neutral surfaces, tables, dividers, and key caps.                                    |
+| `--color-border-hover`         | `neutral-600`, `neutral-500` | Border under the pointer.                                                                      |
+| `--color-control-border`       | `neutral-500`                | Resting border of neutral text controls and toggles, drawn at a fraction on text controls.     |
+| `--color-background`           | `neutral-50`, `neutral-950`  | The page.                                                                                      |
+| `--color-foreground`           | `neutral-100`, `neutral-900` | The quiet background tone one step off the page: neutral soft cards, panels, and alerts.       |
+| `--color-surface`              | `neutral-200`, `neutral-800` | A further step: nested and muted surfaces, and the neutral intent's tint.                      |
+| `--color-text`                 | `neutral-950`, `neutral-50`  | Body text, and the neutral intent's color.                                                     |
+| `--color-text-secondary`       | `neutral-700`, `neutral-400` | Secondary text, such as `.hint`.                                                               |
+| `--color-text-contrast`        | `neutral-50`, `neutral-950`  | Text on a full fill of `--color-text`, such as the mark of a checked neutral toggle.           |
+| `--color-text-hover`           | `neutral-700`, `neutral-200` | Neutral color under the pointer.                                                               |
+| `--color-text-strong`          | `neutral-900`, `neutral-100` | Neutral text, icons, and borders where the fill is not full.                                   |
+| `--color-tooltip`              | `white`, `neutral-700`       | Background of a tooltip bubble with no intent. Chosen per theme so it reads as lifted in both. |
+| `--color-tooltip-contrast`     | `neutral-900`, `neutral-100` | Text on `--color-tooltip`.                                                                     |
+| `--color-success`              | `emerald-700`                | Fill of `.success`.                                                                            |
+| `--color-success-contrast`     | `neutral-50`                 | Text on a full success fill: 5.14:1.                                                           |
+| `--color-success-hover`        | `#007552`, `#008e66`         | Success fill under the pointer.                                                                |
+| `--color-success-subtle`       | `emerald-100`, `emerald-900` | Success tint behind soft components.                                                           |
+| `--color-success-strong`       | `emerald-800`, `emerald-300` | Success text, icons, and borders where the fill is not full.                                   |
+| `--color-warning`              | `amber-600`                  | Fill of `.warning`.                                                                            |
+| `--color-warning-contrast`     | `neutral-950`                | Text on a full warning fill: near-black, not the page color. 6.19:1.                           |
+| `--color-warning-hover`        | `#d46700`, `#e78300`         | Warning fill under the pointer.                                                                |
+| `--color-warning-subtle`       | `amber-100`, `amber-900`     | Warning tint behind soft components.                                                           |
+| `--color-warning-strong`       | `amber-800`, `amber-300`     | Warning text, icons, and borders where the fill is not full.                                   |
+| `--color-destructive`          | `rose-700`                   | Fill of `.destructive`.                                                                        |
+| `--color-destructive-contrast` | `neutral-50`                 | Text on a full destructive fill: 5.78:1.                                                       |
+| `--color-destructive-hover`    | `#c00036`, `#d1054b`         | Destructive fill under the pointer.                                                            |
+| `--color-destructive-subtle`   | `rose-100`, `rose-900`       | Destructive tint behind soft components.                                                       |
+| `--color-destructive-strong`   | `rose-800`, `rose-300`       | Destructive text, icons, and borders where the fill is not full.                               |
+| `--color-info`                 | `indigo-600`                 | Fill of `.info`.                                                                               |
+| `--color-info-contrast`        | `neutral-50`                 | Text on a full info fill: 6.19:1.                                                              |
+| `--color-info-hover`           | `#4b36e9`, `#5e4ff9`         | Info fill under the pointer.                                                                   |
+| `--color-info-subtle`          | `indigo-100`, `indigo-900`   | Info tint behind soft components.                                                              |
+| `--color-info-strong`          | `indigo-800`, `indigo-300`   | Info text, icons, and borders where the fill is not full.                                      |
+
+Theme changes belong in these values, not in component rules that check the theme.
+
+## Intent tokens
+
+An intent class sets these seven slots, and components read them. Because every component reads the same seven names, a class that sets all seven works as an intent, as [Your own intent](#your-own-intent) shows.
+
+| Token               | Purpose                                                                                                                                                                                                                       |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--intent-color`    | The intent's base color, what a fill is made of.                                                                                                                                                                              |
+| `--intent-contrast` | Text on a full fill of `--intent-color`.                                                                                                                                                                                      |
+| `--intent-hover`    | The base color under the pointer.                                                                                                                                                                                             |
+| `--intent-strong`   | The intent as text, icon, or border wherever the fill is not full.                                                                                                                                                            |
+| `--intent-subtle`   | The light tint behind soft components and progress tracks. Neutral uses `--color-surface`.                                                                                                                                    |
+| `--intent-border`   | Line color. With no intent it is the aesthetic's `--ui-ink`, then `--color-border`; text controls and toggles read `--ui-control-ink`, then `--ui-ink`, then `--color-control-border`, and tables read `--ui-rule-ink` first. |
+| `--intent-fill-max` | How far a fill of this intent may go. `100%` for every intent except neutral.                                                                                                                                                 |
+
+`--intent-color` and `--intent-strong` are not interchangeable. The base color is chosen to be filled with; the strong tone is chosen to be read against the page. A soft or ghost component prints the strong tone, which is why a soft warning reads in amber-800 while a solid one is filled with amber-600.
+
+The strong tone also has to stay recognizably its own hue. On a dark page, the `-100` shade of every family is a pale tint with almost no color at small sizes: a soft success badge and a soft destructive one would both read as white. The dark strong tones are `-300` for that reason, and the tints under them are `-900`, which measures 5.0:1 or better wherever a partial fill holds text, and over 9:1 on the page.
+
+`--intent-border` exists so a neutral border stays the quiet border gray rather than the text color. Everything that draws a line reads it: control borders, table rules, dividers, key caps, and quote bars.
+
+`--intent-fill-max` exists for the neutral intent, whose color is the page's own text color. Every other intent is a hue, readable as a pale tint at 12% and saturated at 100%; a gray filled to 100% is a black or white block, the loudest thing on the page for the intent that means nothing in particular. Neutral stops at `20%`, so `.solid` gives it a quiet gray that is still a step past `.soft`. Hover adds its step on top of the cap, so a capped fill still deepens under the pointer.
+
+The text color follows the fill. `--intent-contrast` is the text color for a full fill; printed on a fifth of one, it would be white on light gray. So contrast text appears only once the fill is past halfway, and reaches full strength at a full fill; below that, a component prints `--intent-strong`. A capped neutral therefore prints the strong tone. A state that lifts the cap on purpose, such as a checked checkbox, reaches a full fill and prints the contrast color.
 
 ## Foundation tokens
 
-Foundation tokens are not aliases for one color. They define layout, shape, motion, focus, depth, and layering behavior used by helper classes.
-
-The four `--elevation-*` values below are raw shadows for elements you style yourself. They are a separate thing from `.flat`/`.raised`/`.floating`, which scale a _component's own_ shadow geometry and default to no shadow at all until an aesthetic or one of those classes asks for depth — see [Composing → Elevation](./composing.md#elevation) for that system. The two share `none`/`sm`/`md`/`lg` naming for the same weight of depth, but one is a fixed value and the other multiplies shadow parts, so they will not always paint identically.
-
-| Token                      | Purpose                                                                                                                                     |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--font-default`           | Default app font family.                                                                                                                    |
-| `--container-narrow`       | Narrow content width.                                                                                                                       |
-| `--container-max`          | Default content width.                                                                                                                      |
-| `--container-wide`         | Wide content width.                                                                                                                         |
-| `--layout-gutter`          | Responsive inline page padding.                                                                                                             |
-| `--layout-section-block`   | Responsive section vertical padding.                                                                                                        |
-| `--layout-gap`             | Shared gap for `.view`, `.stack`, `.cluster`, and `.auto-grid`.                                                                             |
-| `--layout-grid-min`        | Minimum column width for `.auto-grid`.                                                                                                      |
-| `--radius-small`           | Small radius for compact utility surfaces such as code elements.                                                                            |
-| `--radius-control`         | Radius for buttons, inputs, tooltips, and compact UI.                                                                                       |
-| `--radius-surface`         | Radius for cards, panels, and alerts.                                                                                                       |
-| `--control-height`         | Default minimum height for controls.                                                                                                        |
-| `--border-width`           | Default border width.                                                                                                                       |
-| `--elevation-color`        | Shadow color the four elevations compose from. Heavier in dark themes.                                                                      |
-| `--elevation-none`         | No shadow. Use on an element that should read as flat against its page.                                                                     |
-| `--elevation-sm`           | A light shadow for your own surface-level elements, such as cards.                                                                          |
-| `--elevation-md`           | A shadow for your own raised elements, such as dropdowns and popovers.                                                                      |
-| `--elevation-lg`           | A shadow for your own full overlays, such as modal dialogs.                                                                                 |
-| `--focus-ring`             | Focus-visible ring color.                                                                                                                   |
-| `--focus-ring-offset`      | Focus-visible outline offset. Unset: the negative of the focused element's line width, so the ring lands on the edge under every aesthetic. |
-| `--focus-ring-width`       | Focus-visible outline/ring width.                                                                                                           |
-| `--motion-duration-fast`   | Fast transition for a table row's hover (`120ms`).                                                                                          |
-| `--motion-duration-normal` | Every component's colour, border, shadow, and press transitions, toggle marks, and the tooltip bubble (`200ms`).                            |
-| `--motion-duration-slow`   | Progress value changes, and the base of the skeleton and progress shimmer cycle (`400ms`).                                                  |
-| `--motion-ease`            | Default easing curve.                                                                                                                       |
-| `--z-popover`              | Popover/tooltip z-index.                                                                                                                    |
-| `--breakpoint-xs`          | Extra-small Tailwind responsive breakpoint.                                                                                                 |
-
-Next: [Customizing](./customizing.md) covers presentation and material tokens — how much of an intent shows, and what a component is made of.
+Foundation tokens set layout, shape, motion, focus, depth, and stacking. Override them on `:root`, or on an element for what is inside it.
+
+The four `--elevation-*` shadows are for elements you style yourself. They are separate from the `.flat`, `.raised`, and `.floating` classes, which scale a component's own shadow and draw nothing until an aesthetic or one of those classes asks for depth; see [Composing → Elevation](./composing.md#elevation). Both use the weights none, small, medium, and large, but one is a fixed value and the other scales shadow parts, so they do not always look the same.
+
+| Token                      | Default                                                | Purpose                                                                                                         |
+| -------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `--font-default`           | `"Segoe UI", system-ui, sans-serif`                    | Page font. See [Fonts](#fonts).                                                                                 |
+| `--container-narrow`       | `48rem`                                                | Width of `.section-content.narrow`.                                                                             |
+| `--container-max`          | `80rem`                                                | Width of `.section-content`.                                                                                    |
+| `--container-wide`         | `90rem`                                                | Width of `.section-content.wide`.                                                                               |
+| `--layout-gutter`          | `clamp(1rem, 4vw, 2rem)`                               | Side padding of `.section`, growing with the window.                                                            |
+| `--layout-section-block`   | `clamp(4rem, 9vw, 7rem)`                               | Top and bottom padding of `.section`, growing with the window.                                                  |
+| `--layout-gap`             | `1rem`                                                 | Gap of `.view`, `.stack`, `.cluster`, and `.auto-grid`.                                                         |
+| `--layout-grid-min`        | `16rem`                                                | Narrowest column of `.auto-grid`.                                                                               |
+| `--radius-small`           | `0.25rem`                                              | Corner of small chips: `.kbd` and `.code`.                                                                      |
+| `--radius-control`         | `0.5rem`                                               | Corner of buttons, fields, and tooltip bubbles.                                                                 |
+| `--radius-surface`         | `0.875rem`                                             | Corner of cards, panels, and alerts.                                                                            |
+| `--control-height`         | `2.5rem`                                               | Minimum height of a default button and a text control.                                                          |
+| `--border-width`           | `1px`                                                  | Border width.                                                                                                   |
+| `--elevation-color`        | `rgb(15 23 42 / 0.08)` light, `rgb(0 0 0 / 0.55)` dark | The shadow color the four elevations use. Heavier on a dark page, where a light shadow would not show.          |
+| `--elevation-none`         | `none`                                                 | No shadow.                                                                                                      |
+| `--elevation-sm`           | `0 1px 2px`, `0 1px 3px`                               | A light shadow for your own surfaces, such as a card.                                                           |
+| `--elevation-md`           | `0 4px 6px -1px`, `0 2px 4px -2px`                     | A shadow for your own raised elements, such as a dropdown menu.                                                 |
+| `--elevation-lg`           | `0 20px 25px -5px`, `0 8px 10px -6px`                  | A shadow for your own overlays, such as a modal dialog.                                                         |
+| `--focus-ring`             | Not set                                                | Color of the keyboard focus ring. When unset, `--color-primary` at 64% opacity, on the focused element.         |
+| `--focus-ring-offset`      | Not set                                                | Distance of the ring from the element. When unset, the ring sits on the element's border under every aesthetic. |
+| `--focus-ring-width`       | `3px`                                                  | Width of the keyboard focus ring.                                                                               |
+| `--motion-duration-fast`   | `120ms`                                                | A table row's hover.                                                                                            |
+| `--motion-duration-normal` | `200ms`                                                | Color, border, shadow, and press transitions, toggle marks, and the tooltip bubble.                             |
+| `--motion-duration-slow`   | `400ms`                                                | Progress value changes, and the base of the skeleton and progress shimmer cycle.                                |
+| `--motion-ease`            | `cubic-bezier(0.2, 0, 0, 1)`                           | Easing for every transition.                                                                                    |
+| `--z-popover`              | `40`                                                   | Stacking order of tooltip bubbles. Use it for your own popovers so they stack the same way.                     |
+| `--breakpoint-xs`          | `30rem`                                                | The `xs:` responsive breakpoint. Only in a `/tw` build; the compiled entrypoints do not declare it.             |
+
+Each `--elevation-*` shadow is made of the listed parts, each in `--elevation-color`. The four shadows are composed once, on the root, so an `--elevation-color` you set on a container does not reach them: set it on `:root`, or set the `--elevation-*` token itself on the container. The elevation classes, such as `.card.raised`, read `--elevation-color` on the element and follow a container's value, with one exception: every aesthetic class sets its own `--elevation-color` on its region. A value set above a `.glass` or `.pixel` region does not reach inside it. Set it on the aesthetic's element itself, where your utility or unlayered CSS beats the class, or on an element inside the region. Under glass, a surface's shadow is built on the `.glass` element, so only a value set there changes it. Under `.neobrutalism` the shadow is drawn in the intent or the ink, and `.cyber` draws no depth, so neither reads the token. The hover step that deepens a fill under the pointer is a presentation token, `--hover-step`; see [Customizing](./customizing.md#presentation-tokens).
+
+## Fonts
+
+The package ships no font files and makes no network requests. Every font token names fonts already installed on the reader's device until you supply your own.
+
+| Token            | Read by                                                                                          | Without your value                                                                                                                              |
+| ---------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--font-default` | The reset, on `html` and `body`, and `.glass` and `.neobrutalism` regions. Controls inherit it.  | `"Segoe UI", system-ui, sans-serif`                                                                                                             |
+| `--font-mono`    | The `kbd`, `code`, and `pre` content helpers, and `<kbd>`, `<code>`, and `<pre>` under `/native` | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace`. Under `/tw`, your Tailwind theme's value. |
+| `--font-pixel`   | [`.pixel`](./aesthetics.md#pixel) and `.pixel-solo`                                              | Not declared. Falls back to a monospace stack.                                                                                                  |
+| `--font-rounded` | [`.chunky-tile`](./aesthetics.md#chunky-tile) and `.chunky-tile-solo`                            | Not declared. Falls back to `--font-default`, then a sans-serif stack.                                                                          |
+| `--font-cyber`   | [`.cyber`](./aesthetics.md#cyber) and `.cyber-solo`                                              | Not declared. Falls back to a monospace stack.                                                                                                  |
+| `--font-sketch`  | [`.sketch`](./aesthetics.md#sketch) and `.sketch-solo`                                           | Not declared. Falls back to the platform `cursive` family.                                                                                      |
+
+`--font-default` reaches the page only through the reset, which `@codenhub/styles`, `/native`, `/tw`, `/tw/native`, and `/tw/reset` include. With `/theme` or `/components` alone, set `font-family` on `body` yourself, and set `--font-default` to the same font: `.glass` and `.neobrutalism` regions set their own `font-family` from the token, so a font set only on `body` does not reach inside them. Or set only the token, and write `font-family: var(--font-default)` on `body`. The aesthetic tokens are read by the aesthetic's own class, so they work with any entrypoint.
+
+To use a web font, load it the way you load any font, then name it in the token. Set the token on `:root` for the whole page, or on any element for that part of it:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400..700&display=swap" />
+```
+
+```css
+:root {
+  --font-default: "Inter", system-ui, sans-serif;
+}
+```
+
+A self-hosted font is declared with `@font-face` and named the same way:
+
+```css
+@font-face {
+  font-family: "Pixelify Sans";
+  src: url("/fonts/pixelify-sans.woff2") format("woff2");
+  font-weight: 400 700;
+  font-display: swap;
+}
+
+:root {
+  --font-pixel: "Pixelify Sans", monospace;
+}
+```
+
+Load weights 400 to 700, and 800 for `--font-rounded`: components set `font-weight` from 400 to 700, and `.chunky-tile` sets its labels in 800. A browser that lacks a weight fakes it by thickening the regular one, which smears a pixel or handwriting face. Always end the stack with a generic family, such as `sans-serif` or `monospace`, so text still renders while the font loads or if it fails to.
+
+## Next
+
+The screen has your colors in both themes. [Aesthetics](./aesthetics.md) changes what it is made of: thick black outlines, frosted glass, pixels, and more.