@navecss/core 0.1.0

package/dist/chunk-BVON7XKC.js

@@ -0,0 +1,394 @@
+import { media } from '@navecss/tokens/breakpoints';
+
+// src/atoms.ts
+var srOnlyDeclarations = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  padding: "0",
+  margin: "-1px",
+  overflow: "hidden",
+  "clip-path": "inset(50%)",
+  "white-space": "nowrap",
+  "border-width": "0"
+};
+var srOnlyRevealed = {
+  position: "static",
+  width: "auto",
+  height: "auto",
+  margin: "0",
+  overflow: "visible",
+  "clip-path": "none",
+  "white-space": "normal"
+};
+var atoms = {
+  // ── Display ────────────────────────────────────────────────────────────────
+  flex: {
+    declarations: { display: "flex" }
+  },
+  inlineFlex: {
+    declarations: { display: "inline-flex" }
+  },
+  grid: {
+    declarations: { display: "grid" }
+  },
+  block: {
+    declarations: { display: "block" }
+  },
+  inlineBlock: {
+    declarations: { display: "inline-block" }
+  },
+  hidden: {
+    declarations: { display: "none" }
+  },
+  // ── Flex ───────────────────────────────────────────────────────────────────
+  flexCol: {
+    declarations: { "flex-direction": "column" }
+  },
+  flexWrap: {
+    declarations: { "flex-wrap": "wrap" }
+  },
+  itemsCenter: {
+    declarations: { "align-items": "center" }
+  },
+  itemsStart: {
+    declarations: { "align-items": "flex-start" }
+  },
+  itemsEnd: {
+    declarations: { "align-items": "flex-end" }
+  },
+  justifyCenter: {
+    declarations: { "justify-content": "center" }
+  },
+  justifyBetween: {
+    declarations: { "justify-content": "space-between" }
+  },
+  justifyEnd: {
+    declarations: { "justify-content": "flex-end" }
+  },
+  flexGrow: {
+    declarations: { "flex-grow": "1" }
+  },
+  flexShrink0: {
+    declarations: { "flex-shrink": "0" }
+  },
+  gap: {
+    declarations: { gap: "var(--nave-spacing-content-md)" }
+  },
+  // ── Position ───────────────────────────────────────────────────────────────
+  relative: {
+    declarations: { position: "relative" }
+  },
+  absolute: {
+    declarations: { position: "absolute" }
+  },
+  insetFull: {
+    declarations: { inset: "0" }
+  },
+  // ── Sizing ─────────────────────────────────────────────────────────────────
+  wFull: {
+    declarations: { width: "100%" }
+  },
+  hFull: {
+    declarations: { height: "100%" }
+  },
+  minW0: {
+    declarations: { "min-width": "0" }
+  },
+  // ── Typography ─────────────────────────────────────────────────────────────
+  truncate: {
+    declarations: {
+      overflow: "hidden",
+      "text-overflow": "ellipsis",
+      "white-space": "nowrap"
+    }
+  },
+  /**
+   * srOnly — visually hidden, accessible to screen readers.
+   * Every property in the shared declaration set is load-bearing: the 1x1 box
+   * stays in the accessibility tree where display: none would not, the box is
+   * 1px rather than 0 because a zero-size box is dropped from that tree by some
+   * assistive technology, the negative margin cancels it out of layout flow,
+   * clip-path is used rather than clip so it keeps working if a consumer
+   * overrides position, and nowrap stops long text rendering as a visible
+   * column of single characters. Do not simplify.
+   */
+  srOnly: {
+    declarations: srOnlyDeclarations
+  },
+  /**
+   * srOnlyFocusable — srOnly that reveals itself when it (or a descendant)
+   * receives keyboard focus. The skip-link pattern needs this: an element
+   * hidden until it receives keyboard focus. Plain srOnly on a skip link
+   * produces a focusable element that is permanently invisible, so a
+   * keyboard user tabs into apparent nothingness.
+   *
+   * :focus-visible — the element itself is the focusable (e.g. the skip
+   *   link anchor carries this atom directly).
+   * :focus-within  — the hidden element wraps the focusable rather than
+   *   being it.
+   */
+  srOnlyFocusable: {
+    declarations: srOnlyDeclarations,
+    pseudos: {
+      ":focus-visible": srOnlyRevealed,
+      ":focus-within": srOnlyRevealed
+    }
+  },
+  noWrap: {
+    declarations: { "white-space": "nowrap" }
+  },
+  breakWord: {
+    declarations: { "overflow-wrap": "break-word" }
+  },
+  textLeft: {
+    declarations: { "text-align": "left" }
+  },
+  textCenter: {
+    declarations: { "text-align": "center" }
+  },
+  textRight: {
+    declarations: { "text-align": "right" }
+  },
+  // ── Interaction ────────────────────────────────────────────────────────────
+  /**
+   * interactive — base for any clickable non-button element.
+   * -webkit-tap-highlight-color removes the grey tap flash on iOS/Android.
+   * -webkit-user-select is required alongside user-select: every released Safari and every
+   * iOS browser (all WebKit-based, regardless of the label on the tin) reads only the
+   * prefixed property; the unprefixed one is Safari-preview-only per BCD.
+   */
+  interactive: {
+    declarations: {
+      cursor: "pointer",
+      "-webkit-user-select": "none",
+      "user-select": "none",
+      "-webkit-tap-highlight-color": "transparent"
+    }
+  },
+  /**
+   * focusRing — keyboard focus indicator.
+   * :focus-visible — keyboard users see it, mouse users do not.
+   */
+  focusRing: {
+    declarations: {
+      outline: "none"
+    },
+    pseudos: {
+      ":focus-visible": {
+        outline: "var(--nave-border-width-focus) solid var(--nave-color-border-focus)",
+        "outline-offset": "2px"
+      }
+    }
+  },
+  /**
+   * disabledState — visual + behavioural disabled treatment.
+   * Applies from either the native `disabled` attribute or
+   * `aria-disabled="true"`. 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.
+   *
+   * Expresses disablement through the dedicated disabled colour tokens
+   * (content.disabled, border.disabled) rather than a blanket opacity: a
+   * uniform dim composites everything the element paints, including a
+   * focusRing outline on the aria-disabled branch.
+   * `color` also carries inline icons (reset.css's `svg:not([fill])
+   * { fill: currentcolor }`); `border-color` is inert on a borderless
+   * element. Deliberately silent on `background-color`: the atom cannot
+   * know whether the element is a filled control, a ghost button, a link
+   * or a label, so a filled control's disabled fill is a component
+   * obligation, not this atom's.
+   *
+   * No `cursor` here: `pointer-events: none` stops the element from ever being hit-tested,
+   * so a `cursor` declared on it can never paint (the browser resolves the pointer against
+   * whatever is underneath instead). That is equally true of reset.css's
+   * `[disabled], [aria-disabled='true'] { cursor: not-allowed }` on an element carrying this
+   * atom: while the atom applies, no cursor paints on that element at all. The reset rule
+   * serves the disabled elements that do NOT carry this atom. What is removed here is a
+   * declaration that never rendered, so nothing a user sees changes.
+   */
+  disabledState: {
+    declarations: {},
+    pseudos: {
+      ':disabled, [aria-disabled="true"]': {
+        color: "var(--nave-color-content-disabled)",
+        "border-color": "var(--nave-color-border-disabled)",
+        "pointer-events": "none"
+      }
+    }
+  },
+  // ── Visual ─────────────────────────────────────────────────────────────────
+  rounded: {
+    declarations: { "border-radius": "var(--nave-radius-control)" }
+  },
+  roundedCard: {
+    declarations: { "border-radius": "var(--nave-radius-card)" }
+  },
+  roundedFull: {
+    declarations: { "border-radius": "var(--nave-radius-full)" }
+  },
+  border: {
+    declarations: {
+      border: "var(--nave-border-width-sm) solid var(--nave-color-border-default)"
+    }
+  },
+  overflowHidden: {
+    declarations: { overflow: "hidden" }
+  },
+  overflowAuto: {
+    declarations: { overflow: "auto" }
+  },
+  // ── Transition ─────────────────────────────────────────────────────────────
+  transition: {
+    declarations: {
+      "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)"
+    }
+  },
+  // ── Containment ────────────────────────────────────────────────────────────
+  //
+  // container establishes a containment context so that child components
+  // can use @container queries to respond to available space rather than
+  // viewport size. This is the correct tool for component-level responsiveness.
+  //
+  // Usage:
+  //   <div className={styles.cardWrapper}>   ← apply container atom here
+  //     <Card />                             ← Card uses @container internally
+  //   </div>
+  //
+  // Named containers:
+  //   If you need to query a specific named container, define it in your
+  //   component's CSS Module directly — the container shorthand with a name
+  //   requires a string value that cannot be expressed as a static atom:
+  //     .wrapper { container: my-sidebar / inline-size; }
+  //
+  // container-type: inline-size is the correct default for most cases.
+  //   It queries the inline (horizontal) dimension only, which is what
+  //   almost all responsive component layouts need. Using `size` queries
+  //   both dimensions and requires the container to have a known block size,
+  //   which is rarely what you want for standard flow layout.
+  /**
+   * container
+   * Establishes an inline-size containment context.
+   * Apply to the wrapper of any component that uses @container queries.
+   * Required — container queries have no effect without a containment ancestor.
+   */
+  container: {
+    declarations: {
+      "container-type": "inline-size"
+    }
+  },
+  // ── Responsive ─────────────────────────────────────────────────────────────
+  //
+  // Philosophy: mobile-first. All responsive atoms start from the smallest
+  // context and expand upward using min-width (>=) queries, except phoneOnly
+  // which is the one legitimate max-width exception — it targets a specific
+  // device class, not "below X."
+  //
+  // Media strings come from @navecss/tokens/breakpoints.
+  // Never write breakpoint values as magic numbers here or in consumer atoms.
+  //
+  // Naming: [behaviour]-[when]
+  //   hide*   — visibility
+  //   stack*  — flex-direction change
+  //   wFull*  — width change
+  //   [when]  — matches the media export name (phoneOnly, tabletPortraitUp, etc.)
+  //
+  // Why no show* atoms?
+  //   Restoring display requires knowing the original value (block, flex, grid).
+  //   That context belongs in the component. Use hide* on the element that has
+  //   a replacement, rather than show* on the replacement itself.
+  //
+  // Why only phoneOnly for stack* and wFull*?
+  //   Stack and full-width behaviours applied above phone are layout decisions
+  //   that belong in component-specific consumer atoms, not shared utilities.
+  //   The built-in set models good mobile-first habits — it doesn't provide
+  //   shortcuts around them.
+  /**
+   * hidePhoneOnly
+   * Hidden on phone. Visible on tablet portrait and above.
+   * Use for: elements that have a dedicated phone replacement.
+   */
+  hidePhoneOnly: {
+    declarations: {},
+    media: {
+      [media.phoneOnly]: {
+        declarations: { display: "none" }
+      }
+    }
+  },
+  /**
+   * hideTabletPortraitUp
+   * Hidden on tablet portrait and above. Visible on phone only.
+   * Use for: mobile-only elements (hamburger triggers, bottom nav, etc.)
+   */
+  hideTabletPortraitUp: {
+    declarations: {},
+    media: {
+      [media.tabletPortraitUp]: {
+        declarations: { display: "none" }
+      }
+    }
+  },
+  /**
+   * hideTabletLandscapeUp
+   * Hidden on tablet landscape and above. Visible on phone and tablet portrait.
+   * Use for: compact tablet navigation that gives way to a full desktop nav.
+   */
+  hideTabletLandscapeUp: {
+    declarations: {},
+    media: {
+      [media.tabletLandscapeUp]: {
+        declarations: { display: "none" }
+      }
+    }
+  },
+  /**
+   * hideDesktopUp
+   * Hidden on desktop and above. Visible on tablet landscape and below.
+   * Use for: mobile/tablet UI that has a desktop structural replacement.
+   */
+  hideDesktopUp: {
+    declarations: {},
+    media: {
+      [media.desktopUp]: {
+        declarations: { display: "none" }
+      }
+    }
+  },
+  /**
+   * stackPhoneOnly
+   * flex-direction: column on phone. Assumes the element is display: flex.
+   * Use for: button groups, form rows, icon+label pairs that stack on mobile.
+   */
+  stackPhoneOnly: {
+    declarations: {},
+    media: {
+      [media.phoneOnly]: {
+        declarations: { "flex-direction": "column" }
+      }
+    }
+  },
+  /**
+   * wFullPhoneOnly
+   * width: 100% on phone only.
+   * Use for: buttons and inputs that should be full-width on mobile.
+   */
+  wFullPhoneOnly: {
+    declarations: {},
+    media: {
+      [media.phoneOnly]: {
+        declarations: { width: "100%" }
+      }
+    }
+  }
+};
+var toClassName = (name) => `nave-${name.replaceAll(/([A-Z])/g, "-$1").toLowerCase()}`;
+var atomClassMap = Object.fromEntries(
+  Object.keys(atoms).map((name) => [name, toClassName(name)])
+);
+
+export { atomClassMap, atoms, toClassName };

