@navecss/tokens 0.1.1 → 0.2.0

package/README.md

@@ -46,7 +46,7 @@ Every custom property the stylesheet declares is listed in [TOKENS.md](./TOKENS.
 | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@navecss/tokens`               | JS entry point — the typed constants described under `@navecss/tokens/js` below. Not a CSS entry: `@import url('@navecss/tokens/css')` is the stylesheet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `@navecss/tokens/css`           | The generated stylesheet — `@import url('@navecss/tokens/css')`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `@navecss/tokens/js`            | Typed ESM token constants — the DTCG 2025.10 token set; every `--nave-color-*` custom property ships in the stylesheet above and not through this export, the `--nave-color-tint` seed included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `@navecss/tokens/js`            | Typed ESM token constants — the DTCG 2025.10 token set; every `--nave-color-*` custom property (the `--nave-color-tint` seed included) ships as a value in the stylesheet above and not through this export, but its NAME is typed here as `ColorPropertyName`, exported alongside `TokenName`/`TokenValue` and disjoint from them                                                                                                                                                                                                                                                                                                                                                      |
 | `@navecss/tokens/breakpoints`   | Breakpoint values, em conversions, media strings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `@navecss/tokens/core-contract` | The shipped core-contract manifest, as JSON, for a token layer you generate yourself and load through `@navecss/core/no-tokens`: the `--nave-*` custom-property names `@navecss/core` reads, generated from that package's own source rather than listed by hand, and not the colour namespace alone. Import it with `with { type: 'json' }`. A clean check against it means those names are present rather than that your token set is complete; for what else it does and does not establish, read the header comment in `@navecss/core/no-tokens`. A validator reading the manifest directly should refuse a `formatVersion` higher than it understands, rather than mis-reading it. |
 | `@navecss/tokens/build`         | The token build as a JavaScript API: `build` and `validate`, the two operations the `navecss-tokens` binary wraps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

package/dist/core-contract.json

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

package/dist/lib/bin.js

@@ -20,11 +20,21 @@ function normalizationQualifier(seedNormalization) {
 const USAGE = 'Usage:\n' +
     '  navecss-tokens build --seed=<colour> --out=<dir> [--source=<file>] [--overrides=<file>]\n' +
     '  navecss-tokens validate --source=<file>';
+function assertNoDuplicateFlags(tokens) {
+    const seen = new Set();
+    for (const token of tokens) {
+        if (token.kind !== 'option' || token.name === undefined)
+            continue;
+        if (seen.has(token.name)) {
+            throw new UsageError(`--${token.name} was given more than once; each flag accepts exactly one value.\n${USAGE}`);
+        }
+        seen.add(token.name);
+    }
+}
 function parseBuildArgs(args) {
     let values;
     try {
-        ;
-        ({ values } = parseArgs({
+        const parsed = parseArgs({
             args,
             options: {
                 out: { type: 'string' },
@@ -33,9 +43,14 @@ function parseBuildArgs(args) {
                 source: { type: 'string' },
             },
             strict: true,
-        }));
+            tokens: true,
+        });
+        assertNoDuplicateFlags(parsed.tokens);
+        values = parsed.values;
     }
     catch (error) {
+        if (error instanceof UsageError)
+            throw error;
         throw new UsageError(error.message);
     }
     if (!values.seed)
@@ -52,10 +67,18 @@ function parseBuildArgs(args) {
 function parseValidateArgs(args) {
     let values;
     try {
-        ;
-        ({ values } = parseArgs({ args, options: { source: { type: 'string' } }, strict: true }));
+        const parsed = parseArgs({
+            args,
+            options: { source: { type: 'string' } },
+            strict: true,
+            tokens: true,
+        });
+        assertNoDuplicateFlags(parsed.tokens);
+        values = parsed.values;
     }
     catch (error) {
+        if (error instanceof UsageError)
+            throw error;
         throw new UsageError(error.message);
     }
     if (!values.source)

package/dist/lib/facade.js

@@ -6,8 +6,10 @@ import { detectCollidingNames, refuseOnCollision } from "./collision.js";
 import { detectVersionSkew } from "./core-version.js";
 import { composeDtcgOutputs } from "./dtcg-outputs.js";
 import { MissingContractTokensError, UsageError } from "./errors.js";
+import { isOutPathConflict } from "./out-path-conflict.js";
 import { readOverrides } from "./overrides.js";
 import { findPackageRoot } from "./package-root.js";
+import { readManifest } from "./read-manifest.js";
 import { formatOklch } from "./theming/color-math.js";
 import { composeConsumerBuild } from "./theming/consumer-build.js";
 import { validateAgainstManifest } from "./theming/core-contract.js";
@@ -20,10 +22,6 @@ export { DuplicateTokenNameRefusal, MissingContractTokensError, TokenCollisionRe
 export { SeedIngestRefusal } from "./theming/seed-ingest.js";
 export { formatVersionSkewFact } from "./validate-report.js";
 const PACKAGE_ROOT = findPackageRoot(import.meta.url);
-async function readManifest() {
-    const raw = await readFile(path.join(PACKAGE_ROOT, 'dist', 'core-contract.json'), 'utf8');
-    return JSON.parse(raw);
-}
 export async function build(options) {
     const sourcePath = options.source ?? path.join(PACKAGE_ROOT, 'tokens.json');
     if (!existsSync(sourcePath)) {
@@ -57,7 +55,15 @@ export async function build(options) {
         ? { ...file, content: `${file.content}\n${theming.css}` }
         : file);
     const allFiles = [...merged, ...theming.files];
-    await writeOutputs(allFiles);
+    try {
+        await writeOutputs(allFiles);
+    }
+    catch (error) {
+        if (isOutPathConflict(error)) {
+            throw new UsageError(`could not write to --out="${options.outDir}": ${error.message}`);
+        }
+        throw error;
+    }
     return {
         resolvedSeed: formatOklch(theming.primaryRecord.usedSeed),
         seedNormalization: theming.primaryRecord.normalization,

package/dist/lib/formats.js

@@ -1,3 +1,4 @@
+import { shippedThemingPropertyNames } from "./theming/emit.js";
 const HEADER = '/* Nave Design System — generated, do not edit */';
 const LAYER_ORDER_STATEMENT = '@layer tokens.defaults, tokens.presets, reset, atomic, components.nave, components.consumer, overrides;';
 const PREFIX = '--nave-';
@@ -15,8 +16,10 @@ const isPublic = (token) => !token.path.includes('_primitive') && token.path[0]
 const isReducibleDuration = (token) => token.type === 'duration' &&
     token.path[0] === 'motion' &&
     token.name !== 'motion-duration-instant';
+const isZIndexShaped = (token) => token.type === 'number' && token.path[0] === 'layer';
+const atPropertySyntaxFor = (token) => isZIndexShaped(token) ? '<integer>' : AT_PROPERTY_SYNTAX[token.type];
 function isRegistrable(token) {
-    const syntax = AT_PROPERTY_SYNTAX[token.type];
+    const syntax = atPropertySyntaxFor(token);
     if (syntax === undefined)
         return false;
     if (syntax !== '<length>')
@@ -26,7 +29,7 @@ function isRegistrable(token) {
 function buildAtProperty(token) {
     return [
         `  @property ${PREFIX}${token.name} {`,
-        `    syntax: '${AT_PROPERTY_SYNTAX[token.type]}';`,
+        `    syntax: '${atPropertySyntaxFor(token)}';`,
         `    inherits: true;`,
         `    initial-value: ${token.value};`,
         `  }`,
@@ -93,8 +96,11 @@ export function formatJsTokens(tokens) {
         '',
         '/** The DTCG 2025.10 token set as a typed const object (e.g. `--nave-font-size-md`).',
         ' *  Keys are CSS custom property names. The semantic colour layer',
-        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css`',
-        ' *  and is not part of this export.',
+        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css` and is',
+        ' *  not part of this object; its property NAMES are typed separately as',
+        ' *  `ColorPropertyName`, and its VALUES are reachable only through CSS (e.g.',
+        ' *  `var(--nave-color-action-primary)`): the browser resolves each one for the',
+        ' *  active colour scheme, and the neutral-derived ones also follow the tint.',
         ' */',
         'export const tokens = {',
         entries,
@@ -107,13 +113,20 @@ export function formatTsDeclarations(tokens) {
         .filter((t) => isPublic(t))
         .map((t) => `  '${PREFIX}${t.name}': ${typeof t.value === 'number' ? 'number' : 'string'}`)
         .join('\n');
+    const colorPropertyNameMembers = [...shippedThemingPropertyNames()]
+        .toSorted((a, b) => a.localeCompare(b))
+        .map((name) => `  | '${name}'`)
+        .join('\n');
     return [
         HEADER,
         '',
         '/** The DTCG 2025.10 token set as a typed const object (e.g. `--nave-font-size-md`).',
         ' *  Keys are CSS custom property names. The semantic colour layer',
-        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css`',
-        ' *  and is not part of this export.',
+        ' *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css` and is',
+        ' *  not part of this object; its property NAMES are typed separately as',
+        ' *  `ColorPropertyName`, and its VALUES are reachable only through CSS (e.g.',
+        ' *  `var(--nave-color-action-primary)`): the browser resolves each one for the',
+        ' *  active colour scheme, and the neutral-derived ones also follow the tint.',
         ' */',
         'export declare const tokens: {',
         keys,
@@ -122,6 +135,14 @@ export function formatTsDeclarations(tokens) {
         'export declare type TokenName = keyof typeof tokens',
         'export declare type TokenValue = typeof tokens[TokenName]',
         '',
+        '/** Every `--nave-color-*` custom property the semantic colour layer emits: names',
+        ' *  only, no value (see the doc comment above `tokens` for where the values live).',
+        ' *  Disjoint from `TokenName` — a consumer who wants both writes',
+        ' *  `TokenName | ColorPropertyName`.',
+        ' */',
+        'export declare type ColorPropertyName =',
+        colorPropertyNameMembers,
+        '',
     ].join('\n');
 }
 function buildBreakpointMap(tokens) {

package/dist/lib/out-path-conflict.d.ts

@@ -0,0 +1,3 @@
+export declare function isOutPathConflict(error: unknown): error is Error & {
+    code: string;
+};

package/dist/lib/out-path-conflict.js

@@ -0,0 +1,7 @@
+const OUT_PATH_CONFLICT_CODES = new Set(['EEXIST', 'EISDIR', 'ENOTDIR']);
+export function isOutPathConflict(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        OUT_PATH_CONFLICT_CODES.has(error.code));
+}

