@navecss/core 0.1.1 → 0.3.0

package/nave.css-data.json

@@ -0,0 +1,12 @@
+{
+  "version": 1.1,
+  "atDirectives": [
+    {
+      "name": "@nave",
+      "description": {
+        "kind": "markdown",
+        "value": "The `@nave` at-rule applies one or more of Nave’s built-in atomic utilities to the CSS rule it appears in. Loading this file stops an editor from reporting `@nave` as an unknown at-rule and shows this description on hover; it does not complete atom names.\n\n- **Display:** `flex`, `inlineFlex`, `grid`, `block`, `inlineBlock`, `hidden`\n- **Flex:** `flexCol`, `flexWrap`, `itemsCenter`, `itemsStart`, `itemsEnd`, `justifyCenter`, `justifyBetween`, `justifyEnd`, `flexGrow`, `flexShrink0`, `gap`\n- **Position:** `relative`, `absolute`, `insetFull`\n- **Sizing:** `wFull`, `hFull`, `minW0`\n- **Typography:** `truncate`, `srOnly`, `srOnlyFocusable`, `noWrap`, `breakWord`, `textLeft`, `textCenter`, `textRight`\n- **Interaction:** `interactive`, `focusRing`, `disabledState`\n- **Visual:** `rounded`, `roundedCard`, `roundedFull`, `border`, `overflowHidden`, `overflowAuto`\n- **Transition:** `transition`\n- **Containment:** `container`\n- **Responsive:** `hidePhoneOnly`, `hideTabletPortraitUp`, `hideTabletLandscapeUp`, `hideDesktopUp`, `stackPhoneOnly`, `wFullPhoneOnly`\n\nAtoms registered through `extend` are valid and are not listed here."
+      }
+    }
+  ]
+}

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@navecss/core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
-  "description": "Nave design system — layer architecture, reset, atomic utilities, PostCSS plugin",
+  "description": "Nave design system — layer architecture, reset, atomic utilities, and the Vite, PostCSS and Lightning CSS adapters and a command line for the @nave directive",
   "keywords": [
     "css",
     "design-system",
     "css-layers",
     "atomic-css",
     "postcss-plugin",
+    "vite-plugin",
+    "lightningcss",
     "zero-runtime"
   ],
   "homepage": "https://github.com/navecss/navecss/tree/main/packages/core#readme",
@@ -31,15 +33,39 @@
       "import": "./dist/atoms.js"
     },
     "./postcss": {
-      "types": "./dist/postcss.d.ts",
-      "import": "./dist/postcss.js"
+      "import": {
+        "types": "./dist/postcss.d.ts",
+        "default": "./dist/postcss.js"
+      },
+      "require": {
+        "types": "./dist/postcss.d.cts",
+        "default": "./dist/postcss.cjs"
+      }
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./lightningcss": {
+      "types": "./dist/lightningcss.d.ts",
+      "import": "./dist/lightningcss.js"
+    },
+    "./standalone": "./dist/standalone.css",
+    "./check": {
+      "types": "./dist/check.d.ts",
+      "import": "./dist/check.js"
     },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "navecss-core": "./dist/bin.js"