package/dist/cx.d.ts

@@ -0,0 +1,72 @@
+import { AtomName } from './atoms.js';
+
+/**
+ * cx — typed atomic class composer for Nave.
+ *
+ * Two channels, because the two things they carry are different:
+ *
+ *   cx(...)      — Nave built-in atoms only. Typed, autocompleted, and an
+ *                  unknown name is a compile error.
+ *   cx.raw(...)  — any class string, returned untouched. The declared way to
+ *                  step outside the system.
+ *
+ * Both accept falsy arguments (undefined, null, false) and filter them out, so
+ * conditional classes work the same on either side. Both return a
+ * space-separated class string for className={}.
+ *
+ * Validation, not just autocomplete:
+ *   cx() takes AtomName, so a typo'd name ('interactve'), a name typed from
+ *   the CSS side ('sr-only' — the atom key is srOnly and the emitted class is
+ *   nave-sr-only; neither spelling is the key), and a class from anywhere
+ *   outside Nave are all refused by your own tsc, with nothing installed from
+ *   us. This is TypeScript only: a JavaScript consumer gets none of it.
+ *
+ * Composing with your own classes:
+ *   A CSS Module hash is a string, not an atom, so it no longer goes inside
+ *   cx(). Compose in the template literal, the way the @nave directive
+ *   composes in the rule body:
+ *
+ *     className={`${cx('interactive', 'focusRing')} ${styles.root}`}
+ *
+ *   and reach for cx.raw() when the class comes from outside any system Nave
+ *   can see — a legacy global class, a third-party widget's class:
+ *
+ *     className={`${cx('interactive')} ${cx.raw('legacy-card')}`}
+ *
+ *   A CONDITIONAL class goes inside a call, never into a slot: cx.raw()
+ *   filters a falsy argument out, while `${isActive && styles.active}`
+ *   interpolates the string 'false' into your className.
+ *
+ *   An atom name held in a variable needs a literal type. `const n = 'flex'`
+ *   is one; a let binding, an array element or an object property widens to
+ *   string, so annotate it with the exported AtomName type (or `as const`).
+ *
+ * Why cx.raw() never maps:
+ *   cx() resolves an atom name to that atom's global class, so cx('container')
+ *   is 'nave-container'. cx.raw() does not consult the atom map at all, so
+ *   cx.raw('container') is the literal 'container'. That is what makes it
+ *   impossible for Nave to shadow one of your own class names on this channel,
+ *   rather than merely documented — and the names at issue are the ordinary
+ *   ones: container, hidden, grid, flex, block, border, rounded, transition,
+ *   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.
+ *
+ * Note on consumer atoms:
+ *   Atoms defined via navePlugin({ extend }) are @nave-directive only.
+ *   They do not generate global CSS classes and are not available in cx().
+ *   cx() covers Nave built-in atoms only.
+ */
+
+type Falsy = false | null | undefined;
+interface Cx {
+    (...args: (AtomName | Falsy)[]): string;
+    raw: (...args: (Falsy | string)[]) => string;
+}
+declare const cx: Cx;
+
+export { AtomName, cx };

