@navecss/core 0.4.0 → 0.6.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

@@ -107,10 +107,140 @@ 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. 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.
+
+**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,8 +323,11 @@ 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
-Next.js, webpack, or any other pipeline that runs PostCSS plugins, use the PostCSS plugin. A host
+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, use [`@navecss/prune`](https://github.com/navecss/navecss/tree/main/packages/prune#readme)
+to ship only the atoms the build can read a use for, or the PostCSS plugin to keep every atom. On
+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 +351,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 +375,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,8 +448,9 @@ 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.
@@ -456,16 +595,27 @@ list: with an empty list, or none, it fails the build. Each client build records
 `nave-used-atoms.json` file described below, the atoms it read from each listed package's calls,
 where the calls it could not read are, and any `keepFor` key that names no package the build read.
 
-`keepFor` stands in for the package's own calls, never for a call your code makes, so three problems
+`keepFor` stands in for the package's own calls, never for a call your code makes, so four problems
 in a listed package still fail the build. A module of the package that re-exports `cx` under the
 name `cx` still fails when a file of yours imports `cx` from that module itself, in an `import` or
 `export ... from` statement, or a dependency that does more than re-export it imports it from there,
 and the report gives the `cxModules` entry that lets the build read those calls. Through a module
 that only re-exports it, such as the package's own entry file or another package, a listed module
 would be two steps away, so there the report names each file of yours that takes it: import `cx`
-from `@navecss/core/cx` there instead. A module that gives `cx` out under another name, as a default
-or inside a namespace, still fails when your code takes that export, and the report names each file
-of yours that does: import `cx` from `@navecss/core/cx` there instead. And a module of the package
+from `@navecss/core/cx` there instead. A CommonJS module that forwards it with
+`module.exports = require(...)` or `exports.cn = require(...).cn`, or with what TypeScript emits for
+`export { cn } from` and `export * from` when it compiles to CommonJS, counts as one that only
+re-exports it. A module that gives `cx` out under another name, as a default
+or inside a namespace, or by assigning it first (`export const cn = cx`), still fails when your code
+takes that export, and the report names each file of yours that does: import `cx` from
+`@navecss/core/cx` there instead. A module of the package that uses `cx` where the build cannot
+follow it to an export, such as `obj.cn = cx`, `memo(cx)` or `{ cn: cx }`, or that takes a module
+holding a `cx` export in a way the build reads neither as calls only nor as a forward,
+such as the CommonJS that Babel, esbuild or Rollup write for `export * from`, fails whenever it is
+part of the build, whatever your code takes from the package, because the build cannot tell whether
+a call of yours goes through it. The report names the file and the form. The fix is the package's,
+in a release of it or a patched copy: export `cx` by name from an ES module. Until then, ship every
+atom (below). And a module of the package
 that you list in `cxModules` but that does not re-export Nave's `cx` under that name still fails:
 remove it from `cxModules`.
 
@@ -481,6 +631,11 @@ A class your code takes at run time from `@navecss/core/atoms` (`atomClassMap[va
 `toClassName('grid')`) is one the build does not read: it neither reads nor refuses it, so list its
 atom in `keep`.
 
+A package listed in `keepFor` can give `cx` to your code without the build failing if it redefines
+or adds a method on `Function.prototype` or `Object.prototype`, or declares its own function under
+one of the names compilers reserve for their interop helpers, such as `__importStar`: the build
+cannot see either.
+
 If your pages are rendered outside the build, by a backend that serves its own templates and uses
 Vite for its assets only, the build reads none of their classes. While `keep` is empty, the plugin
 warns when it has read no HTML page, no server render and no use of Nave at all: no `cx()` call, no
@@ -490,7 +645,9 @@ templates use in `keep`, or, if they are many, ship every atom (below).
 
 The PostCSS plugin and the Lightning CSS adapter read no `cx()` call and leave every atom in the
 layer, on Next.js and webpack alike; so does a page with no bundler, which links the standalone
-stylesheet.
+stylesheet. On Next.js,
+[`@navecss/prune`](https://github.com/navecss/navecss/tree/main/packages/prune#readme) ships only
+the atoms its build can read a use for.
 
 A server build leaves packages in `node_modules` external by default, so it does not read their
 code. For such a package that depends on `@navecss/core`, the build warns, naming it, unless it is
@@ -562,6 +719,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.
@@ -592,6 +825,10 @@ If you are using only `cx()` or tokens, you do not need to install it.
 
 #### Next.js
 
+To ship only the atoms the build can read a use for, use
+[`@navecss/prune`](https://github.com/navecss/navecss/tree/main/packages/prune#readme) in place of
+this plugin. The setup below keeps every atom.
+
 Next.js reads a PostCSS plugin by its package name, so give it the name as a key and do not
 call `navePlugin()`:
 
@@ -618,6 +855,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
@@ -667,7 +909,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.
@@ -696,6 +939,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
@@ -795,6 +1053,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
@@ -881,18 +1142,24 @@ 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 })`                                                |
-| `@navecss/core/collect`      | Reads which atoms a module uses, for build tools; not meant for application code                      |
+| 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 |
+
+## Trademark
+
+This package is not affiliated with, endorsed by or sponsored by Vercel or the Next.js project.
+
+Vercel, the Vercel design, Next.js and related marks, designs and logos are trademarks or registered trademarks of Vercel, Inc. or its affiliates in the US and other countries.

package/dist/{atom-names-2OreuBx9.d.ts → atom-names-B8Ud-7zD.d.ts}

@@ -24,4 +24,5 @@ declare const toClassName: (name: AtomName) => string;
  */
 declare const atomClassMap: Record<AtomName, string>;
 
-export { type AtomName as A, atomClassMap as a, toClassName as t };
+export { atomClassMap as a, toClassName as t };
+export type { AtomName as A };

package/dist/atoms.d.ts

@@ -1,4 +1,4 @@
-export { A as AtomName, a as atomClassMap, t as toClassName } from './atom-names-2OreuBx9.js';
+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>;
@@ -406,4 +406,5 @@ declare const atoms: {
     };
 };
 
-export { type AtomDefinition, atoms };
+export { atoms };
+export type { AtomDefinition };