@navecss/core 0.3.0 → 0.5.0

package/CONSUMER-ATOMS.md

@@ -122,20 +122,22 @@ Compiles to:
     user-select: none;
     -webkit-tap-highlight-color: transparent;
     outline: none;
-    transition-property: color, background-color, border-color, opacity, box-shadow;
-    transition-duration: var(--nave-motion-duration-base);
-    transition-timing-function: var(--nave-motion-easing-standard);
-    background: var(--nave-color-action-primary);
-    color: var(--nave-color-on-action-primary);
-    padding: var(--nave-spacing-control-md) var(--nave-spacing-control-lg);
-    border-radius: var(--nave-radius-control);
-    font-weight: var(--nave-font-weight-medium);
     &:focus-visible {
       outline-style: solid;
       outline-width: var(--nave-border-width-focus, 2px);
       outline-color: var(--nave-color-border-focus, currentColor);
       outline-offset: 2px;
     }
+    & {
+      transition-property: color, background-color, border-color, opacity, box-shadow;
+      transition-duration: var(--nave-motion-duration-base);
+      transition-timing-function: var(--nave-motion-easing-standard);
+      background: var(--nave-color-action-primary);
+      color: var(--nave-color-on-action-primary);
+      padding: var(--nave-spacing-control-md) var(--nave-spacing-control-lg);
+      border-radius: var(--nave-radius-control);
+      font-weight: var(--nave-font-weight-medium);
+    }
     &:hover {
       background: var(--nave-color-action-primary-hover);
     }
@@ -293,15 +295,17 @@ Compiles to:
     display: flex;
     flex-direction: column;
     gap: var(--nave-spacing-content-md);
-    background: var(--nave-color-surface-raised);
-    border-radius: var(--nave-radius-card);
-    padding: var(--nave-spacing-content-md);
     @container (width >= 28rem) {
       & {
         flex-direction: row;
         align-items: center;
       }
     }
+    & {
+      background: var(--nave-color-surface-raised);
+      border-radius: var(--nave-radius-card);
+      padding: var(--nave-spacing-content-md);
+    }
   }
 }
 ```

package/LICENSE

@@ -55,3 +55,25 @@ JavaScript under dist/: the member names of a version 3 source map, the
 layout of its mappings string, the base64 VLQ encoding of each field in it,
 and the base64 alphabet. The code implementing them is this package's own, and
 everything in this package is offered under the MIT licence above.
+
+This package also includes material copied from or derived from mdn-data
+(css/properties.json in the mdn/data repository, version 2.37.2,
+https://github.com/mdn/data), which its authors dedicated to the public domain
+under CC0 1.0 Universal (https://creativecommons.org/publicdomain/zero/1.0/),
+and from CSS Logical Properties and Values Module Level 1, CSS Overflow Module
+Level 3, CSS Overscroll Behavior Module Level 1, CSS Scroll Snap Module Level 1,
+CSS Box Sizing Module Level 4, CSS Fonts Module Level 4, CSS Text Module Level
+4, CSS Gaps Module Level 1, CSS Fragmentation Module Level 4, CSS Backgrounds
+and Borders Module Level 3, and CSS Cascading and Inheritance Module Level 5 (in
+the w3c/csswg-drafts repository, at commit
+40527902c4d0840cdb7a808c8cd42302be1c3bc8). Copyright (c) 2026 World Wide Web
+Consortium. Those specifications, and the repository carrying them, are
+published under the W3C Software and Document License
+(https://www.w3.org/copyright/software-license-2023/).
+
+What is copied or derived is implemented in
+src/directive/property-table.generated.ts, built into the JavaScript under
+dist/: the names of CSS properties, the properties each shorthand sets, which
+names are legacy name aliases of another property, and which logical and
+physical properties belong to one group. The code using them is this package's
+own, and everything in this package is offered under the MIT licence above.

package/README.md

@@ -21,7 +21,7 @@ pnpm add @navecss/core
   included, is reachable only through the package's `exports` map: there is no
   `main` field to fall back on.
 - **ES modules.** `@navecss/core/cx`, `@navecss/core/atoms`,
-  `@navecss/core/vite`, `@navecss/core/lightningcss` and `@navecss/core/check` load through `import` only. A `require()` of any of
+  `@navecss/core/vite`, `@navecss/core/lightningcss`, `@navecss/core/check` and `@navecss/core/collect` load through `import` only. A `require()` of any of
   them fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`, which reads as though the
   entry point did not exist. In TypeScript, set `moduleResolution` to `bundler`,
   `node16` or `nodenext`; under `node10` their types are not found. A CommonJS