package/dist/cx.js

@@ -0,0 +1,9 @@
+import { atomClassMap } from './chunk-BVON7XKC.js';
+
+// src/cx.ts
+var cx = (...args) => args.filter(Boolean).map(
+  (arg) => Object.hasOwn(atomClassMap, arg) ? atomClassMap[arg] : arg
+).join(" ");
+cx.raw = (...args) => args.filter(Boolean).join(" ");
+
+export { cx };

package/dist/index.css

@@ -0,0 +1,48 @@
+/*
+ * Nave Design System — core entry point
+ * Import this once in your app, before any stylesheet of yours that
+ * declares a layer.
+ *
+ * The @layer statement below is the cascade contract: seven names across five
+ * top-level layers (tokens, reset, atomic, components, overrides), each name
+ * beating every name before it. Do not reorder. The contract holds only if
+ * this statement is the first @layer declaration the document sees: a layer
+ * your CSS declares earlier keeps that earlier position, and the order
+ * inverts. Author into a sublayer, never into a bare parent (a parent
+ * outranks its own sublayers). Unlayered CSS beats every layer. All of this
+ * is for normal declarations: !important reverses layer order, which the
+ * reset uses on purpose. Full contract:
+ * https://github.com/navecss/navecss/blob/main/docs/04-adr/0003-layer-cascade-contract.md
+ *
+ *   tokens.defaults     → CSS custom properties (read-only, set by @navecss/tokens)
+ *   tokens.presets      → RESERVED: 0.1.0 ships zero presets, but the
+ *                         slot is declared now so a preset always beats the defaults
+ *                         regardless of import order, and a consumer's `overrides`
+ *                         always beats a preset. Retrofitting this slot later would be
+ *                         a breaking change to the published cascade contract.
+ *                         A project's own `navecss-tokens build` output lands here too.
+ *   reset               → Cross-browser normalisation
+ *   atomic              → Global atom classes that cx() names: defaults, below
+ *                         component CSS (@nave inlines into your own rule instead)
+ *   components.nave     → Components Nave publishes
+ *   components.consumer → Your component CSS: @layer components.consumer { … }
+ *   overrides           → Your deliberate exceptions to everything above
+ */
+@layer tokens.defaults, tokens.presets, reset, atomic, components.nave, components.consumer, overrides;
+
+/* Token layer — all CSS custom properties.
+ * Imported plain: tokens.css declares its own `@layer tokens.defaults` so that
+ * consumers importing @navecss/tokens/css directly are layered correctly too.
+ * Adding layer(tokens.defaults) here would nest it a second time. */
+@import url('@navecss/tokens/css');
+
+/* Reset layer. Imported plain: dist/reset.css now declares its own
+ * `@layer reset` so that consumers importing ./reset directly are layered
+ * correctly too. Adding layer(reset) here would nest it a second time. */
+@import url('./reset.css');
+
+/* Atomic layer. Imported plain: dist/atomic.css now declares its own
+ * `@layer atomic` so that consumers importing ./atomic directly are
+ * layered correctly too. Adding layer(atomic) here would nest it a second
+ * time. */
+@import url('./atomic.css');

