@codenhub/styles 0.1.0 → 0.2.0

package/llms-full.txt

@@ -12,8 +12,7 @@ pnpm add @codenhub/styles
 
 ## Usage
 
-Import the compiled stylesheet for the complete token, reset, utility, and
-component-class surface:
+Import the compiled stylesheet for the complete token, reset, utility, and component-class surface:
 
 ```css
 @import "@codenhub/styles";
@@ -27,72 +26,17 @@ component-class surface:
 </main>
 ```
 
-Apps using Tailwind CSS v4 can instead process the source entrypoint:
-
-```css
-@import "tailwindcss";
-@import "@codenhub/styles/tw";
-
-@source "./src";
-```
-
-The root follows the system color-scheme preference. Apply `.light` or `.dark`
-to force a theme for the root or a subtree.
-
-```html
-<html class="dark">
-  <body>
-    <button class="btn primary">Dark themed button</button>
-  </body>
-</html>
-```
-
-The aliases `.theme-light`, `.theme-dark`, and `data-theme="light|dark"` are
-also supported. See [Concepts](./docs/concepts.md#theme-selection) for
-precedence details.
-
-`.solid`, `.soft`, and `.ghost` set how much intent fills a component; `.edged`
-and `.edgeless` set whether it draws a boundary. Both axes cascade, so a
-container sets the look below it and any element can still override it.
-`.solid` also takes the boundary away, because a filled box ringed in another
-color is what the blend behind `.edged` exists to prevent; `.solid.edged` is the
-way back to a line.
-
-```html
-<div class="soft">
-  <button class="btn primary">Soft</button>
-  <span class="badge success">Soft</span>
-  <button class="btn primary ghost edged">Outlined</button>
-</div>
-```
-
-Aesthetics decide what a component is made of. They are opt-in, so import the
-stylesheet after the base one to make `.neobrutalism`, `.glass`, `.pixel`, and
-`.chunky-tile` available. They cascade to any subtree the same way, and each is
-also importable on its own from `@codenhub/styles/aesthetics/<name>`.
-
-```css
-@import "@codenhub/styles";
-@import "@codenhub/styles/aesthetics";
-```
-
-```html
-<section class="neobrutalism">
-  <button class="btn primary">Thick ink and a hard shadow</button>
-</section>
-```
+For the Tailwind CSS v4 entrypoint, theme selection, the intent/presentation axes, and opt-in aesthetics, see [Setup](./docs/setup.md), [Concepts](./docs/concepts.md), and [Usage](./docs/usage/index.md).
 
 ## Documentation
 
-- [Documentation overview](./docs/index.md): What the package is, what it
-  does and does not do, and where to go next.
+- [Documentation overview](./docs/index.md): What the package is, what it does and does not do, and where to go next.
 - [Setup](./docs/setup.md): Installation, entrypoints, and configuration.
 - [Concepts](./docs/concepts.md): The three-axis model and the token system.
-- [Usage](./docs/usage/index.md): Composing, theming, customizing,
-  aesthetics, and each component family.
-- [Integrating](./docs/integrating/index.md): Wiring the stylesheet into
-  Next.js, Vue, Svelte, Astro, or a Tailwind CSS v4 build.
+- [Usage](./docs/usage/index.md): Composing, theming, customizing, aesthetics, and each component family.
+- [Integrating](./docs/integrating/index.md): Wiring the stylesheet into Next.js, Vue, Svelte, Astro, or a Tailwind CSS v4 build.
 - [Accessibility](./docs/accessibility.md): CSS accessibility hooks and non-goals.
+- [Changelog](./docs/changelog/index.md): Release history, including breaking changes.
 
 ## Requirements
 
@@ -105,169 +49,166 @@ also importable on its own from `@codenhub/styles/aesthetics/<name>`.
 
 ## Notes
 
-This package has no JavaScript behavior. `--layout-gap` replaces the removed
-`--layout-stack-gap` and `--layout-cluster-gap` tokens; no compatibility aliases
-are provided.
+This package has no JavaScript behavior; no version provides compatibility aliases for a removed class or token. `0.2.0` removes `.btn.loading` (compose a disabled `.btn` with a `.loader` child instead) and `.alert.icon`'s built-in glyph (drop a consumer-supplied icon into `.alert-icon` instead), and `.tooltip` now requires a `.tooltip-bubble` child element rather than a `data-tooltip` attribute. See the [changelog](./docs/changelog/index.md) for the complete history.
 
 ## License
 
-Licensed under Apache-2.0. Embedded SVG icons derived from
-[Lucide](https://lucide.dev) are ISC-licensed, and loaders derived from
-[svg-spinners](https://github.com/n3r4zzurr0/svg-spinners) are MIT-licensed.
-See [NOTICE](NOTICE) for the required notices.
+Licensed under Apache-2.0. Embedded SVG icons derived from [Lucide](https://lucide.dev) are ISC-licensed, and loaders derived from [svg-spinners](https://github.com/n3r4zzurr0/svg-spinners) are MIT-licensed. See [NOTICE](NOTICE) for the required notices.
 
 <!-- Source: docs/index.md -->
 
 # @codenhub/styles
 
-`@codenhub/styles` is a CSS-only design system: tokens, a reset, typography and
-layout utilities, and composable classes for buttons, forms, feedback,
-surfaces, and tooltips. Every component separates three independent choices —
-which color, how much of it, and what it's made of — so changing one never
-requires a component-specific variant. Four optional aesthetics
-(`.neobrutalism`, `.glass`, `.pixel`, `.chunky-tile`) restyle that same
-component set without touching markup.
+`@codenhub/styles` is a CSS-only design system: tokens, a reset, typography and layout utilities, and composable classes for buttons, forms, feedback, surfaces, and tooltips. Every component separates three independent choices — which color, how much of it, and what it's made of — so changing one never requires a component-specific variant. Four optional aesthetics (`.neobrutalism`, `.glass`, `.pixel`, `.chunky-tile`) restyle that same component set without touching markup.
 
-The package ships as ready-to-import compiled CSS, or as Tailwind CSS v4
-source entrypoints for a project that already runs Tailwind. Both cover the
-same classes; the difference is which build processes them.
+The package ships as ready-to-import compiled CSS, or as Tailwind CSS v4 source entrypoints for a project that already runs Tailwind. Both cover the same classes; the difference is which build processes them.
 
 ## What it does
 
-- Publishes color, foundation, intent, presentation, and material design
-  tokens as CSS custom properties, themed with `light-dark()`.
-- Provides a reset, focus-visible handling, and responsive layout/content
-  utilities.
-- Provides composable classes for buttons, form controls and toggles, alerts,
-  badges, loaders, progress, cards/panels, tables, quotes, code, and
-  tooltips.
-- Provides four opt-in aesthetics that restyle the same components by setting
-  material tokens, not by adding component variants.
-- Provides classless mappings so plain HTML elements pick up base styling
-  without added classes, from a dedicated entrypoint.
+- Publishes color, foundation, intent, presentation, and material design tokens as CSS custom properties, themed with `light-dark()`.
+- Provides a reset, focus-visible handling, and responsive layout/content utilities.
+- Provides composable classes for buttons, form controls and toggles, alerts, badges, loaders, progress, cards/panels, tables, quotes, code, and tooltips.
+- Provides four opt-in aesthetics that restyle the same components by setting material tokens, not by adding component variants.
+- Provides classless mappings so plain HTML elements pick up base styling without added classes, from a dedicated entrypoint.
 - Publishes Tailwind CSS v4 source entrypoints alongside the compiled output.
 
 ## What it does not do
 
-- No JavaScript. There is no runtime, no framework bindings, and no build-time
-  code generation beyond the CSS itself.
-- No semantic HTML, ARIA, keyboard behavior, focus management, validation, or
-  announcement timing. See [Accessibility](docs/accessibility.md) for the exact
-  line between what the CSS provides and what an application must still add.
-- No theme-toggling logic. Theme selection is a class or attribute a consumer
-  applies; wiring a toggle to system preference, storage, or a user setting is
-  outside this package. The `@codenhub/theme` package covers that need for
-  consumers who want it.
-- No shipped font binaries. `.pixel` and `.chunky-tile` accept a
-  consumer-supplied font and fall back to a system stack when none is given.
-- No compatibility layer for removed tokens or classes. Breaking changes are
-  documented, not silently aliased.
+- No JavaScript. There is no runtime, no framework bindings, and no build-time code generation beyond the CSS itself.
+- No semantic HTML, ARIA, keyboard behavior, focus management, validation, or announcement timing. See [Accessibility](docs/accessibility.md) for the exact line between what the CSS provides and what an application must still add.
+- No theme-toggling logic. Theme selection is a class or attribute a consumer applies; wiring a toggle to system preference, storage, or a user setting is outside this package. The `@codenhub/theme` package covers that need for consumers who want it.
+- No shipped font binaries. `.pixel` and `.chunky-tile` accept a consumer-supplied font and fall back to a system stack when none is given.
+- No compatibility layer for removed tokens or classes. Breaking changes are documented, not silently aliased.
 
 ## Next steps
 
-- [Setup](docs/setup.md): Install the package, choose an entrypoint, and render a
-  first component.
-- [Concepts](docs/concepts.md): The three-axis model, the token system, and how
-  theme selection works — read this before the usage guides.
-- [Usage](docs/usage/index.md): Guides for composing axes, theming, customizing,
-  aesthetics, and each component family.
-- [Integrating](docs/integrating/index.md): Wiring the stylesheet into Next.js,
-  Vue, Svelte, Astro, or a Tailwind CSS v4 build.
-- [Accessibility](docs/accessibility.md): CSS accessibility hooks and what
-  remains an application responsibility.
+- [Setup](docs/setup.md): Install the package, choose an entrypoint, and render a first component.
+- [Concepts](docs/concepts.md): The three-axis model, the token system, and how theme selection works — read this before the usage guides.
+- [Usage](docs/usage/index.md): Guides for composing axes, theming, customizing, aesthetics, and each component family.
+- [Integrating](docs/integrating/index.md): Wiring the stylesheet into Next.js, Vue, Svelte, Astro, or a Tailwind CSS v4 build.
+- [Accessibility](docs/accessibility.md): CSS accessibility hooks and what remains an application responsibility.
 
-<!-- Source: docs/accessibility.md -->
+<!-- Source: docs/setup.md -->
 
-# Accessibility responsibilities
+# Setup
 
-This package provides CSS hooks for accessible states. It does not provide semantic HTML, ARIA attributes, keyboard behavior, focus management, validation, announcement timing, or JavaScript behavior.
+## Installation
 
-## Provided By CSS
-
-| Feature                 | Behavior                                                                                                                   |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `:focus-visible`        | Global focus-visible outline using `--focus-ring`, `--focus-ring-width`, and `--focus-ring-offset`.                        |
-| Form control focus      | `.ipt`, `.textarea`, and `.select` draw the global focus ring and move their line to the intent color.                     |
-| Control boundaries      | Text controls rest at `--_line-rest` of their intent, under 3:1 by choice; hover and focus take the tone whole.            |
-| Toggle boundaries       | `.checkbox`, `.radio`, and `.switch` draw their line whole, because it is the only thing marking an unchecked box.         |
-| Cascaded `.edgeless`    | Floored on every text control: a container cannot erase the line of a field or toggle nobody classed.                      |
-| Own `.edgeless`         | On the element, `.ipt`, `.textarea`, `.select`, and `.switch` do drop their line and do not meet 1.4.11 at rest.           |
-| `.checkbox`/`.radio`    | Never drop their line, on the element or from a container. `.edgeless` on them is unsupported, not merely discouraged.     |
-| Invalid controls        | `[aria-invalid="true"]` applies destructive border/focus color on form controls.                                           |
-| Disabled controls       | `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]`, and `.disabled` apply disabled cursor/opacity where supported.  |
-| Current page            | `[aria-current="page"]` applies primary color and stronger font weight.                                                    |
-| Open state              | `[data-state="open"]` styles supported surfaces and tooltips.                                                              |
-| Reduced-motion loaders  | Loader variants use animated embedded SVGs normally and static masks when `prefers-reduced-motion: reduce` matches.        |
-| Reduced-motion document | The reset additionally shortens document animations and transitions when `prefers-reduced-motion: reduce` matches.         |
-| Reduced transparency    | `.glass` drops its blur and becomes an opaque surface when `prefers-reduced-transparency: reduce` matches.                 |
-| Filled labels           | Every intent's `.solid` label meets 1.4.3 (4.5:1) as normal text, in both themes. Lowest is success at 5.14:1.             |
-| Warning ink             | `--color-warning-contrast` is the near-black tone, not the page tone. Amber dark enough to carry white is not amber.       |
-| Partial fills           | Contrast ink appears only past a half fill, so a capped plate keeps `--intent-strong` rather than walking toward the page. |
-| Intent hue in dark      | `--intent-strong` is the `-300` shade in dark, so a soft or ghost label keeps its own hue instead of reading white.        |
-| Toggle marks            | A checked mark meets 3:1 as a state indicator on every plate its fill class can paint, in both themes.                     |
-| Forced colors           | `forced-colors: active` preserves visible borders and checked states using system colors.                                  |
-| Text direction          | Quote bar, alert icon, progress fill, vertical divider, and switch knob mirror under `dir="rtl"`. No class needed.         |
-
-The loader fallback is embedded in loader CSS, so focused imports that include
-loaders honor reduced motion without the reset. This includes
-`@codenhub/styles/components`, `@codenhub/styles/tw/components`,
-`@codenhub/styles/tw/button`, and `@codenhub/styles/tw/loader`. The complete and
-native entrypoints include both that fallback and the reset's broader animation
-and transition shortening.
-
-In forced colors, class-based form controls including `.text-control` receive a
-2px `Highlight` system-color focus outline. The native entrypoint provides the
-same visible system outline for unclassed text inputs, selects, textareas,
-checkboxes, and radios.
-
-Custom checkboxes and radios use the system `Canvas`, `CanvasText`, `Highlight`,
-and `HighlightText` colors in forced-colors mode so checked and unchecked states
-remain distinct. Shape, size, and spacing remain unchanged.
-
-## Required Outside CSS
+```sh
+pnpm add @codenhub/styles
+```
 
-Use semantic HTML and behavior appropriate for the component.
+## Quick start
 
-| UI                | Required outside CSS                                                                                            |
-| ----------------- | --------------------------------------------------------------------------------------------------------------- |
-| Buttons           | Use `<button>` for actions or accessible links for navigation. Add accessible names for `.btn.icon`.            |
-| Forms             | Use labels, `type`, validation logic, `aria-describedby`, and error message relationships.                      |
-| Alerts            | Add `role="status"` or `role="alert"` based on announcement urgency.                                            |
-| Toasts            | Add live-region behavior, dismissal behavior, focus rules, and pause/timeout logic when needed.                 |
-| Tooltips          | Provide accessible names/descriptions. CSS pseudo-element content is not enough for all assistive tech.         |
-| Progress          | Use semantic progress elements or ARIA values when numeric progress must be announced.                          |
-| Skeletons/loaders | Mark decorative loading visuals with `aria-hidden="true"` and expose loading state elsewhere when needed.       |
-| Popovers/modals   | Provide focus trapping, escape handling, inert background behavior, labels, and roles outside this CSS package. |
+Import the compiled stylesheet for the complete token, reset, utility, and component-class surface, then compose helper classes in markup:
 
-## State Attribute Guidance
+```css
+@import "@codenhub/styles";
+```
 
-Prefer native attributes first:
+```html
+<main class="stack">
+  <p class="text-label">Status</p>
+  <h1 class="text-title">Ready to publish</h1>
+  <button class="btn primary">Continue</button>
+</main>
+```
+
+The full stylesheet applies global reset and focus-visible rules, but does not apply the optional classless native-element mappings, and does not include aesthetics. Import focused entrypoints when global rules are not appropriate; see [Import paths](#import-paths) below.
+
+Aesthetics are opt-in. Import the combined aesthetics stylesheet, or one aesthetic on its own, after the base stylesheet so its rules win:
+
+```css
+@import "@codenhub/styles";
+@import "@codenhub/styles/aesthetics";
+```
 
 ```html
-<button class="btn primary" disabled>Saving</button>
-<input class="ipt" aria-invalid="true" aria-describedby="email-error" />
+<section class="neobrutalism">
+  <button class="btn primary">Thick ink and a hard shadow</button>
+</section>
 ```
 
-Use ARIA or data attributes when native attributes are not available for the element or library:
+A project already running Tailwind CSS v4 imports the source entrypoint instead; see [Integrating → Tailwind CSS v4](docs/integrating/tailwind.md).
+
+## Configuration
+
+The root follows the operating-system color-scheme preference. Apply `.light` or `.dark` to the root or any ancestor to force token values for that subtree. `.theme-light`, `.theme-dark`, and `data-theme="light|dark"` are aliases.
 
 ```html
-<a class="btn secondary" aria-disabled="true">Unavailable</a>
-<button class="tooltip tooltip-icon" data-state="open" data-tooltip="More details" aria-label="More details">?</button>
+<html class="dark">
+  <body>
+    <button class="btn primary">Dark themed button</button>
+  </body>
+</html>
 ```
 
-`aria-disabled="true"` communicates disabled state but does not prevent activation. JavaScript or element choice must prevent activation when required.
+See [Concepts → Theme selection](docs/concepts.md#theme-selection) for how selectors resolve and [Usage → Theming](docs/usage/theming.md) for the full color token reference.
+
+### Dark variant
+
+`/tw` source entrypoints define a custom `dark:` variant for your own utilities. It fires under an explicit dark selector (`.dark`, `.theme-dark`, or `[data-theme="dark"]`, on the element or an ancestor), or under the system preference when nothing under it forces a theme explicitly:
+
+```html
+<html>
+  <body>
+    <p class="dark:text-white">Follows the OS preference here</p>
+    <div class="light">
+      <p class="dark:text-white">Stays light -- this subtree forced it</p>
+    </div>
+  </body>
+</html>
+```
+
+An explicit selector at any depth wins over the system preference, in either direction, the same as the token theme it tracks.
+
+The one place it does not track the token theme: nesting an explicit selector inside the opposite one. `color-scheme` inherits, so a `.light` nested inside `.dark` themes its own tokens correctly regardless of depth -- the nearest declaration always wins. `dark:` matches by selector instead, and `.dark *` matches every descendant of a `.dark` element with no way to stop at a nearer `.light` in between, so a `dark:` utility inside that nested `.light` still fires even though the tokens around it are light. Apply one theme per subtree rather than nesting opposite ones if a page uses both tokens and `dark:` utilities together.
+
+## Import paths
+
+Compiled entrypoints are ready-to-import CSS and require only tooling that can resolve package CSS imports. `/tw` entrypoints publish copied, uncompiled source from `dist/tw`; a Tailwind v4 build must still process their `@theme`, `@utility`, `@apply`, and related directives. Focused source component entrypoints include theme tokens so their classes can work independently.
+
+| Import path                      | Composition and effects                                                                                                                                                                                           |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@codenhub/styles`               | Compiled complete surface: Tailwind base/theme output, tokens, typography, utilities, components, and reset. Applies global reset, root theme, and focus rules.                                                   |
+| `@codenhub/styles/theme`         | Compiled Tailwind theme variables, Codenhub tokens, and the presentation classes. Sets root theme properties and system/explicit theme selectors; no reset or component classes.                                  |
+| `@codenhub/styles/components`    | Compiled theme tokens, typography utilities, and every component class. Includes static reduced-motion loader masks; no reset, layout/content utilities, or native mappings.                                      |
+| `@codenhub/styles/native`        | Compiled complete surface plus classless mappings for headings, text, content elements, form controls, and buttons. Applies the reset and broad element selectors.                                                |
+| `@codenhub/styles/aesthetics`    | Compiled `.neobrutalism`, `.glass`, `.pixel`, and `.chunky-tile` classes. Adds no tokens or components of its own; import after the base stylesheet.                                                              |
+| `@codenhub/styles/aesthetics/*`  | One compiled aesthetic: `/neobrutalism`, `/glass`, `/pixel`, or `/chunky-tile`. Same rules and ordering as the combined file.                                                                                     |
+| `@codenhub/styles/tw`            | Source equivalent of the complete stylesheet. Imports Tailwind itself, theme, typography, utilities, components, and reset; applies the same global rules.                                                        |
+| `@codenhub/styles/tw/theme`      | Source theme, tokens, and presentation classes. Imports Tailwind's theme layer; emits root/system/explicit theme selectors and defines the package's custom `dark:` variant.                                      |
+| `@codenhub/styles/tw/components` | Published Tailwind source for theme, typography, buttons, feedback, forms, loaders, surfaces, and tooltips, including static reduced-motion loader masks. No reset, layout/content utilities, or native mappings. |
+| `@codenhub/styles/tw/surface`    | Source theme plus `.surface`, `.card`, and `.panel`.                                                                                                                                                              |
+| `@codenhub/styles/tw/button`     | Published Tailwind source for theme and `.btn`. Pair it with `/tw/loader` for a loading state composed from `.loader`.                                                                                            |
+| `@codenhub/styles/tw/form`       | Source theme plus field, public `text-control`, input, textarea, select, checkbox, radio, and switch utilities.                                                                                                   |
+| `@codenhub/styles/tw/feedback`   | Source theme plus alert, badge, skeleton, and progress utilities and their keyframes.                                                                                                                             |
+| `@codenhub/styles/tw/loader`     | Published Tailwind source for activity indicators and loaders, including static reduced-motion masks. It has no theme or reset side effects and uses `currentColor`.                                              |
+| `@codenhub/styles/tw/tooltip`    | Source theme plus tooltip utilities.                                                                                                                                                                              |
+| `@codenhub/styles/tw/reset`      | Source theme, typography utilities, and global reset/accessibility rules. It changes root/body/elements and selection, motion, focus, scrollbar, and forced colors.                                               |
+| `@codenhub/styles/tw/native`     | Source complete surface plus reset and classless native-element mappings; broadest global effects.                                                                                                                |
+| `@codenhub/styles/tw/typography` | Source theme plus typography utilities; sets theme selectors but no reset or classless mappings.                                                                                                                  |
+| `@codenhub/styles/tw/utilities`  | Source theme and typography composition plus layout and content utilities; safelists the package utility names.                                                                                                   |
+| `@codenhub/styles/tw/aesthetics` | Source aesthetics, combined. `/tw/aesthetics/neobrutalism`, `/glass`, `/pixel`, and `/chunky-tile` publish one apiece. Plain CSS with no theme or reset side effects.                                             |
+
+Avoid importing overlapping entrypoints in the same build unless duplicate generated CSS is acceptable; pick the narrowest entrypoint that covers what a page needs.
+
+## Requirements
+
+- Consumer tooling must resolve package CSS imports.
+- Chrome 123, Safari 17.5, or Firefox 121 and newer. Color tokens are declared with `light-dark()` and selected by `color-scheme` (Firefox 120), and `.input-group` propagates a nested control's invalid and disabled state with `:has()` (Firefox 121).
+- Tailwind CSS 4 or newer is required only for `/tw` source entrypoints.
+- The package has no JavaScript runtime. Apps must provide semantic HTML, ARIA, keyboard behavior, focus management, validation, and announcements; see [Accessibility](docs/accessibility.md).
 
 <!-- Source: docs/concepts.md -->
 
 # Concepts
 
-Read this before the usage guides. It explains the mental model every
-component, token, and class in this package shares.
+Read this before the usage guides. It explains the mental model every component, token, and class in this package shares.
 
 ## The three axes
 
-Every component separates three independent choices, so each can change
-without a component-specific variant:
+Every component separates three independent choices, so each can change without a component-specific variant:
 
 | Axis         | Question        | Classes                                                                                   | Inheritance  |
 | ------------ | --------------- | ----------------------------------------------------------------------------------------- | ------------ |
@@ -282,25 +223,16 @@ without a component-specific variant:
 </section>
 ```
 
-Intent stays on the component so a semantic container cannot accidentally
-recolor nested controls. Presentation and aesthetic cascade from a container;
-putting either class directly on a component overrides the inherited choice.
-Components apply documented clamps when an axis would remove an essential edge
-or overwhelm compact geometry.
+Intent stays on the component so a semantic container cannot accidentally recolor nested controls. Presentation and aesthetic cascade from a container; putting either class directly on a component overrides the inherited choice. Components apply documented clamps when an axis would remove an essential edge or overwhelm compact geometry.
 
-The maintained contract is the intersection of the combinations documented in
-[Usage](docs/usage/index.md) and demonstrated by the playground. Undocumented and
-undemonstrated combinations may produce CSS but are not supported behavior.
+The maintained contract is the intersection of the combinations documented in [Usage](docs/usage/index.md) and demonstrated by the playground. Undocumented and undemonstrated combinations may produce CSS but are not supported behavior.
 
-- [Usage → Composing](docs/usage/composing.md) shows how the three axes combine
-  on each component, with the full axis-support matrix.
-- [Usage → Aesthetics](docs/usage/aesthetics.md) covers each aesthetic and its
-  documented exceptions in depth.
+- [Usage → Composing](docs/usage/composing.md) shows how the three axes combine on each component, with the full axis-support matrix.
+- [Usage → Aesthetics](docs/usage/aesthetics.md) covers each aesthetic and its documented exceptions in depth.
 
 ## The token system
 
-Tokens are CSS custom properties, grouped by what they control rather than
-where they're used:
+Tokens are CSS custom properties, grouped by what they control rather than where they're used:
 
 | Category     | Controls                                                                                    | Reference                                                         |
 | ------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
@@ -311,369 +243,501 @@ where they're used:
 | Material     | What a component is made of — radius, border width, shadow geometry, translucency.          | [Usage → Customizing](docs/usage/customizing.md#material-tokens)     |
 | Aesthetic    | Per-aesthetic knobs such as `--pixel-unit` or `--tile-lift`.                                | [Usage → Customizing](docs/usage/customizing.md#aesthetic-tokens)    |
 
-Color and foundation tokens are the ones most apps touch first, to match a
-brand palette or spacing scale. Intent, presentation, and material tokens are
-lower-level: components read them, and only presentation classes, aesthetic
-classes, or a consumer override should set them.
+Color and foundation tokens are the ones most apps touch first, to match a brand palette or spacing scale. Intent, presentation, and material tokens are lower-level: components read them, and only presentation classes, aesthetic classes, or a consumer override should set them.
 
 ## Theme selection
 
-The root follows the operating-system `color-scheme` preference until an
-explicit selector overrides it.
+The root follows the operating-system `color-scheme` preference until an explicit selector overrides it.
 
 | Theme | Equivalent selectors                             |
 | ----- | ------------------------------------------------ |
 | Light | `.light`, `.theme-light`, `[data-theme="light"]` |
 | Dark  | `.dark`, `.theme-dark`, `[data-theme="dark"]`    |
 
-- Theme selectors set `color-scheme` and nothing else. Because `color-scheme`
-  inherits, a selector themes its entire subtree.
-- With no explicit selector, `:root` uses `color-scheme: light dark`, so the
-  system preference decides.
-- A theme selector on `:root` overrides the system preference in either
-  direction.
-- A nested explicit selector overrides an inherited theme, so the nearest
-  themed ancestor controls that subtree at any depth.
-- If conflicting light and dark selectors are placed on the same element, the
-  dark declaration wins because it appears later with equal specificity. Do
-  not rely on this conflict behavior; apply one theme per element.
-- Component colors resolve from tokens or `currentColor`, so they follow the
-  theme without separate dark-variant rules, with no exception: every glyph
-  the package draws is a `currentColor` mask. Icon artwork a consumer brings
-  is theirs to theme.
-
-Setting `color-scheme` yourself on an element also re-themes the tokens below
-it, because that is the only signal the palette reads. This also themes native
-UI such as scrollbars and form-control internals to match.
-
-This mechanism works from Chrome 123, Safari 17.5, and Firefox 120; the package
-overall requires Firefox 121 for `:has()` (see [Setup](docs/setup.md#requirements)).
+- Theme selectors set `color-scheme` and nothing else. Because `color-scheme` inherits, a selector themes its entire subtree.
+- With no explicit selector, `:root` uses `color-scheme: light dark`, so the system preference decides.
+- A theme selector on `:root` overrides the system preference in either direction.
+- A nested explicit selector overrides an inherited theme, so the nearest themed ancestor controls that subtree at any depth.
+- If conflicting light and dark selectors are placed on the same element, the dark declaration wins because it appears later with equal specificity. Do not rely on this conflict behavior; apply one theme per element.
+- Component colors resolve from tokens or `currentColor`, so they follow the theme without separate dark-variant rules, with no exception: every glyph the package draws is a `currentColor` mask. Icon artwork a consumer brings is theirs to theme.
+- The Tailwind source entrypoints' `dark:` variant tracks this rule for the explicit-selector-versus-system-preference choice: it fires under an explicit dark selector, or under the system preference when the subtree carries no explicit selector at all. It does not track the previous rule the same way: that one holds because `color-scheme` inherits, so the nearest declaration always wins regardless of depth, while `dark:` matches by selector -- `.dark *` matches every descendant of a `.dark` element, with no way to stop at a nearer `.light` in between. A `.light` subtree nested inside `.dark` themes its tokens correctly but still matches `dark:`'s explicit arm. See [Setup → Dark variant](docs/setup.md#dark-variant).
 
-<!-- Source: docs/integrating/astro.md -->
+Setting `color-scheme` yourself on an element also re-themes the tokens below it, because that is the only signal the palette reads. This also themes native UI such as scrollbars and form-control internals to match.
 
-# Astro
+This mechanism works from Chrome 123, Safari 17.5, and Firefox 120; the package overall requires Firefox 121 for `:has()` (see [Setup](docs/setup.md#requirements)).
 
-Import the package from a shared layout's frontmatter so every page that
-uses that layout loads it once:
+<!-- Source: docs/usage/index.md -->
 
-```astro
----
-// src/layouts/Layout.astro
-import "@codenhub/styles";
----
+# Usage
 
-<html lang="en">
-  <body>
-    <slot />
-  </body>
-</html>
-```
+These guides assume the [Concepts](docs/concepts.md) mental model: intent, presentation, and aesthetic as three independent axes, resolved through tokens a component reads.
 
-Apply `.dark` or `.light` on `<html>` to force a theme instead of following
-the system preference; see [Setup → Configuration](docs/setup.md#configuration).
+- [Composing](docs/usage/composing.md): Combining the three axes on a component, the axis-support matrix, and elevation modifiers.
+- [Theming](docs/usage/theming.md): The color, intent, and foundation token reference.
+- [Customizing](docs/usage/customizing.md): The presentation and material token reference, aesthetic knobs, and defining a custom intent.
+- [Aesthetics](docs/usage/aesthetics.md): Each shipped aesthetic in depth, including its documented exceptions.
+- [Buttons](docs/usage/buttons.md)
+- [Forms](docs/usage/forms.md)
+- [Feedback](docs/usage/feedback.md)
+- [Tooltips](docs/usage/tooltips.md)
+- [Content and layout](docs/usage/content-and-layout.md): Layout helpers, tables, quotes, code, surfaces, and typography utilities.
 
-A project running Tailwind CSS v4 imports `@codenhub/styles/tw` through
-Astro's Tailwind integration instead; see [Tailwind CSS v4](docs/integrating/tailwind.md)
-for the `@source` directive Astro needs to scan `src/`.
+## Supported surface
 
-<!-- Source: docs/integrating/index.md -->
+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.
 
-# Integrating
+<!-- Source: docs/usage/composing.md -->
 
-This package has no JavaScript and no framework bindings; see
-[Introduction](docs/index.md#what-it-does-not-do). Integrating it into a
-framework is entirely about where that framework loads a global stylesheet,
-and whether the project runs Tailwind CSS v4.
+# Composing the three axes
 
-Every stack does the same two things:
+See [Concepts](docs/concepts.md#the-three-axes) for what each axis means. This page covers how they combine in markup, what the presentation classes mean in depth, which components support which axis, and elevation.
 
-1. Import one [entrypoint](docs/setup.md#import-paths) — the compiled
-   `@codenhub/styles` for any build, or `@codenhub/styles/tw` when the
-   project already runs Tailwind CSS v4 — from wherever that framework loads
-   global CSS.
-2. Import `@codenhub/styles/aesthetics` (or `/tw/aesthetics`) after it, only
-   if the project uses an [aesthetic](docs/usage/aesthetics.md).
+## Combining axes
 
-| Stack                                    | Guide                            |
-| ---------------------------------------- | -------------------------------- |
-| A Tailwind CSS v4 project on any bundler | [Tailwind CSS v4](docs/integrating/tailwind.md) |
-| Next.js / React                          | [Next.js](docs/integrating/nextjs.md)           |
-| Vue                                      | [Vue](docs/integrating/vue.md)                  |
-| Svelte / SvelteKit                       | [Svelte](docs/integrating/svelte.md)            |
-| Astro                                    | [Astro](docs/integrating/astro.md)              |
+```html
+<div class="soft">
+  <button class="btn primary">Soft primary button</button>
+  <span class="badge success">Soft success badge</span>
+  <button class="btn primary ghost edged">Outlined; the element wins</button>
+</div>
+```
 
-A project with no framework — a plain Vite, webpack, or Parcel build — needs
-nothing beyond [Setup](docs/setup.md#quick-start): import the compiled
-stylesheet from the project's existing global CSS entry.
+A declaration on the element always beats one inherited from a container, so a container sets the default look for its subtree and any element opts out.
 
-<!-- Source: docs/integrating/nextjs.md -->
+Intent classes do not cascade. `.primary` and its siblings stay on the element that shows the intent, because a container silently recoloring every descendant is a trap rather than a feature — see [Theming → Intent tokens](docs/usage/theming.md#intent-tokens). Use `.neutral` to opt an element back out of an inherited intent context. Presentation and [material tokens](docs/usage/customizing.md#material-tokens) do cascade, so a container can set the look of its whole subtree while any element overrides it.
 
-# Next.js
+## Presentation
 
-Next.js only allows global CSS to be imported from one place. Import the
-package from the root layout in the App Router, or from the custom App in
-the Pages Router — not from a page or component further down the tree.
+Presentation has two independent axes. `.solid`, `.soft`, and `.ghost` decide how much intent fills a component; `.edged` and `.edgeless` decide whether it draws a boundary. They set [presentation tokens](docs/usage/customizing.md#presentation-tokens) and nothing else, so they work on the component itself or on any ancestor.
 
-```tsx
-// app/layout.tsx
-import "@codenhub/styles";
+| Class       | Look                                                       |
+| ----------- | ---------------------------------------------------------- |
+| `.solid`    | Intent-colored fill with contrast text.                    |
+| `.soft`     | Lightly tinted fill with intent-colored text.              |
+| `.ghost`    | No fill at rest, with intent-colored text.                 |
+| `.edged`    | Intent-colored boundary at the aesthetic's material width. |
+| `.edgeless` | No boundary.                                               |
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  );
-}
-```
+Values each class ships:
 
-```tsx
-// pages/_app.tsx
-import "@codenhub/styles";
-import type { AppProps } from "next/app";
+| Class       | `--ui-fill` | `--ui-fg-on-fill` | `--ui-border` |
+| ----------- | ----------- | ----------------- | ------------- |
+| `.solid`    | `100%`      | `100%`            |               |
+| `.soft`     | `12%`       | `0%`              |               |
+| `.ghost`    | `0%`        | `0%`              |               |
+| `.edged`    |             |                   | `100%`        |
+| `.edgeless` |             |                   | `0%`          |
 
-export default function App({ Component, pageProps }: AppProps) {
-  return <Component {...pageProps} />;
-}
-```
+`.card`, `.panel`, `.alert`, `.kbd`, `.code`, and `.pre` override `.soft`'s fill at rest to `0%` for the no-named-intent case only, and reveal it on `.card`'s own `:hover`/`.interactive`/`.hoverable` -- the one place a component remaps what a presentation class resolves to for part of its intent range, the same way text controls cap it at `6%` cascaded. A named intent on any of the six keeps the ordinary `12%`. `.badge` reads the identical intent/presentation classes but keeps its 12% wash at rest even with no named intent, since it has no border to fall back on and would otherwise disappear rather than read quieter. See [Content and layout → Surfaces](docs/usage/content-and-layout.md#surfaces) and [Feedback](docs/usage/feedback.md).
 
-Apply `.dark` or `.light` on `<html>` to force a theme instead of following
-the system preference; see [Setup → Configuration](docs/setup.md#configuration).
+The combinations mean exactly what they spell:
 
-```tsx
-<html lang="en" className="dark">
+```html
+<button class="btn primary">Solid, the button default</button>
+<button class="btn soft edged">Tinted with a border</button>
+<button class="btn primary ghost edged">Outline</button>
+<button class="btn ghost">Ghost; picks up a tint on hover</button>
+<input class="ipt soft edgeless" />
+<!-- A field sunk into the page -->
 ```
 
-A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
-same file instead; see [Tailwind CSS v4](docs/integrating/tailwind.md) for the `@source`
-directive Next.js needs to scan its own `app`/`src` directories.
-
-<!-- Source: docs/integrating/svelte.md -->
+A fill class never decides an edge and an edge class never decides a fill. Use `.solid.edgeless` for a filled box with no line — and prefer it on a neutral one, because a capped fill leaves the box translucent and the edge blend then paints a second coat of the same tint rather than disappearing into it (measured 1.53:1 against its own plate in light, 1.82:1 in dark).
 
-# Svelte
+The edge is the silhouette and nothing else. Rules _inside_ a component that has an inside are a separate switch — see [Content and layout → Table rules](docs/usage/content-and-layout.md#table-rules) — because tying them to this axis made them arrive by implication rather than by request.
 
-In SvelteKit, import the package from the root layout so it loads once for
-every route:
+With no presentation class in scope, each component keeps its own default: buttons are filled, alerts and badges are tinted, surfaces and controls are neutral and bordered.
 
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script>
-  import "@codenhub/styles";
-  let { children } = $props();
-</script>
+| Component                                       | Reads                                       |
+| ----------------------------------------------- | ------------------------------------------- |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`   | Fill, text, border, and border width.       |
+| `.kbd`                                          | Fill, text, border, and border width.       |
+| `.data-table`                                   | Header fill and text, border, border width. |
+| `.ipt`, `.textarea`, `.select`, `.text-control` | Border, border width, and a capped fill.    |
+| `.input-group`                                  | Border, border width, and a capped fill.    |
+| `.checkbox`, `.radio`                           | A capped fill, checked and unchecked.       |
+| `.switch`                                       | Border, border width, and a capped fill.    |
+| `.quote`                                        | Fill, text, border, and width.              |
+| `.code`, `.pre`, `.tooltip-bubble`              | Fill, text, border, and material.           |
+| `.loader`, `.skeleton`, `.progress`, `.divider` | Intent only, not presentation.              |
 
-{@render children()}
-```
+A text control caps a **cascaded** fill at `6%`, keeping typed text legible when a `.solid` container reaches a field nobody classed. A fill class written on the control itself names its own cap instead, because that is a consumer describing what they want: `.soft` takes `12%` and `.solid` takes `20%`.
 
-In a plain Svelte + Vite app, import it from the entry file instead:
+| On a text control | fill |
+| ----------------- | ---- |
+| `.ghost`          | 0%   |
+| cascaded `.solid` | 6%   |
+| `.soft`           | 12%  |
+| `.solid`          | 20%  |
 
-```ts
-// main.ts
-import "@codenhub/styles";
-import { mount } from "svelte";
-import App from "./App.svelte";
+A toggle's cap does not have that split: it is `40%` whether the presentation class is on the checkbox/radio/switch itself or cascaded from a container, the same value for all three. That is where an unchecked `.ghost` (0%), `.soft`/default (12%), and `.solid` (the cap) read as three distinct plates instead of shades of the same wash. Being checked pins the fill to `100%` instead, whatever the presentation class asks — a checkbox, a radio, and a switch each have one "on" look, and presentation only shapes them unchecked. See [Forms](docs/usage/forms.md) for the full toggle reference.
 
-mount(App, { target: document.getElementById("app")! });
-```
+The same split governs the edge: a cascaded `.edgeless` is floored and the element's own is honoured — except on `.checkbox` and `.radio`, which never drop their line at all, and on `.switch.ghost`, which keeps its line specifically against its own `.edgeless`: `.ghost` already asks for zero fill, so removing the line too would leave nothing marking the track but the knob. `.switch.ghost.edgeless` renders the same as `.switch.ghost.edged` rather than as a distinct, boundary-less look. See [Forms](docs/usage/forms.md) for the full toggle and text control reference.
 
-Apply `.dark` or `.light` on `<html>` (edit `src/app.html` in SvelteKit) to
-force a theme instead of following the system preference; see
-[Setup → Configuration](docs/setup.md#configuration).
+A tooltip bubble is filled, over a tinted ground. An intent fills it with that intent's own color: `.tooltip-bubble.primary` is the primary color, black on a light page and white on a dark one, and `.tooltip-bubble.destructive` is a red bubble.
 
-A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
-app's CSS entry instead; see [Tailwind CSS v4](docs/integrating/tailwind.md).
+With no intent the bubble is `--color-tooltip`, the one plate in the package chosen per theme rather than derived from an intent. Composed like everything else it was `20%` of the page's ink over the surface tone, which steps _lighter_ than the surface on a dark page and _darker_ on a light one — so the dark bubble read as lifted and the light one as a mid-grey slab two steps darker than every card on the screen. The token states each direction instead: near-white over a light page, a mid grey over a dark one. `--color-tooltip-contrast` is its ink.
 
-<!-- Source: docs/integrating/tailwind.md -->
+Near-white is only 1.04:1 against a light page, so the bubble draws a hairline as well, and floors it: a container's `.solid` or `.edgeless` cannot take the boundary away from a bubble nobody classed, while `.tooltip-bubble.edgeless` still can. The ground keeps the bubble opaque at every fill, so a cascaded presentation leaves it readable over whatever it floats above. It reads the material tokens too, so an [aesthetic](docs/usage/aesthetics.md) in scope shapes the bubble like any other component. See [Tooltips](docs/usage/tooltips.md) for the full tooltip reference.
 
-# Tailwind CSS v4
+## Component axis reference
 
-A project that already runs Tailwind CSS v4 can process this package's
-source instead of its compiled output. `/tw` entrypoints publish copied,
-uncompiled source from `dist/tw`; your own Tailwind build compiles it
-alongside your app, so its `@theme`, `@utility`, and `@apply` directives
-resolve together with yours.
+This table is the authoritative axis map for demonstrated components. "Shape" means the component reads applicable radius, border-width, shadow, hover, or clip/edge material tokens; an aesthetic may intentionally affect only the materials that component draws.
 
-```css
-@import "tailwindcss";
-@import "@codenhub/styles/tw";
+Presentation is two independent axes, so they get a column each. A `Yes` means the class changes what the component computes, which `tests/browser/axes.spec.ts` asserts against `registry.json` in both directions: an axis marked `Yes` must move, and an axis marked `No` must not.
 
-@source "./src";
-```
+| Components                                                | Intent | Fill | Edge | Aesthetic material |
+| --------------------------------------------------------- | ------ | ---- | ---- | ------------------ |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`             | Yes    | Yes  | Yes  | Shape              |
+| `.loader`                                                 | Yes    | No   | No   | No                 |
+| `.kbd`, `.data-table`                                     | Yes    | Yes  | Yes  | Radius and edge    |
+| `.quote`                                                  | Yes    | Yes  | Yes  | Edge width         |
+| `.divider`, `.skeleton`                                   | Yes    | No   | No   | No                 |
+| `.ipt`, `.textarea`, `.select`, `.text-control`           | Yes    | Yes  | Yes  | Shape              |
+| `.input-group`                                            | Yes    | Yes  | Yes  | Shape              |
+| `.surface`                                                | Yes    | Yes  | Yes  | Shape              |
+| `.checkbox`, `.radio`                                     | Yes    | Yes  | No   | Radius and edge    |
+| `.switch`                                                 | Yes    | Yes  | Yes  | Radius and edge    |
+| `.progress`                                               | Yes    | No   | No   | No                 |
+| `.code`, `.pre`                                           | Yes    | Yes  | Yes  | Radius and clip    |
+| `.tooltip-bubble`                                         | Yes    | Yes  | Yes  | Shape and overlay  |
+| `.table-wrap`, `.quote-inline`, layout and text utilities | No     | No   | No   | No                 |
 
-`@source` tells Tailwind's build where to scan for the utility and component
-class names actually used in your markup, so it can generate only what is
-referenced. Point it at your app's source, not at this package — `/tw`
-already ships every class definition it publishes.
+`.checkbox` and `.radio` are the only components that read one axis and not the other. Their line is the only thing marking an unchecked box, so it is drawn whatever the edge class says, from a container or from the element itself. `.edgeless` on either is unsupported rather than merely discouraged.
 
-Add aesthetics from the source entrypoint the same way as the compiled one,
-after the base import:
+Every other text control floors a _cascaded_ `.edgeless` and honours its own: a `.edgeless` toolbar will not erase the line of a field nobody classed, while `.ipt.edgeless` is a consumer describing what they want and gets it.
 
-```css
-@import "tailwindcss";
-@import "@codenhub/styles/tw";
-@import "@codenhub/styles/tw/aesthetics";
+Intent aliases such as `.danger` and `.error` occupy the same intent axis as `.destructive`; they do not add component behavior. State and modifier classes such as `.interactive`, `.hoverable`, `.pressable`, `.invalid`, `.compact`, and `.vertical` sit above this map and are documented with their component.
 
-@source "./src";
+## Elevation
+
+Depth is a modifier, not an axis. Nothing is raised until an [aesthetic](docs/usage/aesthetics.md) draws depth or one of these classes asks for it.
+
+| Class             | Alias       | Depth                                                                    |
+| ----------------- | ----------- | ------------------------------------------------------------------------ |
+| `.elevation-none` | `.flat`     | Removes part-based elevation; glass surfaces keep their complete shadow. |
+| `.elevation-sm`   | `.raised`   | One unit of the depth in scope. Cards, tiles, popovers that sit close.   |
+| `.elevation-md`   | `.floating` | Twice it, for menus and popovers.                                        |
+
+Both names in a row are equivalent, interchangeable classes — `.elevation-sm` and `.raised` are aliases, not a canonical form and a deprecated one, the way `.destructive` and `.danger` are on the intent axis. The `none`/`sm`/`md` naming matches the raw `--elevation-*` tokens in [Theming](docs/usage/theming.md#foundation-tokens) for the same weight of depth, even though the two are read from different places.
+
+Each is one unitless multiplier over whatever shadow geometry is in scope, so the same class reads as a soft blur on a plain page and as a hard offset slab under `.neobrutalism` — the aesthetic decides what depth looks like, the class decides how much of it this element takes.
+
+```html
+<article class="card elevation-sm">Lifted</article>
+<div class="elevation-md panel">A menu surface</div>
+<article class="card elevation-none">Flat, whatever the page or container says</article>
 ```
 
-Import a focused `/tw/*` entrypoint instead of the combined one — such as
-`/tw/button` or `/tw/form` — when a build only needs one component family;
-see the full [import path table](docs/setup.md#import-paths) for what each one
-composes. Tailwind CSS 4 or newer is required for every `/tw` entrypoint.
+The multiplier does not inherit: an elevation class lifts or flattens the element it is written on only, and an unclassed element inside it takes no depth of its own. Give each element that needs depth its own elevation class. Spread is deliberately left out of the multiplication, because an aesthetic that draws its edge as an inset ring spends spread on it and scaling that would erase the edge.
 
-<!-- Source: docs/integrating/vue.md -->
+<!-- Source: docs/usage/theming.md -->
 
-# Vue
+# Theming
 
-Import the package once, from the app's entry file, before the app mounts:
+Color tokens are how you restyle the palette; see [Concepts → Theme selection](docs/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.
 
-```ts
-// main.ts
-import "@codenhub/styles";
-import { createApp } from "vue";
-import App from "./App.vue";
+## Color tokens
 
-createApp(App).mount("#app");
+Each color token holds both of its theme values at once through `light-dark()`, and the element's `color-scheme` picks one.
+
+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`.
+
+```html
+<section data-theme="dark">
+  <article>Dark token subtree</article>
+</section>
 ```
 
-Apply `.dark` or `.light` on the root element to force a theme instead of
-following the system preference; see
-[Setup → Configuration](docs/setup.md#configuration).
+| 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.                                                                            |
 
-A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from a CSS
-entry file instead of `main.ts`, using the `@tailwindcss/vite` plugin; see
-[Tailwind CSS v4](docs/integrating/tailwind.md).
+> **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.
 
-<!-- Source: docs/setup.md -->
+## Intent tokens
 
-# Setup
+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.
 
-## Installation
+| 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. Resolves to `--color-border` when no intent is set.                       |
+| `--intent-fill-max` | How far a fill of this intent is allowed to go. `100%` for every intent but neutral.  |
 
-```sh
-pnpm add @codenhub/styles
-```
+`--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.
 
-## Quick start
+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.
 
-Import the compiled stylesheet for the complete token, reset, utility, and
-component-class surface, then compose helper classes in markup:
+`--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.
+
+`--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.
+
+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.
+
+That means a capped neutral takes the strong tone whole rather than a fraction of the way toward the page. Tying it to the fill instead cost a neutral `.solid` button four points of contrast and a neutral tooltip nearly ten. 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.
+
+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%.
 
 ```css
-@import "@codenhub/styles";
+.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);
+  --intent-fill-max: 100%;
+}
 ```
 
 ```html
-<main class="stack">
-  <p class="text-label">Status</p>
-  <h1 class="text-title">Ready to publish</h1>
-  <button class="btn primary">Continue</button>
-</main>
+<button class="btn brand">Custom intent</button> <span class="badge brand soft">Works everywhere</span>
 ```
 
-The full stylesheet applies global reset and focus-visible rules, but does not
-apply the optional classless native-element mappings, and does not include
-aesthetics. Import focused entrypoints when global rules are not appropriate;
-see [Import paths](#import-paths) below.
+> **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.
+
+## 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 `.elevation-none`/`.elevation-sm`/ `.elevation-md` (aliased as `.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](docs/usage/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. Negative, so the ring lands on the edge.  |
+| `--focus-ring-width`       | Focus-visible outline/ring width.                                       |
+| `--motion-duration-fast`   | Fast transition for buttons and input interactions (`120ms`).           |
+| `--motion-duration-normal` | Normal transition for layout and modals (`200ms`).                      |
+| `--motion-duration-slow`   | Slow animation for skeleton loaders and progress bars (`400ms`).        |
+| `--motion-ease`            | Default easing curve.                                                   |
+| `--z-popover`              | Popover/tooltip z-index.                                                |
+| `--breakpoint-xs`          | Extra-small Tailwind responsive breakpoint.                             |
+| `--breakpoint-2xl`         | Extended large Tailwind responsive breakpoint.                          |
+
+Next: [Customizing](docs/usage/customizing.md) covers presentation and material tokens — how much of an intent shows, and what a component is made of.
+
+<!-- Source: docs/usage/customizing.md -->
+
+# Customizing
+
+Presentation tokens decide how much of an intent shows. Material tokens decide what a component is made of. Aesthetic tokens are the small set of named knobs a shipped aesthetic exposes to scale its own look.
+
+## Presentation tokens
 
-Aesthetics are opt-in. Import the combined aesthetics stylesheet, or one
-aesthetic on its own, after the base stylesheet so its rules win:
+Presentation tokens describe _how much_ of an intent a component shows, never _which_ intent it shows. They are unitless numbers and percentages, so they carry no color and inherit safely: a container sets them once and every component below resolves them against its own intent.
+
+| Token             | Purpose                                                                    |
+| ----------------- | -------------------------------------------------------------------------- |
+| `--ui-fill`       | Percentage of the intent color mixed into the background.                  |
+| `--ui-fg-on-fill` | Percentage blended from the intent readable tone toward its contrast tone. |
+| `--ui-border`     | Percentage of the intent color mixed into the border color.                |
+
+A component resolves them with `color-mix` from its published default. Hover is derived by adding `--hover-step` to the resting fill and using `--intent-hover`; there are no per-presentation hover tokens.
+
+No fill class writes `--ui-border` and no edge class writes `--ui-fill`. A filled box with no line is `.solid.edgeless`, which is worth reaching for on a neutral component: neutral caps its fill, so the box stays translucent and a border over it paints a second coat of the same tint instead of blending into it.
 
 ```css
-@import "@codenhub/styles";
-@import "@codenhub/styles/aesthetics";
+background: color-mix(in oklab, var(--color-primary) var(--ui-fill, 100%), transparent);
 ```
 
+Two choices there are deliberate. Mixing toward `transparent` rather than a background token lets a tinted surface adapt to whatever it is placed on. Mixing in `oklab` keeps the wide-gamut token palette intact and blends perceptually, where `srgb` would clip it.
+
+A computed color therefore reaches the page as a resolved `color-mix` result rather than the token's own `oklch` syntax. It is the same color; code that compares computed color strings should compare colors instead.
+
+> **Presentation token contract**: only presentation classes and consumer overrides set these tokens; components only read them. Setting a value that no presentation class produces is supported but unvalidated. See [Composing](docs/usage/composing.md) for the classes that ship these values.
+
+## Material tokens
+
+Material tokens describe what a component is _made of_ rather than which intent it shows or how strongly. They control shape, borders, shadows, translucency, filters, and transforms.
+
+Components read each with a fallback, so leaving them unset produces the default look. Setting them on a container restyles the whole subtree. Only shadow geometry is split into colorless parts that inherit safely; color-capable inputs such as `--ui-ink` and `--ui-surface-shadow` may include their own colors.
+
+| Token                   | Purpose                                                                                                       | Fallback             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `--ui-radius`           | Corner radius for controls.                                                                                   | `--radius-control`   |
+| `--ui-radius-surface`   | Corner radius for surfaces.                                                                                   | `--radius-surface`   |
+| `--ui-border-width`     | Edge thickness.                                                                                               | `--border-width`     |
+| `--ui-border-max`       | Ceiling on computed edge width.                                                                               | `100px`              |
+| `--ui-ink`              | Neutral line color when no intent is set.                                                                     | `--color-border`     |
+| `--ui-rule`             | Lines inside a table. Unset draws the head and foot boundaries only; `0%` draws none; `100%` rules every row. | unset                |
+| `--ui-shadow-x`         | Shadow horizontal offset.                                                                                     | `0px`                |
+| `--ui-shadow-y`         | Shadow vertical offset.                                                                                       | `0px`                |
+| `--ui-shadow-blur`      | Shadow blur radius.                                                                                           | `0px`                |
+| `--ui-shadow-spread`    | Shadow spread radius.                                                                                         | `0px`                |
+| `--ui-shadow-inset`     | The `inset` keyword for an inner ring.                                                                        | Empty                |
+| `--ui-hover-shadow-x`   | Shadow horizontal offset while hovered.                                                                       | `--ui-shadow-x`      |
+| `--ui-hover-shadow-y`   | Shadow vertical offset while hovered.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-shadow-x`  | Shadow horizontal offset while pressed.                                                                       | `--ui-shadow-x`      |
+| `--ui-active-shadow-y`  | Shadow vertical offset while pressed.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-transform` | Transform while pressed. `none` under `prefers-reduced-motion`.                                               | `scale(0.97)`        |
+| `--ui-shadow-ink`       | Percentage of shadow color taken from intent ink.                                                             | `0%`                 |
+| `--ui-shadow-edge`      | Declared, even empty, when the shadow is the element's edge rather than its depth. Read for presence.         | Unset                |
+| `--ui-elevation`        | Unitless multiplier over shadow geometry.                                                                     | `1`                  |
+| `--ui-surface-shadow`   | Complete multi-layer shadow accepted by surfaces only.                                                        | Unset                |
+| `--ui-surface-ground`   | Ground a surface sits on.                                                                                     | `--color-background` |
+| `--ui-bg-alpha`         | Multiplier over fill for translucent materials.                                                               | `1`                  |
+| `--ui-backdrop`         | Backdrop filter accepted by surfaces only.                                                                    | `none`               |
+| `--ui-hover-transform`  | Transform while an interactive element is hovered.                                                            | `none`               |
+| `--ui-clip`             | Structural component silhouette.                                                                              | `none`               |
+| `--ui-clip-tight`       | Compact component silhouette.                                                                                 | `--ui-clip`          |
+| `--ui-focus-inset`      | Inset focus layer width.                                                                                      | Unset                |
+
 ```html
-<section class="neobrutalism">
-  <button class="btn primary">Thick ink and a hard shadow</button>
+<section style="--ui-radius: 0; --ui-border-width: 3px">
+  <button class="btn primary">Square and heavy</button>
+  <input class="ipt" placeholder="Matches" />
 </section>
 ```
 
-A project already running Tailwind CSS v4 imports the source entrypoint
-instead; see [Integrating → Tailwind CSS v4](docs/integrating/tailwind.md).
+> **Material token contract**: components read these; aesthetic classes and consumer overrides set them.
 
-## Configuration
+### Shape and ring composition
+
+Clipping removes borders, outlines, and outer shadows. An aesthetic that uses a clip can replace the border with an inset shadow by setting `--ui-shadow-inset` and the four shadow geometry parts. Set `--ui-border-max: 0px` when that ring replaces the component border. Focusable components restore the clipped focus outline through `--ui-focus-inset`.
+
+Declare `--ui-shadow-edge` when that ring _is_ the border. The ring then takes the element's edge color, which carries the edge axis as its alpha, so `.edged` draws it and `.edgeless` does not — the same answer a real border gives. Without it the ring paints on every component the aesthetic reaches and the edge classes have no effect. Use `--ui-shadow-ink` instead when the shadow is depth cast in the intent's own ink, such as a hard offset slab, which an `.edgeless` element still gets.
+
+The token is read for its presence, not its value: declare it empty to switch the ring on, and `initial` to switch it back off in an aesthetic nested inside one that declares it.
+
+```css
+.stepped {
+  --ui-clip: polygon(/* structural silhouette */);
+  --ui-clip-tight: none;
+  --ui-border-max: 0px;
+  --ui-shadow-inset: inset;
+  --ui-shadow-edge: ;
+  --ui-shadow-x: 0px;
+  --ui-shadow-y: 0px;
+  --ui-shadow-blur: 0px;
+  --ui-shadow-spread: 4px;
+  --ui-focus-inset: var(--focus-ring-width);
+}
+```
+
+Variables prefixed `--_` are internal composition outputs — `--_bg`, `--_fg`, `--_edge`, `--_fill`, `--_shadow`, and the `--_d-*` resting slots a component states for `box` to read. Do not set or read them; only the `--ui-*` inputs above are public.
+
+## Aesthetic tokens
+
+The shipped [aesthetic classes](docs/usage/aesthetics.md) set material tokens for you. Only aesthetics with a token listed below expose an aesthetic-specific token. Tune all other behavior through the shared material tokens above. Listed tokens are available only where that aesthetic's stylesheet is imported.
+
+| Token                    | Aesthetic       | Purpose                                                     | Default                           |
+| ------------------------ | --------------- | ----------------------------------------------------------- | --------------------------------- |
+| `--neo-offset`           | `.neobrutalism` | Hard shadow offset and distance the press travels.          | `4px`                             |
+| `--glass-radius`         | `.glass`        | Control corner radius.                                      | `0.75rem`                         |
+| `--glass-radius-surface` | `.glass`        | Surface corner radius.                                      | `1rem`                            |
+| `--pixel-unit`           | `.pixel`        | One pixel of the grid. The corner cut and the ring are one. | `4px`                             |
+| `--font-pixel`           | `.pixel`        | Consumer-supplied pixel font stack.                         | Falls back to the monospace stack |
+| `--tile-radius`          | `.chunky-tile`  | Corner radius, on controls and surfaces alike.              | `0.75rem`                         |
+| `--tile-lift`            | `.chunky-tile`  | Depth of the seated bar, and how far a press travels.       | `4px`                             |
+| `--font-rounded`         | `.chunky-tile`  | Consumer-supplied rounded font stack.                       | Falls back to the page stack      |
 
-The root follows the operating-system color-scheme preference. Apply `.light`
-or `.dark` to the root or any ancestor to force token values for that subtree.
-`.theme-light`, `.theme-dark`, and `data-theme="light|dark"` are aliases.
+All four aesthetics reach the same way: each knob is _read_ with its default as a `var()` fallback rather than declared, so it resolves once into a private on the aesthetic's own class (`--_pixel-unit`, `--_neo-offset`, `--_tile-radius`, `--_tile-lift`, and so on). Set a knob on the element carrying the aesthetic class, or on any ancestor including `:root`:
 
 ```html
-<html class="dark">
+<section class="pixel" style="--pixel-unit: 6px">
+  <button class="btn primary">Chunkier</button>
+</section>
+```
+
+```html
+<html class="pixel" style="--pixel-unit: 6px">
   <body>
-    <button class="btn primary">Dark themed button</button>
+    <button class="btn primary">Also chunkier, set from the root</button>
   </body>
 </html>
 ```
 
-See [Concepts → Theme selection](docs/concepts.md#theme-selection) for how
-selectors resolve and [Usage → Theming](docs/usage/theming.md) for the full color
-token reference.
+Knobs and material tokens reach in opposite directions, and telling them apart matters. A knob resolves once at the aesthetic's own class and inherits down already-resolved, so it reaches the aesthetic **from above**: setting it on the element or any ancestor works, but setting it on a _descendant_ of the aesthetic class changes nothing — the value has already been read. `--ui-radius` and the other material tokens above are read fresh by each component as it draws, so they reach **at or below** the element carrying them, which is how you round one card differently from its neighbours without touching the knob at all.
 
-## Import paths
+Shipped aesthetics set the shared material tokens above. `.neobrutalism` and `.pixel` set `--ui-ink` for their neutral outline; intent classes still override the intent slots on each component.
 
-Compiled entrypoints are ready-to-import CSS and require only tooling that can
-resolve package CSS imports. `/tw` entrypoints publish copied, uncompiled
-source from `dist/tw`; a Tailwind v4 build must still process their `@theme`,
-`@utility`, `@apply`, and related directives. Focused source component
-entrypoints include theme tokens so their classes can work independently.
+## Component internals
 
-| Import path                      | Composition and effects                                                                                                                                                                                           |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@codenhub/styles`               | Compiled complete surface: Tailwind base/theme output, tokens, typography, utilities, components, and reset. Applies global reset, root theme, and focus rules.                                                   |
-| `@codenhub/styles/theme`         | Compiled Tailwind theme variables, Codenhub tokens, and the presentation classes. Sets root theme properties and system/explicit theme selectors; no reset or component classes.                                  |
-| `@codenhub/styles/components`    | Compiled theme tokens, typography utilities, and every component class. Includes static reduced-motion loader masks; no reset, layout/content utilities, or native mappings.                                      |
-| `@codenhub/styles/native`        | Compiled complete surface plus classless mappings for headings, text, content elements, form controls, and buttons. Applies the reset and broad element selectors.                                                |
-| `@codenhub/styles/aesthetics`    | Compiled `.neobrutalism`, `.glass`, `.pixel`, and `.chunky-tile` classes. Adds no tokens or components of its own; import after the base stylesheet.                                                              |
-| `@codenhub/styles/aesthetics/*`  | One compiled aesthetic: `/neobrutalism`, `/glass`, `/pixel`, or `/chunky-tile`. Same rules and ordering as the combined file.                                                                                     |
-| `@codenhub/styles/tw`            | Source equivalent of the complete stylesheet. Imports Tailwind itself, theme, typography, utilities, components, and reset; applies the same global rules.                                                        |
-| `@codenhub/styles/tw/theme`      | Source theme, tokens, and presentation classes. Imports Tailwind's theme layer; emits root/system/explicit theme selectors and defines the package's custom `dark:` variant.                                      |
-| `@codenhub/styles/tw/components` | Published Tailwind source for theme, typography, buttons, feedback, forms, loaders, surfaces, and tooltips, including static reduced-motion loader masks. No reset, layout/content utilities, or native mappings. |
-| `@codenhub/styles/tw/surface`    | Source theme plus `.surface`, `.card`, and `.panel`.                                                                                                                                                              |
-| `@codenhub/styles/tw/button`     | Published Tailwind source for theme, activity indicators, and `.btn`; includes static reduced-motion masks because buttons compose `.loader-mask` for loading state.                                              |
-| `@codenhub/styles/tw/form`       | Source theme plus field, public `text-control`, input, textarea, select, checkbox, radio, and switch utilities.                                                                                                   |
-| `@codenhub/styles/tw/feedback`   | Source theme plus alert, badge, skeleton, and progress utilities and their keyframes.                                                                                                                             |
-| `@codenhub/styles/tw/loader`     | Published Tailwind source for activity indicators and loaders, including static reduced-motion masks. It has no theme or reset side effects and uses `currentColor`.                                              |
-| `@codenhub/styles/tw/tooltip`    | Source theme plus tooltip utilities.                                                                                                                                                                              |
-| `@codenhub/styles/tw/reset`      | Source theme, typography utilities, and global reset/accessibility rules. It changes root/body/elements and selection, motion, focus, scrollbar, and forced colors.                                               |
-| `@codenhub/styles/tw/native`     | Source complete surface plus reset and classless native-element mappings; broadest global effects.                                                                                                                |
-| `@codenhub/styles/tw/typography` | Source theme plus typography utilities; sets theme selectors but no reset or classless mappings.                                                                                                                  |
-| `@codenhub/styles/tw/utilities`  | Source theme and typography composition plus layout and content utilities; safelists the package utility names.                                                                                                   |
-| `@codenhub/styles/tw/aesthetics` | Source aesthetics, combined. `/tw/aesthetics/neobrutalism`, `/glass`, `/pixel`, and `/chunky-tile` publish one apiece. Plain CSS with no theme or reset side effects.                                             |
+Component classes may define scoped implementation variables such as `--surface-padding`, `--field-gap`, `--input-group-pad`, `--switch-*`, `--table-*`, `--quote-*`, and `--tooltip-*`. These variables are internal wiring for class composition and are not the public token contract.
 
-Avoid importing overlapping entrypoints in the same build unless duplicate
-generated CSS is acceptable; pick the narrowest entrypoint that covers what a
-page needs.
+Consumers should customize broad behavior through color, foundation, motion, elevation, radius, layout, and focus tokens first. The only supported component-scoped input is `--progress-value` on the `.progress` element, because consumers must provide a value such as `64%`.
 
-## Requirements
+`--layout-gap` replaces the removed `--layout-stack-gap` and `--layout-cluster-gap` tokens. No compatibility aliases are provided.
 
-- Consumer tooling must resolve package CSS imports.
-- Chrome 123, Safari 17.5, or Firefox 121 and newer. Color tokens are declared
-  with `light-dark()` and selected by `color-scheme` (Firefox 120), and
-  `.input-group` propagates a nested control's invalid and disabled state with
-  `:has()` (Firefox 121).
-- Tailwind CSS 4 or newer is required only for `/tw` source entrypoints.
-- The package has no JavaScript runtime. Apps must provide semantic HTML,
-  ARIA, keyboard behavior, focus management, validation, and announcements;
-  see [Accessibility](docs/accessibility.md).
+Next: [Aesthetics](docs/usage/aesthetics.md) covers each shipped aesthetic's complete look and its documented exceptions.
 
 <!-- Source: docs/usage/aesthetics.md -->
 
 # Aesthetics
 
-An aesthetic decides what a component is _made of_: its radius, border
-thickness, shadow, and shape. Aesthetics ship from opt-in entrypoints, so
-importing the stylesheet is what makes the classes available:
+An aesthetic decides what a component is _made of_: its radius, border thickness, shadow, and shape. Aesthetics ship from opt-in entrypoints, so importing the stylesheet is what makes the classes available:
 
 ```css
 @import "@codenhub/styles";
 @import "@codenhub/styles/aesthetics";
 ```
 
-Import them after the base stylesheet. `.neobrutalism` and `.pixel` replace
-the neutral border color, and they do so at zero specificity, so source order
-is what lets them win.
+Import them after the base stylesheet. `.neobrutalism` and `.pixel` replace the neutral border color, and they do so at zero specificity, so source order is what lets them win.
 
 Like presentation, an aesthetic class cascades to any subtree:
 
@@ -691,33 +755,19 @@ Like presentation, an aesthetic class cascades to any subtree:
 | `.pixel`        | Corners cut by one grid unit, a chunky outline drawn as an inset ring, and the consumer-supplied `--font-pixel` over monospace. |
 | `.chunky-tile`  | Rounded slabs seated on a darker shade of themselves, with a press that moves the element down into its own bar.                |
 
-Aesthetics compose with every supported fill and edge pair. `.ghost.edgeless`
-intentionally removes the visible material traits from components whose
-aesthetic is expressed only through their fill, edge, or elevation.
+Aesthetics compose with every supported fill and edge pair. `.ghost.edgeless` intentionally removes the visible material traits from components whose aesthetic is expressed only through their fill, edge, or elevation.
 
-An explicit presentation on the element still wins over the aesthetic's
-defaults. The aesthetic supplies edge thickness; presentation only decides
-whether that edge is drawn.
+An explicit presentation on the element still wins over the aesthetic's defaults. The aesthetic supplies edge thickness; presentation only decides whether that edge is drawn.
 
-An aesthetic directly on a component likewise wins over an inherited
-aesthetic. This includes tooltip pseudo-elements: `.tooltip.glass` gets the
-complete glass bubble under a pixel ancestor, and `.tooltip.pixel` gets the
-complete stepped bubble under a glass ancestor.
+An aesthetic directly on a component likewise wins over an inherited aesthetic. This includes tooltip bubbles: `.tooltip-bubble.glass` gets the complete glass bubble under a pixel ancestor, and `.tooltip-bubble.pixel` gets the complete stepped bubble under a glass ancestor.
 
-Each aesthetic that scales from one number publishes it as a knob — see
-[Customizing → Aesthetic tokens](docs/usage/customizing.md#aesthetic-tokens) for how
-knobs resolve and where they can be set. This page covers what each
-aesthetic looks like and where it makes documented exceptions.
+Each aesthetic that scales from one number publishes it as a knob — see [Customizing → Aesthetic tokens](docs/usage/customizing.md#aesthetic-tokens) for how knobs resolve and where they can be set. This page covers what each aesthetic looks like and where it makes documented exceptions.
 
 ## Neobrutalism
 
-The shadow is cast in the component's own intent, so a success button throws
-a green shadow and a destructive card a red one. With no intent, both the
-outline and the shadow use the ink, which follows the theme rather than the
-palette.
+The shadow is cast in the component's own intent, so a success button throws a green shadow and a destructive card a red one. With no intent, both the outline and the shadow use the ink, which follows the theme rather than the palette.
 
-`--neo-offset` is the knob: the shadow offset and the distance the press
-travels are the same number, so scaling the look scales both at once.
+`--neo-offset` is the knob: the shadow offset and the distance the press travels are the same number, so scaling the look scales both at once.
 
 ```html
 <section class="neobrutalism" style="--neo-offset: 6px">
@@ -727,26 +777,15 @@ travels are the same number, so scaling the look scales both at once.
 
 **Exceptions:**
 
-- Content chips are left alone. A `.kbd`, `.code`, or `.pre` is content
-  rather than structure, and an ink edge on one reads as a defect: a key cap
-  keeps the quiet border color and a code chip keeps no border at all.
-- Only `.btn` and `.card.interactive` respond to hover and press. A card
-  becomes a control when it opts in with `.interactive`; a plain card, an
-  alert, or a panel is a container and stays put.
-- An alert rests on the slab under this aesthetic and nowhere else. Here the
-  slab is a second ink line rather than depth, and an alert is the only
-  container the package rests flat, so without it a neobrutalist alert is
-  the one box on the page that reads as unfinished. It is a resting default,
-  so `.flat` still takes it off and `.floating` still doubles it.
+- Content chips are left alone. A `.kbd`, `.code`, or `.pre` is content rather than structure, and an ink edge on one reads as a defect: a key cap keeps the quiet border color and a code chip keeps no border at all.
+- Only `.btn` and an opted-in `.card` respond to hover and press. A card opts in with `.interactive`, or with one of its halves — `.hoverable` for the hover response alone, `.pressable` for the press alone; a plain card, an alert, or a panel is a container and stays put.
+- An alert rests on the slab under this aesthetic and nowhere else. Here the slab is a second ink line rather than depth, and an alert is the only container the package rests flat, so without it a neobrutalist alert is the one box on the page that reads as unfinished. It is a resting default, so `.flat` still takes it off and `.floating` still doubles it.
 
 ## Glass
 
-`.glass` needs something behind it to blur. On a flat page background it
-renders as a plain translucent panel.
+`.glass` needs something behind it to blur. On a flat page background it renders as a plain translucent panel.
 
-`--glass-radius` and `--glass-radius-surface` are the corners, at `0.75rem`
-and `1rem`. Glass is rounder than the base geometry because a translucent
-panel with a tight corner reads as a cut-out rather than as a pane.
+`--glass-radius` and `--glass-radius-surface` are the corners, at `0.75rem` and `1rem`. Glass is rounder than the base geometry because a translucent panel with a tight corner reads as a cut-out rather than as a pane.
 
 ```html
 <section class="glass" style="--glass-radius-surface: 1.5rem">
@@ -756,18 +795,12 @@ panel with a tight corner reads as a cut-out rather than as a pane.
 
 **Exceptions:**
 
-- The blur applies to `.card`, `.panel`, `.alert`, and the tooltip bubble
-  only. Controls stay solid and sit on the glass: a blur under every control
-  of a dense cluster costs a composited layer apiece and reads as noise.
-  Controls still take the aesthetic's radius, border, and shadow.
-- Under `prefers-reduced-transparency: reduce`, glass surfaces drop the blur
-  and become opaque.
+- The blur applies to `.card`, `.panel`, `.alert`, and the tooltip bubble only. Controls stay solid and sit on the glass: a blur under every control of a dense cluster costs a composited layer apiece and reads as noise. Controls still take the aesthetic's radius, border, and shadow.
+- Under `prefers-reduced-transparency: reduce`, glass surfaces drop the blur and become opaque.
 
 ## Pixel
 
-`--pixel-unit` is one pixel of the imaginary low-resolution grid, `4px` by
-default. One square unit is cut from each corner and the outline is one unit
-thick, so the cut and what covers it are the same size.
+`--pixel-unit` is one pixel of the imaginary low-resolution grid, `4px` by default. One square unit is cut from each corner and the outline is one unit thick, so the cut and what covers it are the same size.
 
 ```html
 <section class="pixel" style="--pixel-unit: 6px">
@@ -777,44 +810,17 @@ thick, so the cut and what covers it are the same size.
 
 **Exceptions:**
 
-- Corners are one unit or nothing. Chips square instead of stepping —
-  badges, key caps, code, checkboxes, and switches all read
-  `--ui-clip-tight`, which this aesthetic sets to none, because one unit off
-  each corner of a 24px badge is a bite rather than a corner. Tables,
-  progress bars, and skeletons square too, each for its own reason: a
-  table's `overflow: hidden` fights the clip and the corners square off
-  where the two meet, and progress and skeleton never read a clip at all —
-  a squaring aesthetic reaches them through `border-radius` alone. `.pre` is
-  the one exception that steps: it carries no clip override, so it inherits
-  the same polygon a button or a card gets, and with no border by default
-  the cut shows with no ring around it.
-- The outline is an inset ring, because a clip removes a real border — and
-  the focus ring, for the same reason, is a second inset layer rather than
-  an outline. Both are the element's own edge rather than a shadow, so the
-  border answers `.edged` and `.edgeless` the way a border does: a
-  `.edgeless` badge and a `.solid` button draw none, a `.edged` card draws
-  one, and a field keeps one whatever a container asks for.
-- The tooltip trigger and `.radio` are hardcoded past the clip rather than
-  reached by it. `.tooltip-icon` forces `clip-path: none`, since a stepped
-  badge would clip its own bubble away with it. `.radio` forces the same,
-  because the circle is the only thing telling it from a checkbox at a
-  glance, and a stepped polygon would square it.
-- `--font-pixel` is yours to supply. The package ships no font binary, so the
-  aesthetic has no network side effect and falls back to the monospace
-  stack.
+- Corners are one unit or nothing. Chips square instead of stepping — badges, key caps, code, checkboxes, and switches all read `--ui-clip-tight`, which this aesthetic sets to none, because one unit off each corner of a 24px badge is a bite rather than a corner. Tables, progress bars, and skeletons square too, each for its own reason: a table's `overflow: hidden` fights the clip and the corners square off where the two meet, and progress and skeleton never read a clip at all — a squaring aesthetic reaches them through `border-radius` alone. `.pre` is the one exception that steps: it carries no clip override, so it inherits the same polygon a button or a card gets, and with no border by default the cut shows with no ring around it.
+- The outline is an inset ring, because a clip removes a real border — and the focus ring, for the same reason, is a second inset layer rather than an outline. Both are the element's own edge rather than a shadow, so the border answers `.edged` and `.edgeless` the way a border does: a `.edgeless` badge and a `.solid` button draw none, a `.edged` card draws one, and a field keeps one whatever a container asks for.
+- The tooltip trigger and `.radio` are hardcoded past the clip rather than reached by it. `.tooltip-icon` forces `clip-path: none` because the docs call it a circular fixed identity, the same reason `.radio` forces it: the circle is the only thing telling it from a checkbox at a glance, and a stepped polygon would square either one.
+- `--font-pixel` is yours to supply. The package ships no font binary, so the aesthetic has no network side effect and falls back to the monospace stack.
+- Numeral legibility depends on the face you pick. At UI sizes -- pagination, counters, small badges -- some pixel/bitmap faces render lookalike digits such as `2`/`8` or `3`/`9` closely enough to misread at a glance; this is a property of the font, not something the aesthetic's CSS can correct. Prefer a face with clearly distinct digit shapes wherever small numeric text matters.
 
 ## Chunky tile
 
-Rounded slabs sitting on a darker shade of themselves, pressed flat on
-click. The look mobile learning and game apps use; it is named for what it
-is made of rather than for any one product.
+Rounded slabs sitting on a darker shade of themselves, pressed flat on click. The look mobile learning and game apps use; it is named for what it is made of rather than for any one product.
 
-`--tile-lift` is how deep the bar is and how far a press travels, `4px` by
-default. One number drives both, so the top edge drops by exactly the bar's
-depth and the bottom edge does not move. `--tile-radius` is the corner,
-`0.75rem`, and it is one value rather than a control/surface pair on
-purpose — the shared corner is what makes a button and the card it sits in
-read as the same object.
+`--tile-lift` is how deep the bar is and how far a press travels, `4px` by default. One number drives both, so the top edge drops by exactly the bar's depth and the bottom edge does not move. `--tile-radius` is the corner, `0.75rem`, and it is one value rather than a control/surface pair on purpose — the shared corner is what makes a button and the card it sits in read as the same object.
 
 ```html
 <section class="chunky-tile" style="--tile-lift: 6px; --tile-radius: 0.5rem">
@@ -822,49 +828,29 @@ read as the same object.
 </section>
 ```
 
-The bar is a darker shade of the element's own colour rather than a shadow
-under it, so it follows every intent: a success button sits on a dark green
-edge, a destructive one on a dark red edge, and a plain card on a grey edge
-that matches the line it already draws. Measured on the light palette,
-`.btn.success` is `#007a55` on `#004c34`. On a dark page a near-black
-surface cannot go darker, so its bar lands lighter and reads as a rim.
+The bar is a darker shade of the element's own colour rather than a shadow under it, so it follows every intent: a success button sits on a dark green edge, a destructive one on a dark red edge, and a plain card on a grey edge that matches the line it already draws. Measured on the light palette, `.btn.success` is `#007a55` on `#004c34`. On a dark page a near-black surface cannot go darker, so its bar lands lighter and reads as a rim.
 
 **Exceptions:**
 
-- Only what the registry rests above zero sits on a bar — buttons and cards.
-  A badge, chip, field, or tooltip is flat until it asks for depth with
-  `.raised`, and `.flat` takes the bar off anything:
+- Only what the registry rests above zero sits on a bar — buttons and cards. A badge, chip, field, or tooltip is flat until it asks for depth with `.raised`, and `.flat` takes the bar off anything:
 
   ```html
   <div class="card soft edgeless info flat">Promo panel, deliberately flat</div>
   ```
 
-- `--font-rounded` is yours to supply. A heavy rounded grotesque is most of
-  this look and the package ships no font binary, so with nothing supplied
-  the page's own stack is used.
-- Action labels are drawn heavier and slightly tracked. Casing is left
-  alone: how a label is worded is the application's decision, so if you want
-  uppercase buttons, write that rule in your own stylesheet.
-- `.card.interactive` presses like a `.btn`, so a chunky answer tile drops
-  onto its bar on click. A plain `.card` stays put.
-- The shipped `.primary` is a near-black monochrome, which leaves a primary
-  button's bar almost invisible against its own plate; give `.primary` a hue
-  if it is the call to action.
-- Depth in this aesthetic is the bar, never a blurred drop shadow. Anything
-  the registry rests flat sits flush on the page.
+- `--font-rounded` is yours to supply. A heavy rounded grotesque is most of this look and the package ships no font binary, so with nothing supplied the page's own stack is used.
+- Action labels are drawn heavier and slightly tracked. Casing is left alone: how a label is worded is the application's decision, so if you want uppercase buttons, write that rule in your own stylesheet.
+- `.card.interactive` presses like a `.btn`, so a chunky answer tile drops onto its bar on click; `.card.pressable` gets the same press on its own. A plain `.card` stays put.
+- The shipped `.primary` is a near-black-or-near-white monochrome depending on theme, and the bar mixes toward a fixed black regardless of theme. In light theme this leaves a primary button's bar almost invisible against its own near-black plate (measured `1.04:1`, 10 units of sRGB distance); in dark theme the near-white plate against the same black-anchored bar reads fine (`2.48:1`, 154 units). Give `.primary` a hue of its own if it is the call to action and needs the depth cue in both themes.
+- Depth in this aesthetic is the bar, never a blurred drop shadow. Anything the registry rests flat sits flush on the page.
 
 <!-- Source: docs/usage/buttons.md -->
 
 # Buttons
 
-Use `.btn` with one optional intent class, one optional fill class, one
-optional edge class, optional size class, and optional state. See
-[Composing](docs/usage/composing.md) for how the intent, presentation, and aesthetic
-axes combine on any component.
+Use `.btn` with one optional intent class, one optional fill class, one optional edge class, optional size class, and optional state. See [Composing](docs/usage/composing.md) for how the intent, presentation, and aesthetic axes combine on any component.
 
-Intent classes map color tokens into button tone slots.
-[Presentation](docs/usage/composing.md#presentation) decides how much of that intent
-reaches background, text, border, and hover.
+Intent classes map color tokens into button tone slots. [Presentation](docs/usage/composing.md#presentation) decides how much of that intent reaches background, text, border, and hover.
 
 Intent classes:
 
@@ -878,29 +864,22 @@ Intent classes:
 | `.destructive`, `.danger`, `.error` | Destructive or error action.   |
 | `.info`                             | Informational action.          |
 
-Every component that supports intent accepts the same list and reads the
-same [intent tokens](docs/usage/theming.md#intent-tokens), so a custom intent class
-works everywhere without touching a component.
+Every component that supports intent accepts the same list and reads the same [intent tokens](docs/usage/theming.md#intent-tokens), so a custom intent class works everywhere without touching a component.
 
-`.neutral` is the only intent that does not fill all the way. Its color is
-the page's own text color, so a full fill of it would be a black or white
-slab — the loudest element on the page, for the intent that means nothing in
-particular. It stops at `--intent-fill-max`, which is why a `.solid` neutral
-is a quiet plate a step past `.soft` rather than a block of ink. Set the slot
-on your own intent classes; see [Theming → Intent tokens](docs/usage/theming.md#intent-tokens).
+`.neutral` is the only intent that does not fill all the way. Its color is the page's own text color, so a full fill of it would be a black or white slab — the loudest element on the page, for the intent that means nothing in particular. It stops at `--intent-fill-max`, which is why a `.solid` neutral is a quiet plate a step past `.soft` rather than a block of ink. Set the slot on your own intent classes; see [Theming → Intent tokens](docs/usage/theming.md#intent-tokens).
 
 Size and shape classes:
 
-| Class                                                                  | Purpose                                                     |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `.pill`                                                                | Fully rounded button corners (`border-radius: 9999px`).     |
-| `.sm`                                                                  | Smaller button.                                             |
-| `.lg`                                                                  | Larger button.                                              |
-| `.p-sm`, `.compact`                                                    | Compact padding modifier (`px-2.5 py-1`).                   |
-| `.p-lg`, `.spacious`                                                   | Spacious padding modifier (`px-6 py-3`).                    |
-| `.icon`                                                                | Square icon button. Use an accessible name in HTML.         |
-| `.loading`                                                             | Loading state. Hides text and shows CSS activity indicator. |
-| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                           |
+| Class                                                                  | Purpose                                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.pill`                                                                | Fully rounded button corners (`border-radius: 9999px`).                                                                                                                                                                                   |
+| `.sm`                                                                  | Smaller button.                                                                                                                                                                                                                           |
+| `.lg`                                                                  | Larger button.                                                                                                                                                                                                                            |
+| `.p-xs`, `.dense`                                                      | Tightest padding modifier (`px-2 py-0.5`; icon `p-0.5`). Also drops the `--control-height` minimum so a chip-sized button fits a table cell or a dense toolbar; every other size and padding class keeps that floor for a labeled button. |
+| `.p-sm`, `.compact`                                                    | Compact padding modifier (`px-2.5 py-1`; icon `p-1`).                                                                                                                                                                                     |
+| `.p-lg`, `.spacious`                                                   | Spacious padding modifier (`px-6 py-3`; icon `p-3`).                                                                                                                                                                                      |
+| `.icon`                                                                | Square icon button, sized to its own padding rather than to `--control-height`. Use an accessible name in HTML.                                                                                                                           |
+| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                                                                                                                                                                                                         |
 
 Examples:
 
@@ -910,236 +889,306 @@ Examples:
 <button class="btn warning soft">Warning soft</button>
 <button class="btn destructive ghost edgeless">Danger ghost</button>
 <button class="btn icon primary" aria-label="Create">+</button>
-<button class="btn primary loading" disabled>Saving</button>
+<button class="btn primary" disabled>
+  <span class="loader sm" aria-hidden="true"></span>
+  Saving
+</button>
 ```
 
-`.loading` is a state, not a color or presentation class. Prefer combining
-it with disabled behavior so users cannot trigger duplicate work. Loading
-buttons keep only opacity and transform transitions active so spinner and
-surface colors stay synchronized when theme tokens change.
+## Loading
 
-On the base look a press scales the button down a little
-(`--ui-active-transform`, `scale(0.97)`). [Aesthetics](docs/usage/aesthetics.md) swap
-in their own press gesture, and `prefers-reduced-motion` turns it off.
+The package ships no loading state of its own: a loading button is a disabled `.btn` composed with a real [`.loader`](docs/usage/feedback.md) child, the same activity indicator every other component uses. Disable the button so users cannot trigger duplicate work, and drop a `.loader` in beside the label — any of its variants (`.dots-wave`, `.bars-wave`, and so on) work the same way. Whether to also hide the label is your call; the package has no built-in mechanism for that.
 
-Use `<button>` for actions or an accessible link for navigation; see
-[Accessibility](docs/accessibility.md).
+On the base look a press scales the button down a little (`--ui-active-transform`, `scale(0.97)`). [Aesthetics](docs/usage/aesthetics.md) swap in their own press gesture, and `prefers-reduced-motion` turns it off.
 
-<!-- Source: docs/usage/composing.md -->
+Use `<button>` for actions or an accessible link for navigation; see [Accessibility](docs/accessibility.md).
 
-# Composing the three axes
+<!-- Source: docs/usage/forms.md -->
+
+# Forms
 
-See [Concepts](docs/concepts.md#the-three-axes) for what each axis means. This
-page covers how they combine in markup, what the presentation classes mean in
-depth, which components support which axis, and elevation.
+| Class or Selector                                                     | Purpose                                                                  |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `.field`                                                              | Vertical field wrapper.                                                  |
+| `.label`                                                              | Form label text.                                                         |
+| `.hint`                                                               | Secondary helper text.                                                   |
+| `.hint.error`                                                         | 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.                                                        |
 
-## Combining axes
+## Icons
+
+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.
+
+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](docs/usage/feedback.md#example) — the package no longer paints one there either.
+
+`.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`.
 
 ```html
-<div class="soft">
-  <button class="btn primary">Soft primary button</button>
-  <span class="badge success">Soft success badge</span>
-  <button class="btn primary ghost edged">Outlined; the element wins</button>
+<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>
+</label>
+<label class="field">
+  <span class="label">Search</span>
+  <div class="input-group">
+    <input class="ipt" type="search" />
+    <i class="ic-search" aria-hidden="true"></i>
+  </div>
+</label>
+```
+
+The group reads intent and both [presentation](docs/usage/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](docs/usage/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.
+
+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 slot works the same way for a text affix — a URL host, a currency symbol, a unit — not just an icon:
+
+```html
+<div class="input-group">
+  <span>example.com/</span>
+  <input class="ipt" type="text" />
 </div>
 ```
 
-A declaration on the element always beats one inherited from a container, so
-a container sets the default look for its subtree and any element opts out.
+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.
+
+## Toggles
 
-Intent classes do not cascade. `.primary` and its siblings stay on the
-element that shows the intent, because a container silently recoloring every
-descendant is a trap rather than a feature — see
-[Theming → Intent tokens](docs/usage/theming.md#intent-tokens). Use `.neutral` to opt
-an element back out of an inherited intent context. Presentation and
-[material tokens](docs/usage/customizing.md#material-tokens) do cascade, so a
-container can set the look of its whole subtree while any element overrides
-it.
+`.checkbox`, `.radio`, and `.switch` accept the same intent classes as buttons to set the checked color:
 
-## Presentation
+| Class                               | Meaning                 |
+| ----------------------------------- | ----------------------- |
+| `.neutral` _(default)_              | Text color, capped.     |
+| `.primary`                          | Primary color.          |
+| `.secondary`                        | Secondary/accent color. |
+| `.success`                          | Success color.          |
+| `.warning`                          | Warning color.          |
+| `.destructive`, `.danger`, `.error` | Destructive color.      |
+| `.info`                             | Info color.             |
 
-Presentation has two independent axes. `.solid`, `.soft`, and `.ghost`
-decide how much intent fills a component; `.edged` and `.edgeless` decide
-whether it draws a boundary. They set
-[presentation tokens](docs/usage/customizing.md#presentation-tokens) and nothing
-else, so they work on the component itself or on any ancestor.
+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:
 
-| Class       | Look                                                       |
-| ----------- | ---------------------------------------------------------- |
-| `.solid`    | Intent-colored fill with contrast text.                    |
-| `.soft`     | Lightly tinted fill with intent-colored text.              |
-| `.ghost`    | No fill at rest, with intent-colored text.                 |
-| `.edged`    | Intent-colored boundary at the aesthetic's material width. |
-| `.edgeless` | No boundary.                                               |
+| 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) |
 
-Values each class ships:
+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.
 
-| Class       | `--ui-fill` | `--ui-fg-on-fill` | `--ui-border` |
-| ----------- | ----------- | ----------------- | ------------- |
-| `.solid`    | `100%`      | `100%`            |               |
-| `.soft`     | `12%`       | `0%`              |               |
-| `.ghost`    | `0%`        | `0%`              |               |
-| `.edged`    |             |                   | `100%`        |
-| `.edgeless` |             |                   | `0%`          |
+## Text controls
 
-The combinations mean exactly what they spell:
+Text controls also take intent, which colors the resting border and the focus-visible border, and both [presentation](docs/usage/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.
+
+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.
 
 ```html
-<button class="btn primary">Solid, the button default</button>
-<button class="btn soft edged">Tinted with a border</button>
-<button class="btn primary ghost edged">Outline</button>
-<button class="btn ghost">Ghost; picks up a tint on hover</button>
-<input class="ipt soft edgeless" />
-<!-- A field sunk into the page -->
+<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 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" />
+</div>
 ```
 
-A fill class never decides an edge and an edge class never decides a fill.
-Use `.solid.edgeless` for a filled box with no line — and prefer it on a
-neutral one, because a capped fill leaves the box translucent and the edge
-blend then paints a second coat of the same tint rather than disappearing
-into it (measured 1.53:1 against its own plate in light, 1.82:1 in dark).
+`.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.
 
-The edge is the silhouette and nothing else. Rules _inside_ a component that
-has an inside are a separate switch — see
-[Content and layout → Table rules](docs/usage/content-and-layout.md#table-rules) —
-because tying them to this axis made them arrive by implication rather than
-by request.
+```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>
+```
 
-With no presentation class in scope, each component keeps its own default:
-buttons are filled, alerts and badges are tinted, surfaces and controls are
-neutral and bordered.
+`.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.
 
-| Component                                       | Reads                                       |
-| ----------------------------------------------- | ------------------------------------------- |
-| `.btn`, `.alert`, `.badge`, `.card`, `.panel`   | Fill, text, border, and border width.       |
-| `.kbd`                                          | Fill, text, border, and border width.       |
-| `.data-table`                                   | Header fill and text, border, border width. |
-| `.ipt`, `.textarea`, `.select`, `.text-control` | Border, border width, and a capped fill.    |
-| `.input-group`                                  | Border, border width, and a capped fill.    |
-| `.checkbox`, `.radio`                           | A capped fill, checked and unchecked.       |
-| `.switch`                                       | Border, border width, and a capped fill.    |
-| `.quote`                                        | Fill, text, border, and width.              |
-| `.code`, `.pre`, `.tooltip`                     | Fill, text, border, and material.           |
-| `.loader`, `.skeleton`, `.progress`, `.divider` | Intent only, not presentation.              |
+## Example
+
+```html
+<label class="field">
+  <span class="label">Email</span>
+  <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
+  <span class="hint error" 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>
+```
 
-Text controls and toggles cap a **cascaded** fill at `6%`, keeping typed
-text legible when a `.solid` container reaches a field nobody classed. A
-fill class written on the control itself names its own cap instead, because
-that is a consumer describing what they want: `.soft` takes `12%` and
-`.solid` takes `20%`. A switch caps at `40%`, where its three fills separate
-far enough to read on a track.
+Use labels, `type`, validation logic, `aria-describedby`, and error message relationships; see [Accessibility](docs/accessibility.md).
 
-| On a text control | fill |
-| ----------------- | ---- |
-| `.ghost`          | 0%   |
-| cascaded `.solid` | 6%   |
-| `.soft`           | 12%  |
-| `.solid`          | 20%  |
+<!-- Source: docs/usage/feedback.md -->
+
+# Feedback
+
+| Class            | Purpose                                                                      |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `.alert`         | Inline feedback surface.                                                     |
+| `.alert-icon`    | Sizing and alignment for an icon element dropped in as a child of `.alert`.  |
+| `.badge`         | Compact status pill.                                                         |
+| `.loader-mask`   | Low-level activity indicator composition utility. Applies the spinner mask.  |
+| `.loader`        | Standalone inline loader artwork.                                            |
+| `.skeleton`      | Ambient loading placeholder.                                                 |
+| `.progress`      | Progress track. Uses `--progress-value` variable.                            |
+| `.active`        | Optional on `.progress` to add a track shimmer.                              |
+| `.indeterminate` | Optional on `.progress` to animate a moving fill without `--progress-value`. |
+
+Activity indicator modifier classes compose with `.loader`:
+
+| Class                  | Animation style                         |
+| ---------------------- | --------------------------------------- |
+| _(default)_            | Circular spinner (rotating arc).        |
+| `.dots-wave`           | Three dots bouncing up/down in a wave.  |
+| `.dots-fade`           | Three dots fading in and out.           |
+| `.dots-queue`          | Dot queuing from left to right.         |
+| `.dots-rotate`         | Side dots rotating around a center dot. |
+| `.dots-grow`           | Three dots growing and shrinking.       |
+| `.dots-grow-alternate` | Outer dots small, center dot pulses.    |
+| `.dot-bounce`          | Single dot bouncing with squash effect. |
+| `.bars-wave`           | Three vertical bars scaling in a wave.  |
+| `.pulse-ring`          | Two concentric rings pulsing outward.   |
+
+These variants retain their embedded SVG animations normally. Under `prefers-reduced-motion: reduce`, loader CSS substitutes a corresponding static mask. This fallback is part of focused loader, button, and components imports; it does not depend on the global reset. See [Accessibility](docs/accessibility.md).
+
+Loader size modifiers:
+
+| Class    | Size                 |
+| -------- | -------------------- |
+| _(none)_ | Default (`1.75rem`). |
+| `.sm`    | Small (`1.25rem`).   |
+| `.lg`    | Large (`2.25rem`).   |
+
+Alerts, badges, progress bars, skeletons, and loaders accept `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, `.danger`, `.error`, and `.info`. Without an intent, they use the text palette, except `.loader`, which keeps `currentColor` so it matches whatever content surrounds it.
+
+Skeletons, loaders, progress bars, and dividers are indicators. They read intent but ignore fill and edge [presentation](docs/usage/composing.md#presentation).
 
-The same split governs the edge: a cascaded `.edgeless` is floored and the
-element's own is honoured — except on `.checkbox` and `.radio`, which never
-drop their line at all. See [Forms](docs/usage/forms.md) for the full toggle and text
-control reference.
-
-A tooltip bubble is filled, over a tinted ground. An intent fills it with
-that intent's own color: `.tooltip.primary` is the primary color, black on a
-light page and white on a dark one, and `.tooltip.destructive` is a red
-bubble.
-
-With no intent the bubble is `--color-tooltip`, the one plate in the package
-chosen per theme rather than derived from an intent. Composed like
-everything else it was `20%` of the page's ink over the surface tone, which
-steps _lighter_ than the surface on a dark page and _darker_ on a light
-one — so the dark bubble read as lifted and the light one as a mid-grey
-slab two steps darker than every card on the screen. The token states each
-direction instead: near-white over a light page, a mid grey over a dark
-one. `--color-tooltip-contrast` is its ink.
-
-Near-white is only 1.04:1 against a light page, so the bubble draws a
-hairline as well, and floors it: a container's `.solid` or `.edgeless`
-cannot take the boundary away from a bubble nobody classed, while
-`.tooltip.edgeless` still can. The ground keeps the bubble opaque at every
-fill, so a cascaded presentation leaves it readable over whatever it floats
-above. It reads the material tokens too, so an [aesthetic](docs/usage/aesthetics.md)
-in scope shapes the bubble like any other component. See
-[Tooltips](docs/usage/tooltips.md) for the full tooltip reference.
+```html
+<span class="loader success" aria-hidden="true"></span> <span class="skeleton info"></span>
+```
 
-## Component axis reference
+The package ships no icon of its own: `.alert` is already `flex`, so an icon dropped in as a child is spaced from the message by its `gap-3` with nothing to trigger. `.alert-icon` only sizes and aligns whatever icon element you provide — an inline `<svg>`, an `<img>`, or a class from an icon set such as `@codenhub/icons` — the same contract [`.input-group`](docs/usage/forms.md#icons) documents.
 
-This table is the authoritative axis map for demonstrated components. "Shape"
-means the component reads applicable radius, border-width, shadow, hover, or
-clip/edge material tokens; an aesthetic may intentionally affect only the
-materials that component draws.
+Alerts and badges read the shared [presentation](docs/usage/composing.md#presentation) classes. Without one they use a tinted surface, intent-colored text, and a mixed intent border -- except a neutral `.alert` (no named intent), which rests untinted instead, the same no-named-intent carve-out `.card.soft` and `.panel` use: a plain `--color-foreground` plate rather than 12% of near-black ink over the page. A named intent (`.alert.success`, `.alert.destructive`, and so on) keeps its ordinary tint. `.badge` is unaffected either way -- it has no border to fall back on at rest, so untinting it would make a neutral badge disappear rather than read quieter.
 
-Presentation is two independent axes, so they get a column each. A `Yes` means
-the class changes what the component computes, which
-`tests/browser/axes.spec.ts` asserts against `registry.json` in both
-directions: an axis marked `Yes` must move, and an axis marked `No` must not.
+## Example
 
-| Components                                                | Intent | Fill | Edge | Aesthetic material |
-| --------------------------------------------------------- | ------ | ---- | ---- | ------------------ |
-| `.btn`, `.alert`, `.badge`, `.card`, `.panel`             | Yes    | Yes  | Yes  | Shape              |
-| `.loader`                                                 | Yes    | No   | No   | No                 |
-| `.kbd`, `.data-table`                                     | Yes    | Yes  | Yes  | Radius and edge    |
-| `.quote`                                                  | Yes    | Yes  | Yes  | Edge width         |
-| `.divider`, `.skeleton`                                   | Yes    | No   | No   | No                 |
-| `.ipt`, `.textarea`, `.select`, `.text-control`           | Yes    | Yes  | Yes  | Shape              |
-| `.input-group`                                            | Yes    | Yes  | Yes  | Shape              |
-| `.surface`                                                | Yes    | Yes  | Yes  | Shape              |
-| `.checkbox`, `.radio`                                     | Yes    | Yes  | No   | Radius and edge    |
-| `.switch`                                                 | Yes    | Yes  | Yes  | Radius and edge    |
-| `.progress`                                               | Yes    | No   | No   | No                 |
-| `.code`, `.pre`                                           | Yes    | Yes  | Yes  | Radius and clip    |
-| `.tooltip`                                                | Yes    | Yes  | Yes  | Shape and overlay  |
-| `.table-wrap`, `.quote-inline`, layout and text utilities | No     | No   | No   | No                 |
+```html
+<div class="alert success" role="status">Saved successfully.</div>
+<div class="alert primary solid" role="status">Deployment started.</div>
+<div class="alert warning soft" role="status">
+  <svg class="alert-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
+    <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+    <path d="M12 9v4" />
+    <path d="M12 17h.01" />
+  </svg>
+  Review required.
+</div>
+<div class="alert destructive ghost edged" role="alert">Deployment failed.</div>
+<span class="badge warning">Queued</span>
+<span class="badge success solid">Live</span>
+<span class="badge info soft">Draft</span>
+<span class="loader" aria-hidden="true"></span>
+<span class="loader dots-wave" aria-hidden="true"></span>
+<span class="loader dots-fade" aria-hidden="true"></span>
+<span class="loader bars-wave" aria-hidden="true"></span>
+<span class="loader pulse-ring sm" aria-hidden="true"></span>
+<span class="loader dots-grow lg" aria-hidden="true"></span>
+<div class="progress" role="progressbar" aria-label="Upload progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64" style="--progress-value: 64%"></div>
+<div class="progress secondary active" role="progressbar" aria-label="Upload progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64" style="--progress-value: 64%"></div>
+<div class="progress info indeterminate" role="progressbar" aria-label="Loading" aria-valuemin="0" aria-valuemax="100"></div>
+```
 
-`.checkbox` and `.radio` are the only components that read one axis and not
-the other. Their line is the only thing marking an unchecked box, so it is
-drawn whatever the edge class says, from a container or from the element
-itself. `.edgeless` on either is unsupported rather than merely discouraged.
+Add `role="status"` or `role="alert"` to alerts based on announcement urgency, mark decorative loading visuals with `aria-hidden="true"`, and use semantic progress elements or ARIA values when numeric progress must be announced; see [Accessibility](docs/accessibility.md).
 
-Every other text control floors a _cascaded_ `.edgeless` and honours its own:
-a `.edgeless` toolbar will not erase the line of a field nobody classed, while
-`.ipt.edgeless` is a consumer describing what they want and gets it.
+<!-- Source: docs/usage/tooltips.md -->
 
-Intent aliases such as `.danger` and `.error` occupy the same intent axis as
-`.destructive`; they do not add component behavior. State and modifier
-classes such as `.interactive`, `.loading`, `.invalid`, `.compact`, and
-`.vertical` sit above this map and are documented with their component.
+# Tooltips
 
-## Elevation
+| Class or Attribute                     | Purpose                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| `.tooltip`                             | Wrapper around a trigger and a bubble. Paints nothing itself.            |
+| `.tooltip-bubble`                      | The message. A real element, styled like any other surface.              |
+| `.tooltip-icon`                        | Circular icon-style trigger, for a message with nothing else to hang on. |
+| `[data-tooltip-position="top"]`        | Positions the bubble above the trigger, on `.tooltip`.                   |
+| `[data-tooltip-position="bottom"]`     | Positions the bubble below the trigger, on `.tooltip`.                   |
+| `[data-tooltip-position="left"]`       | Positions the bubble left of the trigger, on `.tooltip`.                 |
+| `[data-tooltip-position="right"]`      | Positions the bubble right of the trigger, on `.tooltip`.                |
+| No `data-tooltip-position`             | Defaults to top placement.                                               |
+| `[data-state="open"]`                  | Shows the bubble without hover, on `.tooltip`.                           |
+| `.tooltip-bubble.raised` / `.floating` | Adds one or two units of depth. The bubble is flat by default.           |
 
-Depth is a modifier, not an axis. Nothing is raised until an
-[aesthetic](docs/usage/aesthetics.md) draws depth or one of these classes asks for it.
+A tooltip is composition, not a single class: `.tooltip` wraps a trigger element and a `.tooltip-bubble`, and shows the bubble on hover or focus within the wrapper. This replaced a `::after` pseudo-element that carried the message as `content: attr(data-tooltip)` — CSS generated content is not reliably exposed to assistive tech, and cannot be the target of an `aria-describedby`, since that needs a real element with a real `id`. A real bubble can be. Wire the association yourself: give the bubble an `id`, give the trigger `aria-describedby` pointing at it, and put `role="tooltip"` on the bubble.
 
-| Class             | Alias       | Depth                                                                    |
-| ----------------- | ----------- | ------------------------------------------------------------------------ |
-| `.elevation-none` | `.flat`     | Removes part-based elevation; glass surfaces keep their complete shadow. |
-| `.elevation-sm`   | `.raised`   | One unit of the depth in scope. Cards, tiles, popovers that sit close.   |
-| `.elevation-md`   | `.floating` | Twice it, for menus and popovers.                                        |
+A tooltip bubble's fill, ground color, and floor behavior are covered in [Composing → Presentation](docs/usage/composing.md#presentation), and its material follows whichever [aesthetic](docs/usage/aesthetics.md) is in scope. Intent, presentation, aesthetic, and elevation classes go on `.tooltip-bubble` — the element that actually paints — not on `.tooltip`, the same rule every component in this package follows: put the class on the element that shows it.
 
-Both names in a row are equivalent, interchangeable classes — `.elevation-sm`
-and `.raised` are aliases, not a canonical form and a deprecated one, the way
-`.destructive` and `.danger` are on the intent axis. The `none`/`sm`/`md`
-naming matches the raw `--elevation-*` tokens in
-[Theming](docs/usage/theming.md#foundation-tokens) for the same weight of depth, even
-though the two are read from different places.
+The bubble rests flat. It draws no shadow of its own on a plain page, and zeroes an aesthetic's part-based depth (such as `.neobrutalism`'s slab) the same way `.flat` does elsewhere. Add [`.raised` or `.floating`](docs/usage/composing.md#elevation) to lift it, on the bubble itself — `.tooltip-bubble.floating` is the pre-0.1.0 look. An aesthetic whose shadow is a complete value, like `.glass`, still reaches the bubble as it reaches any surface.
 
-Each is one unitless multiplier over whatever shadow geometry is in scope, so
-the same class reads as a soft blur on a plain page and as a hard offset slab
-under `.neobrutalism` — the aesthetic decides what depth looks like, the
-class decides how much of it this element takes.
+Intent works on a tooltip bubble the same way it works on a filled component: `.tooltip-bubble.primary` fills the bubble with the primary color, black text on a light page and white on a dark one; `.tooltip-bubble.destructive` is a red bubble with the same logic. With no intent, the bubble uses `--color-tooltip`, a plate chosen per theme rather than derived from an intent; see [Composing → Presentation](docs/usage/composing.md#presentation) for why.
+
+## Example
 
 ```html
-<article class="card elevation-sm">Lifted</article>
-<div class="elevation-md panel">A menu surface</div>
-<article class="card elevation-none">Flat, whatever the page or container says</article>
+<span class="tooltip">
+  <button aria-describedby="status-bubble">Status</button>
+  <span class="tooltip-bubble" role="tooltip" id="status-bubble">Saved 2 minutes ago</span>
+</span>
+
+<span class="tooltip" data-tooltip-position="bottom">
+  <button aria-describedby="docs-bubble">Docs</button>
+  <span class="tooltip-bubble" role="tooltip" id="docs-bubble">Opens in a new tab</span>
+</span>
+
+<span class="tooltip">
+  <button class="btn primary" aria-describedby="deploy-bubble">Deploy</button>
+  <span class="tooltip-bubble raised primary" role="tooltip" id="deploy-bubble">Primary intent, lifted a step</span>
+</span>
+
+<span class="tooltip" data-state="open">
+  <span aria-describedby="pinned-bubble">Pinned</span>
+  <span class="tooltip-bubble" role="tooltip" id="pinned-bubble">Always visible, no hover needed</span>
+</span>
+
+<span class="tooltip" data-tooltip-position="right">
+  <span class="tooltip-icon" tabindex="0" aria-label="More details" aria-describedby="icon-bubble">?</span>
+  <span class="tooltip-bubble" role="tooltip" id="icon-bubble">More details</span>
+</span>
 ```
 
-The multiplier is a plain number, so it inherits: a container lifts or
-flattens a whole region and any element inside it still opts out on itself.
-Spread is deliberately left out of the multiplication, because an aesthetic
-that draws its edge as an inset ring spends spread on it and scaling that
-would erase the edge.
+The first two show plain triggers with default (top) and explicit bottom placement. The third combines an intent with `.raised` on the bubble to show they compose freely — the intent decides the bubble's fill, `.raised` decides whether it casts depth. The fourth uses `data-state="open"` on the wrapper to keep a tooltip visible without a hover or focus interaction, useful for a tooltip that should be demonstrated or tested without simulating pointer input. The fifth uses `.tooltip-icon` as the trigger, for a message with no other element to hang it on.
+
+`.tooltip` composes with any trigger: wrap an existing `.btn` or `.badge` in it and both keep their own look, gaining a bubble beside them. `.tooltip-icon` is only the circular chip for the case where there is nothing else to be the trigger.
+
+Showing and hiding the bubble is CSS-only — `:hover` and `:focus-within` on `.tooltip` — but that is presentational. It is not a complete accessible tooltip implementation by itself: provide the `id`/`aria-describedby`/`role="tooltip"` association outside the CSS; see [Accessibility](docs/accessibility.md).
+
+Next: [Content and layout](docs/usage/content-and-layout.md) covers layout helpers, content chips and tables, surfaces, and typography utilities.
 
 <!-- Source: docs/usage/content-and-layout.md -->
 
@@ -1147,26 +1196,19 @@ would erase the edge.
 
 ## Layout
 
-Layout helpers use the shared `--layout-gap` token. `.tight` sets it to
-`0.5rem` and `.loose` sets it to `1.5rem` within a view, stack, cluster, or
-auto-grid.
+Layout helpers use the shared `--layout-gap` token. `.tight` sets it to `0.5rem` and `.loose` sets it to `1.5rem` within a view, stack, cluster, or auto-grid.
 
-- `.view` is a flex container; `.vertical` and `.horizontal` set its
-  direction, and horizontal views wrap with centered cross-axis alignment.
+- `.view` is a flex container; `.vertical` and `.horizontal` set its direction, and horizontal views wrap with centered cross-axis alignment.
 - `.stack` is a vertical flex stack.
-- `.cluster` is a wrapping horizontal flex row; `.between` adds
-  `space-between` alignment.
+- `.cluster` is a wrapping horizontal flex row; `.between` adds `space-between` alignment.
 - `.auto-grid` is a responsive auto-fit grid using `--layout-grid-min`.
-- `.tight` and `.loose` set the shared gap to `0.5rem` or `1.5rem` on views,
-  stacks, clusters, and auto-grids.
+- `.tight` and `.loose` set the shared gap to `0.5rem` or `1.5rem` on views, stacks, clusters, and auto-grids.
 - `.section` adds responsive block padding and an inline gutter.
-- `.section-content` centers content at `--container-max`; `.narrow` and
-  `.wide` select the corresponding container tokens.
-- `.divider` is horizontal; `.vertical` makes it self-stretch vertically. It
-  takes intent, but presentation classes do not affect it.
+- `.section-content` centers content at `--container-max`; `.narrow` and `.wide` select the corresponding container tokens.
+- `.divider` is horizontal; `.vertical` makes it self-stretch vertically. It takes intent, but presentation classes do not affect it.
+- `.visually-hidden` hides content visually while keeping it in the accessibility tree, using the standard clip-based recipe. Not named `.sr-only`: on a `/tw` entry the consumer's own Tailwind build already ships a real `.sr-only`, and a same-named utility of this package's own would silently collide with it in the cascade — the same reason `.data-table` is not named `.table`.
 
-The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no
-compatibility aliases.
+The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no compatibility aliases.
 
 ## Content
 
@@ -1184,8 +1226,7 @@ compatibility aliases.
 
 ### Table rules
 
-A table draws three kinds of line, and `.ruled` and `.ruleless` move all of
-them together:
+A table draws three kinds of line, and `.ruled` and `.ruleless` move all of them together:
 
 | Class       | Head and foot boundaries | Rules between body rows |
 | ----------- | ------------------------ | ----------------------- |
@@ -1194,36 +1235,32 @@ them together:
 | `.ruled`    | Yes                      | Yes                     |
 
 ```html
-<table class="data-table">Head and foot boundaries only</table>
-<table class="data-table ruled">Every row separated</table>
-<table class="data-table ruleless">No lines inside the table at all</table>
+<table class="data-table">
+  Head and foot boundaries only
+</table>
+<table class="data-table ruled">
+  Every row separated
+</table>
+<table class="data-table ruleless">
+  No lines inside the table at all
+</table>
 ```
 
-The boundaries under a head and above a foot separate the parts of a table
-from each other, so they are drawn by default where the row rules are not.
-Rules between body rows used to arrive on their own, because the
-component's published edge default is `edged` and the edge axis wrote the
-rules along with the boundary — so whether you got them depended on a
-registry default rather than on anything in your markup.
+The boundaries under a head and above a foot separate the parts of a table from each other, so they are drawn by default where the row rules are not. Rules between body rows used to arrive on their own, because the component's published edge default is `edged` and the edge axis wrote the rules along with the boundary — so whether you got them depended on a registry default rather than on anything in your markup.
 
-`--ui-rule` is the token behind both classes, so a container can set the
-answer for a whole region without classing each table:
+`--ui-rule` is the token behind both classes, so a container can set the answer for a whole region without classing each table:
 
 ```html
 <section style="--ui-rule: 100%">
-  <table class="data-table">Ruled by the region</table>
+  <table class="data-table">
+    Ruled by the region
+  </table>
 </section>
 ```
 
-The frame around the table is the edge axis and is asked for the same way:
-`.data-table` publishes `edgeless`, so `.edged` draws one. None of the
-three switches reaches the others — `.data-table.ruleless.edged` is a
-framed table with no lines inside it, and `.data-table.ruled` is a
-frameless one with every row separated.
+The frame around the table is the edge axis and is asked for the same way: `.data-table` publishes `edgeless`, so `.edged` draws one. None of the three switches reaches the others — `.data-table.ruleless.edged` is a framed table with no lines inside it, and `.data-table.ruled` is a frameless one with every row separated.
 
-A table's rows deliberately inherit its intent instead of resetting it, so
-`.data-table.success` tints throughout. A row carrying its own intent still
-wins:
+A table's rows deliberately inherit its intent instead of resetting it, so `.data-table.success` tints throughout. A row carrying its own intent still wins:
 
 ```html
 <table class="data-table success">
@@ -1238,37 +1275,30 @@ wins:
 </table>
 ```
 
-This is the one place intent cascades, because a table's rows are parts of
-the table rather than independent components.
+This is the one place intent cascades, because a table's rows are parts of the table rather than independent components.
 
-`.data-table`, `.kbd`, `.code`, and `.pre` also read
-[presentation](docs/usage/composing.md#presentation). A table applies it to its
-header, its rules and its border; a chip to its whole plate:
+`.data-table`, `.kbd`, `.code`, and `.pre` also read [presentation](docs/usage/composing.md#presentation). A table applies it to its header, its rules and its border; a chip to its whole plate:
 
 ```html
-<table class="data-table success soft edged">...</table>
-<table class="data-table">A ghost table: rules and type, no header plate</table>
+<table class="data-table success soft edged">
+  ...
+</table>
+<table class="data-table">
+  A ghost table: rules and type, no header plate
+</table>
 <kbd class="kbd primary solid">Ctrl</kbd>
 <kbd class="kbd primary soft edged">Shift</kbd>
 ```
 
-`.ghost` means two different things on these components, and both are worth
-knowing before you reach for it.
+`.ghost` means two different things on these components, and both are worth knowing before you reach for it.
+
+On `.data-table` it removes the header plate along with the body tint, so `.data-table.ghost` is boundaries and type alone. The component rests at `soft`, so that is something to ask for rather than the default.
 
-On `.data-table` it removes the header plate along with the body tint, so
-`.data-table.ghost` is boundaries and type alone. The component rests at
-`soft`, so that is something to ask for rather than the default.
+`.soft` rests untinted throughout -- `--color-foreground`, no intent color mixed in, for every intent, including the resting default, on the head plate and the table's own base fill alike. A table has no hover or interaction state to reveal a tint into the way `.card.soft` does on `.interactive`/`.hoverable`, so unlike a card there is no state where a `.data-table.success.soft` reveals green; only the boundary and rule lines still read the intent.
 
-On `.kbd`, `.code`, and `.pre` it is **not supported**. All three rest on
-`--intent-subtle`, and that ground draws the plate whatever the fill says —
-so `.ghost` took the fill away and changed nothing visible. Worse, the
-ground alone is a near-page tint: a ghost chip measured the same `#e5e5e5`
-for neutral and primary on the light page, and `#f5f5f5` at 1.04:1 against
-it for secondary. All three rest at `.soft` instead, which puts a real `12%`
-of the intent over the ground and separates them.
+On `.kbd`, `.code`, and `.pre` it is **not supported**. All three rest on `--intent-subtle`, and that ground draws the plate whatever the fill says — so `.ghost` took the fill away and changed nothing visible. Worse, the ground alone is a near-page tint: a ghost chip measured the same `#e5e5e5` for neutral and primary on the light page, and `#f5f5f5` at 1.04:1 against it for secondary. A named intent rests at `.soft` instead, which puts a real `12%` of the intent over the ground and separates it from the others; the no-named-intent case reads no differently from `.ghost` either way, so it rests at the ground alone rather than adding an unmotivated wash of its own.
 
-Use `.table-wrap` around `.data-table` when table width may exceed its
-container:
+Use `.table-wrap` around `.data-table` when table width may exceed its container:
 
 ```html
 <div class="table-wrap">
@@ -1291,38 +1321,38 @@ container:
 
 ## Surfaces
 
-| Class                | Purpose                                                                      |
-| -------------------- | ---------------------------------------------------------------------------- |
-| `.card`              | Bordered container, surface radius, padded. Rests at elevation `1`.          |
-| `.panel`             | Flush container for sidebars, toolbars, and wells. No elevation.             |
-| `.interactive`       | On `.card`. Adds pointer cursor, hover and press response, and a focus ring. |
-| `.p-sm`, `.compact`  | On `.card` or `.panel`. Reduces padding.                                     |
-| `.p-lg`, `.spacious` | On `.card` or `.panel`. Increases padding.                                   |
-| `.flush`             | On `.card` or `.panel`. Removes padding, for edge-to-edge content.           |
-
-Both read intent, [presentation](docs/usage/composing.md#presentation), and
-[material tokens](docs/usage/customizing.md#material-tokens). A plain `.card` is a
-neutral bordered container; only an explicit presentation tints it. Resting
-at elevation `1` is not a visible shadow by itself — nothing draws depth
-until an [aesthetic](docs/usage/aesthetics.md) supplies shadow geometry or
-`.elevation-sm`/`.elevation-md` asks for it; see
-[Composing → Elevation](docs/usage/composing.md#elevation).
-
-On the base look, `.card.interactive` scales down slightly on press
-(`--ui-active-transform`, `scale(0.97)`); an [aesthetic](docs/usage/aesthetics.md)
-substitutes its own press gesture, and `prefers-reduced-motion` turns it off.
+| Class                | Purpose                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `.card`              | Bordered container, surface radius, padded. Rests at elevation `1`.                   |
+| `.panel`             | Flush container for sidebars, toolbars, and wells. No elevation.                      |
+| `.interactive`       | On `.card`. Adds pointer cursor, hover and press response, and a focus ring.          |
+| `.hoverable`         | On `.card`. The hover half of `.interactive`: hover response only, no pointer cursor. |
+| `.pressable`         | On `.card`. The press half of `.interactive`: press response and pointer cursor.      |
+| `.p-xs`, `.dense`    | On `.card` or `.panel`. Reduces padding further than `.compact`.                      |
+| `.p-sm`, `.compact`  | On `.card` or `.panel`. Reduces padding.                                              |
+| `.p-lg`, `.spacious` | On `.card` or `.panel`. Increases padding.                                            |
+| `.flush`             | On `.card` or `.panel`. Removes padding, for edge-to-edge content.                    |
+
+Both read intent, [presentation](docs/usage/composing.md#presentation), and [material tokens](docs/usage/customizing.md#material-tokens). A plain `.card` is a neutral bordered container; only an explicit presentation tints it. Resting at elevation `1` is not a visible shadow by itself — nothing draws depth until an [aesthetic](docs/usage/aesthetics.md) supplies shadow geometry or `.elevation-sm`/`.elevation-md` asks for it; see [Composing → Elevation](docs/usage/composing.md#elevation).
+
+`.card.soft` with no named intent is untinted at rest — a plain `--color-foreground` plate, no ink mixed in, marking a different container without drawing attention to it. The intent tint and a `--color-surface` ground only appear together, on `:hover`, and only on `.card.interactive`/`.card.hoverable`: a plain `.card.soft` with neither has no hover state to reveal into and stays at the quiet rest. A named intent (`.card.soft.success`, `.card.soft.destructive`, and so on) keeps its ordinary tint at rest instead, and deepens further on hover the same way any other filled surface does — only the no-intent case is untinted, since removing an intent's own color would silence it rather than quiet it. `.solid` and `.ghost` are unaffected either way.
+
+`.panel` with no named intent behaves the same way, permanently rather than on hover: a plain `.panel` rests at the same untinted `--color-foreground` plate a neutral `.card.soft` does, because a panel has no hover state to reveal a tint into. `.panel.primary`, `.panel.destructive`, and every other named intent keep their ordinary tint. `.kbd`, `.code`, and `.pre` follow the same no-named-intent rule for their own fill, without moving off their `--intent-subtle` ground.
+
+On the base look, `.card.interactive` scales down slightly on press (`--ui-active-transform`, `scale(0.97)`); an [aesthetic](docs/usage/aesthetics.md) substitutes its own press gesture, and `prefers-reduced-motion` turns it off.
+
+`.interactive` is the pair `.hoverable` (hover response only, no pointer cursor) and `.pressable` (press response and pointer cursor) applied together. Take one half for a card that answers a single gesture: a card that warms on hover but holds its own action in a nested button takes `.hoverable`, so pressing that button does not dip the whole card.
 
 ```html
 <article class="card">Neutral card</article>
-<article class="card success soft">Tinted success card</article>
+<article class="card success solid">Filled success card</article>
 <article class="card primary ghost edged">Intent border, no fill</article>
-<a class="card interactive" href="/package">Responds to hover and press</a>
+<a class="card success soft interactive" href="/package">Success-tinted at rest; deepens on hover</a>
+<article class="card hoverable">Warms on hover; the action is a nested button</article>
 <aside class="panel">Flush panel</aside>
 ```
 
-`.interactive` is styling only. Use a real interactive element and give it
-an accessible name; a `<div class="card interactive">` is not focusable or
-operable by keyboard.
+`.interactive` and `.pressable` are styling only. Use a real interactive element and give it an accessible name; a `<div class="card interactive">` is not focusable or operable by keyboard.
 
 ## Typography utilities
 
@@ -1339,784 +1369,437 @@ All typography classes and `.selection-contrast` are `@utility` classes.
 | `.text-body`          | Default body copy.                                           |
 | `.selection-contrast` | Inverts `::selection` colors to primary-contrast background. |
 
-<!-- Source: docs/usage/customizing.md -->
+<!-- Source: docs/integrating/index.md -->
 
-# Customizing
+# Integrating
 
-Presentation tokens decide how much of an intent shows. Material tokens
-decide what a component is made of. Aesthetic tokens are the small set of
-named knobs a shipped aesthetic exposes to scale its own look.
+This package has no JavaScript and no framework bindings; see [Introduction](docs/index.md#what-it-does-not-do). Integrating it into a framework is entirely about where that framework lets you load a global stylesheet, and whether the project runs Tailwind CSS v4.
 
-## Presentation tokens
+## The shared model
 
-Presentation tokens describe _how much_ of an intent a component shows,
-never _which_ intent it shows. They are unitless numbers and percentages, so
-they carry no color and inherit safely: a container sets them once and every
-component below resolves them against its own intent.
+Every stack does the same two imports, from the same kind of place — a root layout, an app entry file, or a global CSS file, never a page or a component further down the tree:
 
-| Token             | Purpose                                                                    |
-| ----------------- | -------------------------------------------------------------------------- |
-| `--ui-fill`       | Percentage of the intent color mixed into the background.                  |
-| `--ui-fg-on-fill` | Percentage blended from the intent readable tone toward its contrast tone. |
-| `--ui-border`     | Percentage of the intent color mixed into the border color.                |
+1. One [entrypoint](docs/setup.md#import-paths) — the compiled `@codenhub/styles` for any build, or `@codenhub/styles/tw` when the project already runs Tailwind CSS v4.
+2. `@codenhub/styles/aesthetics` (or `/tw/aesthetics`) after it, only if the project uses an [aesthetic](docs/usage/aesthetics.md).
 
-A component resolves them with `color-mix` from its published default. Hover
-is derived by adding `--hover-step` to the resting fill and using
-`--intent-hover`; there are no per-presentation hover tokens.
+Importing from one place matters for two reasons. Some frameworks only _allow_ global CSS from a designated root file and fail the build otherwise — Next.js's Pages Router is one, see [Next.js → Troubleshooting](docs/integrating/nextjs.md#troubleshooting). Where a framework allows it more broadly, as Next.js's App Router does, importing from the root remains the recommended choice for predictable CSS ordering — and importing per-component instead would load the same reset and token rules once per component rather than once per app.
 
-No fill class writes `--ui-border` and no edge class writes `--ui-fill`. A
-filled box with no line is `.solid.edgeless`, which is worth reaching for on
-a neutral component: neutral caps its fill, so the box stays translucent and
-a border over it paints a second coat of the same tint instead of blending
-into it.
+## Which guide to follow
 
-```css
-background: color-mix(in oklab, var(--color-primary) var(--ui-fill, 100%), transparent);
+| Stack                                    | Guide                            |
+| ---------------------------------------- | -------------------------------- |
+| A Tailwind CSS v4 project on any bundler | [Tailwind CSS v4](docs/integrating/tailwind.md) |
+| Next.js / React                          | [Next.js](docs/integrating/nextjs.md)           |
+| Vue                                      | [Vue](docs/integrating/vue.md)                  |
+| Svelte / SvelteKit                       | [Svelte](docs/integrating/svelte.md)            |
+| Astro                                    | [Astro](docs/integrating/astro.md)              |
+
+A project with no framework — a plain Vite, webpack, or Parcel build — needs nothing beyond [Setup → Quick start](docs/setup.md#quick-start): import the compiled stylesheet from the project's existing global CSS entry.
+
+## Verifying it worked
+
+After the import, render one styled element and confirm it picked up the package's tokens rather than the browser default:
+
+```html
+<button class="btn primary">Continue</button>
 ```
 
-Two choices there are deliberate. Mixing toward `transparent` rather than a
-background token lets a tinted surface adapt to whatever it is placed on.
-Mixing in `oklab` keeps the wide-gamut token palette intact and blends
-perceptually, where `srgb` would clip it.
+A rounded, filled button in the primary color means the stylesheet loaded. Unstyled browser-default text most often means the import specifier didn't resolve — check the [import paths table](docs/setup.md#import-paths) for the exact one your entrypoint needs, and confirm your build tooling resolves package CSS imports at all, see [Setup → Requirements](docs/setup.md#requirements).
 
-A computed color therefore reaches the page as a resolved `color-mix` result
-rather than the token's own `oklch` syntax. It is the same color; code that
-compares computed color strings should compare colors instead.
+<!-- Source: docs/integrating/tailwind.md -->
 
-> **Presentation token contract**: only presentation classes and consumer
-> overrides set these tokens; components only read them. Setting a value
-> that no presentation class produces is supported but unvalidated. See
-> [Composing](docs/usage/composing.md) for the classes that ship these values.
+# Tailwind CSS v4
 
-## Material tokens
+A project that already runs Tailwind CSS v4 can process this package's source instead of its compiled output, so both sets of classes compile through the same Tailwind build.
 
-Material tokens describe what a component is _made of_ rather than which
-intent it shows or how strongly. They control shape, borders, shadows,
-translucency, filters, and transforms.
+## Why source instead of compiled
 
-Components read each with a fallback, so leaving them unset produces the
-default look. Setting them on a container restyles the whole subtree. Only
-shadow geometry is split into colorless parts that inherit safely;
-color-capable inputs such as `--ui-ink` and `--ui-surface-shadow` may
-include their own colors.
+`/tw` entrypoints publish copied, uncompiled source from `dist/tw`; your own Tailwind build compiles it alongside your app, so its `@theme`, `@utility`, and `@apply` directives resolve together with yours. The compiled entrypoints (`@codenhub/styles`) still work in a Tailwind project, but then two separate CSS pipelines run side by side instead of one — use `/tw` unless a specific reason rules it out.
 
-| Token                   | Purpose                                                                                                       | Fallback             |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
-| `--ui-radius`           | Corner radius for controls.                                                                                   | `--radius-control`   |
-| `--ui-radius-surface`   | Corner radius for surfaces.                                                                                   | `--radius-surface`   |
-| `--ui-border-width`     | Edge thickness.                                                                                               | `--border-width`     |
-| `--ui-border-max`       | Ceiling on computed edge width.                                                                               | `100px`              |
-| `--ui-ink`              | Neutral line color when no intent is set.                                                                     | `--color-border`     |
-| `--ui-rule`             | Lines inside a table. Unset draws the head and foot boundaries only; `0%` draws none; `100%` rules every row. | unset                |
-| `--ui-shadow-x`         | Shadow horizontal offset.                                                                                     | `0px`                |
-| `--ui-shadow-y`         | Shadow vertical offset.                                                                                       | `0px`                |
-| `--ui-shadow-blur`      | Shadow blur radius.                                                                                           | `0px`                |
-| `--ui-shadow-spread`    | Shadow spread radius.                                                                                         | `0px`                |
-| `--ui-shadow-inset`     | The `inset` keyword for an inner ring.                                                                        | Empty                |
-| `--ui-hover-shadow-x`   | Shadow horizontal offset while hovered.                                                                       | `--ui-shadow-x`      |
-| `--ui-hover-shadow-y`   | Shadow vertical offset while hovered.                                                                         | `--ui-shadow-y`      |
-| `--ui-active-shadow-x`  | Shadow horizontal offset while pressed.                                                                       | `--ui-shadow-x`      |
-| `--ui-active-shadow-y`  | Shadow vertical offset while pressed.                                                                         | `--ui-shadow-y`      |
-| `--ui-active-transform` | Transform while pressed. `none` under `prefers-reduced-motion`.                                               | `scale(0.97)`        |
-| `--ui-shadow-ink`       | Percentage of shadow color taken from intent ink.                                                             | `0%`                 |
-| `--ui-shadow-edge`      | Declared, even empty, when the shadow is the element's edge rather than its depth. Read for presence.         | Unset                |
-| `--ui-elevation`        | Unitless multiplier over shadow geometry.                                                                     | `1`                  |
-| `--ui-surface-shadow`   | Complete multi-layer shadow accepted by surfaces only.                                                        | Unset                |
-| `--ui-surface-ground`   | Ground a surface sits on.                                                                                     | `--color-background` |
-| `--ui-bg-alpha`         | Multiplier over fill for translucent materials.                                                               | `1`                  |
-| `--ui-backdrop`         | Backdrop filter accepted by surfaces only.                                                                    | `none`               |
-| `--ui-hover-transform`  | Transform while an interactive element is hovered.                                                            | `none`               |
-| `--ui-clip`             | Structural component silhouette.                                                                              | `none`               |
-| `--ui-clip-tight`       | Compact component silhouette.                                                                                 | `--ui-clip`          |
-| `--ui-focus-inset`      | Inset focus layer width.                                                                                      | Unset                |
+## Import the source entrypoint
 
-```html
-<section style="--ui-radius: 0; --ui-border-width: 3px">
-  <button class="btn primary">Square and heavy</button>
-  <input class="ipt" placeholder="Matches" />
-</section>
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw";
+
+@source "./src";
 ```
 
-> **Material token contract**: components read these; aesthetic classes and
-> consumer overrides set them.
+Tailwind CSS v4 scans your project automatically — most projects need nothing beyond the two imports above. `@source` paths resolve relative to the CSS file that declares them, not your project root, so `./src` here means "the `src/` next to this stylesheet"; adjust it to match where your own global stylesheet actually lives. Add `@source` only for markup Tailwind's automatic scan won't reach on its own: a path excluded by default (`.gitignore`d, or inside `node_modules` — an external component library, for instance) or, in a monorepo, one outside this file's own directory tree. Point it at your app's markup, not at this package — `/tw` already ships every class definition it publishes, so scanning it too only slows the build without adding classes.
 
-### Shape and ring composition
+## Add aesthetics
 
-Clipping removes borders, outlines, and outer shadows. An aesthetic that uses
-a clip can replace the border with an inset shadow by setting
-`--ui-shadow-inset` and the four shadow geometry parts. Set
-`--ui-border-max: 0px` when that ring replaces the component border.
-Focusable components restore the clipped focus outline through
-`--ui-focus-inset`.
-
-Declare `--ui-shadow-edge` when that ring _is_ the border. The ring then
-takes the element's edge color, which carries the edge axis as its alpha, so
-`.edged` draws it and `.edgeless` does not — the same answer a real border
-gives. Without it the ring paints on every component the aesthetic reaches
-and the edge classes have no effect. Use `--ui-shadow-ink` instead when the
-shadow is depth cast in the intent's own ink, such as a hard offset slab,
-which an `.edgeless` element still gets.
-
-The token is read for its presence, not its value: declare it empty to
-switch the ring on, and `initial` to switch it back off in an aesthetic
-nested inside one that declares it.
+Add an aesthetic from the source entrypoint the same way as the compiled one, after the base import:
 
 ```css
-.stepped {
-  --ui-clip: polygon(/* structural silhouette */);
-  --ui-clip-tight: none;
-  --ui-border-max: 0px;
-  --ui-shadow-inset: inset;
-  --ui-shadow-edge: ;
-  --ui-shadow-x: 0px;
-  --ui-shadow-y: 0px;
-  --ui-shadow-blur: 0px;
-  --ui-shadow-spread: 4px;
-  --ui-focus-inset: var(--focus-ring-width);
+@import "tailwindcss";
+@import "@codenhub/styles/tw";
+@import "@codenhub/styles/tw/aesthetics";
+
+@source "./src";
+```
+
+## Using a focused entrypoint
+
+Import a focused `/tw/*` entrypoint instead of the combined one — such as `/tw/button` or `/tw/form` — when a build only needs one component family; see the full [import path table](docs/setup.md#import-paths) for what each one composes.
+
+## Troubleshooting
+
+**Classes resolve to no styling**
+
+- **What happened:** components use documented classes like `.btn.primary`, but no styling appears even though `@import "@codenhub/styles/tw"` is in the stylesheet.
+- **Why:** this is rarely `@source` itself — Tailwind already scans your project automatically. The more common cause is markup living somewhere that automatic scan excludes by default: a `.gitignore`d path, or a component pulled from `node_modules`. Tailwind may not see a class used only there and skips generating a rule for it.
+- **Fix:** add an explicit `@source` pointing at that directory, resolved relative to this stylesheet — matching the [example above](#import-the-source-entrypoint).
+
+**Duplicate token and reset rules**
+
+- **What happened:** the built stylesheet is larger than expected, and browser devtools show the same custom properties or reset rules defined twice.
+- **Why:** importing both a compiled entrypoint (`@codenhub/styles`) and a `/tw` entrypoint (`@codenhub/styles/tw`) in the same build compiles the same tokens and reset from two independent sources; Tailwind's build has no way to know they describe the same package.
+- **Fix:** pick one path per project — `/tw` entrypoints for a project running Tailwind CSS v4, compiled entrypoints everywhere else.
+
+Tailwind CSS 4 or newer is required for every `/tw` entrypoint.
+
+<!-- Source: docs/integrating/nextjs.md -->
+
+# Next.js
+
+Next.js has two router architectures, and they treat global CSS differently:
+
+- **App Router** (an `app/` directory): global CSS — including an external package's stylesheet like this one — can be imported from any layout, page, or component under `app/`. Importing it from the root layout is only a recommendation, for predictable CSS ordering across routes; Next.js does not enforce it and no error occurs if you import it elsewhere.
+- **Pages Router** (a `pages/` directory, no `app/`): global CSS is restricted to `pages/_app.tsx`. Importing it from anywhere else fails the build — Next.js enforces this itself, not this package; see [Troubleshooting](#troubleshooting).
+- **Both directories present** (mid-migration): import the stylesheet in both root files. The two routers serve their own routes independently, so a route under `pages/` never sees a stylesheet imported only in `app/layout.tsx`, and vice versa.
+
+## Import the stylesheet
+
+Add the import to the root file for your router:
+
+**App Router**
+
+```tsx
+// app/layout.tsx
+import "@codenhub/styles";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
 }
 ```
 
-Variables named `--shape-*` are internal composition outputs. Do not set or
-read them; only the `--ui-*` inputs above are public.
+**Pages Router**
 
-## Aesthetic tokens
+```tsx
+// pages/_app.tsx
+import "@codenhub/styles";
+import type { AppProps } from "next/app";
 
-The shipped [aesthetic classes](docs/usage/aesthetics.md) set material tokens for you.
-Only aesthetics with a token listed below expose an aesthetic-specific
-token. Tune all other behavior through the shared material tokens above.
-Listed tokens are available only where that aesthetic's stylesheet is
-imported.
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
 
-| Token                    | Aesthetic       | Purpose                                                     | Default                           |
-| ------------------------ | --------------- | ----------------------------------------------------------- | --------------------------------- |
-| `--neo-offset`           | `.neobrutalism` | Hard shadow offset and distance the press travels.          | `4px`                             |
-| `--glass-radius`         | `.glass`        | Control corner radius.                                      | `0.75rem`                         |
-| `--glass-radius-surface` | `.glass`        | Surface corner radius.                                      | `1rem`                            |
-| `--pixel-unit`           | `.pixel`        | One pixel of the grid. The corner cut and the ring are one. | `4px`                             |
-| `--font-pixel`           | `.pixel`        | Consumer-supplied pixel font stack.                         | Falls back to the monospace stack |
-| `--tile-radius`          | `.chunky-tile`  | Corner radius, on controls and surfaces alike.              | `0.75rem`                         |
-| `--tile-lift`            | `.chunky-tile`  | Depth of the seated bar, and how far a press travels.       | `4px`                             |
-| `--font-rounded`         | `.chunky-tile`  | Consumer-supplied rounded font stack.                       | Falls back to the page stack      |
+Running Tailwind CSS v4? `@import "@codenhub/styles/tw"` is a CSS directive, so it belongs in a CSS file, not a bare import in `layout.tsx`/`_app.tsx` — add it (with `@import "tailwindcss"` and, if needed, `@source`) to your global CSS file, and import that file from the same root file shown above instead. See [Tailwind CSS v4](docs/integrating/tailwind.md).
 
-All four aesthetics reach the same way: each knob is _read_ with its default
-as a `var()` fallback rather than declared, so it resolves once into a
-private on the aesthetic's own class (`--_pixel-unit`, `--_neo-offset`,
-`--_tile-radius`, `--_tile-lift`, and so on). Set a knob on the element
-carrying the aesthetic class, or on any ancestor including `:root`:
+## Force a theme
 
-```html
-<section class="pixel" style="--pixel-unit: 6px">
-  <button class="btn primary">Chunkier</button>
-</section>
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following the system preference; see [Setup → Configuration](docs/setup.md#configuration).
+
+```tsx
+<html lang="en" className="dark">
 ```
 
-```html
-<html class="pixel" style="--pixel-unit: 6px">
-  <body>
-    <button class="btn primary">Also chunkier, set from the root</button>
-  </body>
-</html>
+## Troubleshooting
+
+**Pages Router build fails with "Global CSS cannot be imported from files other than your Custom `<App>`"**
+
+- **What happened:** Next.js rejected a global CSS `import` statement outside `pages/_app.tsx`. This restriction is specific to the Pages Router — Next.js enforces it itself, not this package, and it applies to any global CSS import, not specifically to `@codenhub/styles`. It does not apply to the App Router, where the same import works from any layout, page, or component.
+- **Why:** the Pages Router has no per-route CSS boundary the way the App Router does, so Next.js requires one predictable file for global stylesheets to avoid ordering conflicts between pages.
+- **Fix:** move the `import "@codenhub/styles"` line to `pages/_app.tsx`, and remove it from wherever it currently is.
+
+## See also
+
+- [Setup → Import paths](docs/setup.md#import-paths): every entrypoint this package publishes.
+- [Usage](docs/usage/index.md): component classes to compose once the stylesheet is loaded.
+
+<!-- Source: docs/integrating/vue.md -->
+
+# Vue
+
+Vue places no restriction on where CSS is imported from, but importing it once, from the app's entry file, keeps the reset and tokens from loading more than once and guarantees they're in place before any component renders.
+
+## Import the stylesheet
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { createApp } from "vue";
+import App from "./App.vue";
+
+createApp(App).mount("#app");
 ```
 
-Knobs and material tokens reach in opposite directions, and telling them
-apart matters. A knob resolves once at the aesthetic's own class and
-inherits down already-resolved, so it reaches the aesthetic **from above**:
-setting it on the element or any ancestor works, but setting it on a
-_descendant_ of the aesthetic class changes nothing — the value has already
-been read. `--ui-radius` and the other material tokens above are read fresh
-by each component as it draws, so they reach **at or below** the element
-carrying them, which is how you round one card differently from its
-neighbours without touching the knob at all.
+Running Tailwind CSS v4? Import `@codenhub/styles/tw` from a CSS entry file instead of `main.ts`, using the `@tailwindcss/vite` plugin — see [Tailwind CSS v4](docs/integrating/tailwind.md).
 
-Shipped aesthetics set the shared material tokens above. `.neobrutalism` and
-`.pixel` set `--ui-ink` for their neutral outline; intent classes still
-override the intent slots on each component.
+## Force a theme
 
-## Component internals
+Apply `.dark` or `.light` on the root element to force a theme instead of following the system preference; see [Setup → Configuration](docs/setup.md#configuration).
 
-Component classes may define scoped implementation variables such as
-`--button-*`, `--surface-*`, `--control-*`, `--feedback-*`, and `--tooltip-*`.
-These variables are internal wiring for class composition and are not the
-public token contract.
+## See also
 
-Consumers should customize broad behavior through color, foundation, motion,
-elevation, radius, layout, and focus tokens first. The only supported
-component-scoped input is `--progress-value` on the `.progress` element,
-because consumers must provide a value such as `64%`.
+- [Setup → Import paths](docs/setup.md#import-paths): every entrypoint this package publishes.
+- [Usage](docs/usage/index.md): component classes to compose once the stylesheet is loaded.
 
-`--layout-gap` replaces the removed `--layout-stack-gap` and
-`--layout-cluster-gap` tokens. No compatibility aliases are provided.
+<!-- Source: docs/integrating/svelte.md -->
 
-Next: [Aesthetics](docs/usage/aesthetics.md) covers each shipped aesthetic's complete
-look and its documented exceptions.
+# Svelte
 
-<!-- Source: docs/usage/feedback.md -->
+## Import the stylesheet
 
-# Feedback
+**SvelteKit** — import from the root layout so it loads once for every route:
 
-| Class            | Purpose                                                                      |
-| ---------------- | ---------------------------------------------------------------------------- |
-| `.alert`         | Inline feedback surface.                                                     |
-| `.icon`          | Subclass of `.alert`. Adds a corresponding intent icon and padding.          |
-| `.badge`         | Compact status pill.                                                         |
-| `.loader-mask`   | Low-level activity indicator composition utility. Applies the spinner mask.  |
-| `.loader`        | Standalone inline loader artwork.                                            |
-| `.skeleton`      | Ambient loading placeholder.                                                 |
-| `.progress`      | Progress track. Uses `--progress-value` variable.                            |
-| `.active`        | Optional on `.progress` to add a track shimmer.                              |
-| `.indeterminate` | Optional on `.progress` to animate a moving fill without `--progress-value`. |
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import "@codenhub/styles";
+  let { children } = $props();
+</script>
+
+{@render children()}
+```
+
+**Plain Svelte + Vite** — import from the entry file instead:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { mount } from "svelte";
+import App from "./App.svelte";
 
-Activity indicator modifier classes compose with `.loader`:
+mount(App, { target: document.getElementById("app")! });
+```
 
-| Class                  | Animation style                         |
-| ---------------------- | --------------------------------------- |
-| _(default)_            | Circular spinner (rotating arc).        |
-| `.dots-wave`           | Three dots bouncing up/down in a wave.  |
-| `.dots-fade`           | Three dots fading in and out.           |
-| `.dots-queue`          | Dot queuing from left to right.         |
-| `.dots-rotate`         | Side dots rotating around a center dot. |
-| `.dots-grow`           | Three dots growing and shrinking.       |
-| `.dots-grow-alternate` | Outer dots small, center dot pulses.    |
-| `.dot-bounce`          | Single dot bouncing with squash effect. |
-| `.bars-wave`           | Three vertical bars scaling in a wave.  |
-| `.pulse-ring`          | Two concentric rings pulsing outward.   |
+Running Tailwind CSS v4? Import `@codenhub/styles/tw` from the app's CSS entry instead — see [Tailwind CSS v4](docs/integrating/tailwind.md).
 
-These variants retain their embedded SVG animations normally. Under
-`prefers-reduced-motion: reduce`, loader CSS substitutes a corresponding
-static mask. This fallback is part of focused loader, button, and components
-imports; it does not depend on the global reset. See
-[Accessibility](docs/accessibility.md).
+## Force a theme
 
-Loader size modifiers:
+Apply `.dark` or `.light` on `<html>` (edit `src/app.html` in SvelteKit) to force a theme instead of following the system preference; see [Setup → Configuration](docs/setup.md#configuration).
 
-| Class    | Size              |
-| -------- | ----------------- |
-| _(none)_ | Default (`2rem`). |
-| `.sm`    | Small (`1.5rem`). |
-| `.lg`    | Large (`2.5rem`). |
+## See also
 
-Alerts, badges, progress bars, skeletons, and loaders accept `.primary`,
-`.secondary`, `.success`, `.warning`, `.destructive`, `.danger`, `.error`,
-and `.info`. Without an intent, they use the text palette, except `.loader`,
-which keeps `currentColor` so it matches whatever content surrounds it.
+- [Setup → Import paths](docs/setup.md#import-paths): every entrypoint this package publishes.
+- [Usage](docs/usage/index.md): component classes to compose once the stylesheet is loaded.
 
-Skeletons, loaders, progress bars, and dividers are indicators. They read
-intent but ignore fill and edge [presentation](docs/usage/composing.md#presentation).
+<!-- Source: docs/integrating/astro.md -->
 
-```html
-<span class="loader success" aria-hidden="true"></span>
-<span class="skeleton info"></span>
-```
+# Astro
 
-`.icon` is a subclass of `.alert`. When applied as `.alert.icon`, it
-increases the left padding and adds an embedded SVG. Success, warning, and
-destructive intents use corresponding symbols; other intents use the
-information symbol.
+Astro renders components statically by default, but a global stylesheet import still only needs to happen once — from a shared layout, not from individual pages or islands.
 
-Alerts and badges read the shared [presentation](docs/usage/composing.md#presentation)
-classes. Without one they use a tinted surface, intent-colored text, and a
-mixed intent border.
+## Import the stylesheet
 
-## Example
+```astro
+---
+// src/layouts/Layout.astro
+import "@codenhub/styles";
+---
 
-```html
-<div class="alert success" role="status">Saved successfully.</div>
-<div class="alert primary solid" role="status">Deployment started.</div>
-<div class="alert warning soft icon" role="status">Review required.</div>
-<div class="alert destructive ghost edged" role="alert">Deployment failed.</div>
-<span class="badge warning">Queued</span>
-<span class="badge success solid">Live</span>
-<span class="badge info soft">Draft</span>
-<span class="loader" aria-hidden="true"></span>
-<span class="loader dots-wave" aria-hidden="true"></span>
-<span class="loader dots-fade" aria-hidden="true"></span>
-<span class="loader bars-wave" aria-hidden="true"></span>
-<span class="loader pulse-ring sm" aria-hidden="true"></span>
-<span class="loader dots-grow lg" aria-hidden="true"></span>
-<div
-  class="progress"
-  role="progressbar"
-  aria-label="Upload progress"
-  aria-valuemin="0"
-  aria-valuemax="100"
-  aria-valuenow="64"
-  style="--progress-value: 64%"
-></div>
-<div
-  class="progress secondary active"
-  role="progressbar"
-  aria-label="Upload progress"
-  aria-valuemin="0"
-  aria-valuemax="100"
-  aria-valuenow="64"
-  style="--progress-value: 64%"
-></div>
-<div
-  class="progress info indeterminate"
-  role="progressbar"
-  aria-label="Loading"
-  aria-valuemin="0"
-  aria-valuemax="100"
-></div>
+<html lang="en">
+  <body>
+    <slot />
+  </body>
+</html>
 ```
 
-Add `role="status"` or `role="alert"` to alerts based on announcement
-urgency, mark decorative loading visuals with `aria-hidden="true"`, and use
-semantic progress elements or ARIA values when numeric progress must be
-announced; see [Accessibility](docs/accessibility.md).
+Every page that uses this layout loads the stylesheet once. Running Tailwind CSS v4? Import `@codenhub/styles/tw` through Astro's Tailwind integration instead — see [Tailwind CSS v4](docs/integrating/tailwind.md), including when an explicit `@source` is actually needed.
 
-<!-- Source: docs/usage/forms.md -->
-
-# Forms
+## Force a theme
 
-| Class or Selector                                                     | Purpose                                                       |
-| --------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `.field`                                                              | Vertical field wrapper.                                       |
-| `.label`                                                              | Form label text.                                              |
-| `.hint`                                                               | Secondary helper text.                                        |
-| `.hint.error`                                                         | 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 icons. |
-| `.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.                                             |
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following the system preference; see [Setup → Configuration](docs/setup.md#configuration).
 
-## Icons
+## See also
 
-The package ships no icons. 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 are the consumer's to choose now.
+- [Setup → Import paths](docs/setup.md#import-paths): every entrypoint this package publishes.
+- [Usage](docs/usage/index.md): component classes to compose once the stylesheet is loaded.
 
-`.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`.
+<!-- Source: docs/accessibility.md -->
 
-```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>
-</label>
-<label class="field">
-  <span class="label">Search</span>
-  <div class="input-group">
-    <input class="ipt" type="search" />
-    <i class="ic-search" aria-hidden="true"></i>
-  </div>
-</label>
-```
+# Accessibility responsibilities
 
-The group reads intent and both [presentation](docs/usage/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](docs/usage/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.
+This package provides CSS hooks for accessible states. It does not provide semantic HTML, ARIA attributes, keyboard behavior, focus management, validation, announcement timing, or JavaScript behavior.
 
-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.
+## Provided by CSS
 
-## Toggles
+### Focus and state
 
-`.checkbox`, `.radio`, and `.switch` accept the same intent classes as
-buttons to set the checked color:
+| Feature            | Behavior                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`   | Global focus-visible outline using `--focus-ring`, `--focus-ring-width`, and `--focus-ring-offset`.                                                                                                                                                                                                                             |
+| Form control focus | `.ipt`, `.textarea`, and `.select` draw the global focus ring and move their line to the intent color.                                                                                                                                                                                                                          |
+| Invalid controls   | `[aria-invalid="true"]` applies destructive border/focus color on form controls.                                                                                                                                                                                                                                                |
+| Disabled controls  | `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]`, and `.disabled` apply disabled cursor/opacity where supported.                                                                                                                                                                                                       |
+| Open state         | `[data-state="open"]` styles supported surfaces and tooltips.                                                                                                                                                                                                                                                                   |
+| Native `<dialog>`  | `dialog:not([open])` and a centered `dialog[open]` are restored in author origin, so `.card` composed onto a `<dialog>` (the closest primitive the package ships) does not render open on load or lose its centering to another rule. Focus trapping, escape handling, and inert-background behavior stay outside this package. |
 
-| Class                               | Meaning                 |
-| ----------------------------------- | ----------------------- |
-| `.neutral` _(default)_              | Text color, capped.     |
-| `.primary`                          | Primary color.          |
-| `.secondary`                        | Secondary/accent color. |
-| `.success`                          | Success color.          |
-| `.warning`                          | Warning color.          |
-| `.destructive`, `.danger`, `.error` | Destructive color.      |
-| `.info`                             | Info color.             |
+### Visually hidden content
 
-All three toggles rest at `.solid`, and **`.ghost` is not supported on any of
-them.** An unchecked ghost toggle is the silhouette every toggle already
-has, and a checked one is a mark on nothing — a tick floating on the page, a
-dot with no ring around it. A container that cascades `.ghost` onto a
-toggle is floored rather than obeyed.
+`.visually-hidden` hides content from sighted users while keeping it in the accessibility tree, using the standard clip-based recipe. It ships wherever the layout utilities do -- `.`, `./native`, `./tw`, `./tw/native`, and `./tw/utilities` -- including the vanilla entries with no Tailwind utility layer of their own; it is not part of `./components` or the narrower `./tw/components`/`./tw/*` component slices. See [Content and layout](docs/usage/content-and-layout.md).
 
-Presentation decides the fill in both states. Being checked lifts the cap
-rather than pinning a fill, so the class still chooses:
+### Control boundaries
 
-| Toggle            | unchecked       | checked                         |
-| ----------------- | --------------- | ------------------------------- |
-| `.solid`, default | 20%, switch 40% | 100%, mark in the contrast tone |
-| `.soft`           | 12%             | 12%, mark in the strong tone    |
+| Feature              | Behavior                                                                                                                                                                                                                                                                                 |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Control boundaries   | Text controls rest at `--_line-rest` of their intent, under 3:1 by choice; hover and focus take the tone whole.                                                                                                                                                                          |
+| Toggle boundaries    | `.checkbox`, `.radio`, and `.switch` draw their line whole, because it is the only thing marking an unchecked box.                                                                                                                                                                       |
+| Cascaded `.edgeless` | Floored on every text control: a container cannot erase the line of a field or toggle nobody classed.                                                                                                                                                                                    |
+| Own `.edgeless`      | On the element, `.ipt`, `.textarea`, `.select`, and `.switch` do drop their line and do not meet 1.4.11 at rest, except `.switch.ghost`: `.ghost` already asks for zero fill, so dropping the line too would leave no boundary at all, and `.switch.ghost.edgeless` keeps it up instead. |
+| `.checkbox`/`.radio` | Never drop their line, on the element or from a container. `.edgeless` on them is unsupported, not merely discouraged.                                                                                                                                                                   |
 
-A checked checkbox and a checked switch cut their mark out of that plate. A
-checked radio thickens its ring to twice the resting line and takes the
-intent whole on it, so `.radio.soft` is the classic ring-and-dot radio and
-`.radio.solid` is a filled circle whose dot stays readable — the mark
-follows the plate rather than being pinned to the intent color.
+### Motion and transparency
 
-## Text controls
+| Feature                 | Behavior                                                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| Reduced-motion loaders  | Loader variants use animated embedded SVGs normally and static masks when `prefers-reduced-motion: reduce` matches. |
+| Reduced-motion document | The reset additionally shortens document animations and transitions when `prefers-reduced-motion: reduce` matches.  |
+| Reduced transparency    | `.glass` drops its blur and becomes an opaque surface when `prefers-reduced-transparency: reduce` matches.          |
 
-Text controls also take intent, which colors the resting border and the
-focus-visible border, and both [presentation](docs/usage/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.
+The loader fallback is embedded in loader CSS, so focused imports that include loaders honor reduced motion without the reset. This includes `@codenhub/styles/components`, `@codenhub/styles/tw/components`, and `@codenhub/styles/tw/loader`. The complete and native entrypoints include both that fallback and the reset's broader animation and transition shortening.
 
-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.
+### Color and contrast
 
-```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 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" />
-</div>
-```
+| Feature            | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Filled labels      | Every intent's `.solid` label meets 1.4.3 (4.5:1) as normal text, in both themes. Lowest is success at 5.14:1.                                                                                                                                                                                                                                                                                                                            |
+| Warning ink        | `--color-warning-contrast` is the near-black tone, not the page tone. Amber dark enough to carry white is not amber.                                                                                                                                                                                                                                                                                                                      |
+| Partial fills      | Contrast ink appears only past a half fill, so a capped plate keeps `--intent-strong` rather than walking toward the page.                                                                                                                                                                                                                                                                                                                |
+| Intent hue in dark | `--intent-strong` is the `-300` shade in dark, so a soft or ghost label keeps its own hue instead of reading white.                                                                                                                                                                                                                                                                                                                       |
+| Toggle marks       | A checked mark meets 3:1 as a state indicator on every plate its fill class can paint, in both themes.                                                                                                                                                                                                                                                                                                                                    |
+| Soft-edged border  | `.alert`, `.panel`, `.badge`, `.kbd`, and `.code`/`.pre`'s `.edged` border blends toward the component's own fill; at `.soft`'s 12% fill this misses 3:1 against the fill for some intents, and which ones misses depends on the theme. Known, not fixed -- `--color-border`/`--intent-border` is a shared blend seam every one of them reads, so a targeted fix would need to touch it for one component without moving it for the rest. |
 
-`.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.
+### Forced colors and direction
 
-```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>
-```
+| Feature        | Behavior                                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Forced colors  | `forced-colors: active` preserves visible borders and checked states using system colors.                          |
+| Text direction | Quote bar, alert icon, progress fill, vertical divider, and switch knob mirror under `dir="rtl"`. No class needed. |
 
-`.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.
+In forced colors, class-based form controls including `.text-control` receive a 2px `Highlight` system-color focus outline. The native entrypoint provides the same visible system outline for unclassed text inputs, selects, textareas, checkboxes, and radios.
 
-## Example
+Custom checkboxes and radios use the system `Canvas`, `CanvasText`, `Highlight`, and `HighlightText` colors in forced-colors mode so checked and unchecked states remain distinct. Shape, size, and spacing remain unchanged.
 
-```html
-<label class="field">
-  <span class="label">Email</span>
-  <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
-  <span class="hint error" 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>
-```
+## Required outside CSS
 
-Use labels, `type`, validation logic, `aria-describedby`, and error message
-relationships; see [Accessibility](docs/accessibility.md).
+Use semantic HTML and behavior appropriate for the component.
 
-<!-- Source: docs/usage/index.md -->
+| UI                | Required outside CSS                                                                                            |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| Buttons           | Use `<button>` for actions or accessible links for navigation. Add accessible names for `.btn.icon`.            |
+| Forms             | Use labels, `type`, validation logic, `aria-describedby`, and error message relationships.                      |
+| Alerts            | Add `role="status"` or `role="alert"` based on announcement urgency.                                            |
+| Toasts            | Add live-region behavior, dismissal behavior, focus rules, and pause/timeout logic when needed.                 |
+| Tooltips          | Give the bubble a real `id` and `role="tooltip"`, and reference it from the trigger's `aria-describedby`.       |
+| Progress          | Use semantic progress elements or ARIA values when numeric progress must be announced.                          |
+| Skeletons/loaders | Mark decorative loading visuals with `aria-hidden="true"` and expose loading state elsewhere when needed.       |
+| Popovers/modals   | Provide focus trapping, escape handling, inert background behavior, labels, and roles outside this CSS package. |
 
-# Usage
+## State attribute guidance
 
-These guides assume the [Concepts](docs/concepts.md) mental model: intent,
-presentation, and aesthetic as three independent axes, resolved through
-tokens a component reads.
+Prefer native attributes first:
 
-- [Composing](docs/usage/composing.md): Combining the three axes on a component, the
-  axis-support matrix, and elevation modifiers.
-- [Theming](docs/usage/theming.md): The color, intent, and foundation token reference.
-- [Customizing](docs/usage/customizing.md): The presentation and material token
-  reference, aesthetic knobs, and defining a custom intent.
-- [Aesthetics](docs/usage/aesthetics.md): Each shipped aesthetic in depth, including
-  its documented exceptions.
-- [Buttons](docs/usage/buttons.md)
-- [Forms](docs/usage/forms.md)
-- [Feedback](docs/usage/feedback.md)
-- [Tooltips](docs/usage/tooltips.md)
-- [Content and layout](docs/usage/content-and-layout.md): Layout helpers, tables,
-  quotes, code, surfaces, and typography utilities.
+```html
+<button class="btn primary" disabled>Saving</button> <input class="ipt" aria-invalid="true" aria-describedby="email-error" />
+```
 
-## Supported surface
+Use ARIA or data attributes when native attributes are not available for the element or 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.
+```html
+<a class="btn secondary" aria-disabled="true">Unavailable</a>
+<span class="tooltip" data-state="open">
+  <span class="tooltip-icon" tabindex="0" aria-label="More details" aria-describedby="more-details-bubble">?</span>
+  <span class="tooltip-bubble" role="tooltip" id="more-details-bubble">More details</span>
+</span>
+```
 
-<!-- Source: docs/usage/theming.md -->
+`aria-disabled="true"` communicates disabled state but does not prevent activation. JavaScript or element choice must prevent activation when required.
 
-# Theming
+<!-- Source: docs/changelog/0.2.0.md -->
 
-Color tokens are how you restyle the palette; see
-[Concepts → Theme selection](docs/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.
+# 0.2.0
 
-## Color tokens
+Fixes from a stress-test pass composing real screens (`app-shell`, `form`, `settings`) against the published `0.1.x` model. Several change default token values rather than adding new surface, so this lands as one minor rather than a run of patches -- see [Changed](#changed) for what an upgrader needs to check.
 
-Each color token holds both of its theme values at once through
-`light-dark()`, and the element's `color-scheme` picks one.
+## Added
 
-```html
-<section data-theme="dark">
-  <article>Dark token subtree</article>
-</section>
-```
+- `.visually-hidden`, a utility that hides content from sighted users while keeping it in the accessibility tree. Ships wherever the layout utilities do (`.`, `/native`, `/tw`, `/tw/native`, `/tw/utilities`), including the vanilla entries that have no Tailwind utility layer of their own; not part of `/components` or the narrower `/tw/*` component slices.
+- `.tooltip-bubble`, a real element for a tooltip's message that can carry its own `id` and be referenced by `aria-describedby`.
+- `.alert-icon`, sizing and alignment for a consumer-supplied icon element dropped into `.alert` -- any inline SVG, `<img>`, or icon-set class works, not just a built-in glyph.
+- `dialog:not([open])`/`dialog[open]` restated in author origin, so `.card` composed onto a `<dialog>` hides until opened and centers when shown, without a dialog primitive of its own.
+- `.icon` added to `registry.json` under `modifiers.shape`. The button shape modifier was already shipped and documented; it was missing only from the machine-readable contract.
+- `.switch.ghost.edgeless` now renders a track instead of disappearing.
 
-| 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-subtle`          | Low-emphasis companion tone for text. Use as soft surface or subtle background.                                   |
-| `--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.                                                                            |
+## Changed
 
-> **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.
+- **Tooltips are composition, not a single class.** `.tooltip` now wraps a trigger and a `.tooltip-bubble`, one more DOM node than before. Intent, presentation, aesthetic, and elevation classes move to `.tooltip-bubble`, the element that actually paints.
+- **`.checkbox`, `.radio`, and `.switch` default to `.soft` instead of `.solid`, and their checked state now composes one plate regardless of presentation.** Unchecked, `.ghost` (0% fill), `.soft` (12%), and `.solid` now read as three distinct plates instead of three shades of one wash; `.ghost` is a supported look on every toggle for the first time.
+- **A neutral (no named intent) `.card.soft`, `data-table`, `.panel`, or `.alert` rests untinted instead of mixing a 12% ink wash.** A named intent (`.card.soft.destructive`, `.alert.success`, and so on) is unaffected and keeps its ordinary tint; `.badge` is unaffected either way, since it has no border to fall back on if untinted.
+- **Elevation no longer cascades onto descendants.** `--ui-elevation`, `--elevation-y`, and `--elevation-blur` are registered non-inheriting, so an elevation class lifts only the element it is written on. A container that used to lift a whole unclassed subtree in one class now needs an elevation class on each element that wants depth.
+- `--input-group-gap` replaces a hardcoded gap in `.input-group`; unchanged by default for icon compositions, and settable to `0` on a text affix for a flush look.
+- `.loader`'s sizes step down from 24/32/40px to 20/28/36px for `.sm`/default/`.lg`.
+- A `/tw` consumer's own `dark:` utilities now also fire under `prefers-color-scheme: dark` when no explicit theme selector is present, matching how the token palette already follows the OS default.
 
-## Intent tokens
+## Removed
 
-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.
+- **`.btn.loading`.** A loading button is now a disabled `.btn` composed with a real `.loader` child instead of a hardcoded `::after` spinner -- any loader variant works, not just one circular spinner.
+- **`.alert.icon`'s hardcoded per-intent SVG mask.** Replaced by `.alert-icon` (above), sized for a consumer-supplied icon element.
 
-| 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. Resolves to `--color-border` when no intent is set.                       |
-| `--intent-fill-max` | How far a fill of this intent is allowed to go. `100%` for every intent but neutral.  |
+## Fixed
 
-`--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.
-
-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.
-
-`--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.
-
-`--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.
-
-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.
-
-That means a capped neutral takes the strong tone whole rather than a
-fraction of the way toward the page. Tying it to the fill instead cost a
-neutral `.solid` button four points of contrast and a neutral tooltip nearly
-ten. 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.
-
-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%.
+- `.icon` buttons kept the wrong `min-width` floor under `.compact`/`.spacious`; all three padding tiers now size `.icon` to its own padding.
+- `.chunky-tile`'s offset shadow read as a solid fill behind a small `.icon.ghost` button; halved for that combination.
+- Table row and boundary rules stayed a 1px hairline under `.chunky-tile`'s 2px frame; both now track the same width token the frame uses.
+- `.progress`'s track failed WCAG 1.4.11 in both themes; `--progress-surface` now mixes enough ink to clear 3:1.
+- `.card.soft.edged`'s border was nearly invisible against its own fill in light theme; `--color-border`'s light value moved one step darker.
+- A badge nested inside an untinted `data-table` lost its own fill; box now restates its fill cap on every element that uses it, so a nested badge, button, or chip no longer inherits its container's cap.
 
-```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);
-  --intent-fill-max: 100%;
-}
-```
+<!-- Source: docs/changelog/0.1.1.md -->
 
-```html
-<button class="btn brand">Custom intent</button>
-<span class="badge brand soft">Works everywhere</span>
-```
+# 0.1.1
 
-> **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.
+## Fixed
 
-## Foundation tokens
+- `.p-xs` and its alias `.dense` now clear a button's `--control-height` minimum, so a chip-sized button fits inside a table cell or a dense toolbar. Before this, every button kept the full control-height floor even at the tightest padding, so a button that small could not be built. Every other size and padding class still keeps the floor, so a plain button is unchanged. An icon-only `.p-xs`/`.dense` button also gives up its `min-width`; size the glyph yourself, as the package sizes no icons.
 
-Foundation tokens are not aliases for one color. They define layout, shape,
-motion, focus, depth, and layering behavior used by helper classes.
+<!-- Source: docs/changelog/0.1.0.md -->
 
-The four `--elevation-*` values below are raw shadows for elements you style
-yourself. They are a separate thing from `.elevation-none`/`.elevation-sm`/
-`.elevation-md` (aliased as `.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](docs/usage/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.
+# 0.1.0
 
-| 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. Negative, so the ring lands on the edge.  |
-| `--focus-ring-width`       | Focus-visible outline/ring width.                                       |
-| `--motion-duration-fast`   | Fast transition for buttons and input interactions (`120ms`).           |
-| `--motion-duration-normal` | Normal transition for layout and modals (`200ms`).                      |
-| `--motion-duration-slow`   | Slow animation for skeleton loaders and progress bars (`400ms`).        |
-| `--motion-ease`            | Default easing curve.                                                   |
-| `--z-popover`              | Popover/tooltip z-index.                                                |
-| `--breakpoint-xs`          | Extra-small Tailwind responsive breakpoint.                             |
-| `--breakpoint-2xl`         | Extended large Tailwind responsive breakpoint.                          |
+`0.1.0` replaces the model published in `0.0.4` wholesale. The old model had three orthogonal axes with per-component clamps and no chosen default: a plain element got whatever `var()` fallback each component happened to declare. This release makes each decision explicitly and is the baseline the `0.x` line builds on. Nearly everything below is breaking against `0.0.4`; there are no compatibility aliases.
 
-Next: [Customizing](docs/usage/customizing.md) covers presentation and material
-tokens — how much of an intent shows, and what a component is made of.
+## Changed
 
-<!-- Source: docs/usage/tooltips.md -->
+- **Every element now composes from three named axes.** _Intent_ (`.primary`, `.success`, `.destructive`, …) sets hue only. _Presentation_ sets how much of that hue fills the element and whether it draws an edge. _Aesthetic_ sets the material — radius, edge width, shadow, silhouette, type. Intent is redeclared per component; presentation and aesthetic cascade, so a container can set the look of a subtree while any element opts out. [Concepts](docs/concepts.md) and [Composing](docs/usage/composing.md) describe the full model.
+- **Presentation is two independent questions.** Fill is `.solid` / `.soft` / `.ghost`; edge is `.edged` / `.edgeless`. Exactly one of each applies, and they never decide each other. The common web button — a subtle fill with a border — is `.soft.edged`, which had no spelling before.
+- **`.bare` is renamed `.ghost`.** `.bare` and `.edgeless` both read as "less of something", so the name is now a fill and only a fill: no fill at rest, a tint on hover.
+- **Hover is derived, not declared.** A hovered element takes its resting fill plus one published step and its `--intent-hover` colour. There are no hover tokens to set. An outline button therefore tints on hover rather than filling completely.
+- **A sunk text field is `.soft.edgeless`.** Two classes saying two things, where `.soft` alone used to silently suppress the field's border.
+- **Table row rules are opt-in via `.ruled`.** Rules no longer arrive by implication from a component's edge default. The head and foot separators stay at every presentation.
+- **Depth is a modifier, not part of a component.** `surface` no longer carries a structural shadow, so cards, buttons, and chips on a plain page rest flat. Use `.raised` / `.floating` (or `.elevation-sm` / `.elevation-md`) to add depth, and `.flat` to remove an aesthetic's.
+- **The Tailwind v4 entrypoint moved from `/overrides` to `/native`.**
 
-# Tooltips
+## Added
 
-| Class or Attribute                      | Purpose                                                        |
-| --------------------------------------- | -------------------------------------------------------------- |
-| `.tooltip`                              | Tooltip host. Uses `data-tooltip` as pseudo-element content.   |
-| `.tooltip.tooltip-icon`                 | Circular icon-style tooltip host.                              |
-| `[data-tooltip-position="top"]`         | Positions tooltip above host.                                  |
-| `[data-tooltip-position="bottom"]`      | Positions tooltip below host.                                  |
-| `[data-tooltip-position="left"]`        | Positions tooltip left of host.                                |
-| `[data-tooltip-position="right"]`       | Positions tooltip right of host.                               |
-| No `data-tooltip-position`              | Defaults to top placement.                                     |
-| `[data-state="open"]`                   | Shows tooltip without hover.                                   |
-| `.tooltip.raised` / `.tooltip.floating` | Adds one or two units of depth. The bubble is flat by default. |
-
-A tooltip bubble's fill, ground color, and floor behavior are covered in
-[Composing → Presentation](docs/usage/composing.md#presentation), and its material
-follows whichever [aesthetic](docs/usage/aesthetics.md) is in scope, including the
-pseudo-element itself.
-
-The bubble rests flat. It draws no shadow of its own on a plain page, and
-zeroes an aesthetic's part-based depth (such as `.neobrutalism`'s slab) the
-same way `.flat` does elsewhere. Add [`.raised` or
-`.floating`](docs/usage/composing.md#elevation) to lift it — `.tooltip.floating` is the
-pre-0.1.0 look. An aesthetic whose shadow is a complete value, like `.glass`,
-still reaches the bubble as it reaches any surface.
+- **Opt-in aesthetics.** `.neobrutalism`, `.glass`, `.pixel`, and `.chunky-tile`, each shipped as its own entrypoint (`@codenhub/styles/aesthetics/pixel`, …) and as an aggregate (`@codenhub/styles/aesthetics`). An aesthetic sets material tokens only; it never repaints hue. See [Aesthetics](docs/usage/aesthetics.md).
+- **An elevation modifier.** `.flat` / `.raised` / `.floating` (and the `.elevation-none` / `-sm` / `-md` names) multiply an aesthetic's shadow geometry. Unitless, so a container can flatten a whole toolbar and any element can opt back in.
+- **Granular Tailwind v4 source entrypoints.** `@codenhub/styles/tw` and per-family subpaths (`/tw/button`, `/tw/form`, `/tw/feedback`, `/tw/tooltip`, `/tw/utilities`, `/tw/aesthetics/*`, …) for consumers compiling their own build. `package.json` is also exported.
+- **`.input-group`.** A wrapper that draws one box and lets the control inside give up its own paint, so an icon can sit alongside a field. The package ships no icons — any element works in the slot.
+- **`registry.json`.** A machine-readable record of every supported class, each component's default fill/edge/elevation, the axes it reads, and every bound and exception with its reason.
+- **`--intent-strong`**, the intent tone chosen to be read on a page, used wherever a fill is partial.
 
-```html
-<button
-  class="tooltip tooltip-icon"
-  data-tooltip="More details"
-  data-tooltip-position="right"
-  aria-label="More details"
->
-  ?
-</button>
-```
+## Removed
 
-CSS pseudo-element tooltips are presentational. They are not a complete
-accessible tooltip implementation by themselves — provide accessible
-names/descriptions outside the CSS; see [Accessibility](docs/accessibility.md).
+- **`.out` and `.fill`.** Outline is now `.ghost.edged`; there is no class that makes an outline button fill completely on hover.
+- **`--ui-border-scale` / `.out`'s doubled border.** The edge width comes from the aesthetic and nothing else, which removed the per-component border ceilings small components needed.
+- **`--color-text-subtle`**, which nothing read.
+- **`--layout-stack-gap` and `--layout-cluster-gap`**, replaced by a single `--layout-gap`.
+- **The bundled input-field icons.** Icons were a `background-image` data URI with a light and a dark copy per glyph; they are gone, and `.input-group` carries a consumer-supplied icon instead.