@@ -107,10 +107,141 @@ Requires the Vite plugin or the PostCSS plugin. Everything stays in CSS files.
 ```
 
 Declarations are inlined at build time, and nothing of `@nave` is left at run time.
-Pseudo-class rules (`:focus-visible` from `focusRing`), `@media` and
-`@container` blocks are emitted as native CSS nesting inside your rule, so they
-apply to every selector in a selector list. Native nesting is inside the browser
-floor under [Requirements](#requirements).
+Pseudo-class rules (`:focus-visible` from `focusRing`), `@media` and `@container` blocks are
+emitted as native CSS nesting inside your rule, each right after its own atom's declarations, so
+they apply to every selector in a selector list. Native nesting is inside the browser floor under
+[Requirements](#requirements), and [Order inside a rule](#order-inside-a-rule) says what wins when
+your rule sets the same property.
+
+#### Order inside a rule
+
+`@nave a b;` expands where you write it, in the order CSS mixins will apply
+`@apply --a; @apply --b;`: the declarations of `a`, then the pseudo-class,
+`@media` and `@container` blocks of `a`, then the same for `b`. Whatever your rule
+says after the directive comes after all of it. So of two declarations of one
+property that both apply, the later one wins, unless the earlier one has the more
+specific selector (an atom's pseudo-class block, such as the `:focus-visible` of
+`focusRing`, does), as anywhere else in CSS.
+
+```css
+.panel {
+  @nave flex hideDesktopUp;
+  gap: var(--nave-spacing-content-md);
+}
+```
+
+expands to:
+
+```css
+.panel {
+  display: flex;
+  @media (width >= 75em) {
+    & {
+      display: none;
+    }
+  }
+  & {
+    gap: var(--nave-spacing-content-md);
+  }
+}
+```
+
+A declaration that follows a nested block is written inside `& { }`, the wrapper
+Nave already uses for a directive written after a nested rule. Under a selector
+list, `&` matches with the specificity of the list's most specific selector, so a
+wrapped declaration can win over a rule elsewhere that a bare one would lose to;
+write it above the directive if that matters.
+
+The order you write is the order that wins:
+
+| You write                             | From 75em up     |
+| ------------------------------------- | ---------------- |
+| `@nave flex hideDesktopUp;`           | hidden           |
+| `@nave hideDesktopUp flex;`           | shown, as flex   |
+| `display: grid; @nave hideDesktopUp;` | hidden           |
+| `@nave hideDesktopUp; display: grid;` | shown, as a grid |
+
+Name a responsive or state atom after the atoms it adjusts, and write a declaration
+that should give way to an atom's variants above the directive. A declaration or a
+nested block below the directive is how you customize an atom inside your own rule.
+
+The same order applies to the focus atoms. After `@nave focusRing;`, a later
+`&:focus-visible { outline-color: var(--brand) }` recolours the ring, and a later
+`&:focus { outline: none }` or `&:focus-visible { outline: none }` removes it,
+which leaves the element with no focus indicator from `focusRing` under keyboard
+focus. After `@nave srOnlyFocusable;`, a later `&:focus-visible { position: fixed }`
+places the revealed element, and a later `clip-path: inset(50%)` in the same state
+hides it again, so a skip link stays hidden when it has focus. To keep the atom's
+result, write the block above the directive. The order warning below reports each
+of these, and says so when the ring or the reveal is lost.
+
+**The order warning.** Where something later in the rule overrides one of an atom's
+pseudo-class, `@media` or `@container` blocks with a different value, the build
+prints a warning at the later content. Where moving something lets the atom win
+without a new warning, it says what to move, and it always shows how to mark the
+directive if the later value is meant to win:
+
+```text
+src/panel.css:3:3: @nave: display: grid comes after "hideDesktopUp", so under @media (width >= 75em) display is grid, not none. Before @navecss/core 0.5.0 "hideDesktopUp" won, because an atom's blocks were placed last in the rule. To let "hideDesktopUp" win, move display: grid above the directive. If it is meant to win, mark the directive that names "hideDesktopUp": `@nave /* nave-allow-override: display */ hideDesktopUp;`
+```
+
+Where no move clears the warning, as when the later value comes from another atom's
+block and moving either only turns the pair round, it prints only the marker. Write
+the atom that should win last, and mark the directive the warning then names.
+
+It never fails the build, and `onUnknown` does not change it. The Vite plugin prints
+it through Vite's logger, the PostCSS plugin as a PostCSS warning (and with `console.warn` on
+Next.js under Turbopack, which does not print PostCSS warnings), the Lightning CSS
+adapter with `console.warn`, and `navecss-core expand` on standard error, without
+changing its exit code. No option turns it off for the whole project.
+
+A directive written inside a nested rule that applies to the same element, such as
+`.card { & { @nave hideDesktopUp } display: flex; }`, is checked the same way: its atoms' blocks
+are compared with what follows the directive inside that nested rule, and with what each
+enclosing rule holds after the nested rule. A warning of the second kind says nothing about
+earlier releases, because that later content already won in them.
+
+**Marking an override you mean.** Name the property in a comment inside the
+directive:
+
+```css
+.panel {
+  @nave /* nave-allow-override: display */ hideDesktopUp;
+  display: grid;
+}
+```
+
+The comment says that what comes after this directive's atoms (a later atom in it,
+or your rule's own content) is meant to win for the properties it names. It
+silences the warning for those properties on this directive and nothing else: an
+override of another property, or of another directive's atoms, still warns. A
+shorthand covers its longhands (`outline` covers `outline-color`). You can add a
+reason after `--`: `/* nave-allow-override: display -- a grid on wide screens */`.
+The head `nave-allow-override:` is matched in lower case only, as `eslint-disable`
+is, so a comment that writes it in another case is not a marker: it allows nothing,
+and the warning it was meant to silence still prints.
+The comment never reaches your CSS. Only a comment inside the directive is read,
+because some build steps remove the others before Nave sees the stylesheet (Vite
+under `css.transformer: 'lightningcss'`, for one). A marker naming a property that
+nothing overrides any more is reported, so remove it when you reorder. The Vite plugin under
+`css.transformer: 'lightningcss'` does not report one, at any targets, because it cannot tell
+whether Lightning CSS has already moved what follows the directive.
+
+#### Output size
+
+`@nave` copies an atom's declarations into every rule that uses it. That is the design: the directive is a build-time stand-in for native CSS mixins, whose `@apply` puts a mixin's declarations into the rule that applies it ([why](https://github.com/navecss/navecss/blob/main/docs/04-adr/0006-nave-directive-stands-in-for-css-mixins.md)). A browser that supports native mixins does that expansion itself, so such a stylesheet carries each mixin's body once, plus a short `@apply` where it is used; a build step has to write the copies out.
+
+What the copies cost, in a model of a large app (10,000 component rules using a 25-atom design system and class names of about 20 characters, minified): about 70 percent of the raw CSS, 40 percent after gzip and 30 percent after brotli at level 11. Your app will differ, so measure your own bundle. What reduces it:
+
+- **Compress CSS ahead of time with brotli at its highest level (11)**, instead of compressing on the fly at a lower one. In the model, level 11 sent 260 KB where level 5 sent 330 KB, which saves more than any way of removing the copies that was tried (below).
+- **Split CSS by route**, so a page loads a shared part and its own rules rather than the whole app's. Split into one shared part and 40 routes, a page in the model loaded 65 KB at level 11, about a quarter, though all the parts together came to 348 KB, a third more than the single bundle.
+
+What Nave does not do, and why:
+
+- **It does not merge the copies into shared rules with combined selector lists.** In the model that saved 0.3 percent under brotli at level 11 and made gzip output 19 percent larger, because each selector then repeats once per atom, far apart. With 7-character class names the same merge saved 2 percent under gzip, 4 under brotli at level 11 and 12 under brotli at level 5, still less than level 11 saves over level 5. It also changed the computed style of 4 to 6 percent of the elements sampled: two atoms that set the same property stop resolving in the order you wrote them, and an atom's `@media` blocks move relative to your own declarations.
+- **It does not turn your `@nave` atoms into shared classes for your markup to carry** (`cx()` does that for Nave's built-in atoms, where you choose it). That would move them into the `atomic` layer, below your component CSS, so your other rules and Nave's own component styles start beating them, and the class names it would add to your JavaScript and HTML cost about as much as the CSS it would remove under brotli, and about half as much under gzip.
+
+The lasting fix is native CSS mixins. Once they ship in a browser and the specification settles, Nave adds a flag that writes `@mixin` and `@apply`, and once all three engines support them that becomes the default.
 
 ### Escape hatch — cx() utility
 
@@ -193,7 +324,8 @@ Every custom property Nave declares is in the stylesheet you already installed,
 
 ## Setting up `@nave`
 
-On Vite, use the Vite plugin: it is the one route this package teaches for Vite. On
+On Vite, use the Vite plugin: it is the one route this package teaches for Vite, and for Astro,
+which builds with Vite ([Astro](#astro) has its config). On
 Next.js, webpack, or any other pipeline that runs PostCSS plugins, use the PostCSS plugin. A host
 that runs Lightning CSS directly uses [the Lightning CSS adapter](#lightning-css-adapter-setup),
 and a project with no bundler uses [`navecss-core expand`](#navecss-core-expand).
@@ -218,8 +350,8 @@ It has no dependency and no peer. It expands `@nave` after Vite's own CSS step h
 through `@import`, a Sass file (including a `@mixin` that holds a directive), a CSS Module, an
 `?inline` or `?url` import, a Vue or Svelte style block and a `.css` inside `node_modules` are all
 read as the CSS they compile to, in `vite build` and in the dev server, under either
-`css.transformer`. A `?raw` import returns the file's text as it is. Astro is not covered: it was
-not measured at this release, and no fixture of it runs.
+`css.transformer`. A `?raw` import returns the file's text as it is. Astro has its own setup and
+its own measured list: [Astro](#astro).
 
 **It also chooses which atoms ship.** A `cx()` call in your code whose atoms the build cannot read,
 such as `cx(variant)` with a prop, is an error in the dev server and fails `vite build`.
@@ -242,10 +374,15 @@ Nave class it cannot see has no rule unless its atom is listed in `keep`.
 
 **Under `css.transformer: 'lightningcss'`** the plugin expands exactly as it does under the default
 transformer once both floor keys below are set. At Vite's default targets, which sit below the
-floor, Lightning CSS lowers CSS nesting before any plugin runs, and two things change.
+floor, Lightning CSS lowers CSS nesting before any plugin runs, and three things change.
 A directive written after a declaration that follows a nested rule can be moved ahead of that
 declaration: in `.a { &:hover { color: red; } display: grid; @nave block; }`, `grid` wins with no
-message, where the default transformer makes `block` win. A directive in a group rule nested in a
+message, where the default transformer makes `block` win.
+What a rule says after a directive becomes a rule of its own, after the directive's, so it
+already resolves in the order [Order inside a rule](#order-inside-a-rule) describes, but no order
+warning is printed for it: a later `&:focus { outline: none }` after `focusRing`, for one, removes
+the ring there with no message.
+A directive in a group rule nested in a
 style rule (`.a { @media (...) { @nave flex; } }`) still fails the build, but the message no longer
 names the `& { @nave ...; }` workaround, and its position is in the CSS as Lightning CSS rewrote
 it, not in your file. The plugin also drops one message and only that one: Lightning CSS's
@@ -310,12 +447,28 @@ newest 8.x at the time of each release.
 The Vite plugin also chooses which of Nave's atoms reach your stylesheet. It reads the `cx()` calls
 in the code the build compiles, dependencies included, and ships the rules for the atoms those calls
 name, for the atom of each Nave class written as text (`nave-grid` in `index.html` or in a string in
-your code, say), and for the atoms you list in `keep` and `keepFor`; `srOnlyFocusable` also ships
-whenever `srOnly` does. The dev server serves the same atoms, from the code it has read. This is
+your code, say) and each Nave class a CSS Module composes from global (`composes: nave-flex from global`),
+and for the atoms you list in `keep` and `keepFor`; `srOnlyFocusable` also ships whenever `srOnly`
+does. The dev server serves the same atoms, from the code it has read. This is
 what `navePlugin()` does with no options. On the CSS-first path, where `@nave` copies an atom's
 declarations into your own rule, a project that never calls `cx()` and writes no Nave class ships no
 rule from the atom layer.
 
+In a build, the plugin also turns each `cx()` call it read into the class string the call returns, so
+the map from atom names to classes does not ship: `cx('flex', 'grid')` becomes `"nave-flex nave-grid"`,
+and `cx('flex', on && 'grid')` becomes `["nave-flex", on && "nave-grid"].filter(Boolean).join(" ")`,
+with each argument evaluated once, in the order you wrote it. A direct `cx.raw()` call becomes the
+same join, and a direct `cx.dynamic()` call a lookup in a map of the atoms in `keep` and `keepFor`.
+The dev server keeps the run-time functions, which return the same strings. A bundle holds neither
+the name map nor the atoms' declarations when every use of `cx` in it is one of those direct calls
+and no module that imports `cx` calls `eval` directly. Two forms keep the map, since the build
+cannot follow the alias: `const r = cx.raw` and `const { raw } = cx`. So does a package listed in
+`keepFor` whose calls the build cannot read, because those calls stay calls to the run-time `cx()`.
+A module that calls `eval` directly keeps its import of `cx`, and with it the map, whatever text it
+runs (`eval('1')` too), because that text can read the module's names and the build cannot read the
+text. An indirect call, `(0, eval)(text)` or `globalThis.eval(text)`, runs its text in the global
+scope, where `cx` is not visible, and does not keep the import.
+
 So that nothing is dropped on a guess, a `cx()` call whose atoms the build cannot read fails the
 build. `vite build` reads every module first and fails once, at the end, with a report that lists
 each such use with its file, and its line and column when the source maps lead back to them, then
@@ -514,9 +667,10 @@ build, that list is the set of atoms its CSS holds, so you can diff it between b
 **Shipping every atom.** `navePlugin({ atomic: 'all' })` reads no `cx()` call and ships every atom,
 as the PostCSS plugin does. It suits a project whose Nave classes are mostly written where no build
 reads them, such as a backend's own templates or HTML from a CMS, where listing them in `keep` is
-not practical. It gives up what this section describes: no `cx()` call is read or checked, a name
-that is no atom passes through `cx()` as text, as it does without the plugin, and `cx.dynamic()`
-maps through every atom. The dev server serves every atom too, the plugin sets neither
+not practical. It gives up what this section describes: no `cx()` call is read, checked or turned
+into its class string, so the name map ships, a name that is no atom passes through `cx()` as text,
+as it does without the plugin, and `cx.dynamic()` maps through every atom. The dev server serves
+every atom too, the plugin sets neither
 `optimizeDeps.exclude` nor `resolve.noExternal`, no build writes `nave-used-atoms.json`, and
 `keep`, `keepFor` and `cxModules` are still checked for well-formed values and otherwise do nothing.
 It is also the way out that the plugin's own check names when a build's atom layer does not hold
@@ -546,6 +700,82 @@ their own code, and `keepFor` does not reach it.
 
 List every atom your components can apply at run time, `focusRing`, `srOnly`, `srOnlyFocusable`, `hidden` and the `hide*` atoms included where you use them: a consumer passes them to `keepFor` under your package's name, and one left out renders as if the class were absent in their production build.
 
+#### Astro
+
+Astro builds with Vite, so the Vite plugin is the route there too. Add it under `vite` in your
+Astro config, which is where Astro takes Vite plugins, and put the floor key under `vite` as well:
+Astro's own `build` has no `cssTarget`, and drops one written there without an error.
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import { navePlugin } from '@navecss/core/vite'
+
+export default defineConfig({
+  vite: {
+    plugins: [navePlugin()],
+    build: { cssTarget: ['chrome125', 'edge125', 'firefox128', 'safari18', 'ios18'] },
+  },
+})
+```
+
+The build chooses which atoms ship, so run your checks, keyboard, screen-reader and automated
+accessibility checks included, against a production build as well as in dev: `astro build`, then
+`astro preview` or however you serve production.
+
+Put Nave's order statement first in the `<head>` of every layout, as an inline style, ahead of
+anything that can bring a style, `<ClientRouter />` included:
+
+```astro
+---
+// src/layouts/Layout.astro
+import '../styles/app.css'
+---
+<html lang="en">
+  <head>
+    <style is:inline>@layer tokens.defaults, tokens.presets, reset, atomic, components.nave, components.consumer, overrides;</style>
+    <meta charset="utf-8" />
+    <!-- the rest of your head, <ClientRouter /> included -->
+  </head>
+  <body><slot /></body>
+</html>
+```
+
+Astro can place a page's or a component's own style ahead of your layout's stylesheet, and with
+`<ClientRouter />` it does so whatever the page imports first. A `@layer` in that style then fixes
+its layer's place before Nave's order statement does, and the order inverts with no error. Astro
+leaves an `is:inline` style where you write it, so this one is the first `@layer` the page sees.
+`astro dev` does not show the inversion a build makes, so check the order in a build. The statement
+is the one `@navecss/core/layers` holds, and the two must stay identical. Write the rules of a
+`<style>` block inside `@layer components.consumer`, as for any CSS of yours: Astro leaves them
+outside every layer otherwise, where they beat all of them.
+
+The build chooses atoms as [Which atoms the build ships](#which-atoms-the-build-ships) says, with
+three things particular to Astro. Astro writes its CSS in its server build, before the browser's
+build runs, so an atom named only by code the browser runs, such as a `client:only` component or a
+`<script>` in an `.astro` file, fails the build: list it in `keep`. A dependency the server build
+leaves external is read just as late: add it to `resolve.noExternal` under `vite`, which reaches
+every environment Astro builds, where `ssr.noExternal` does not. And in `output: 'server'` with
+prerendered pages, the stylesheet the on-demand pages share ships every atom.
+
+Both end-of-build checks, the `@nave` scan and the check that the atom layer holds exactly the atoms
+the build chose, also read the stylesheets Astro writes into the page instead of as files (those
+under 4 kB, by default). The file a message names for one of those is the name the stylesheet had
+before Astro inlined it, so no file of that name is in `dist`. In an `.astro` file, the line of a
+`@nave` error counts from the start of the `<style>` block that holds it, not from the top of the
+file, and its column can differ from your file's, because Astro rewrites the block's whitespace.
+
+In `astro dev`, the first paint holds the stylesheet as Vite's own CSS step left it, every atom and
+every `@nave` unexpanded, until the page's scripts load; after that the dev server serves what the
+build would, as far as it has read. The build is unaffected. As on any Vite project, run your
+checks, keyboard, screen-reader and automated accessibility checks included, against a production
+build as well as in dev: `astro build`, then `astro preview` or however you serve production.
+
+A fixture measures this on Astro 7.4.0, with Vite 8.3.5 underneath: `@nave` expanded in `.css`
+files and in `<style>` and `<style is:global>` blocks, and `cx()` read in frontmatter, in templates
+and in React islands, in `astro build` for a static site and for `output: 'server'`, and in
+`astro dev`. Islands in Vue, Svelte or Solid were not measured.
+
 ### PostCSS plugin setup
 
 For Next.js, webpack under `postcss-loader`, and any other pipeline that runs PostCSS plugins.
@@ -602,6 +832,11 @@ Without it, Turbopack compiles for older browsers and rewrites every `light-dark
 Nave's colours included, into `--lightningcss-light` and `--lightningcss-dark` variables. Spell
 the floor out as above: Next 15 rejects the shorter `baseline 2024` with `Unknown browser baseline`.
 
+**Where Nave's warnings show.** With webpack (`next build --webpack`), `next build` prints them under `Compiled with warnings`, once for each compilation that reads the stylesheet, so a CSS Module imported from a Server Component can show the same warning twice; `next dev --webpack` may not print a global stylesheet's, so read them from `next build`. Turbopack does not print PostCSS warnings, so under Turbopack the plugin prints them itself on standard error, with the file, line and column, in `next build` and `next dev` alike. Neither bundler shows them in the browser console or Next's error overlay.
+A problem that [`onUnknown`](#options) covers is a warning only under `'warn'`; under the
+default, `'error'`, it fails the build on either bundler. Where the warnings show was measured
+on Next 16.4.1, not on Next 15.
+
 **If your Vite config sets `css.transformer: 'lightningcss'`, this plugin never
 runs.** That option replaces Vite's CSS pipeline with Lightning CSS, which does
 not run PostCSS plugins at all: the build stays green, `@nave` reaches the
@@ -651,7 +886,8 @@ Nave's own messages, with the file's path and the line and column of each proble
 and the map as a string, ready for `transform()`'s `code` and `inputSourceMap`. `resolver.read` reads each file
 `bundleAsync()` asks for and returns its expanded text, so a file reached through `@import` is
 covered too. It takes `extend` (an object of your own atoms) and `onUnknown` as the other plugins
-do ([Options](#options)); under `'warn'` it prints each problem with `console.warn`.
+do ([Options](#options)); under `'warn'` it prints each problem with `console.warn`, and prints
+the [order warning](#order-inside-a-rule) the same way under every `onUnknown`.
 
 The adapter imports nothing from `lightningcss`, types included, and declares no peer: you bring
 your own copy. The supported range is documented, not declared: `lightningcss` 1.24.1 and later.
@@ -680,6 +916,21 @@ in one error, positioned at the first: its message, then
 others. The report covers one stylesheet, so a bundler that stops at the first
 failing file reports one file per build. Under `'warn'`, each problem is a
 warning of its own.
+The [order warning](#order-inside-a-rule) is not one of these problems: it is printed as a
+warning whatever `onUnknown` says. On Turbopack, Next 16's default bundler, which shows no
+PostCSS warning, the PostCSS plugin prints each problem under `'warn'` and each order warning
+to the terminal instead, as `file:line:column:` and the message
+([where Next.js shows them](#nextjs)). It knows Turbopack by the `TURBOPACK` environment
+variable, which Next.js sets for it, so wherever that variable is set and not empty, under Vite
+or the PostCSS CLI as well, it does the same and raises no PostCSS warning. The Vite plugin and
+the Lightning CSS adapter do not read the variable. The PostCSS plugin also takes
+`printWarnings` (default `true`): with `printWarnings: false` it raises each problem under
+`'warn'` and each order warning as a PostCSS warning and prints none of them, whatever
+`TURBOPACK` holds, for a tool that runs the plugin itself and reports the warnings it raises.
+Such a tool can import `isOrderWarning(warning)` from `@navecss/core/postcss` to tell them
+apart: it is `true` for an order warning and `false` for each of these problems, so the tool
+can report an order warning as the plugin does, whatever `onUnknown` says, and never fail a
+build on one.
 
 To add atoms of your own to `@nave`, pass them as `extend`: see
 [CONSUMER-ATOMS.md](./CONSUMER-ATOMS.md). An `extend` object written inline in
@@ -779,6 +1030,9 @@ across every file is printed in one run, one report per stylesheet. Exit codes:
   `--watch`, a directory that could not be watched. Nothing is written, except that files written
   before an `--out` that failed stay written.
 
+An order warning is printed and is not a problem here: it changes neither the exit code nor what is
+written.
+
 It does not resolve or inline `@import`; that would make it a CSS bundler. It
 expands only the files you name with `--source`, so a stylesheet you import that
 holds `@nave` needs a pair of its own. An `@import` of a relative or absolute URL
@@ -865,17 +1119,18 @@ Consumers of `@navecss/tokens` alone get no guide: it ships only in this package
 
 ## Exports
 
-| Export                       | Description                                                                                           |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `@navecss/core`              | CSS entry point — `@import url('@navecss/core')`                                                      |
-| `@navecss/core/layers`       | The `@layer` order statement alone. Import it first, before any other stylesheet                      |
-| `@navecss/core/no-tokens`    | Entry point for projects that generate their own Nave token layer; see the header comment in the file |
-| `@navecss/core/reset`        | Reset stylesheet only. It reads Nave's custom properties, so it needs a token layer beside it         |
-| `@navecss/core/atomic`       | Generated atomic CSS (global `nave-` classes)                                                         |
-| `@navecss/core/cx`           | `cx()` / `cx.raw()` utilities + `AtomName` type                                                       |
-| `@navecss/core/atoms`        | Atom definitions + `atomClassMap`                                                                     |
-| `@navecss/core/vite`         | Vite plugin — `navePlugin()`                                                                          |
-| `@navecss/core/lightningcss` | Lightning CSS adapter — `navePlugin()`, returning `expand` and `resolver`                             |
-| `@navecss/core/standalone`   | The whole stylesheet in one file, with no `@import`, for projects with no bundler                     |
-| `@navecss/core/postcss`      | PostCSS plugin — `navePlugin()`                                                                       |
-| `@navecss/core/check`        | The survival check as a function — `check({ source })`                                                |
+| Export                       | Description                                                                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `@navecss/core`              | CSS entry point — `@import url('@navecss/core')`                                                                  |
+| `@navecss/core/layers`       | The `@layer` order statement alone. Import it first, before any other stylesheet                                  |
+| `@navecss/core/no-tokens`    | Entry point for projects that generate their own Nave token layer; see the header comment in the file             |
+| `@navecss/core/reset`        | Reset stylesheet only. It reads Nave's custom properties, so it needs a token layer beside it                     |
+| `@navecss/core/atomic`       | Generated atomic CSS (global `nave-` classes)                                                                     |
+| `@navecss/core/cx`           | `cx()` / `cx.raw()` utilities + `AtomName` type                                                                   |
+| `@navecss/core/atoms`        | Atom definitions + `atomClassMap`                                                                                 |
+| `@navecss/core/vite`         | Vite plugin — `navePlugin()`                                                                                      |
+| `@navecss/core/lightningcss` | Lightning CSS adapter — `navePlugin()`, returning `expand` and `resolver`                                         |
+| `@navecss/core/standalone`   | The whole stylesheet in one file, with no `@import`, for projects with no bundler                                 |
+| `@navecss/core/postcss`      | PostCSS plugin — `navePlugin()`                                                                                   |
+| `@navecss/core/check`        | The survival check as a function — `check({ source })`                                                            |
+| `@navecss/core/collect`      | Reads which atoms a module uses and trims the atom layer to them, for build tools; not meant for application code |

package/dist/atom-names-B8Ud-7zD.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The names of Nave's built-in atoms, and the class each one gets.
+ *
+ * cx() needs this and nothing else, so it lives apart from the declaration data in atoms.ts:
+ * a module that imports atoms.ts hands a consumer's bundler every atom's CSS declarations,
+ * not every bundler can drop them, and cx() would pay that for a name map.
+ *
+ * atoms.ts is checked against this list (`satisfies Record<AtomName, AtomDefinition>`), so
+ * an atom added there and missing here, or the other way round, fails the typecheck. Keep the
+ * two in the same order as well: atomic.css is written in the order of atoms.ts, the Vite
+ * plugin lists the atoms in the order of this list, and a test holds the two together.
+ */
+declare const atomNames: readonly ["flex", "inlineFlex", "grid", "block", "inlineBlock", "hidden", "flexCol", "flexWrap", "itemsCenter", "itemsStart", "itemsEnd", "justifyCenter", "justifyBetween", "justifyEnd", "flexGrow", "flexShrink0", "gap", "relative", "absolute", "insetFull", "wFull", "hFull", "minW0", "truncate", "srOnly", "srOnlyFocusable", "noWrap", "breakWord", "textLeft", "textCenter", "textRight", "interactive", "focusRing", "disabledState", "rounded", "roundedCard", "roundedFull", "border", "overflowHidden", "overflowAuto", "transition", "container", "hidePhoneOnly", "hideTabletPortraitUp", "hideTabletLandscapeUp", "hideDesktopUp", "stackPhoneOnly", "wFullPhoneOnly"];
+type AtomName = (typeof atomNames)[number];
+/**
+ * Converts a camelCase atom name to its nave-kebab-case CSS class name.
+ * focusRing → nave-focus-ring
+ */
+declare const toClassName: (name: AtomName) => string;
+/**
+ * Map of atom name → global CSS class name.
+ * Used by cx() and the directive core's diagnostic hints.
+ * Only covers Nave built-in atoms — consumer atoms are @nave-directive only.
+ */
+declare const atomClassMap: Record<AtomName, string>;
+
+export { atomClassMap as a, toClassName as t };
+export type { AtomName as A };

package/dist/atoms.d.ts

@@ -1,3 +1,5 @@
+export { A as AtomName, a as atomClassMap, t as toClassName } from './atom-names-B8Ud-7zD.js';
+
 type CSSDeclarations = Record<string, string>;
 type PseudoMap = Record<string, CSSDeclarations>;
 interface MediaBlock {
@@ -403,17 +405,6 @@ declare const atoms: {
         };
     };
 };
-type AtomName = keyof typeof atoms;
-/**
- * Converts a camelCase atom name to its nave-kebab-case CSS class name.
- * focusRing → nave-focus-ring
- */
-declare const toClassName: (name: AtomName) => string;
-/**
- * Map of atom name → global CSS class name.
- * Used by cx() and the directive core's diagnostic hints.
- * Only covers Nave built-in atoms — consumer atoms are @nave-directive only.
- */
-declare const atomClassMap: Record<AtomName, string>;
 
-export { type AtomDefinition, type AtomName, atomClassMap, atoms, toClassName };
+export { atoms };
+export type { AtomDefinition };

package/dist/atoms.js

@@ -1 +1,2 @@
-export { atomClassMap, atoms, toClassName } from './chunk-LIUB4EES.js';
+export { atoms } from './chunk-CUL5PLPI.js';
+export { atomClassMap, toClassName } from './chunk-GZL2VW7C.js';