@codenhub/styles 0.1.0 → 0.1.1

package/docs/accessibility.md

@@ -1,54 +1,66 @@
 ---
 title: Accessibility
+order: 5
 ---
 
 # Accessibility responsibilities
 
 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.
 
-## 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
+## Provided by CSS
+
+### Focus and state
+
+| 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.                                                             |
+
+### Control boundaries
+
+| 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.       |
+| `.checkbox`/`.radio` | Never drop their line, on the element or from a container. `.edgeless` on them is unsupported, not merely discouraged. |
+
+### Motion and transparency
+
+| 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.          |
+
+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.
+
+### Color and contrast
+
+| 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.                     |
+
+### Forced colors and direction
+
+| 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. |
+
+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
 
 Use semantic HTML and behavior appropriate for the component.
 
@@ -63,20 +75,18 @@ Use semantic HTML and behavior appropriate for the component.
 | 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. |
 
-## State Attribute Guidance
+## State attribute guidance
 
 Prefer native attributes first:
 
 ```html
-<button class="btn primary" disabled>Saving</button>
-<input class="ipt" aria-invalid="true" aria-describedby="email-error" />
+<button class="btn primary" disabled>Saving</button> <input class="ipt" aria-invalid="true" aria-describedby="email-error" />
 ```
 
 Use ARIA or data attributes when native attributes are not available for the element or library:
 
 ```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>
+<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>
 ```
 
 `aria-disabled="true"` communicates disabled state but does not prevent activation. JavaScript or element choice must prevent activation when required.

package/docs/changelog/0.1.0.md

@@ -0,0 +1,37 @@
+---
+title: 0.1.0
+date: 2026-08-31
+description: The three-axis styling model, split presentation, opt-in aesthetics, and Tailwind v4 source entrypoints.
+---
+
+# 0.1.0
+
+`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.
+
+## Changed
+
+- **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](../concepts.md) and [Composing](../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`.**
+
+## Added
+
+- **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](../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.
+
+## Removed
+
+- **`.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.

package/docs/changelog/0.1.1.md

@@ -0,0 +1,10 @@
+---
+title: 0.1.1
+date: 2026-09-10
+---
+
+# 0.1.1
+
+## Fixed
+
+- `.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.

package/docs/changelog/index.md

@@ -0,0 +1,10 @@
+---
+title: Changelog
+curated: true
+group: Changelog
+---
+
+# Changelog
+
+- [0.1.1](0.1.1.md)
+- [0.1.0](0.1.0.md)

package/docs/concepts.md

@@ -1,17 +1,16 @@
 ---
 title: Concepts
 description: The three-axis model, the token system, and how theme selection works.
+order: 2
 ---
 
 # 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  |
 | ------------ | --------------- | ----------------------------------------------------------------------------------------- | ------------ |
@@ -26,25 +25,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](./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](./usage/index.md) and demonstrated by the playground. Undocumented and undemonstrated combinations may produce CSS but are not supported behavior.
 
