@navecss/core 0.1.1 → 0.2.0

package/ATOMS.md

@@ -51,24 +51,24 @@ variants, if any.
 
 ## Typography
 
-| Atom              | Class                    | Declarations                                                                                                                                                                                    | Variants                            |
-| ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `truncate`        | `nave-truncate`          | `overflow: hidden;`<br>`text-overflow: ellipsis;`<br>`white-space: nowrap;`                                                                                                                     | —                                   |
-| `srOnly`          | `nave-sr-only`           | `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` | `nave-sr-only-focusable` | `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`<br>`:focus-within` |
-| `noWrap`          | `nave-no-wrap`           | `white-space: nowrap;`                                                                                                                                                                          | —                                   |
-| `breakWord`       | `nave-break-word`        | `overflow-wrap: break-word;`                                                                                                                                                                    | —                                   |
-| `textLeft`        | `nave-text-left`         | `text-align: left;`                                                                                                                                                                             | —                                   |
-| `textCenter`      | `nave-text-center`       | `text-align: center;`                                                                                                                                                                           | —                                   |
-| `textRight`       | `nave-text-right`        | `text-align: right;`                                                                                                                                                                            | —                                   |
+| Atom              | Class                    | Declarations                                                                                                                                                                                    | Variants                                                                                                                                                                                                                                                                                                                                  |
+| ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `truncate`        | `nave-truncate`          | `overflow: hidden;`<br>`text-overflow: ellipsis;`<br>`white-space: nowrap;`                                                                                                                     | —                                                                                                                                                                                                                                                                                                                                         |
+| `srOnly`          | `nave-sr-only`           | `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` | `nave-sr-only-focusable` | `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`          | `nave-no-wrap`           | `white-space: nowrap;`                                                                                                                                                                          | —                                                                                                                                                                                                                                                                                                                                         |
+| `breakWord`       | `nave-break-word`        | `overflow-wrap: break-word;`                                                                                                                                                                    | —                                                                                                                                                                                                                                                                                                                                         |
+| `textLeft`        | `nave-text-left`         | `text-align: left;`                                                                                                                                                                             | —                                                                                                                                                                                                                                                                                                                                         |
+| `textCenter`      | `nave-text-center`       | `text-align: center;`                                                                                                                                                                           | —                                                                                                                                                                                                                                                                                                                                         |
+| `textRight`       | `nave-text-right`        | `text-align: right;`                                                                                                                                                                            | —                                                                                                                                                                                                                                                                                                                                         |
 
 ## Interaction
 
