@navecss/tokens 0.3.0 → 0.4.0

package/README.md

@@ -26,7 +26,7 @@ This emits the token layer's custom properties (`--nave-*`) inside `@layer token
 
 ## 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.
 

package/TOKENS.md

@@ -167,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                         |
@@ -179,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.3.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/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/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/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

@@ -423,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));
@@ -436,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

@@ -99,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navecss/tokens",
-  "version": "0.3.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",

package/tokens.json

@@ -37,6 +37,10 @@
           {
             "against": "surface.overlay",
             "class": "text"
+          },
+          {
+            "against": "action.highlight",
+            "class": "text"
           }
         ],
         "content.secondary": [
@@ -51,6 +55,10 @@
           {
             "against": "surface.overlay",
             "class": "text"
+          },
+          {
+            "against": "action.highlight",
+            "class": "text"
           }
         ],
         "content.tertiary": [