package/dist/lib/read-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { CoreContractManifest } from './theming/core-contract.ts';
+export declare function readManifest(): Promise<CoreContractManifest>;

package/dist/lib/read-manifest.js

@@ -0,0 +1,17 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { UsageError } from "./errors.js";
+import { findPackageRoot } from "./package-root.js";
+const PACKAGE_ROOT = findPackageRoot(import.meta.url);
+export async function readManifest() {
+    let raw;
+    try {
+        raw = await readFile(path.join(PACKAGE_ROOT, 'dist', 'core-contract.json'), 'utf8');
+    }
+    catch (error) {
+        throw new UsageError(`could not read this package's own dist/core-contract.json: ${error.message}. ` +
+            'This is a broken install of @navecss/tokens, not something your build/validate ' +
+            'arguments can fix — reinstall the package.');
+    }
+    return JSON.parse(raw);
+}

package/dist/lib/reader.d.ts

@@ -5,4 +5,10 @@ export interface FlatToken {
     readonly type: string;
     readonly value: string | number;
 }
+export interface RawToken {
+    path: string[];
+    ref?: string;
+    type: string;
+    rawValue: unknown;
+}
 export declare function readTokens(source: unknown, sourceName?: string): FlatToken[];

package/dist/lib/reader.js

@@ -1,14 +1,35 @@
-import { renderTokenValue } from "./composite-value.js";
 import { classifyMalformed, formatUnreadableNodesRefusal } from "./dtcg-malformed.js";
 import { classifyDraftShape, refuseTypeReason } from "./dtcg-shape.js";
 import { DtcgShapeRefusal } from "./errors.js";
