@navecss/tokens 0.2.0 → 0.4.0

package/README.md

@@ -22,11 +22,11 @@ pnpm add @navecss/tokens
 @import url('@navecss/tokens/css');
 ```
 
-This emits the token layer's custom properties (`--nave-*`) inside `@layer tokens.defaults`. Keep the `/css`: unlike `@navecss/core`, whose bare package name is its stylesheet, the bare `@navecss/tokens` is the JavaScript entry point. `@navecss/core` imports this automatically; install `@navecss/tokens` on its own only if you are building without `@navecss/core` (for example, on top of Base UI or Radix UI directly).
+This emits the token layer's custom properties (`--nave-*`) inside `@layer tokens.defaults`. Keep the `/css`: unlike `@navecss/core`, whose bare package name is its stylesheet, the bare `@navecss/tokens` is the JavaScript entry point. `@navecss/core` imports this automatically; install `@navecss/tokens` on its own only if you are building without `@navecss/core` (for example, with Radix UI, or with [`@navecss/base-ui`](https://github.com/navecss/navecss/tree/main/packages/base-ui#readme), which styles Base UI's components from these tokens and does not need core).
 
 ## What ships
 
-- **Colour** — the semantic colours consumers use (`action`, `content`, `surface`, `border`, `feedback`, and foregrounds for the primary action and the feedback roles), each with a light and a dark value through `light-dark()`. The `neutral`, `primary` and `danger` scales they are derived from stay inside the build: no step of them is emitted as a custom property. The neutral colours re-hue live from one custom property, under Theming below.
+- **Colour** — the semantic colours consumers use (`action`, `content`, `surface`, `border`, `feedback`, a scrim for behind a modal panel (`backdrop`), and foregrounds for the primary action and the feedback roles), each with a light and a dark value through `light-dark()`. The `neutral`, `primary` and `danger` scales they are derived from stay inside the build: no step of them is emitted as a custom property. The neutral colours re-hue live from one custom property, under Theming below.
 - **Typography, spacing, size, shape, shadow, motion, z-index, opacity** — the rest of the token taxonomy, authored once in `tokens.json` and compiled by the first-party DTCG 2025.10 reader.
 - **Breakpoints** — a JS-only export (`@navecss/tokens/breakpoints`): custom properties cannot hold media-query ranges, so these ship as typed constants and prebuilt Level 4 media-query strings instead.
 
@@ -99,7 +99,7 @@ Write `--flag=value` and not `--flag value`. A `#rrggbb` seed passed as a
 separate word begins a shell comment, so the rest of the command is discarded
 and you get a usage error rather than a wrong colour.
 
