@codenhub/styles 0.1.0 → 0.2.0

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,25 @@ 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.
+- 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](./setup.md#dark-variant).
+
+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.

package/docs/integrating/tailwind.md

@@ -1,15 +1,18 @@
 ---
 title: Tailwind CSS v4
 description: Using the /tw source entrypoints in a Tailwind CSS v4 project.
+order: 1
 ---
 
 # Tailwind CSS v4
 
-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.
+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.
+
+## Why source instead of compiled
+
+`/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.
+
+## Import the source entrypoint
 
 ```css
 @import "tailwindcss";
@@ -18,13 +21,11 @@ resolve together with yours.
 @source "./src";
 ```
 
-`@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.
+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.
 
-Add aesthetics from the source entrypoint the same way as the compiled one,
-after the base import:
+## Add aesthetics
+
+Add an aesthetic from the source entrypoint the same way as the compiled one, after the base import:
 
 ```css
 @import "tailwindcss";
@@ -34,7 +35,22 @@ after the base import:
 @source "./src";
 ```
 
-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](../setup.md#import-paths) for what each one
-composes. Tailwind CSS 4 or newer is required for every `/tw` entrypoint.
+## 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](../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.

package/docs/integrating/vue.md

@@ -1,11 +1,14 @@
 ---
 title: Vue
 description: Loading the stylesheet in a Vue / Vite app.
+order: 3
 ---
 
 # Vue
 
-Import the package once, from the app's entry file, before the app mounts:
+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
@@ -16,10 +19,13 @@ import App from "./App.vue";
 createApp(App).mount("#app");
 ```
 
-Apply `.dark` or `.light` on the root element 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 a CSS entry file instead of `main.ts`, using the `@tailwindcss/vite` plugin — see [Tailwind CSS v4](./tailwind.md).
+
+## Force a theme
+
+Apply `.dark` or `.light` on the root element 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 a CSS
-entry file instead of `main.ts`, using the `@tailwindcss/vite` plugin; 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.

package/docs/setup.md

@@ -1,6 +1,7 @@
 ---
 title: Setup
 description: Install the package, pick an entrypoint, and render a first component.
+order: 1
 ---
 
 # Setup
@@ -13,8 +14,7 @@ pnpm add @codenhub/styles
 
 ## Quick start
 
-Import the compiled stylesheet for the complete token, reset, utility, and
-component-class surface, then compose helper classes in markup:
+Import the compiled stylesheet for the complete token, reset, utility, and component-class surface, then compose helper classes in markup:
 
 ```css
 @import "@codenhub/styles";
@@ -28,13 +28,9 @@ component-class surface, then compose helper classes in markup:
 </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.
+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:
+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";
@@ -47,14 +43,11 @@ aesthetic on its own, after the base stylesheet so its rules win:
 </section>
 ```
 
-A project already running Tailwind CSS v4 imports the source entrypoint
-instead; see [Integrating → Tailwind CSS v4](./integrating/tailwind.md).
+A project already running Tailwind CSS v4 imports the source entrypoint instead; see [Integrating → Tailwind CSS v4](./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.
+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
 <html class="dark">
@@ -64,17 +57,30 @@ or `.dark` to the root or any ancestor to force token values for that subtree.
 </html>
 ```
 
-See [Concepts → Theme selection](./concepts.md#theme-selection) for how
-selectors resolve and [Usage → Theming](./usage/theming.md) for the full color
-token reference.
+See [Concepts → Theme selection](./concepts.md#theme-selection) for how selectors resolve and [Usage → Theming](./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.
+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                                                                                                                                                                                           |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -88,7 +94,7 @@ entrypoints include theme tokens so their classes can work independently.
 | `@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/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`.                                              |
@@ -99,18 +105,11 @@ entrypoints include theme tokens so their classes can work independently.
 | `@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.
+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).
+- 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](./accessibility.md).
+- The package has no JavaScript runtime. Apps must provide semantic HTML, ARIA, keyboard behavior, focus management, validation, and announcements; see [Accessibility](./accessibility.md).