-import { refuseBothReferenceForms, resolveTokenPointer } from "./json-pointer.js";
+import { refuseBothReferenceForms } from "./json-pointer.js";
+import { refuseUnsupportedReservedKey } from "./reserved-keys.js";
+import { resolveValue } from "./resolve-value.js";
 import { nameFromPath } from "./token-name.js";
 export { kebabName } from "./token-name.js";
-const REF_RE = /^\{([^{}]+)\}$/;
+const RESERVED_METADATA_KEYS = new Set([
+    '$deprecated',
+    '$description',
+    '$extensions',
+    '$ref',
+    '$type',
+    '$value',
+]);
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function assertRecognisedDollarKey(key, at) {
+    if (RESERVED_METADATA_KEYS.has(key))
+        return;
+    refuseUnsupportedReservedKey(key, at);
+    throw new TypeError(`DTCG 2025.10 reader: "${at}" starts with "$", which DTCG 2025.10 ` +
+        'reserves for metadata — it is not a valid token or group name');
+}
+function assertTokenDollarKeys(node, path) {
+    for (const key of Object.keys(node)) {
+        if (key.startsWith('$'))
+            assertRecognisedDollarKey(key, [...path, key].join('.'));
+    }
+}
 function readTokenNode(node, path, inheritedType) {
     const hasValue = '$value' in node;
     const hasRef = typeof node.$ref === 'string';
@@ -17,6 +38,13 @@ function readTokenNode(node, path, inheritedType) {
     const at = path.join('.');
     if (hasValue && hasRef)
         refuseBothReferenceForms(at);
+    assertTokenDollarKeys(node, path);
+    const childKeys = Object.keys(node).filter((key) => !key.startsWith('$'));
+    if (childKeys.length > 0) {
+        throw new TypeError(`DTCG 2025.10 reader: "${at}" carries both a $value and child token(s) (${childKeys.join(', ')}) ` +
+            '— a node is either a token (a $value/$ref leaf) or a group (children only), never both; ' +
+            'give the children their own group, separate from this token');
+    }
     const type = typeof node.$type === 'string' ? node.$type : inheritedType;
     if (type === undefined) {
         throw new TypeError(`DTCG 2025.10 reader: no resolvable $type for token "${at}"`);
@@ -41,8 +69,16 @@ function collectRawTokens(node, path, inheritedType, out) {
     }
     const groupType = typeof node.$type === 'string' ? node.$type : inheritedType;
     for (const [key, child] of Object.entries(node)) {
-        if (key.startsWith('$'))
+        if (key.startsWith('$')) {
+            assertRecognisedDollarKey(key, [...path, key].join('.'));
             continue;
+        }
+        if (key.includes('.')) {
+            throw new TypeError(`DTCG 2025.10 reader: "${[...path, key].join('.')}" contains a literal "." in "${key}" ` +
+                "— dotted keys are ambiguous against this reader's own dotted alias paths " +
+                '(a group "a" -> "b" -> "c" and a group "a" with a key "b.c" both name the path ' +
+                '"a.b.c"), and the format has no other separator to disambiguate them');
+        }
         collectRawTokens(child, [...path, key], groupType, out);
     }
 }
@@ -81,43 +117,6 @@ function refuseUnreadableNodes(raw, sourceName) {
         throw new DtcgShapeRefusal(formatUnreadableNodesRefusal(drafts, malformed, sourceName), drafts);
     }
 }
-function resolveReference(key, targetPath, context) {
-    if (context.visiting.has(key)) {
-        throw new TypeError(`DTCG 2025.10 reader: reference cycle detected at "${key}" -> "${targetPath}"`);
-    }
-    const target = context.byPath.get(targetPath);
-    if (!target) {
-        throw new TypeError(`DTCG 2025.10 reader: "${key}" references unresolved target "${targetPath}"`);
-    }
-    context.visiting.add(key);
-    const value = resolveValue(target, context);
-    context.visiting.delete(key);
-    return value;
-}
-function resolveValue(token, context) {
-    const key = token.path.join('.');
-    const cached = context.resolved.get(key);
-    if (cached !== undefined)
-        return cached;
-    let value;
-    if (token.ref !== undefined) {
-        const targetPath = resolveTokenPointer(token.ref, key, (path) => context.byPath.has(path));
-        value = resolveReference(key, targetPath, context);
-    }
-    else if (typeof token.rawValue === 'string' && REF_RE.test(token.rawValue)) {
-        value = resolveReference(key, REF_RE.exec(token.rawValue)[1], context);
-    }
-    else if (typeof token.rawValue === 'string' &&
-        (token.rawValue.includes('{') || token.rawValue.includes('}'))) {
-        throw new TypeError(`DTCG 2025.10 reader: "${key}" embeds a reference inside a larger string ("${token.rawValue}") — ` +
-            'only a whole-value alias (curly braces around one dotted path, nothing else) is supported');
-    }
-    else {
-        value = renderTokenValue(token.type, token.rawValue, key);
-    }
-    context.resolved.set(key, value);
-    return value;
-}
 export function readTokens(source, sourceName) {
     const raw = [];
     collectRawTokens(source, [], undefined, raw);
@@ -126,6 +125,7 @@ export function readTokens(source, sourceName) {
         byPath: new Map(raw.map((t) => [t.path.join('.'), t])),
         resolved: new Map(),
         visiting: new Set(),
+        depth: 0,
     };
     return raw.map((token) => ({
         path: token.path,

package/dist/lib/reserved-keys.d.ts

@@ -0,0 +1 @@
+export declare function refuseUnsupportedReservedKey(key: string, at: string): void;

package/dist/lib/reserved-keys.js

@@ -0,0 +1,18 @@
+const UNSUPPORTED_RESERVED_KEYS = [
+    {
+        key: '$root',
+        reason: 'DTCG 2025.10 §6.2 "Root Tokens in Groups". Move its $value to a sibling token with an ' +
+            'ordinary name (for example "base") and alias that instead: {group.base}.',
+    },
+    {
+        key: '$extends',
+        reason: 'DTCG 2025.10 §6.4 "Extending Groups". Copy the extended group\'s tokens into this group, ' +
+            'or alias them individually with {group.token}.',
+    },
+];
+export function refuseUnsupportedReservedKey(key, at) {
+    const found = UNSUPPORTED_RESERVED_KEYS.find((entry) => entry.key === key);
+    if (found === undefined)
+        return;
+    throw new TypeError(`DTCG 2025.10 reader: "${at}" uses "${key}", which this reader does not support yet (${found.reason})`);
+}

package/dist/lib/resolve-value.d.ts

@@ -0,0 +1,8 @@
+import type { RawToken } from './reader.ts';
+export interface ResolveContext {
+    byPath: ReadonlyMap<string, RawToken>;
+    resolved: Map<string, string | number>;
+    visiting: Set<string>;
+    depth: number;
+}
+export declare function resolveValue(token: RawToken, context: ResolveContext): string | number;

package/dist/lib/resolve-value.js

@@ -0,0 +1,56 @@
+import { renderTokenValue } from "./composite-value.js";
+import { resolveTokenPointer } from "./json-pointer.js";
+const REF_RE = /^\{([^{}]+)\}$/;
+const MAX_ALIAS_CHAIN_DEPTH = 1000;
+function resolveReference(key, targetPath, context) {
+    if (context.visiting.has(key)) {
+        throw new TypeError(`DTCG 2025.10 reader: reference cycle detected at "${key}" -> "${targetPath}"`);
+    }
+    const target = context.byPath.get(targetPath);
+    if (!target) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" references unresolved target "${targetPath}"`);
+    }
+    if (context.depth >= MAX_ALIAS_CHAIN_DEPTH) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" -> "${targetPath}" exceeds the maximum alias chain depth ` +
+            `(${MAX_ALIAS_CHAIN_DEPTH}); this reads as a generated or malformed source rather than an ` +
+            'authored one');
+    }
+    context.visiting.add(key);
+    context.depth += 1;
+    const value = resolveValue(target, context);
+    context.depth -= 1;
+    context.visiting.delete(key);
+    return value;
+}
+function refuseUnsafeStringValue(key, rawValue) {
+    if (rawValue.includes(';') || rawValue.includes('/*')) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" carries a ";" or a comment opener ("/*") in its value ` +
+            `("${rawValue}") — a raw string value is spliced directly into generated CSS, and ` +
+            'either would splice a second declaration in beside it');
+    }
+    if (rawValue.includes('{') || rawValue.includes('}')) {
+        throw new TypeError(`DTCG 2025.10 reader: "${key}" embeds a reference inside a larger string ("${rawValue}") — ` +
+            'only a whole-value alias (curly braces around one dotted path, nothing else) is supported');
+    }
+}
+export function resolveValue(token, context) {
+    const key = token.path.join('.');
+    const cached = context.resolved.get(key);
+    if (cached !== undefined)
+        return cached;
+    let value;
+    if (token.ref !== undefined) {
+        const targetPath = resolveTokenPointer(token.ref, key, (path) => context.byPath.has(path));
+        value = resolveReference(key, targetPath, context);
+    }
+    else if (typeof token.rawValue === 'string' && REF_RE.test(token.rawValue)) {
+        value = resolveReference(key, REF_RE.exec(token.rawValue)[1], context);
+    }
+    else {
+        if (typeof token.rawValue === 'string')
+            refuseUnsafeStringValue(key, token.rawValue);
+        value = renderTokenValue(token.type, token.rawValue, key);
+    }
+    context.resolved.set(key, value);
+    return value;
+}

package/dist/lib/theming/comment-open-tracker.js

@@ -13,6 +13,8 @@ export function linesThatBeginInsideAnUnclosedComment(lines) {
             isInsideAnOpenComment = isLineStillInsideAnOpenComment(line, isInsideAnOpenComment, reading);
         }
     }
+    markLinesFlaggedByTheUrlOpaqueReading(lines, beginningsInsideAnUnclosedComment);
+    markLinesFlaggedByTheEscapedLineBreakReading(lines, beginningsInsideAnUnclosedComment);
     return beginningsInsideAnUnclosedComment;
 }
 const AS_THE_TOKENIZER_READS_IT = {
@@ -79,3 +81,190 @@ function indexAfterAStringLiteral(line, quoteIndex, quote) {
     }
     return -1;
 }
+function markLinesFlaggedByTheUrlOpaqueReading(lines, into) {
+    let state = { isInsideAnOpenComment: false, urlCarry: 'none' };
+    for (const [index, line] of lines.entries()) {
+        if (state.isInsideAnOpenComment)
+            into.add(index);
+        state = scanLineWithOpaqueUrlContent(line, state);
+    }
+}
+function resumeUrlCarry(line, urlCarry) {
+    if (urlCarry === 'none')
+        return 0;
+    return urlCarry === 'pending' ? resolveUrlContent(line, 0) : indexAfterUnquotedUrlContent(line, 0);
+}
+function scanLineWithOpaqueUrlContent(line, state) {
+    const cursor = resumeUrlCarry(line, state.urlCarry);
+    if (typeof cursor === 'string')
+        return { isInsideAnOpenComment: false, urlCarry: cursor };
+    return scanLineForOpaqueUrlContentAndComments(line, state.isInsideAnOpenComment, cursor);
+}
+function scanLineForOpaqueUrlContentAndComments(line, wasInsideAnOpenComment, cursor) {
+    let isInsideAnOpenComment = wasInsideAnOpenComment;
+    let index = cursor;
+    while (index < line.length) {
+        if (isInsideAnOpenComment) {
+            const closerIndex = line.indexOf('*/', index);
+            if (closerIndex === -1)
+                return { isInsideAnOpenComment: true, urlCarry: 'none' };
+            isInsideAnOpenComment = false;
+            index = closerIndex + 2;
+            continue;
+        }
+        const urlLookup = tryToSkipAnUnquotedUrlToken(line, index);
+        if (typeof urlLookup === 'string')
+            return { isInsideAnOpenComment: false, urlCarry: urlLookup };
+        if (urlLookup !== undefined) {
+            index = urlLookup;
+            continue;
+        }
+        const character = line[index];
+        if (isAQuoteCharacter(character)) {
+            const afterTheString = indexAfterAStringLiteral(line, index, character);
+            index = afterTheString === -1 ? line.length : afterTheString;
+            continue;
+        }
+        if (line.startsWith('/*', index)) {
+            isInsideAnOpenComment = true;
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return { isInsideAnOpenComment, urlCarry: 'none' };
+}
+function isAnIdentifierCharacter(character) {
+    return (character !== undefined && (/[A-Za-z0-9_-]/.test(character) || character.codePointAt(0) > 0x7f));
+}
+function tryToSkipAnUnquotedUrlToken(line, cursor) {
+    if (isAnIdentifierCharacter(line[cursor - 1]) || /[#@]/.test(line[cursor - 1]))
+        return undefined;
+    if (!/^url\(/i.test(line.slice(cursor, cursor + 4)))
+        return undefined;
+    return resolveUrlContent(line, cursor + 4);
+}
+function resolveUrlContent(line, cursor) {
+    let index = cursor;
+    while (index < line.length && /\s/.test(line[index]))
+        index += 1;
+    if (index === line.length)
+        return 'pending';
+    if (isAQuoteCharacter(line[index]))
+        return index;
+    return indexAfterUnquotedUrlContent(line, index);
+}
+function indexAfterUnquotedUrlContent(line, contentStart) {
+    let index = contentStart;
+    while (index < line.length) {
+        if (line[index] === '\\' && index + 1 < line.length) {
+            index += 2;
+            continue;
+        }
+        if (line[index] === ')')
+            return index + 1;
+        index += 1;
+    }
+    return 'contentOpen';
+}
+function markLinesFlaggedByTheEscapedLineBreakReading(lines, into) {
+    let state = NOTHING_IS_OPEN;
+    for (const [index, line] of lines.entries()) {
+        if (state.isInsideAnOpenComment)
+            into.add(index);
+        state = scanLineAcrossEscapedLineBreaksAndUrls(line, state);
+    }
+}
+const NOTHING_IS_OPEN = {
+    isInsideAnOpenComment: false,
+    urlCarry: 'none',
+    openStringQuote: undefined,
+};
+const STILL_INSIDE_AN_OPEN_COMMENT = {
+    ...NOTHING_IS_OPEN,
+    isInsideAnOpenComment: true,
+};
+function scanLineAcrossEscapedLineBreaksAndUrls(line, state) {
+    if (state.openStringQuote !== undefined) {
+        return resumeAnOpenStringCarriedIntoThisLine(line, state.isInsideAnOpenComment, state.openStringQuote);
+    }
+    const cursor = resumeUrlCarry(line, state.urlCarry);
+    if (typeof cursor === 'string')
+        return { ...NOTHING_IS_OPEN, urlCarry: cursor };
+    return scanFromStartOfLine(line, state.isInsideAnOpenComment, cursor);
+}
+function resumeAnOpenStringCarriedIntoThisLine(line, isInsideAnOpenComment, openStringQuote) {
+    const outcome = scanAPossiblyContinuedStringLiteral(line, -1, openStringQuote);
+    if (outcome.kind === 'continuesAcrossAnEscapedLineBreak') {
+        return { ...NOTHING_IS_OPEN, isInsideAnOpenComment, openStringQuote };
+    }
+    if (outcome.kind === 'doesNotClose') {
+        return { ...NOTHING_IS_OPEN, isInsideAnOpenComment };
+    }
+    return scanFromStartOfLine(line, isInsideAnOpenComment, outcome.indexAfter);
+}
+function stringStep(outcome, endOfLine) {
+    if (outcome.kind === 'closes')
+        return outcome.indexAfter;
+    if (outcome.kind === 'continuesAcrossAnEscapedLineBreak')
+        return undefined;
+    return endOfLine;
+}
+function scanFromStartOfLine(line, wasInsideAnOpenComment, cursor) {
+    let isInsideAnOpenComment = wasInsideAnOpenComment;
+    let index = cursor;
+    while (index < line.length) {
+        if (isInsideAnOpenComment) {
+            const closerIndex = line.indexOf('*/', index);
+            if (closerIndex === -1)
+                return STILL_INSIDE_AN_OPEN_COMMENT;
+            isInsideAnOpenComment = false;
+            index = closerIndex + 2;
+            continue;
+        }
+        const urlLookup = tryToSkipAnUnquotedUrlToken(line, index);
+        if (urlLookup !== undefined) {
+            if (typeof urlLookup === 'string')
+                return { ...NOTHING_IS_OPEN, urlCarry: urlLookup };
+            index = urlLookup;
+            continue;
+        }
+        const character = line[index];
+        if (isAQuoteCharacter(character)) {
+            const outcome = scanAPossiblyContinuedStringLiteral(line, index, character);
+            const target = stringStep(outcome, line.length);
+            if (target === undefined)
+                return { ...NOTHING_IS_OPEN, openStringQuote: character };
+            index = target;
+            continue;
+        }
+        if (line.startsWith('/*', index)) {
+            isInsideAnOpenComment = true;
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return { ...NOTHING_IS_OPEN, isInsideAnOpenComment };
+}
+function scanAPossiblyContinuedStringLiteral(line, quoteIndex, quote) {
+    let cursor = quoteIndex + 1;
+    while (cursor < line.length) {
+        if (line[cursor] === '\\') {
+            if (isAnEscapedLineBreakAtEndOfLine(line, cursor)) {
+                return { kind: 'continuesAcrossAnEscapedLineBreak' };
+            }
+            cursor += 2;
+            continue;
+        }
+        if (line[cursor] === quote)
+            return { kind: 'closes', indexAfter: cursor + 1 };
+        cursor += 1;
+    }
+    return { kind: 'doesNotClose' };
+}
+function isAnEscapedLineBreakAtEndOfLine(line, cursor) {
+    if (cursor === line.length - 1)
+        return true;
+    return cursor === line.length - 2 && line[cursor + 1] === '\r';
+}

package/dist/lib/theming/neutral.js

@@ -68,7 +68,7 @@ export function neutralRcsFormula(step, literals) {
     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)`;
+    return `oklch(from var(--nave-color-tint) ${roundTo(found.l, 4)} ${roundTo(found.c, 4)} h / 1)`;
 }
 function roundTo(n, d) {
     const f = 10 ** d;

package/dist/lib/theming/seed-channel-split.js

@@ -1,7 +1,13 @@
 import { clamp01 } from "./seed-refusal.js";
-const CSS_WHITESPACE_EDGES = /^[ \t\n\r\f]+|[ \t\n\r\f]+$/g;
+const CSS_WHITESPACE_CHARS = ' \t\n\r\f';
 function cssTrim(text) {
-    return text.replaceAll(CSS_WHITESPACE_EDGES, '');
+    let start = 0;
+    let end = text.length;
+    while (start < end && CSS_WHITESPACE_CHARS.includes(text[start]))
+        start += 1;
+    while (end > start && CSS_WHITESPACE_CHARS.includes(text[end - 1]))
+        end -= 1;
+    return text.slice(start, end);
 }
 const CSS_NUMBER = /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 export function readNumericToken(text) {
@@ -22,7 +28,6 @@ function parseAlphaToken(token) {
         return clamp01(readNumericToken(t.slice(0, -1)) / 100);
     return clamp01(readNumericToken(t));
 }
-const CSS_WHITESPACE_CHARS = ' \t\n\r\f';
 function splitTopLevel(text, isSeparator) {
     const tokens = [];
     let current = '';

package/dist/lib/validate.js

@@ -10,11 +10,25 @@ export function detectSourceKind(filePath) {
         return 'json';
     return undefined;
 }
-const DECLARED_CUSTOM_PROPERTY_RE = /(--[a-zA-Z0-9-]+)\s*:/g;
-const CSS_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+const DECLARED_CUSTOM_PROPERTY_RE = /(?<![\w\u{80}-\u{10FFFF}-])(--[a-zA-Z0-9-]+)\s*:/gu;
+function stripCssComments(css) {
+    let kept = '';
+    let from = 0;
+    for (;;) {
+        const open = css.indexOf('/*', from);
+        if (open === -1)
+            break;
+        const close = css.indexOf('*/', open + 2);
+        if (close === -1)
+            break;
+        kept += css.slice(from, open);
+        from = close + 2;
+    }
+    return kept + css.slice(from);
+}
 export function scanDeclaredCustomProperties(css) {
     const found = new Set();
-    const declarations = css.replaceAll(CSS_COMMENT_RE, '');
+    const declarations = stripCssComments(css);
     for (const match of declarations.matchAll(DECLARED_CUSTOM_PROPERTY_RE))
         found.add(match[1]);
     return found;

package/dist/palette-record.json

@@ -2,88 +2,88 @@
   "aboutThisFile": "This file is a resolved palette record: what this build produced for every semantic colour slot, in both schemes. It is not a DTCG 2025.10 document, and it is not meant to be read by a DTCG 2025.10 tool, because its keys are flat dotted names and most of its values are relative-colour-syntax strings, neither of which that format expresses. The token document is tokens.json, shipped beside it.",
   "color.surface.base.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)"
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)"
   },
   "color.surface.base.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
   },
   "color.surface.raised.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)"
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)"
   },
   "color.surface.raised.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.225 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.225 0.0067 h / 1)"
   },
   "color.surface.overlay.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)"
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)"
   },
   "color.surface.overlay.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.27 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.27 0.0067 h / 1)"
   },
   "color.surface.sunken.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.985 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.985 0.0067 h / 1)"
   },
   "color.surface.sunken.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.12 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.12 0.0067 h / 1)"
   },
   "color.surface.inverse.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
   },
   "color.surface.inverse.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1)"
   },
   "color.content.primary.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
   },
   "color.content.primary.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1)"
   },
   "color.content.secondary.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.37 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1)"
   },
   "color.content.secondary.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)"
   },
   "color.content.tertiary.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)",
     "$description": "Placeholder and hint text only."
   },
   "color.content.tertiary.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.72 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.72 0.0067 h / 1)",
     "$description": "Placeholder and hint text only."
   },
   "color.content.disabled.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)",
     "$description": "Text inside a disabled interactive component."
   },
   "color.content.disabled.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.37 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1)",
     "$description": "Text inside a disabled interactive component."
   },
   "color.content.inverse.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1)",
     "$description": "Declared foreground for surface.inverse."
   },
   "color.content.inverse.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)",
     "$description": "Declared foreground for surface.inverse."
   },
   "color.content.link.light": {
@@ -98,39 +98,39 @@
   },
   "color.border.default.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.905 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.905 0.0067 h / 1)",
     "$description": "Decorative dividers and card edges."
   },
   "color.border.default.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.37 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1)",
     "$description": "Decorative dividers and card edges."
   },
   "color.border.strong.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.72 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.72 0.0067 h / 1)"
   },
   "color.border.strong.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)"
   },
   "color.border.control.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.59 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.59 0.0067 h / 1)",
     "$description": "Identifying boundary for a control (inputs, form boundaries, and the secondary action control)."
   },
   "color.border.control.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.59 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.59 0.0067 h / 1)",
     "$description": "Identifying boundary for a control (inputs, form boundaries, and the secondary action control)."
   },
   "color.border.disabled.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.94 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.94 0.0067 h / 1)"
   },
   "color.border.disabled.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.27 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.27 0.0067 h / 1)"
   },
   "color.border.focus.light": {
     "$type": "color",
@@ -166,19 +166,19 @@
   },
   "color.on-action.primary.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)"
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)"
   },
   "color.on-action.primary.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
   },
   "color.action.secondary.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1)"
   },
   "color.action.secondary.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.27 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.27 0.0067 h / 1)"
   },
   "color.feedback.danger.light": {
     "$type": "color",
@@ -202,92 +202,92 @@
   },
   "color.on-feedback.danger.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)",
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)",
     "$description": "Declared foreground for the solid feedback.danger background."
   },
   "color.on-feedback.danger.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)",
     "$description": "Declared foreground for the solid feedback.danger background."
   },
   "color.feedback.warning.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)",
     "$description": "Solid-background role for a warning state (shared tinted-neutral family)."
   },
   "color.feedback.warning.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)",
     "$description": "Solid-background role for a warning state (shared tinted-neutral family)."
   },
   "color.feedback.warning.foreground.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)",
     "$description": "Foreground role for warning text and icons."
   },
   "color.feedback.warning.foreground.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)",
     "$description": "Foreground role for warning text and icons."
   },
   "color.on-feedback.warning.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)"
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)"
   },
   "color.on-feedback.warning.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
   },
   "color.feedback.success.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)",
     "$description": "Alias of feedback.warning (shared tinted-neutral family)."
   },
   "color.feedback.success.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)",
     "$description": "Alias of feedback.warning (shared tinted-neutral family)."
   },
   "color.feedback.success.foreground.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)"
   },
   "color.feedback.success.foreground.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)"
   },
   "color.on-feedback.success.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)"
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)"
   },
   "color.on-feedback.success.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
   },
   "color.feedback.info.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)",
     "$description": "Alias of feedback.warning (shared tinted-neutral family)."
   },
   "color.feedback.info.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)",
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)",
     "$description": "Alias of feedback.warning (shared tinted-neutral family)."
   },
   "color.feedback.info.foreground.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1)"
   },
   "color.feedback.info.foreground.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1)"
   },
   "color.on-feedback.info.light": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 1 0 h)"
+    "$value": "oklch(from var(--nave-color-tint) 1 0 h / 1)"
   },
   "color.on-feedback.info.dark": {
     "$type": "color",
-    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h)"
+    "$value": "oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1)"
   }
 }

package/dist/tokens.css

@@ -216,43 +216,43 @@
   }
 
   @property --nave-layer-base {
-    syntax: '<number>';
+    syntax: '<integer>';
     inherits: true;
     initial-value: 0;
   }
 
   @property --nave-layer-dropdown {
-    syntax: '<number>';
+    syntax: '<integer>';
     inherits: true;
     initial-value: 100;
   }
 
   @property --nave-layer-sticky {
-    syntax: '<number>';
+    syntax: '<integer>';
     inherits: true;
     initial-value: 200;
   }
 
   @property --nave-layer-overlay {
-    syntax: '<number>';
+    syntax: '<integer>';
     inherits: true;
     initial-value: 300;
   }
 
   @property --nave-layer-modal {
-    syntax: '<number>';
+    syntax: '<integer>';
     inherits: true;
     initial-value: 400;
   }
 
   @property --nave-layer-toast {
-    syntax: '<number>';
+    syntax: '<integer>';
     inherits: true;
     initial-value: 500;
   }
 
   @property --nave-layer-tooltip {
-    syntax: '<number>';
+    syntax: '<integer>';
     inherits: true;
     initial-value: 600;
   }
@@ -395,39 +395,39 @@
     color-scheme: light dark;
     /* Tint seed: Changing this changes everything Nave derives from it. The contrast of the resulting palette follows from what you set, and checking it is yours. */
     --nave-color-tint: oklch(0.7859 0.1316 186.17);
-    --nave-color-surface-base: light-dark(oklch(from var(--nave-color-tint) 1 0 h), oklch(from var(--nave-color-tint) 0.18 0.0067 h));
-    --nave-color-surface-raised: light-dark(oklch(from var(--nave-color-tint) 1 0 h), oklch(from var(--nave-color-tint) 0.225 0.0067 h));
-    --nave-color-surface-overlay: light-dark(oklch(from var(--nave-color-tint) 1 0 h), oklch(from var(--nave-color-tint) 0.27 0.0067 h));
-    --nave-color-surface-sunken: light-dark(oklch(from var(--nave-color-tint) 0.985 0.0067 h), oklch(from var(--nave-color-tint) 0.12 0.0067 h));
-    --nave-color-surface-inverse: light-dark(oklch(from var(--nave-color-tint) 0.18 0.0067 h), oklch(from var(--nave-color-tint) 0.965 0.0067 h));
-    --nave-color-content-primary: light-dark(oklch(from var(--nave-color-tint) 0.18 0.0067 h), oklch(from var(--nave-color-tint) 0.965 0.0067 h));
-    --nave-color-content-secondary: light-dark(oklch(from var(--nave-color-tint) 0.37 0.0067 h), oklch(from var(--nave-color-tint) 0.835 0.0067 h));
-    --nave-color-content-tertiary: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h), oklch(from var(--nave-color-tint) 0.72 0.0067 h));
-    --nave-color-content-disabled: light-dark(oklch(from var(--nave-color-tint) 0.835 0.0067 h), oklch(from var(--nave-color-tint) 0.37 0.0067 h));
-    --nave-color-content-inverse: light-dark(oklch(from var(--nave-color-tint) 0.965 0.0067 h), oklch(from var(--nave-color-tint) 0.18 0.0067 h));
+    --nave-color-surface-base: 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-surface-raised: light-dark(oklch(from var(--nave-color-tint) 1 0 h / 1), oklch(from var(--nave-color-tint) 0.225 0.0067 h / 1));
+    --nave-color-surface-overlay: light-dark(oklch(from var(--nave-color-tint) 1 0 h / 1), oklch(from var(--nave-color-tint) 0.27 0.0067 h / 1));
+    --nave-color-surface-sunken: light-dark(oklch(from var(--nave-color-tint) 0.985 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.12 0.0067 h / 1));
+    --nave-color-surface-inverse: light-dark(oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1));
+    --nave-color-content-primary: light-dark(oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1));
+    --nave-color-content-secondary: light-dark(oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1));
+    --nave-color-content-tertiary: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.72 0.0067 h / 1));
+    --nave-color-content-disabled: light-dark(oklch(from var(--nave-color-tint) 0.835 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1));
+    --nave-color-content-inverse: light-dark(oklch(from var(--nave-color-tint) 0.965 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.18 0.0067 h / 1));
     --nave-color-content-link: light-dark(oklch(0.47 0.0748 186.17), oklch(0.835 0.123 186.17));
-    --nave-color-border-default: light-dark(oklch(from var(--nave-color-tint) 0.905 0.0067 h), oklch(from var(--nave-color-tint) 0.37 0.0067 h));
-    --nave-color-border-strong: light-dark(oklch(from var(--nave-color-tint) 0.72 0.0067 h), oklch(from var(--nave-color-tint) 0.47 0.0067 h));
-    --nave-color-border-control: light-dark(oklch(from var(--nave-color-tint) 0.59 0.0067 h), oklch(from var(--nave-color-tint) 0.59 0.0067 h));
-    --nave-color-border-disabled: light-dark(oklch(from var(--nave-color-tint) 0.94 0.0067 h), oklch(from var(--nave-color-tint) 0.27 0.0067 h));
+    --nave-color-border-default: light-dark(oklch(from var(--nave-color-tint) 0.905 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.37 0.0067 h / 1));
+    --nave-color-border-strong: light-dark(oklch(from var(--nave-color-tint) 0.72 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.47 0.0067 h / 1));
+    --nave-color-border-control: light-dark(oklch(from var(--nave-color-tint) 0.59 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.59 0.0067 h / 1));
+    --nave-color-border-disabled: light-dark(oklch(from var(--nave-color-tint) 0.94 0.0067 h / 1), oklch(from var(--nave-color-tint) 0.27 0.0067 h / 1));
     --nave-color-border-focus: light-dark(oklch(0.59 0.0939 186.17), oklch(0.59 0.0939 186.17));
     --nave-color-action-primary: light-dark(oklch(0.47 0.0748 186.17), oklch(0.835 0.123 186.17));
     --nave-color-action-primary-hover: light-dark(oklch(0.37 0.0589 186.17), oklch(0.905 0.1106 186.17));
     --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), oklch(from var(--nave-color-tint) 0.18 0.0067 h));
-    --nave-color-action-secondary: light-dark(oklch(from var(--nave-color-tint) 0.965 0.0067 h), oklch(from var(--nave-color-tint) 0.27 0.0067 h));
+    --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-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), oklch(from var(--nave-color-tint) 0.18 0.0067 h));
+    --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));
     /* Feedback tokens: 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. */
-    --nave-color-feedback-warning: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h), oklch(from var(--nave-color-tint) 0.835 0.0067 h));
-    --nave-color-feedback-warning-foreground: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h), oklch(from var(--nave-color-tint) 0.835 0.0067 h));
-    --nave-color-on-feedback-warning: light-dark(oklch(from var(--nave-color-tint) 1 0 h), oklch(from var(--nave-color-tint) 0.18 0.0067 h));
-    --nave-color-feedback-success: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h), oklch(from var(--nave-color-tint) 0.835 0.0067 h));
-    --nave-color-feedback-success-foreground: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h), oklch(from var(--nave-color-tint) 0.835 0.0067 h));
-    --nave-color-on-feedback-success: light-dark(oklch(from var(--nave-color-tint) 1 0 h), oklch(from var(--nave-color-tint) 0.18 0.0067 h));
-    --nave-color-feedback-info: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h), oklch(from var(--nave-color-tint) 0.835 0.0067 h));
-    --nave-color-feedback-info-foreground: light-dark(oklch(from var(--nave-color-tint) 0.47 0.0067 h), oklch(from var(--nave-color-tint) 0.835 0.0067 h));
-    --nave-color-on-feedback-info: light-dark(oklch(from var(--nave-color-tint) 1 0 h), oklch(from var(--nave-color-tint) 0.18 0.0067 h));
+    --nave-color-feedback-warning: 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-warning-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-warning: 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-feedback-success: 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-success-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-success: 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-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));
   }
 }

package/dist/tokens.d.ts

@@ -2,8 +2,11 @@
 
 /** The DTCG 2025.10 token set as a typed const object (e.g. `--nave-font-size-md`).
  *  Keys are CSS custom property names. The semantic colour layer
- *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css`
- *  and is not part of this export.
+ *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css` and is
+ *  not part of this object; its property NAMES are typed separately as
+ *  `ColorPropertyName`, and its VALUES are reachable only through CSS (e.g.
+ *  `var(--nave-color-action-primary)`): the browser resolves each one for the
+ *  active colour scheme, and the neutral-derived ones also follow the tint.
  */
 export declare const tokens: {
   '--nave-font-family-base': string
@@ -88,3 +91,44 @@ export declare const tokens: {
 
 export declare type TokenName = keyof typeof tokens
 export declare type TokenValue = typeof tokens[TokenName]
+
+/** Every `--nave-color-*` custom property the semantic colour layer emits: names
+ *  only, no value (see the doc comment above `tokens` for where the values live).
+ *  Disjoint from `TokenName` — a consumer who wants both writes
+ *  `TokenName | ColorPropertyName`.
+ */
+export declare type ColorPropertyName =
+  | '--nave-color-action-primary'
+  | '--nave-color-action-primary-active'
+  | '--nave-color-action-primary-hover'
+  | '--nave-color-action-secondary'
+  | '--nave-color-border-control'
+  | '--nave-color-border-default'
+  | '--nave-color-border-disabled'
+  | '--nave-color-border-focus'
+  | '--nave-color-border-strong'
+  | '--nave-color-content-disabled'
+  | '--nave-color-content-inverse'
+  | '--nave-color-content-link'
+  | '--nave-color-content-primary'
+  | '--nave-color-content-secondary'
+  | '--nave-color-content-tertiary'
+  | '--nave-color-feedback-danger'
+  | '--nave-color-feedback-danger-foreground'
+  | '--nave-color-feedback-info'
+  | '--nave-color-feedback-info-foreground'
+  | '--nave-color-feedback-success'
+  | '--nave-color-feedback-success-foreground'
+  | '--nave-color-feedback-warning'
+  | '--nave-color-feedback-warning-foreground'
+  | '--nave-color-on-action-primary'
+  | '--nave-color-on-feedback-danger'
+  | '--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'

package/dist/tokens.js

@@ -3,8 +3,11 @@
 
 /** The DTCG 2025.10 token set as a typed const object (e.g. `--nave-font-size-md`).
  *  Keys are CSS custom property names. The semantic colour layer
- *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css`
- *  and is not part of this export.
+ *  (`--nave-color-*`) ships as CSS custom properties in `dist/tokens.css` and is
+ *  not part of this object; its property NAMES are typed separately as
+ *  `ColorPropertyName`, and its VALUES are reachable only through CSS (e.g.
+ *  `var(--nave-color-action-primary)`): the browser resolves each one for the
+ *  active colour scheme, and the neutral-derived ones also follow the tint.
  */
 export const tokens = {
   '--nave-font-family-base': "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navecss/tokens",
-  "version": "0.1.1",
+  "version": "0.2.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",
@@ -53,7 +53,7 @@
   "devDependencies": {
     "@types/node": "^26.6.2",
     "@vitest/coverage-v8": "5.0.1",
-    "prettier": "3.9.8",
+    "prettier": "3.9.9",
     "typescript": "6.0.3",
     "vitest": "5.0.1"
   },