-| Atom            | Class                 | Declarations                                                                                                              | Variants                            |
-| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `interactive`   | `nave-interactive`    | `cursor: pointer;`<br>`-webkit-user-select: none;`<br>`user-select: none;`<br>`-webkit-tap-highlight-color: transparent;` | —                                   |
-| `focusRing`     | `nave-focus-ring`     | `outline: none;`                                                                                                          | `:focus-visible`                    |
-| `disabledState` | `nave-disabled-state` | —                                                                                                                         | `:disabled, [aria-disabled="true"]` |
+| Atom            | Class                 | Declarations                                                                                                              | Variants                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `interactive`   | `nave-interactive`    | `cursor: pointer;`<br>`-webkit-user-select: none;`<br>`user-select: none;`<br>`-webkit-tap-highlight-color: transparent;` | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `focusRing`     | `nave-focus-ring`     | `outline: none;`                                                                                                          | `:focus-visible` — `outline: var(--nave-border-width-focus) solid var(--nave-color-border-focus);`<br>`outline-offset: 2px;`                                                                                                                                                                                                                                                                                                                                   |
+| `disabledState` | `nave-disabled-state` | —                                                                                                                         | `: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
 
@@ -95,14 +95,14 @@ variants, if any.
 
 ## Responsive
 
-| Atom                    | Class                           | Declarations | Variants                    |
-| ----------------------- | ------------------------------- | ------------ | --------------------------- |
-| `hidePhoneOnly`         | `nave-hide-phone-only`          | —            | `@media (width < 37.5em)`   |
-| `hideTabletPortraitUp`  | `nave-hide-tablet-portrait-up`  | —            | `@media (width >= 37.5em)`  |
-| `hideTabletLandscapeUp` | `nave-hide-tablet-landscape-up` | —            | `@media (width >= 56.25em)` |
-| `hideDesktopUp`         | `nave-hide-desktop-up`          | —            | `@media (width >= 75em)`    |
-| `stackPhoneOnly`        | `nave-stack-phone-only`         | —            | `@media (width < 37.5em)`   |
-| `wFullPhoneOnly`        | `nave-w-full-phone-only`        | —            | `@media (width < 37.5em)`   |
+| Atom                    | Class                           | Declarations | Variants                                              |
+| ----------------------- | ------------------------------- | ------------ | ----------------------------------------------------- |
+| `hidePhoneOnly`         | `nave-hide-phone-only`          | —            | `@media (width < 37.5em)` — `display: none;`          |
+| `hideTabletPortraitUp`  | `nave-hide-tablet-portrait-up`  | —            | `@media (width >= 37.5em)` — `display: none;`         |
+| `hideTabletLandscapeUp` | `nave-hide-tablet-landscape-up` | —            | `@media (width >= 56.25em)` — `display: none;`        |
+| `hideDesktopUp`         | `nave-hide-desktop-up`          | —            | `@media (width >= 75em)` — `display: none;`           |
+| `stackPhoneOnly`        | `nave-stack-phone-only`         | —            | `@media (width < 37.5em)` — `flex-direction: column;` |
+| `wFullPhoneOnly`        | `nave-w-full-phone-only`        | —            | `@media (width < 37.5em)` — `width: 100%;`            |
 
 ## Pairing notes
 

package/README.md

@@ -57,7 +57,10 @@ repeats the same statement, which changes nothing
 
 Your component CSS goes in `@layer components.consumer`, and a deliberate
 exception goes in `@layer overrides`, which beats every other layer. Left outside
-any layer, your CSS would beat all of them, `overrides` included. Do not write
+any layer, your CSS would beat all of them, `overrides` included.
+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. Do not write
 into a bare `@layer components` or `@layer tokens`: a rule written directly into a
 layer outranks everything in that layer's sublayers.
 
@@ -142,12 +145,13 @@ What that buys you, and what it does not:
   `hidden`, `grid`, `flex`, `block`, `border`, `rounded`, `transition`,
   `relative`, `absolute`, `gap`, `truncate`, `interactive`) belong on the
   `cx.raw()` side when you mean your own.
-- **Nothing checks the rest of the `className` attribute.** A bare
-  `'legacy-card'` sitting beside these calls is seen by nothing and still works.
-  So `cx.raw()` is a **declared** escape channel, not an enforced one: its value
-  today is that every deliberate step outside the system leaves a token you can
-  find (`grep -r 'cx.raw'`). A lint that closes the attribute itself is not part
-  of this release.
+- **The rest of the `className` attribute is checked by
+  [`@navecss/eslint-plugin`](https://github.com/navecss/navecss/tree/main/packages/eslint-plugin#readme).**
+  A bare `'legacy-card'` sitting beside these calls is not seen by `tsc` or by
+  `@nave`, so `cx.raw()` is a **declared** escape channel — install that plugin
+  for an **enforced** one: it reports an undeclared literal class written in
+  `className`, and requires a reason on a `cx.raw()` call that carries one, so
+  a deliberate step outside the system stays a reasoned, countable call.
 
 ### Tokens only
 
@@ -250,6 +254,71 @@ failure, not a silently incomplete build):
 
 ---
 
+## Editor, linter and coding agent
+
+`@nave` is new to these tools, so each one needs a step, and this package ships what each of
+them reads.
+
+**VS Code.** This package ships a data file that declares `@nave` to the CSS language service:
+
+```json
+{ "css.customData": ["./node_modules/@navecss/core/nave.css-data.json"] }
+```
+
+In a monorepo, the path is relative to the folder you open, so it goes through the
+`node_modules` of the package that depends on `@navecss/core`. VS Code reads the file at
+startup, so reload the window once it is installed.
+
+**Stylelint.** To have `@nave` accepted without disabling `at-rule-no-unknown` for anything
+else, declare it under `languageOptions.syntax.atRules`:
+
+```json
+{ "languageOptions": { "syntax": { "atRules": { "nave": { "prelude": "<custom-ident>+" } } } } }
+```
+
+This needs stylelint 16.17.0 or later. `@navecss/stylelint-config`'s own peer range is
+`^17.0.0`; the two are stated separately because the config does more than this one line, and
+this line works on its own, with no config installed, from 16.17.0 on. For a check that values
+on a list of properties (colour, spacing and others) use a `var()` or an admitted keyword, extend
+[`@navecss/stylelint-config`](https://github.com/navecss/navecss/tree/main/packages/stylelint-config#readme)
+beside this line; it never replaces it.
+
+**ESLint®.** For the JSX side of the same idea — a literal class in `className`, or a literal
+value on a tokenized `style` property — install
+[`@navecss/eslint-plugin`](https://github.com/navecss/navecss/tree/main/packages/eslint-plugin#readme):
+
+```js
+// eslint.config.js
+import nave from '@navecss/eslint-plugin'
+
+export default [
+  // ...your existing config
+  nave.configs.recommended,
+]
+```
+
+**Coding agents.** This package ships a guide for coding agents at `skills/navecss/SKILL.md`:
+the built-in atoms, the custom properties this build emits, the layer order, and where consumer
+CSS goes, for the version you have installed. No agent looks inside `node_modules` on its own,
+so add a pointer to your own `AGENTS.md` (and to `CLAUDE.md` too if you have one, since Claude
+Code reads `AGENTS.md` only where there is no `CLAUDE.md`):
+
+```md
+## Styling: NaveCSS
+
+Before writing or changing CSS or a `className`, read
+`node_modules/@navecss/core/skills/navecss/SKILL.md`, resolved from the
+package that depends on `@navecss/core`. The Nave custom properties and
+built-in atoms it lists are the only ones there are. Atoms this project
+registers through `navePlugin({ extend })` are valid too, in `@nave` only,
+never in `cx()`. If a name you need is in neither place, say so rather
+than invent one.
+```
+
+Consumers of `@navecss/tokens` alone get no guide: it ships only in this package.
+
+---
+
 ## Exports
 
 | Export                    | Description                                                                                           |

package/dist/cx.d.ts

@@ -51,10 +51,11 @@ import { AtomName } from './atoms.js';
  *   relative, absolute, gap, truncate, interactive.
  *
  * What is NOT checked:
- *   Nothing here looks at the rest of the className attribute. A bare string
- *   sitting beside these calls is not seen by anything, so cx.raw() is a
- *   DECLARED escape channel (greppable: `grep -r 'cx.raw'`), not an enforced
- *   one.
+ *   Nothing here looks at the rest of the className attribute. @navecss/eslint-plugin does:
+ *   install it for an ENFORCED escape channel, reporting an undeclared literal class written
+ *   in className and requiring a reason on a cx.raw() call that carries one (a class the
+ *   project declares as its own passes by design). Without it, cx.raw() is only a DECLARED
+ *   escape channel (greppable: `grep -r 'cx.raw'`).
  *
  * Note on consumer atoms:
  *   Atoms defined via navePlugin({ extend }) are @nave-directive only.

package/dist/postcss.d.ts

@@ -16,6 +16,13 @@ import { AtomDefinition } from './atoms.js';
  *   navePlugin({ extend: myAtoms })      // Nave + consumer atoms
  *   navePlugin({ onUnknown: 'warn' })    // Log and skip instead of failing the build
  *
+ * `extend` is trusted, consumer-authored code, run at build time in the same file that could
+ * already run arbitrary JavaScript — it is not sanitised input. `validateExtendAtoms` still
+ * parses every declaration, pseudo selector key, and media/container condition an atom carries,
+ * and rejects any that does not parse as exactly that one construct, since a typo there is
+ * otherwise silent CSS injection into the generated output rather than a build error at the
+ * point of the mistake.
+ *
  * Consumer atoms:
  *   import type { AtomDefinition } from '@navecss/core/postcss'
  *   import { media } from '@navecss/tokens/breakpoints'

package/dist/postcss.js

@@ -2,69 +2,62 @@ import { atoms } from './chunk-BVON7XKC.js';
 import postcss from 'postcss';
 
 // src/selector-utils.ts
-function nextQuote(quote, char) {
-  if (quote) return char === quote ? void 0 : quote;
-  return char === '"' || char === "'" ? char : quote;
-}
-function depthDelta(quote, char) {
-  if (quote) return 0;
-  if (char === "(" || char === "[") return 1;
-  if (char === ")" || char === "]") return -1;
-  return 0;
-}
-function consumeSplitChar(state, char) {
-  const { branches, depth, quote, isEscaped, current } = state;
-  if (isEscaped) {
-    return { branches, depth, quote, isEscaped: false, current: current + char };
-  }
-  if (char === "\\") {
-    return { branches, depth, quote, isEscaped: true, current: current + char };
-  }
-  const nextDepth = depth + depthDelta(quote, char);
-  if (!quote && char === "," && nextDepth === 0) {
-    return {
-      branches: [...branches, current],
-      depth: nextDepth,
-      quote,
-      isEscaped: false,
-      current: ""
-    };
+function isCommentClose(text, index, commentStart) {
+  return text[index] === "/" && text[index - 1] === "*" && index - 1 >= commentStart + 2;
+}
+function isConsumedAsLiteral(state, text, index) {
+  if (state.commentStart !== void 0) {
+    if (isCommentClose(text, index, state.commentStart)) state.commentStart = void 0;
+    return true;
   }
-  return {
-    branches,
-    depth: nextDepth,
-    quote: nextQuote(quote, char),
-    isEscaped: false,
-    current: current + char
-  };
+  if (state.isEscaped) {
+    state.isEscaped = false;
+    return true;
+  }
+  if (text[index] === "\\") {
+    state.isEscaped = true;
+    return true;
+  }
+  if (!state.quote) return false;
+  if (text[index] === state.quote) state.quote = void 0;
+  return true;
+}
+function isCodeChar(state, text, index) {
+  if (isConsumedAsLiteral(state, text, index)) return false;
+  const char = text[index];
+  if (char === '"' || char === "'") {
+    state.quote = char;
+    return false;
+  }
+  if (char === "/" && text[index + 1] === "*") {
+    state.commentStart = index;
+    return false;
+  }
+  return true;
+}
+function codeMask(text) {
+  const state = { quote: void 0, isEscaped: false, commentStart: void 0 };
+  return Array.from({ length: text.length }, (_, index) => isCodeChar(state, text, index));
 }
 function splitTopLevel(selectorList) {
-  let state = {
-    branches: [],
-    depth: 0,
-    quote: void 0,
-    isEscaped: false,
-    current: ""
-  };
-  for (const char of selectorList) state = consumeSplitChar(state, char);
-  return [...state.branches, state.current];
-}
-function hasUnquotedAmpersand(branch) {
-  let quote;
-  let isEscaped = false;
-  for (const char of branch) {
-    if (isEscaped) {
-      isEscaped = false;
-      continue;
-    }
-    if (char === "\\") {
-      isEscaped = true;
-      continue;
+  const mask = codeMask(selectorList);
+  const branches = [];
+  let depth = 0;
+  let start = 0;
+  for (const [index, isCode] of mask.entries()) {
+    if (!isCode) continue;
+    const char = selectorList[index];
+    if (char === "(" || char === "[") depth += 1;
+    else if (char === ")" || char === "]") depth -= 1;
+    else if (char === "," && depth === 0) {
+      branches.push(selectorList.slice(start, index));
+      start = index + 1;
     }
-    if (!quote && char === "&") return true;
-    quote = nextQuote(quote, char);
   }
-  return false;
+  return [...branches, selectorList.slice(start)];
+}
+function hasNestingSelector(branch) {
+  return codeMask(branch).some((isCode, index) => isCode && branch[index] === "&");
 }
 function anchorSelectorList(selectorList) {
   return splitTopLevel(selectorList).map((branch) => {
@@ -74,7 +67,7 @@ function anchorSelectorList(selectorList) {
         `anchorSelectorList: empty selector branch in pseudo key "${selectorList}". Remove the stray or trailing comma: an empty branch would otherwise compile to a bare "&", matching the atom unconditionally.`
       );
     }
-    return hasUnquotedAmpersand(trimmed) ? trimmed : `&${trimmed}`;
+    return hasNestingSelector(trimmed) ? trimmed : `&${trimmed}`;
   }).join(", ");
 }
 
@@ -140,6 +133,98 @@ function stampSource(node, source) {
     child.source = source;
   });
 }
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDeclarationValid(prop, value) {
+  let root;
+  try {
+    root = postcss.parse(`a{${prop}:${value}}`);
+  } catch {
+    return false;
+  }
+  if (root.nodes.length !== 1) return false;
+  const rule = root.nodes[0];
+  if (rule.type !== "rule" || rule.nodes.length !== 1) return false;
+  const decl = rule.nodes[0];
+  if (decl.type !== "decl") return false;
+  return decl.prop === prop && decl.toString() === `${prop}:${value}`.trimEnd();
+}
+function isPropValid(prop) {
+  return isDeclarationValid(prop, "0");
+}
+function isSelectorValid(key) {
+  let selector;
+  try {
+    selector = anchorSelectorList(key);
+  } catch {
+    return false;
+  }
+  let root;
+  try {
+    root = postcss.parse(`${selector}{}`);
+  } catch {
+    return false;
+  }
+  if (root.nodes.length !== 1) return false;
+  const rule = root.nodes[0];
+  return rule.type === "rule" && rule.selector === selector && rule.nodes.length === 0;
+}
+function isConditionValid(atName, condition) {
+  let root;
+  try {
+    root = postcss.parse(`@${atName} ${condition}{}`);
+  } catch {
+    return false;
+  }
+  if (root.nodes.length !== 1) return false;
+  const node = root.nodes[0];
+  return node.type === "atrule" && node.name === atName && node.params === condition.trim() && (node.nodes?.length ?? 0) === 0;
+}
+function fail(describedAs, value) {
+  throw new Error(
+    `navePlugin({ extend }): ${describedAs} does not parse as a single CSS declaration, selector or condition, and would break out of the rule it is spliced into: ${JSON.stringify(value)}. extend is trusted, consumer-authored code, not sanitised input \u2014 fix the atom definition.`
+  );
+}
+function assertDeclarationsSafe(declarations, where) {
+  if (!isPlainObject(declarations)) return;
+  for (const [prop, value] of Object.entries(declarations)) {
+    if (typeof prop === "string" && !isPropValid(prop)) {
+      fail(`${where}'s declaration property "${prop}"`, prop);
+    }
+    if (typeof value === "string" && !isDeclarationValid(prop, value)) {
+      fail(`${where}'s declaration value for "${prop}"`, value);
+    }
+  }
+}
+function assertPseudosSafe(pseudos, where) {
+  if (!isPlainObject(pseudos)) return;
+  for (const [pseudo, declarations] of Object.entries(pseudos)) {
+    if (!isSelectorValid(pseudo)) fail(`${where}'s pseudo "${pseudo}"`, pseudo);
+    assertDeclarationsSafe(declarations, `${where}'s pseudo "${pseudo}"`);
+  }
+}
+function assertAtBlocksSafe(blocks, atName, where) {
+  if (!isPlainObject(blocks)) return;
+  for (const [condition, block] of Object.entries(blocks)) {
+    if (!isConditionValid(atName, condition))
+      fail(`${where}'s ${atName} condition "${condition}"`, condition);
+    if (!isPlainObject(block)) continue;
+    const blockWhere = `${where}'s ${atName} "${condition}"`;
+    assertDeclarationsSafe(block.declarations, blockWhere);
+    assertPseudosSafe(block.pseudos, blockWhere);
+  }
+}
+function validateExtendAtoms(extend) {
+  for (const [name, atom] of Object.entries(extend)) {
+    if (!atom) continue;
+    const where = `atom "${name}"`;
+    assertDeclarationsSafe(atom.declarations, where);
+    assertPseudosSafe(atom.pseudos, where);
+    assertAtBlocksSafe(atom.media, "media", where);
+    assertAtBlocksSafe(atom.container, "container", where);
+  }
+}
 
 // src/postcss.ts
 function reportUnknown(msg, ctx) {
@@ -177,6 +262,7 @@ function insertDeclarations(atRule, declNodes, isFollowingNested) {
 }
 var navePlugin = (options = {}) => {
   const { onUnknown = "error", extend = {} } = options;
+  validateExtendAtoms(extend);
   const allAtoms = { ...atoms, ...extend };
   const validAtomNames = new Set(
     Object.entries(allAtoms).filter(([, definition]) => definition).map(([name]) => name)

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,6 +1,6 @@
 {
   "name": "@navecss/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Nave design system — layer architecture, reset, atomic utilities, PostCSS plugin",
@@ -39,7 +39,9 @@
   "files": [
     "dist",
     "CONSUMER-ATOMS.md",
-    "ATOMS.md"
+    "ATOMS.md",
+    "nave.css-data.json",
+    "skills"
   ],
   "peerDependencies": {
     "postcss": "^8"
@@ -50,7 +52,7 @@
     }
   },
   "dependencies": {
-    "@navecss/tokens": "^0.1.1"
+    "@navecss/tokens": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.2",
@@ -59,10 +61,11 @@
     "@vitest/coverage-v8": "5.0.1",
     "playwright": "1.63.0",
     "postcss": "^8.5.28",
-    "prettier": "3.9.8",
+    "prettier": "3.9.9",
     "tsup": "^8.5.1",
     "typescript": "6.0.3",
-    "vitest": "5.0.1"
+    "vitest": "5.0.1",
+    "vscode-css-languageservice": "6.3.10"
   },
   "engines": {
     "node": ">=22.18"

package/skills/navecss/SKILL.md

@@ -0,0 +1,314 @@
+---
+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.
+
+## `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: var(--nave-border-width-focus) solid var(--nave-color-border-focus);`<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-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
+- `--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.