-0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. Where a check Nave ships runs in a consumer's build over the consumer's values, it reports and does not fail. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.
+0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. No contrast check this entry point runs over a consumer's values can fail the build, and none prints or returns a result. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.
 
 ```bash
 navecss-tokens validate --source=src/styles/nave/tokens.css

package/TOKENS.md

@@ -88,6 +88,7 @@ non-colour value is exactly what its name says.
 | `--nave-border-width-none`  |
 | `--nave-border-width-sm`    |
 | `--nave-border-width-focus` |
+| `--nave-border-width-mark`  |
 | `--nave-border-width-lg`    |
 
 ## Radius
@@ -166,6 +167,7 @@ non-colour value is exactly what its name says.
 | `--nave-color-action-primary-active`       | no                          |
 | `--nave-color-on-action-primary`           | yes                         |
 | `--nave-color-action-secondary`            | yes                         |
+| `--nave-color-action-highlight`            | yes                         |
 | `--nave-color-feedback-danger`             | no                          |
 | `--nave-color-feedback-danger-foreground`  | no                          |
 | `--nave-color-on-feedback-danger`          | yes                         |
@@ -178,3 +180,4 @@ non-colour value is exactly what its name says.
 | `--nave-color-feedback-info`               | yes                         |
 | `--nave-color-feedback-info-foreground`    | yes                         |
 | `--nave-color-on-feedback-info`            | yes                         |
+| `--nave-color-backdrop-modal`              | yes                         |

package/dist/core-contract.json

@@ -2,7 +2,7 @@
   "formatVersion": 1,
   "producer": {
     "name": "@navecss/core",
-    "version": "0.2.0"
+    "version": "0.4.0"
   },
   "tokens": [
     "--nave-border-width-focus",

package/dist/lib/theming/adjacency-source.js

@@ -46,6 +46,11 @@ export const ADJACENCY_EXCLUSIONS = {
         'and is not answered here.',
     'border.default': 'decorative divider: excluded as a decorative divider or card edge, and the ' +
         'exclusion is void the moment such a border is applied to a control.',
+    'backdrop.modal': 'scrim: excluded from the checked pair set because it is translucent, so the colour ' +
+        'it renders is a blend with whatever the page shows beneath it, which no pair in this ' +
+        'list can describe. The exclusion holds only while the scrim is painted behind a fully ' +
+        'modal panel, over a page the reader cannot reach; it is void the moment text, a ' +
+        'control or a focus indicator the reader can reach is drawn on it.',
 };
 export const ADJACENCY_OPEN = {
     'border.strong': 'open: whether this border can identify a control, and therefore whether its ' +

package/dist/lib/theming/adjacency.d.ts

@@ -1,4 +1,5 @@
 import { type Adjacency } from './adjacency-source.ts';
+import { type SlotMapping } from './semantics.ts';
 export type { Adjacency, MeasuredOpenSlots, OrphanCheckResult } from './adjacency-source.ts';
 export { ADJACENCY, ADJACENCY_EXCLUSIONS, ADJACENCY_OPEN, assertNoOrphanedSemanticSlot, } from './adjacency-source.ts';
 declare const MINIMUM_COVERAGE_CATEGORIES: readonly ["contentOnSurface", "inversePair", "onActionOnAction", "textOnFeedback", "sunken", "borderControl", "borderFocus", "filledAction", "filledFeedback"];
@@ -15,3 +16,4 @@ export interface ForbiddenAdjacencyRule {
 export declare function findForbiddenAdjacencyRule(subject: string, against: string): ForbiddenAdjacencyRule | undefined;
 export declare function assertNoForbiddenAdjacency(adjacency?: readonly Adjacency[]): void;
 export declare function assertNoFocusableAdjacentToActionFill(adjacency?: readonly Adjacency[]): void;
+export declare function assertNoTranslucentSlotInDeclaredPair(adjacency?: readonly Adjacency[], mapping?: Readonly<Record<string, SlotMapping>>, achromaticMapping?: Readonly<Record<string, SlotMapping>>): void;

package/dist/lib/theming/adjacency.js

@@ -1,5 +1,6 @@
 import { ADJACENCY } from "./adjacency-source.js";
-import { SEMANTIC_SLOTS } from "./semantics.js";
+import { roundedAlpha } from "./neutral.js";
+import { ACHROMATIC_MAPPING, CHROMATIC_MAPPING, SEMANTIC_SLOTS, } from "./semantics.js";
 export { ADJACENCY, ADJACENCY_EXCLUSIONS, ADJACENCY_OPEN, assertNoOrphanedSemanticSlot, } from "./adjacency-source.js";
 const MINIMUM_COVERAGE_CATEGORIES = [
     'contentOnSurface',
@@ -131,3 +132,39 @@ export function assertNoFocusableAdjacentToActionFill(adjacency = ADJACENCY) {
         }
     }
 }
+const TRANSLUCENT_SLOT_IN_PAIR_REASON = 'The contrast harness reads opaque colours only, and a translucent slot renders as a ' +
+    'blend with whatever lies beneath it, which no pair can describe. This rule records a ' +
+    'decision about which colour pairs this design system will declare and test; it is not ' +
+    'a check to silence or narrow to make a build pass. Remove the declaration, or, if you ' +
+    'need this pair, open an issue describing it and why, and leave it out of the pull ' +
+    'request until that issue is answered.';
+const MAX_ALIAS_DEPTH = 10;
+function isTranslucentWhenResolved(ref, scheme, lookup) {
+    let current = ref;
+    for (let depth = 0; depth < MAX_ALIAS_DEPTH; depth++) {
+        if (!('alias' in current))
+            return current.alpha !== undefined && roundedAlpha(current.alpha) < 1;
+        current = lookup(current.alias)[scheme];
+    }
+    throw new Error('Alias chain too deep — likely a cycle in the semantic mapping.');
+}
+function translucentSlots(mapping, achromaticMapping) {
+    const lookup = (isAchromaticBranch) => (slot) => {
+        const resolved = (isAchromaticBranch ? achromaticMapping[slot] : undefined) ?? mapping[slot];
+        if (!resolved)
+            throw new Error(`Unknown semantic slot: ${slot}`);
+        return resolved;
+    };
+    return new Set(Object.keys(mapping).filter((slot) => [false, true].some((isAchromaticBranch) => ['light', 'dark'].some((scheme) => isTranslucentWhenResolved(lookup(isAchromaticBranch)(slot)[scheme], scheme, lookup(isAchromaticBranch))))));
+}
+export function assertNoTranslucentSlotInDeclaredPair(adjacency = ADJACENCY, mapping = CHROMATIC_MAPPING, achromaticMapping = ACHROMATIC_MAPPING) {
+    const translucent = translucentSlots(mapping, achromaticMapping);
+    for (const pair of adjacency) {
+        for (const slot of [pair.subject, pair.against]) {
+            if (translucent.has(slot)) {
+                throw new Error(`Adjacency rule violation: the translucent slot "${slot}" is declared in the pair ` +
+                    `(${pair.subject}, ${pair.against}). ${TRANSLUCENT_SLOT_IN_PAIR_REASON}`);
+            }
+        }
+    }
+}

package/dist/lib/theming/build-step.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { collectDescriptionsFromSources } from "../dtcg-descriptions.js";
-import { assertCoverageFloor, assertNoFocusableAdjacentToActionFill, assertNoForbiddenAdjacency, assertNoOrphanedSemanticSlot, assertShippedSurfaceCountProvenance, } from "./adjacency.js";
+import { assertCoverageFloor, assertNoFocusableAdjacentToActionFill, assertNoForbiddenAdjacency, assertNoOrphanedSemanticSlot, assertNoTranslucentSlotInDeclaredPair, assertShippedSurfaceCountProvenance, } from "./adjacency.js";
 import { composeBuildRecord } from "./build-record.js";
 import { composeContactSheet } from "./contact-sheet.js";
 import { assertContrastFloors, assertFloorProvenance, assertNoSameStepViolations, checkSameStepLint, runContrastHarness, } from "./contrast.js";
@@ -20,6 +20,7 @@ import { TOKENS_JSON_PATH } from "./tokens-source.js";
 function runSourceGuards(tokensSourcePaths) {
     assertNoForbiddenAdjacency();
     assertNoFocusableAdjacentToActionFill();
+    assertNoTranslucentSlotInDeclaredPair();
     assertCoverageFloor();
     const orphanCheck = assertNoOrphanedSemanticSlot(SEMANTIC_SLOTS);
     assertOnStarShape();

package/dist/lib/theming/copy-lint.d.ts

@@ -8,6 +8,6 @@ export declare function assertDescriptionsAreClean(...descriptionMaps: readonly
 export declare const RETHEMING_NOTICE = "Changing this changes everything Nave derives from it. The contrast of the resulting palette follows from what you set, and checking it is yours.";
 export declare function assertNoticeIsClean(notice?: string, noticeLabel?: string): void;
 export declare const FEEDBACK_SHARED_IDENTITY_NOTICE = "warning, success and info, and their -foreground variants, resolve to one shared value here; only danger differs. Colour alone therefore cannot tell those three states apart, so wherever a feedback token carries meaning, give it a text label naming the state and a distinct icon or shape that differs per state.";
-export declare const NO_CONSUMER_CONTRAST_THRESHOLD_INPUT = "0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. Where a check Nave ships runs in a consumer's build over the consumer's values, it reports and does not fail. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.";
+export declare const NO_CONSUMER_CONTRAST_THRESHOLD_INPUT = "0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. No contrast check this entry point runs over a consumer's values can fail the build, and none prints or returns a result. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.";
 export declare function assertNoticeIsEmitted(css: string, notice: string, noticeLabel: string): void;
 export declare function assertHarnessFramingIsClean(): void;

package/dist/lib/theming/copy-lint.js

@@ -47,7 +47,7 @@ export function assertNoticeIsClean(notice = RETHEMING_NOTICE, noticeLabel = 'Re
     }
 }
 export const FEEDBACK_SHARED_IDENTITY_NOTICE = 'warning, success and info, and their -foreground variants, resolve to one shared value here; only danger differs. Colour alone therefore cannot tell those three states apart, so wherever a feedback token carries meaning, give it a text label naming the state and a distinct icon or shape that differs per state.';
-export const NO_CONSUMER_CONTRAST_THRESHOLD_INPUT = "0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. Where a check Nave ships runs in a consumer's build over the consumer's values, it reports and does not fail. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.";
+export const NO_CONSUMER_CONTRAST_THRESHOLD_INPUT = "0.1.0 ships no consumer contrast-threshold input. No flag of this entry point sets one, and the build reads none. This is the absence of an input, not a limit on the consumer: a consumer may hold whatever contrast target they choose and check their palette against it with their own tooling. No contrast check this entry point runs over a consumer's values can fail the build, and none prints or returns a result. A consumer-settable target is deliberately out of 0.1.0 rather than overlooked.";
 export function assertNoticeIsEmitted(css, notice, noticeLabel) {
     if (!css.includes(notice)) {
         throw new Error(`${noticeLabel} violation: the notice is not present, verbatim, in the emitted CSS. Restore it exactly as authored.`);

package/dist/lib/theming/descriptions.js

@@ -1,4 +1,12 @@
 export const SLOT_DESCRIPTIONS = new Map([
+    [
+        'action.highlight',
+        'Fill for a control under the pointer, the keyboard or a press: a highlighted list or menu item, or a ghost button. Never the only cue for focus or for a state such as selected, checked, open or current, and not for disabled controls.',
+    ],
+    [
+        'backdrop.modal',
+        'Translucent layer between a modal panel and the page, which it recedes. Only behind a fully modal panel; never under text, a control or a focus indicator the reader can reach.',
+    ],
     [
         'border.control',
         'Identifying boundary for a control (inputs, form boundaries, and the secondary action control).',

package/dist/lib/theming/emit.js

@@ -34,7 +34,7 @@ export function emitCss(result, layer = 'tokens.defaults') {
             h: result.records.primary.usedSeed.h,
         });
     const lines = [
-        '/* Nave theming — generated, do not edit. See this package\'s README ("Theming"). */',
+        '/* Nave theming — generated, do not edit. See the @navecss/tokens README ("Theming"). */',
         '',
         `@property ${TINT_PROPERTY} {`,
         `  syntax: '<color>';`,

package/dist/lib/theming/guard-message-probes.js

@@ -1,4 +1,4 @@
-import { ADJACENCY, assertCoverageFloor, assertNoFocusableAdjacentToActionFill, assertNoForbiddenAdjacency, assertNoOrphanedSemanticSlot, } from "./adjacency.js";
+import { ADJACENCY, assertCoverageFloor, assertNoFocusableAdjacentToActionFill, assertNoForbiddenAdjacency, assertNoOrphanedSemanticSlot, assertNoTranslucentSlotInDeclaredPair, } from "./adjacency.js";
 import { assertContrastFloors, assertFloorProvenance, assertNoSameStepViolations, checkSameStepLint, runContrastHarness, } from "./contrast.js";
 import { assertNoticeIsEmitted, RETHEMING_NOTICE } from "./copy-lint.js";
 import { TINT_SEED_COMMENT_STEM } from "./emit.js";
@@ -76,6 +76,13 @@ export const ACCESSIBILITY_GUARD_MESSAGE_PROBES = [
             { subject: 'border.focus', against: 'action.primary', class: 'non-text' },
         ])),
     },
+    {
+        label: 'the translucent-slot-in-a-declared-pair output',
+        capture: () => capturedFailureMessage(() => assertNoTranslucentSlotInDeclaredPair([
+            ...ADJACENCY,
+            { subject: 'content.primary', against: 'backdrop.modal', class: 'text' },
+        ])),
+    },
     {
         label: "the same-step lint's real violation output (build-step.ts's runResultGuards)",
         capture: () => {

package/dist/lib/theming/neutral.d.ts

@@ -9,4 +9,5 @@ export interface NeutralStep {
 }
 export declare function generateNeutralRampLiterals(ceiling?: number): readonly NeutralStep[];
 export declare function resolveNeutralStep(step: number, hue: number, literals?: readonly NeutralStep[]): Oklch;
-export declare function neutralRcsFormula(step: number, literals: readonly NeutralStep[]): string;
+export declare function neutralRcsFormula(step: number, literals: readonly NeutralStep[], alpha?: number): string;
+export declare function roundedAlpha(alpha: number): number;

package/dist/lib/theming/neutral.js

@@ -64,11 +64,17 @@ export function resolveNeutralStep(step, hue, literals = generateNeutralRampLite
         throw new Error(`Neutral step ${step} is not in the shared step table.`);
     return { l: found.l, c: found.c, h: hue };
 }
-export function neutralRcsFormula(step, literals) {
+export function neutralRcsFormula(step, literals, alpha = 1) {
     const found = literals.find((s) => s.step === step);
     if (!found)
         throw new Error(`Neutral step ${step} is not in the shared step table.`);
-    return `oklch(from var(--nave-color-tint) ${roundTo(found.l, 4)} ${roundTo(found.c, 4)} h / 1)`;
+    if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
+        throw new Error(`The alpha for neutral step ${step} must be a finite number from 0 to 1, got ${alpha}.`);
+    }
+    return `oklch(from var(--nave-color-tint) ${roundTo(found.l, 4)} ${roundTo(found.c, 4)} h / ${roundedAlpha(alpha)})`;
+}
+export function roundedAlpha(alpha) {
+    return roundTo(alpha, 4);
 }
 function roundTo(n, d) {
     const f = 10 ** d;

package/dist/lib/theming/pipeline.d.ts

@@ -14,13 +14,15 @@ interface PipelineRecords {
     achromaticBranch: boolean;
     tintHue: number;
 }
+interface ResolvedStep {
+    scale: 'danger' | 'neutral' | 'primary';
+    step: number;
+    alpha?: number;
+}
 export interface ResolvedSlot {
     slot: string;
     branch: 'dark' | 'light';
-    resolved: {
-        scale: 'danger' | 'neutral' | 'primary';
-        step: number;
-    };
+    resolved: ResolvedStep;
     literal: Oklch;
     css: string;
 }

package/dist/lib/theming/pipeline.js

@@ -16,7 +16,13 @@ function resolveStepRef(ref, branch, isAchromaticBranch) {
 function cssForResolved(resolved, ctx) {
     if (resolved.scale === 'neutral') {
         const colour = resolveNeutralStep(resolved.step, ctx.tintHue, ctx.neutralLiterals);
-        return { css: neutralRcsFormula(resolved.step, ctx.neutralLiterals), literal: colour };
+        return {
+            css: neutralRcsFormula(resolved.step, ctx.neutralLiterals, resolved.alpha),
+            literal: colour,
+        };
+    }
+    if (resolved.alpha !== undefined) {
+        throw new Error(`The ${resolved.scale} scale has no translucent form: alpha is written on neutral steps only.`);
     }
     const ramp = resolved.scale === 'primary' ? ctx.primaryRamp : ctx.dangerRamp;
     const colour = rampStep(ramp, resolved.step);

package/dist/lib/theming/semantics.d.ts

@@ -1,5 +1,6 @@
 type Scale = 'neutral' | 'primary' | 'danger';
 export type StepRef = {
+    alpha?: number;
     scale: Scale;
     step: number;
 } | {

package/dist/lib/theming/semantics.js

@@ -7,6 +7,11 @@ export const ACHROMATIC_BRANCH_SLOTS = [
     'border.focus',
 ];
 const ref = (scale, step) => ({ scale, step });
+const translucentRef = (step, alpha) => ({
+    scale: 'neutral',
+    step,
+    alpha,
+});
 const aliasRef = (slot) => ({ alias: slot });
 export const CHROMATIC_MAPPING = {
     'surface.base': { light: ref('neutral', 0), dark: ref('neutral', 900) },
@@ -30,6 +35,7 @@ export const CHROMATIC_MAPPING = {
     'action.primary.active': { light: ref('primary', 800), dark: ref('primary', 150) },
     'on-action.primary': { light: ref('neutral', 0), dark: ref('neutral', 900) },
     'action.secondary': { light: ref('neutral', 100), dark: ref('neutral', 800) },
+    'action.highlight': { light: ref('neutral', 100), dark: ref('neutral', 700) },
     'feedback.danger': { light: ref('danger', 600), dark: ref('danger', 300) },
     'feedback.danger.foreground': { light: ref('danger', 600), dark: ref('danger', 300) },
     'on-feedback.danger': { light: ref('neutral', 0), dark: ref('neutral', 900) },
@@ -48,6 +54,7 @@ export const CHROMATIC_MAPPING = {
         dark: aliasRef('feedback.warning.foreground'),
     },
     'on-feedback.info': { light: ref('neutral', 0), dark: ref('neutral', 900) },
+    'backdrop.modal': { light: translucentRef(950, 0.3), dark: translucentRef(950, 0.6) },
 };
 export const ACHROMATIC_MAPPING = {
     'action.primary': { light: ref('neutral', 800), dark: ref('neutral', 200) },

package/dist/lib/theming/third-party-provenance.d.ts

@@ -1,4 +1,4 @@
-export declare const R6_CONSUMER_ARTIFACTS: readonly ["tokens.css", "tokens.js", "tokens.d.ts", "breakpoints.js", "breakpoints.d.ts", "palette-record.json", "build-record.json"];
+export declare const CONSUMER_ARTIFACTS: readonly ["tokens.css", "tokens.js", "tokens.d.ts", "breakpoints.js", "breakpoints.d.ts", "palette-record.json", "build-record.json"];
 export interface ProvenanceArtifact {
     path: string;
     content: string;

package/dist/lib/theming/third-party-provenance.js

@@ -1,4 +1,4 @@
-export const R6_CONSUMER_ARTIFACTS = [
+export const CONSUMER_ARTIFACTS = [
     'tokens.css',
     'tokens.js',
     'tokens.d.ts',

package/dist/palette-record.json

@@ -180,6 +180,16 @@
     "$type": "color",
     "$value": "oklch(from var(--nave-color-tint) 0.27 0.0067 h / 1)"
   },
+  "color.action.highlight.light": {
+    "$type": "color",
+    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1)",
+    "$description": "Fill for a control under the pointer, the keyboard or a press: a highlighted list or menu item, or a ghost button. Never the only cue for focus or for a state such as selected, checked, open or current, and not for disabled controls."
+  },
+  "color.action.highlight.dark": {
+    "$type": "color",
+    "$value": "oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1)",
+    "$description": "Fill for a control under the pointer, the keyboard or a press: a highlighted list or menu item, or a ghost button. Never the only cue for focus or for a state such as selected, checked, open or current, and not for disabled controls."
+  },
   "color.feedback.danger.light": {
     "$type": "color",
     "$value": "oklch(0.47 0.1455 15.02)",
@@ -289,5 +299,15 @@
   "color.on-feedback.info.dark": {
     "$type": "color",
     "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
+  },
+  "color.backdrop.modal.light": {
+    "$type": "color",
+    "$value": "oklch(from var(--nave-color-tint) 0.12 0.0067 h / 0.3)",
+    "$description": "Translucent layer between a modal panel and the page, which it recedes. Only behind a fully modal panel; never under text, a control or a focus indicator the reader can reach."
+  },
+  "color.backdrop.modal.dark": {
+    "$type": "color",
+    "$value": "oklch(from var(--nave-color-tint) 0.12 0.0067 h / 0.6)",
+    "$description": "Translucent layer between a modal panel and the page, which it recedes. Only behind a fully modal panel; never under text, a control or a focus indicator the reader can reach."
   }
 }

package/dist/tokens.css

@@ -167,6 +167,12 @@
     initial-value: 2px;
   }
 
+  @property --nave-border-width-mark {
+    syntax: '<length>';
+    inherits: true;
+    initial-value: 2px;
+  }
+
   @property --nave-border-width-lg {
     syntax: '<length>';
     inherits: true;
@@ -339,6 +345,7 @@
     --nave-border-width-none: 0px;
     --nave-border-width-sm: 1px;
     --nave-border-width-focus: 2px;
+    --nave-border-width-mark: 2px;
     --nave-border-width-lg: 4px;
     --nave-radius-none: 0px;
     --nave-radius-sm: 4px;
@@ -380,7 +387,7 @@
   }
 }
 
-/* Nave theming — generated, do not edit. See this package's README ("Theming"). */
+/* Nave theming — generated, do not edit. See the @navecss/tokens README ("Theming"). */
 
 @property --nave-color-tint {
   syntax: '<color>';
@@ -416,6 +423,7 @@
     --nave-color-action-primary-active: light-dark(oklch(0.27 0.0398 186.17), oklch(0.94 0.0574 186.17));
     --nave-color-on-action-primary: light-dark(oklch(from var(--nave-color-tint) 1 0 h / 1), oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1));
     --nave-color-action-secondary: light-dark(oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.27 0.0067 h / 1));
+    --nave-color-action-highlight: light-dark(oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1));
     --nave-color-feedback-danger: light-dark(oklch(0.47 0.1455 15.02), oklch(0.835 0.0661 15.02));
     --nave-color-feedback-danger-foreground: light-dark(oklch(0.47 0.1455 15.02), oklch(0.835 0.0661 15.02));
     --nave-color-on-feedback-danger: light-dark(oklch(from var(--nave-color-tint) 1 0 h / 1), oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1));
@@ -429,5 +437,6 @@
     --nave-color-feedback-info: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1));
     --nave-color-feedback-info-foreground: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1));
     --nave-color-on-feedback-info: light-dark(oklch(from var(--nave-color-tint) 1 0 h / 1), oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1));
+    --nave-color-backdrop-modal: light-dark(oklch(from var(--nave-color-tint) 0.12 0.0067 h / 0.3), oklch(from var(--nave-color-tint) 0.12 0.0067 h / 0.6));
   }
 }

package/dist/tokens.d.ts

@@ -61,6 +61,7 @@ export declare const tokens: {
   '--nave-border-width-none': string
   '--nave-border-width-sm': string
   '--nave-border-width-focus': string
+  '--nave-border-width-mark': string
   '--nave-border-width-lg': string
   '--nave-radius-none': string
   '--nave-radius-sm': string
@@ -98,10 +99,12 @@ export declare type TokenValue = typeof tokens[TokenName]
  *  `TokenName | ColorPropertyName`.
  */
 export declare type ColorPropertyName =
+  | '--nave-color-action-highlight'
   | '--nave-color-action-primary'
   | '--nave-color-action-primary-active'
   | '--nave-color-action-primary-hover'
   | '--nave-color-action-secondary'
+  | '--nave-color-backdrop-modal'
   | '--nave-color-border-control'
   | '--nave-color-border-default'
   | '--nave-color-border-disabled'

package/dist/tokens.js

@@ -62,6 +62,7 @@ export const tokens = {
   '--nave-border-width-none': "0px",
   '--nave-border-width-sm': "1px",
   '--nave-border-width-focus': "2px",
+  '--nave-border-width-mark': "2px",
   '--nave-border-width-lg': "4px",
   '--nave-radius-none': "0px",
   '--nave-radius-sm': "4px",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navecss/tokens",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "DTCG 2025.10 design tokens for Nave: seed-derived semantic colours, typography, spacing, and the rest of the token layer, built by a first-party DTCG 2025.10 reader.",
   "keywords": [
     "css",
@@ -51,11 +51,11 @@
     "TOKENS.md"
   ],
   "devDependencies": {
-    "@types/node": "^26.6.2",
-    "@vitest/coverage-v8": "5.0.1",
+    "@types/node": "^26.6.4",
+    "@vitest/coverage-v8": "5.0.3",
     "prettier": "3.9.9",
     "typescript": "6.0.3",
-    "vitest": "5.0.1"
+    "vitest": "5.0.3"
   },
   "engines": {
     "node": ">=22.18"
@@ -79,7 +79,6 @@
     "lint": "eslint build.ts generate-tokens-doc.ts src test --max-warnings 0",
     "lint:fix": "eslint build.ts generate-tokens-doc.ts src test --fix",
     "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
     "check:pack": "node ../../scripts/without-dry-run.mjs publint && node ../../scripts/without-dry-run.mjs attw --pack . --profile esm-only --exclude-entrypoints css"
   }
 }

package/tokens.json

@@ -33,12 +33,32 @@
           {
             "against": "surface.sunken",
             "class": "text"
+          },
+          {
+            "against": "surface.overlay",
+            "class": "text"
+          },
+          {
+            "against": "action.highlight",
+            "class": "text"
           }
         ],
         "content.secondary": [
           {
             "against": "surface.base",
             "class": "text"
+          },
+          {
+            "against": "surface.raised",
+            "class": "text"
+          },
+          {
+            "against": "surface.overlay",
+            "class": "text"
+          },
+          {
+            "against": "action.highlight",
+            "class": "text"
           }
         ],
         "content.tertiary": [
@@ -49,6 +69,14 @@
           {
             "against": "surface.sunken",
             "class": "text"
+          },
+          {
+            "against": "surface.raised",
+            "class": "text"
+          },
+          {
+            "against": "surface.overlay",
+            "class": "text"
           }
         ],
         "content.inverse": [
@@ -67,6 +95,14 @@
           {
             "against": "surface.base",
             "class": "text"
+          },
+          {
+            "against": "surface.raised",
+            "class": "text"
+          },
+          {
+            "against": "surface.overlay",
+            "class": "text"
           }
         ],
         "on-action.primary": [
@@ -155,12 +191,28 @@
           {
             "against": "surface.base",
             "class": "non-text"
+          },
+          {
+            "against": "surface.raised",
+            "class": "non-text"
+          },
+          {
+            "against": "surface.overlay",
+            "class": "non-text"
           }
         ],
         "feedback.danger": [
           {
             "against": "surface.base",
             "class": "non-text"
+          },
+          {
+            "against": "surface.raised",
+            "class": "non-text"
+          },
+          {
+            "against": "surface.overlay",
+            "class": "non-text"
           }
         ],
         "feedback.warning": [
@@ -173,6 +225,18 @@
           {
             "against": "surface.base",
             "class": "non-text"
+          },
+          {
+            "against": "surface.base",
+            "class": "text"
+          },
+          {
+            "against": "surface.raised",
+            "class": "text"
+          },
+          {
+            "against": "surface.overlay",
+            "class": "text"
           }
         ]
       }
@@ -597,6 +661,14 @@
       "$type": "dimension",
       "$description": "Focus ring indicator outline width"
     },
+    "mark": {
+      "$value": {
+        "value": 2,
+        "unit": "px"
+      },
+      "$type": "dimension",
+      "$description": "Strokes of glyphs drawn in CSS: check marks, indeterminate bars"
+    },
     "lg": {
       "$value": {
         "value": 4,
@@ -626,7 +698,7 @@
         "unit": "px"
       },
       "$type": "dimension",
-      "$description": "Inputs, buttons, tags"
+      "$description": "Inputs, buttons, tags, and the popovers, menus and select lists anchored to a control"
     },
     "card": {
       "$value": {