+  },
   "files": [
     "dist",
     "CONSUMER-ATOMS.md",
-    "ATOMS.md"
+    "ATOMS.md",
+    "nave.css-data.json",
+    "skills"
   ],
   "peerDependencies": {
     "postcss": "^8"
@@ -50,19 +76,31 @@
     }
   },
   "dependencies": {
-    "@navecss/tokens": "^0.1.1"
+    "@navecss/tokens": "^0.3.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.2",
-    "@vitest/browser": "5.0.1",
-    "@vitest/browser-playwright": "5.0.1",
-    "@vitest/coverage-v8": "5.0.1",
+    "@rmenke/css-tokenizer-tests": "1.4.0",
+    "@sveltejs/vite-plugin-svelte": "7.3.1",
+    "@types/node": "^26.6.4",
+    "@vitejs/plugin-vue": "6.0.9",
+    "@vitest/browser": "5.0.3",
+    "@vitest/browser-playwright": "5.0.3",
+    "@vitest/coverage-v8": "5.0.3",
+    "lightningcss": "1.33.0",
+    "lightningcss-1-24": "npm:lightningcss@1.24.1",
     "playwright": "1.63.0",
     "postcss": "^8.5.28",
-    "prettier": "3.9.8",
+    "prettier": "3.9.9",
+    "sass": "1.105.1",
+    "source-map": "^0.8.0",
+    "svelte": "5.57.2",
     "tsup": "^8.5.1",
     "typescript": "6.0.3",
-    "vitest": "5.0.1"
+    "vite": "8.3.3",
+    "vite-floor": "npm:vite@8.2.1",
+    "vitest": "5.0.3",
+    "vscode-css-languageservice": "6.3.10",
+    "vue": "3.5.43"
   },
   "engines": {
     "node": ">=22.18"
@@ -83,11 +121,10 @@
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit && tsc --noEmit -p test/browser/tsconfig.json",
-    "lint": "eslint src scripts --max-warnings 0 && stylelint \"src/**/*.css\" --max-warnings 0",
-    "lint:fix": "eslint src scripts --fix && stylelint \"src/**/*.css\" --fix",
-    "test": "node scripts/generate-consumer-theming-fixtures.ts && vitest run",
-    "test:coverage": "node scripts/generate-consumer-theming-fixtures.ts && vitest run --coverage",
-    "test:browser": "node scripts/generate-consumer-theming-fixtures.ts && vitest run --config vitest.browser.config.ts",
-    "check:pack": "node ../../scripts/without-dry-run.mjs publint && node ../../scripts/without-dry-run.mjs attw --pack . --profile esm-only --exclude-entrypoints . layers no-tokens reset atomic"
+    "lint": "eslint src scripts \"test/**/*.ts\" --max-warnings 0 && stylelint \"src/**/*.css\" --max-warnings 0",
+    "lint:fix": "eslint src scripts \"test/**/*.ts\" --fix && stylelint \"src/**/*.css\" --fix",
+    "test": "node scripts/generate-consumer-theming-fixtures.ts && node scripts/generate-vite-plugin-fixtures.ts && vitest run",
+    "test:browser": "node scripts/generate-consumer-theming-fixtures.ts && node scripts/generate-vite-plugin-fixtures.ts && node scripts/generate-lightningcss-fixtures.ts && node scripts/generate-no-bundler-fixture.ts && vitest run --config vitest.browser.config.ts && vitest run --config vitest.chromium.config.ts",
+    "check:pack": "node ../../scripts/without-dry-run.mjs publint && node ../../scripts/without-dry-run.mjs attw --pack . --profile esm-only --exclude-entrypoints . layers no-tokens reset atomic standalone"
   }
 }