package/dist/layers.css

@@ -0,0 +1,15 @@
+/*
+ * Nave Design System — the @layer order statement, alone.
+ *
+ * Import this first, before any other stylesheet. CSS fixes a layer's
+ * position the first time the page declares it, so if a stylesheet of yours
+ * that declares a layer loads before this statement, that layer's position is
+ * fixed first and Nave's order inverts with no error. Imported first, this one
+ * line keeps the order wherever the rest of Nave and your own stylesheets land
+ * in the import graph. Importing '@navecss/core' afterwards is correct: its
+ * own copy of this statement is identical and changes nothing.
+ *
+ * Full contract:
+ * https://github.com/navecss/navecss/blob/main/docs/04-adr/0003-layer-cascade-contract.md
+ */
+@layer tokens.defaults, tokens.presets, reset, atomic, components.nave, components.consumer, overrides;

package/dist/no-tokens.css

@@ -0,0 +1,52 @@
+/*
+ * Nave Design System, entry point for projects that generate their own tokens.
+ *
+ * Import this INSTEAD OF '@navecss/core' if you generate your Nave token
+ * layer yourself and commit it into your project. If you use Nave's shipped
+ * token values (the normal case, and what the README shows), import
+ * '@navecss/core' and ignore this file.
+ *
+ *   @import '@navecss/core/no-tokens';
+ *   @import './your-generated-tokens.css';
+ *
+ * WHAT YOU MUST SUPPLY. This entry ships Nave's reset and atomic layers and
+ * imports no token values at all, so every '--nave-' custom property those
+ * two layers read has to come from your own stylesheet, not only the colours.
+ * A property you do not define is not an error: the declaration that reads it is
+ * discarded, and the property does NOT fall back to whatever Nave's earlier rules
+ * set for it, so the element silently loses that piece of styling.
+ * To pick one that matters, the focus outline on '.nave-focus-ring' is built
+ * from '--nave-border-width-focus', so a token layer that defines every colour
+ * and not that width leaves an element carrying that class with no visible
+ * outline when it is focused.
+ *
+ * Nave ships a contract manifest listing the custom properties it requires
+ * ('@navecss/tokens/core-contract'). The manifest is generated by scanning
+ * the source behind the two layers this entry ships, across every '--nave-'
+ * property that source reads and not the colour namespace alone. What it
+ * checks is NAMES: a clean run means every one of those names is declared in
+ * your layer, and says nothing about the value you gave it.
+ *
+ * WHY A SEPARATE ENTRY. The default entry imports Nave's own token stylesheet.
+ * If you load your own generated token layer as well, the document carries two
+ * sets of the same custom properties. Your own values win, but any property
+ * your layer does not define falls back to Nave's without saying so, which
+ * makes an incomplete token layer look complete. This entry imports no token
+ * stylesheet, so what you supply is all there is, and each custom property is
+ * registered exactly once.
+ *
+ * Everything else is identical to the default entry: the same @layer order
+ * statement, the same reset and atomic imports.
+ */
+@layer tokens.defaults, tokens.presets, reset, atomic, components.nave, components.consumer, overrides;
+
+/* Reset layer. Imported plain: dist/reset.css declares its own
+ * `@layer reset` so that consumers importing ./reset directly are layered
+ * correctly too. Adding layer(reset) here would nest it a second time. */
+@import url('./reset.css');
+
+/* Atomic layer. Imported plain: dist/atomic.css declares its own
+ * `@layer atomic` so that consumers importing ./atomic directly are
+ * layered correctly too. Adding layer(atomic) here would nest it a second
+ * time. */
+@import url('./atomic.css');