-- [Usage → Composing](./usage/composing.md) shows how the three axes combine
-  on each component, with the full axis-support matrix.
-- [Usage → Aesthetics](./usage/aesthetics.md) covers each aesthetic and its
-  documented exceptions in depth.
+- [Usage → Composing](./usage/composing.md) shows how the three axes combine on each component, with the full axis-support matrix.
+- [Usage → Aesthetics](./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                                                         |
 | ------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
@@ -55,40 +45,24 @@ where they're used:
 | Material     | What a component is made of — radius, border width, shadow geometry, translucency.          | [Usage → Customizing](./usage/customizing.md#material-tokens)     |
 | Aesthetic    | Per-aesthetic knobs such as `--pixel-unit` or `--tile-lift`.                                | [Usage → Customizing](./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](./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.
+
+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](./setup.md#requirements)).

package/docs/index.md

@@ -5,58 +5,31 @@ description: What @codenhub/styles is, what it covers, and where to go next.
 
 # @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.
-
-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.
+`@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.
 
 ## 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](./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](./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](./setup.md): Install the package, choose an entrypoint, and render a
-  first component.
-- [Concepts](./concepts.md): The three-axis model, the token system, and how
-  theme selection works — read this before the usage guides.
-- [Usage](./usage/index.md): Guides for composing axes, theming, customizing,
-  aesthetics, and each component family.
-- [Integrating](./integrating/index.md): Wiring the stylesheet into Next.js,
-  Vue, Svelte, Astro, or a Tailwind CSS v4 build.
-- [Accessibility](./accessibility.md): CSS accessibility hooks and what
-  remains an application responsibility.
+- [Setup](./setup.md): Install the package, choose an entrypoint, and render a first component.
+- [Concepts](./concepts.md): The three-axis model, the token system, and how theme selection works — read this before the usage guides.
+- [Usage](./usage/index.md): Guides for composing axes, theming, customizing, aesthetics, and each component family.
+- [Integrating](./integrating/index.md): Wiring the stylesheet into Next.js, Vue, Svelte, Astro, or a Tailwind CSS v4 build.
+- [Accessibility](./accessibility.md): CSS accessibility hooks and what remains an application responsibility.

package/docs/integrating/astro.md

@@ -1,12 +1,14 @@
 ---
 title: Astro
 description: Loading the stylesheet in an Astro app.
+order: 5
 ---
 
 # Astro
 
-Import the package from a shared layout's frontmatter so every page that
-uses that layout loads it once:
+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.
+
+## Import the stylesheet
 
 ```astro
 ---
@@ -21,9 +23,13 @@ import "@codenhub/styles";
 </html>
 ```
 
-Apply `.dark` or `.light` on `<html>` to force a theme instead of following
-the system preference; see [Setup → Configuration](../setup.md#configuration).
+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](./tailwind.md), including when an explicit `@source` is actually needed.
+
+## Force a theme
+
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following the system preference; see [Setup → Configuration](../setup.md#configuration).
+
+## See also
 
-A project running Tailwind CSS v4 imports `@codenhub/styles/tw` through
-Astro's Tailwind integration instead; see [Tailwind CSS v4](./tailwind.md)
-for the `@source` directive Astro needs to scan `src/`.
+- [Setup → Import paths](../setup.md#import-paths): every entrypoint this package publishes.
+- [Usage](../usage/index.md): component classes to compose once the stylesheet is loaded.

package/docs/integrating/index.md

@@ -1,23 +1,24 @@
 ---
-title: Integrating
-description: Wiring the stylesheet into a framework or build target.
+title: Overview
+description: How the stylesheet loads in a framework build, and which guide to follow.
+group: Integrating
+order: 4
 ---
 
 # Integrating
 
-This package has no JavaScript and no framework bindings; see
-[Introduction](../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.
+This package has no JavaScript and no framework bindings; see [Introduction](../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.
 
-Every stack does the same two things:
+## The shared model
 
-1. Import one [entrypoint](../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](../usage/aesthetics.md).
+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:
+
+1. One [entrypoint](../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](../usage/aesthetics.md).
+
+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](./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.
+
+## Which guide to follow
 
 | Stack                                    | Guide                            |
 | ---------------------------------------- | -------------------------------- |
@@ -27,6 +28,14 @@ Every stack does the same two things:
 | Svelte / SvelteKit                       | [Svelte](./svelte.md)            |
 | Astro                                    | [Astro](./astro.md)              |
 
-A project with no framework — a plain Vite, webpack, or Parcel build — needs
-nothing beyond [Setup](../setup.md#quick-start): import the compiled
-stylesheet from the project's existing global CSS entry.
+A project with no framework — a plain Vite, webpack, or Parcel build — needs nothing beyond [Setup → Quick start](../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>
+```
+
+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](../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](../setup.md#requirements).

package/docs/integrating/nextjs.md

@@ -1,13 +1,22 @@
 ---
 title: Next.js
 description: Loading the stylesheet in a Next.js / React app.
+order: 2
 ---
 
 # Next.js
 
-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.
+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
@@ -22,6 +31,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
+**Pages Router**
+
 ```tsx
 // pages/_app.tsx
 import "@codenhub/styles";
@@ -32,13 +43,25 @@ export default function App({ Component, pageProps }: AppProps) {
 }
 ```
 
-Apply `.dark` or `.light` on `<html>` to force a theme instead of following
-the system preference; see [Setup → Configuration](../setup.md#configuration).
+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](./tailwind.md).
+
+## Force a theme
+
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following the system preference; see [Setup → Configuration](../setup.md#configuration).
 
 ```tsx
 <html lang="en" className="dark">
 ```
 
-A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
-same file instead; see [Tailwind CSS v4](./tailwind.md) for the `@source`
-directive Next.js needs to scan its own `app`/`src` directories.
+## 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](../setup.md#import-paths): every entrypoint this package publishes.
+- [Usage](../usage/index.md): component classes to compose once the stylesheet is loaded.

package/docs/integrating/svelte.md

@@ -1,12 +1,14 @@
 ---
 title: Svelte
 description: Loading the stylesheet in a Svelte / SvelteKit app.
+order: 4
 ---
 
 # Svelte
 
-In SvelteKit, import the package from the root layout so it loads once for
-every route:
+## Import the stylesheet
+
+**SvelteKit** — import from the root layout so it loads once for every route:
 
 ```svelte
 <!-- src/routes/+layout.svelte -->
@@ -18,7 +20,7 @@ every route:
 {@render children()}
 ```
 
-In a plain Svelte + Vite app, import it from the entry file instead:
+**Plain Svelte + Vite** — import from the entry file instead:
 
 ```ts
 // main.ts
@@ -29,9 +31,13 @@ import App from "./App.svelte";
 mount(App, { target: document.getElementById("app")! });
 ```
 
-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](../setup.md#configuration).
+Running Tailwind CSS v4? Import `@codenhub/styles/tw` from the app's CSS entry instead — see [Tailwind CSS v4](./tailwind.md).
+
+## Force a theme
+
+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](../setup.md#configuration).
+
+## See also
 
-A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
-app's CSS entry instead; see [Tailwind CSS v4](./tailwind.md).
+- [Setup → Import paths](../setup.md#import-paths): every entrypoint this package publishes.
+- [Usage](../usage/index.md): component classes to compose once the stylesheet is loaded.