package/skills/navecss/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: navecss
+description: 'Reference for Nave — the @nave at-rule, cx()/cx.raw(), --nave-* custom
+  properties and the @layer order — so an agent applies existing atoms and tokens instead
+  of inventing new CSS.'
+---
+
+# navecss
+
+An index of Nave’s vocabulary for a coding agent: every built-in atom, every `--nave-*`
+custom property, the layer order, and the idiom that applies them. See
+[ATOMS.md](../../ATOMS.md) for the same atom table alone, and
+[Theming](https://github.com/navecss/navecss/blob/main/README.md#theming) for how a project
+changes the seed colour and everything derived from it.
+
+## Using `@nave` and `var(--nave-*)`
+
+Apply built-in atoms with the `@nave` at-rule inside a CSS rule; read values through
+`var(--nave-*)`. Both vocabularies are closed sets: the built-in atom names and the
+`--nave-*` names are exactly the ones on this page.
+An atom name that is neither on this page nor in the project’s own `navePlugin({ extend })`
+configuration is not used, and a `--nave-*` name not on this page is not used either:
+when the name you need does not exist, say so rather than invent one.
+An undeclared `--nave-*` name renders nothing; `@navecss/stylelint-config` reports it.
+
+Atoms a project registers through `navePlugin({ extend })` are not listed on this page.
+They are valid in `@nave` only, never in `cx()`, and they live in that project’s own
+`navePlugin({ extend })` configuration, so look for them there
+(their shape is in [CONSUMER-ATOMS.md](../../CONSUMER-ATOMS.md)).
+Where one shares a built-in atom’s name,
+`@nave` applies the project’s atom and `cx()` still returns the built-in,
+so the declarations this page shows for that name are not what `@nave` applies there.
+
+```css
+/* button.module.css */
+@layer components.consumer {
+  .root {
+    @nave interactive focusRing transition;
+    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);
+  }
+}
+```
+
+Consumer rules go in `@layer components.consumer`, and a deliberate exception in
+`@layer overrides`; never write an unlayered rule. Atom names are the camelCase keys listed
+under Atoms below (`focusRing`, `justifyBetween`), never the `nave-` class they emit.
+
+See where `@nave` is valid (nesting depth, `@media`/`@container`, `@keyframes`) in
+[the package README](../../README.md#where-nave-is-valid).
+
+## `cx()`
+
+The JavaScript escape hatch: `cx('interactive', 'focusRing')` returns the class of each
+built-in atom it names, and `cx()` takes built-in atoms and nothing else.
+Its type check is TypeScript only: a JavaScript consumer gets none of it. A type error from
+`cx()` means the name is wrong: it is never a reason to reach for `cx.raw()` or a cast.
+
+In a project whose Vite config uses `navePlugin()` from `@navecss/core/vite`, the build reads every `cx()` call and fails on one whose atoms it cannot list. Pass names it can read (a literal, a condition between literals, a `const` in the same file); to choose by a value, call `cx()` once per case and pick between the results; pass a name known only at run time to `cx.dynamic()`, with its atoms in `keep`. The build's report names its remedies, most preferred first: take the first one that fits. Never set `atomic: 'all'`, never build a `nave-` class from pieces, and never apply a class taken from `@navecss/core/atoms`, to make a report go away. The dev server serves the atoms the build would ship, chosen from the code it has read, so a `nave-*` class with no rule in dev is written where the build cannot see it: move it into code the build reads, or list its atom in `keep`.
+
+## `cx.raw()`
+
+`cx.raw()` is for a class from outside any system Nave sees, the project’s own classes
+included. Where a project class shares an atom’s name, `cx('container')` is Nave’s atom and
+`cx.raw('container')` is the project’s class.
+
+`cx.raw()` is also for a CSS Module class behind a condition, shown by the code span
+`cx.raw(isActive && styles.active)`, because a template-literal slot interpolates a falsy
+condition’s own value — naming `false`, `undefined` and `0` — as a class.
+
+If the project runs `@navecss/eslint-plugin`, its reports name their remedies, most preferred first: take the first one that fits. Never answer a report with a disable comment, and never write a `cx.raw()` reason to make a report go away.
+
+## Atoms
+
+Every built-in atom: the name as written in `@nave` and `cx()`, the declarations it
+applies, and its pseudo-class, `@media` or `@container` variants.
+A name not on this list is not a built-in atom.
+A project’s own `navePlugin({ extend })` atoms are not listed here (see Using `@nave` above);
+a name that is in neither is not used, so do not invent one.
+
+### Display
+
+| Atom          | Declarations             | Variants |
+| ------------- | ------------------------ | -------- |
+| `flex`        | `display: flex;`         | —        |
+| `inlineFlex`  | `display: inline-flex;`  | —        |
+| `grid`        | `display: grid;`         | —        |
+| `block`       | `display: block;`        | —        |
+| `inlineBlock` | `display: inline-block;` | —        |
+| `hidden`      | `display: none;`         | —        |
+
+### Flex
+
+| Atom             | Declarations                           | Variants |
+| ---------------- | -------------------------------------- | -------- |
+| `flexCol`        | `flex-direction: column;`              | —        |
+| `flexWrap`       | `flex-wrap: wrap;`                     | —        |
+| `itemsCenter`    | `align-items: center;`                 | —        |
+| `itemsStart`     | `align-items: flex-start;`             | —        |
+| `itemsEnd`       | `align-items: flex-end;`               | —        |
+| `justifyCenter`  | `justify-content: center;`             | —        |
+| `justifyBetween` | `justify-content: space-between;`      | —        |
+| `justifyEnd`     | `justify-content: flex-end;`           | —        |
+| `flexGrow`       | `flex-grow: 1;`                        | —        |
+| `flexShrink0`    | `flex-shrink: 0;`                      | —        |
+| `gap`            | `gap: var(--nave-spacing-content-md);` | —        |
+
+### Position
+
+| Atom        | Declarations          | Variants |
+| ----------- | --------------------- | -------- |
+| `relative`  | `position: relative;` | —        |
+| `absolute`  | `position: absolute;` | —        |
+| `insetFull` | `inset: 0;`           | —        |
+
+### Sizing
+
+| Atom    | Declarations    | Variants |
+| ------- | --------------- | -------- |
+| `wFull` | `width: 100%;`  | —        |
+| `hFull` | `height: 100%;` | —        |
+| `minW0` | `min-width: 0;` | —        |
+
+### Typography
+
+| Atom              | Declarations                                                                                                                                                                                    | Variants                                                                                                                                                                                                                                                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `truncate`        | `overflow: hidden;`<br>`text-overflow: ellipsis;`<br>`white-space: nowrap;`                                                                                                                     | —                                                                                                                                                                                                                                                                                                                                         |
+| `srOnly`          | `position: absolute;`<br>`width: 1px;`<br>`height: 1px;`<br>`padding: 0;`<br>`margin: -1px;`<br>`overflow: hidden;`<br>`clip-path: inset(50%);`<br>`white-space: nowrap;`<br>`border-width: 0;` | —                                                                                                                                                                                                                                                                                                                                         |
+| `srOnlyFocusable` | `position: absolute;`<br>`width: 1px;`<br>`height: 1px;`<br>`padding: 0;`<br>`margin: -1px;`<br>`overflow: hidden;`<br>`clip-path: inset(50%);`<br>`white-space: nowrap;`<br>`border-width: 0;` | `:focus-visible` — `position: static;`<br>`width: auto;`<br>`height: auto;`<br>`margin: 0;`<br>`overflow: visible;`<br>`clip-path: none;`<br>`white-space: normal;`<br>`:focus-within` — `position: static;`<br>`width: auto;`<br>`height: auto;`<br>`margin: 0;`<br>`overflow: visible;`<br>`clip-path: none;`<br>`white-space: normal;` |
+| `noWrap`          | `white-space: nowrap;`                                                                                                                                                                          | —                                                                                                                                                                                                                                                                                                                                         |
+| `breakWord`       | `overflow-wrap: break-word;`                                                                                                                                                                    | —                                                                                                                                                                                                                                                                                                                                         |
+| `textLeft`        | `text-align: left;`                                                                                                                                                                             | —                                                                                                                                                                                                                                                                                                                                         |
+| `textCenter`      | `text-align: center;`                                                                                                                                                                           | —                                                                                                                                                                                                                                                                                                                                         |
+| `textRight`       | `text-align: right;`                                                                                                                                                                            | —                                                                                                                                                                                                                                                                                                                                         |
+
+### Interaction
+
+| Atom            | Declarations                                                                                                              | Variants                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `interactive`   | `cursor: pointer;`<br>`-webkit-user-select: none;`<br>`user-select: none;`<br>`-webkit-tap-highlight-color: transparent;` | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `focusRing`     | `outline: none;`                                                                                                          | `:focus-visible` — `outline-style: solid;`<br>`outline-width: var(--nave-border-width-focus, 2px);`<br>`outline-color: var(--nave-color-border-focus, currentColor);`<br>`outline-offset: 2px;`                                                                                                                                                                                                                                                                |
+| `disabledState` | —                                                                                                                         | `:disabled, [aria-disabled="true"]` — `color: var(--nave-color-content-disabled);`<br>`border-color: var(--nave-color-border-disabled);`<br>`pointer-events: none;`<br>On the aria-disabled branch the element stays focusable by design: this atom only blocks pointer activation (pointer-events: none), so the component's own activation handler must also check the attribute and no-op on Enter and Space, since CSS cannot prevent keyboard activation. |
+
+### Visual
+
+| Atom             | Declarations                                                                  | Variants |
+| ---------------- | ----------------------------------------------------------------------------- | -------- |
+| `rounded`        | `border-radius: var(--nave-radius-control);`                                  | —        |
+| `roundedCard`    | `border-radius: var(--nave-radius-card);`                                     | —        |
+| `roundedFull`    | `border-radius: var(--nave-radius-full);`                                     | —        |
+| `border`         | `border: var(--nave-border-width-sm) solid var(--nave-color-border-default);` | —        |
+| `overflowHidden` | `overflow: hidden;`                                                           | —        |
+| `overflowAuto`   | `overflow: auto;`                                                             | —        |
+
+### Transition
+
+| Atom         | Declarations                                                                                                                                                                                                        | Variants |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `transition` | `transition-property: color, background-color, border-color, opacity, box-shadow;`<br>`transition-duration: var(--nave-motion-duration-base);`<br>`transition-timing-function: var(--nave-motion-easing-standard);` | —        |
+
+### Containment
+
+| Atom        | Declarations                   | Variants |
+| ----------- | ------------------------------ | -------- |
+| `container` | `container-type: inline-size;` | —        |
+
+### Responsive
+
+| Atom                    | Declarations | Variants                                              |
+| ----------------------- | ------------ | ----------------------------------------------------- |
+| `hidePhoneOnly`         | —            | `@media (width < 37.5em)` — `display: none;`          |
+| `hideTabletPortraitUp`  | —            | `@media (width >= 37.5em)` — `display: none;`         |
+| `hideTabletLandscapeUp` | —            | `@media (width >= 56.25em)` — `display: none;`        |
+| `hideDesktopUp`         | —            | `@media (width >= 75em)` — `display: none;`           |
+| `stackPhoneOnly`        | —            | `@media (width < 37.5em)` — `flex-direction: column;` |
+| `wFullPhoneOnly`        | —            | `@media (width < 37.5em)` — `width: 100%;`            |
+
+## Custom properties
+
+Every `--nave-*` custom property Nave declares, with its description where one exists. A
+name not on this list is not declared — an undeclared `--nave-*` name passes the build and
+renders nothing.
+
+- `--nave-border-width-focus`: Focus ring indicator outline width
+- `--nave-border-width-lg`
+- `--nave-border-width-mark`: Strokes of glyphs drawn in CSS: check marks, indeterminate bars
+- `--nave-border-width-none`
+- `--nave-border-width-sm`: Default border / divider
+- `--nave-color-action-primary`
+- `--nave-color-action-primary-active`
+- `--nave-color-action-primary-hover`
+- `--nave-color-action-secondary`
+- `--nave-color-border-control`: Identifying boundary for a control (inputs, form boundaries, and the secondary action control).
+- `--nave-color-border-default`: Decorative dividers and card edges.
+- `--nave-color-border-disabled`
+- `--nave-color-border-focus`
+- `--nave-color-border-strong`
+- `--nave-color-content-disabled`: Text inside a disabled interactive component.
+- `--nave-color-content-inverse`: Declared foreground for surface.inverse.
+- `--nave-color-content-link`: Do not distinguish a link by colour alone. Nave's own examples keep a non-colour distinction wherever this token is shown.
+- `--nave-color-content-primary`
+- `--nave-color-content-secondary`
+- `--nave-color-content-tertiary`: Placeholder and hint text only.
+- `--nave-color-feedback-danger`: Solid-background role for a destructive control or error state.
+- `--nave-color-feedback-danger-foreground`: Foreground role for danger text and icons.
+- `--nave-color-feedback-info`: Alias of feedback.warning (shared tinted-neutral family).
+- `--nave-color-feedback-info-foreground`
+- `--nave-color-feedback-success`: Alias of feedback.warning (shared tinted-neutral family).
+- `--nave-color-feedback-success-foreground`
+- `--nave-color-feedback-warning`: Solid-background role for a warning state (shared tinted-neutral family).
+- `--nave-color-feedback-warning-foreground`: Foreground role for warning text and icons.
+- `--nave-color-on-action-primary`
+- `--nave-color-on-feedback-danger`: Declared foreground for the solid feedback.danger background.
+- `--nave-color-on-feedback-info`
+- `--nave-color-on-feedback-success`
+- `--nave-color-on-feedback-warning`
+- `--nave-color-surface-base`
+- `--nave-color-surface-inverse`
+- `--nave-color-surface-overlay`
+- `--nave-color-surface-raised`
+- `--nave-color-surface-sunken`
+- `--nave-color-tint`
+- `--nave-font-family-base`: Body / UI typeface
+- `--nave-font-family-display`: Heading typeface — swap for a display font when ready
+- `--nave-font-family-mono`: Code / monospace typeface
+- `--nave-font-size-2xl`
+- `--nave-font-size-3xl`
+- `--nave-font-size-4xl`
+- `--nave-font-size-lg`
+- `--nave-font-size-md`: Base body size (16px default)
+- `--nave-font-size-sm`
+- `--nave-font-size-xl`
+- `--nave-font-size-xs`
+- `--nave-font-weight-bold`
+- `--nave-font-weight-medium`
+- `--nave-font-weight-regular`
+- `--nave-font-weight-semibold`
+- `--nave-layer-base`: Default document flow
+- `--nave-layer-dropdown`: Dropdowns, context menus, select panels
+- `--nave-layer-modal`: Modal dialogs and drawers
+- `--nave-layer-overlay`: Backdrop overlays behind modals
+- `--nave-layer-sticky`: Sticky headers, floating toolbars
+- `--nave-layer-toast`: Toast notifications and snackbars
+- `--nave-layer-tooltip`: Tooltips — always on top of everything
+- `--nave-letter-spacing-normal`: Default — no adjustment
+- `--nave-letter-spacing-tight`: Large headings and display text
+- `--nave-letter-spacing-wide`: Uppercase labels, small caps
+- `--nave-line-height-base`: Default body line height
+- `--nave-line-height-loose`
+- `--nave-line-height-none`: Single-line / icon buttons — no extra leading
+- `--nave-line-height-relaxed`
+- `--nave-line-height-snug`
+- `--nave-line-height-tight`: Headings
+- `--nave-motion-duration-base`: Default state transitions: hover, focus
+- `--nave-motion-duration-fast`: Micro-interactions: tooltips, badges
+- `--nave-motion-duration-instant`: No animation — kept at 0ms even under prefers-reduced-motion
+- `--nave-motion-duration-slow`: Layout shifts: accordion, drawer
+- `--nave-motion-easing-accelerate`: Elements leaving the screen
+- `--nave-motion-easing-decelerate`: Elements entering the screen
+- `--nave-motion-easing-standard`: General-purpose — enters and exits
+- `--nave-opacity-disabled`: Opacity multiplier for muting content that is inert and contains nothing focusable (e.g. a disabled icon or illustration). Nave's own interactive-disabled state is expressed through content.disabled and border.disabled instead, not this token: opacity composites everything an element paints, including a focus indicator inside it.
+- `--nave-radius-card`: Cards, panels, dialogs
+- `--nave-radius-control`: Inputs, buttons, tags, and the popovers, menus and select lists anchored to a control
+- `--nave-radius-full`: Pill / badge shape
+- `--nave-radius-none`
+- `--nave-radius-overlay`: Modals, drawers, sheets
+- `--nave-radius-sm`
+- `--nave-shadow-modal`: Dialogs and modals — highest elevation
+- `--nave-shadow-none`: No elevation
+- `--nave-shadow-overlay`: Popovers, dropdowns, floating elements
+- `--nave-shadow-raised`: Cards, slight elevation above base
+- `--nave-size-avatar-lg`
+- `--nave-size-avatar-md`
+- `--nave-size-avatar-sm`
+- `--nave-size-control-lg`: Large controls
+- `--nave-size-control-md`: Default control height
+- `--nave-size-control-sm`: Small controls
+- `--nave-size-control-xs`: Compact/dense controls
+- `--nave-size-icon-lg`
+- `--nave-size-icon-md`: Default inline icon
+- `--nave-size-icon-sm`
+- `--nave-size-icon-xl`
+- `--nave-size-icon-xs`
+- `--nave-spacing-content-lg`
+- `--nave-spacing-content-md`: Default component gap and padding
+- `--nave-spacing-content-sm`
+- `--nave-spacing-content-xl`
+- `--nave-spacing-content-xs`
+- `--nave-spacing-control-lg`
+- `--nave-spacing-control-md`
+- `--nave-spacing-control-sm`: No matching _primitive.space rung; authored directly
+- `--nave-spacing-control-xs`
+- `--nave-spacing-layout-lg`
+- `--nave-spacing-layout-md`
+- `--nave-spacing-layout-sm`
+- `--nave-spacing-layout-xs`
+
+## Layers
+
+Nave’s layer order: `@layer tokens.defaults, tokens.presets, reset, atomic, components.nave, components.consumer, overrides;`
+
+The order holds only if it is the first `@layer` declaration the page sees:
+a stylesheet that declares a layer and loads earlier fixes that layer’s position first,
+and the order inverts with no error.
+So keep `@navecss/core/layers`, the order statement alone, as the first import of the
+entry stylesheet, and load that stylesheet before anything that brings its own stylesheet,
+components included.
+
+Your own component CSS goes in `@layer components.consumer`; a deliberate exception goes in
+`@layer overrides`, which beats every other layer. A rule left outside any layer beats them
+all, `overrides` included, so never write unlayered CSS.
+That is the order for normal declarations. `!important` reverses it: an `!important` in
+`overrides` loses to one in any earlier layer, Nave’s reset included, and one outside any
+layer loses to every layered one.