package/dist/postcss.d.ts

@@ -0,0 +1,64 @@
+import { Plugin } from 'postcss';
+import { AtomDefinition } from './atoms.js';
+
+/**
+ * Nave PostCSS plugin — resolves @nave directives.
+ *
+ * Inlines atomic utility declarations at build time.
+ * Pseudo rules, @media and @container blocks are emitted as native CSS
+ * nesting inside the parent rule (`&:focus-visible { … }`), never hoisted
+ * out as sibling rules. Browser floor: Baseline 2024.
+ * See https://github.com/navecss/navecss/blob/main/docs/04-adr/0001-native-css-nesting.md
+ *
+ * Setup:
+ *   import { navePlugin } from '@navecss/core/postcss'
+ *   navePlugin()                         // Nave atoms only, fails build on unknown atom
+ *   navePlugin({ extend: myAtoms })      // Nave + consumer atoms
+ *   navePlugin({ onUnknown: 'warn' })    // Log and skip instead of failing the build
+ *
+ * Consumer atoms:
+ *   import type { AtomDefinition } from '@navecss/core/postcss'
+ *   import { media } from '@navecss/tokens/breakpoints'
+ *
+ *   const myAtoms: Record<string, AtomDefinition> = {
+ *     primaryButton: {
+ *       declarations: {
+ *         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)',
+ *       },
+ *       pseudos: {
+ *         ':hover': { background: 'var(--nave-color-action-primary-hover)' },
+ *       },
+ *       media: {
+ *         [media.phoneOnly]: {
+ *           declarations: { width: '100%' },
+ *         },
+ *       },
+ *     },
+ *   }
+ */
+
+interface NavePluginOptions {
+    /**
+     * Consumer-defined atoms merged with Nave built-in atoms.
+     * Consumer atoms win on name collision — your system owns its vocabulary.
+     * These atoms resolve via @nave only. No global class. Not available in cx().
+     */
+    extend?: Record<string, AtomDefinition>;
+    /**
+     * Behaviour on an unknown atom name, or a @nave directive that names no
+     * atom at all.
+     * 'warn'  — log and skip
+     * 'error' — throw, failing the build (default)
+     * 'ignore' — silently skip
+     */
+    onUnknown?: 'warn' | 'error' | 'ignore';
+}
+declare const navePlugin: {
+    (options?: NavePluginOptions): Plugin;
+    postcss: boolean;
+};
+
+export { AtomDefinition, type NavePluginOptions, navePlugin };