@navecss/tokens 0.1.0

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

@@ -0,0 +1,103 @@
+import { loadShippedTokensSource } from "./tokens-source.js";
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPairClass(value) {
+    return value === 'text' || value === 'non-text';
+}
+function flattenSubjectPartners(subject, partners) {
+    if (!Array.isArray(partners)) {
+        throw new TypeError(`Adjacency declaration: adjacency["${subject}"] in @navecss/tokens' own bundled tokens.json is not an array of partners.`);
+    }
+    return partners.map((partner) => {
+        if (!isRecord(partner) || typeof partner.against !== 'string' || !isPairClass(partner.class)) {
+            throw new TypeError(`Adjacency declaration: adjacency["${subject}"] in @navecss/tokens' own bundled tokens.json carries a malformed partner entry.`);
+        }
+        return { subject, against: partner.against, class: partner.class };
+    });
+}
+export function materializeAdjacency(source) {
+    if (!isRecord(source)) {
+        throw new TypeError("Adjacency declaration: @navecss/tokens' own bundled tokens.json did not parse to an object.");
+    }
+    const extensions = source.$extensions;
+    const theming = isRecord(extensions) ? extensions['dev.navecss.theming'] : undefined;
+    const declared = isRecord(theming) ? theming.adjacency : undefined;
+    if (!isRecord(declared)) {
+        throw new Error("Adjacency declaration: @navecss/tokens' own bundled tokens.json carries no $extensions.dev.navecss.theming.adjacency block.");
+    }
+    const result = [];
+    for (const [subject, partners] of Object.entries(declared)) {
+        if (subject === 'comment')
+            continue;
+        result.push(...flattenSubjectPartners(subject, partners));
+    }
+    return result;
+}
+export const ADJACENCY = materializeAdjacency(loadShippedTokensSource());
+export const ADJACENCY_EXCLUSIONS = {
+    'content.disabled': 'disabled text: excluded from the checked pair set, and the exclusion is worded ' +
+        'over a component that is INACTIVE. It does not reach an aria-disabled element ' +
+        'that is still operable and still fires on activation; that case is not excluded ' +
+        'and is not answered here.',
+    'border.disabled': 'disabled control: excluded from the checked pair set, and the exclusion is worded ' +
+        'over a component that is INACTIVE. It does not reach an aria-disabled element ' +
+        'that is still operable and still fires on activation; that case is not excluded ' +
+        '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.',
+};
+export const ADJACENCY_OPEN = {
+    'border.strong': 'open: whether this border can identify a control, and therefore whether its ' +
+        'contrast is checked or it is decorative, is an open question this project has ' +
+        'not settled and is not decided here',
+    'feedback.warning.foreground': 'open, not yet excluded or covered: whether this family gains a standalone ' +
+        'foreground role of its own is unresolved and is not decided here',
+    'feedback.success.foreground': 'open — see feedback.warning.foreground',
+    'feedback.info.foreground': 'open — see feedback.warning.foreground',
+};
+function assertEscapesAreDisjointFromDeclaration(mentioned, exclusions, open) {
+    for (const [record, name] of [
+        [exclusions, 'ADJACENCY_EXCLUSIONS'],
+        [open, 'ADJACENCY_OPEN'],
+    ]) {
+        const both = Object.keys(record).filter((slot) => mentioned.has(slot));
+        if (both.length > 0) {
+            const listed = both.map((slot) => `"${slot}"`).join(', ');
+            throw new Error(`Adjacency escape-record conflict: ${listed} is declared in the adjacency set AND ` +
+                `listed in ${name}. A slot is one or the other: remove the declaration, or remove ` +
+                'the listing that the declaration has already answered.');
+        }
+    }
+}
+export function assertNoOrphanedSemanticSlot(slots, adjacency = ADJACENCY, exclusions = ADJACENCY_EXCLUSIONS, open = ADJACENCY_OPEN) {
+    const mentioned = new Set();
+    for (const pair of adjacency) {
+        mentioned.add(pair.subject);
+        mentioned.add(pair.against);
+    }
+    assertEscapesAreDisjointFromDeclaration(mentioned, exclusions, open);
+    const openSlots = [];
+    const excludedSlots = [];
+    for (const slot of slots) {
+        if (mentioned.has(slot))
+            continue;
+        if (Object.hasOwn(exclusions, slot)) {
+            excludedSlots.push(slot);
+            continue;
+        }
+        if (Object.hasOwn(open, slot)) {
+            openSlots.push(slot);
+            continue;
+        }
+        throw new Error(`Adjacency coverage: the semantic slot "${slot}" carries no adjacency declaration, so ` +
+            'no contrast pair in this build touches it at all. Declare its legal partners in ' +
+            'tokens.json, under $extensions.dev.navecss.theming.adjacency. The two escape records ' +
+            'are not alternatives you may take here: a slot is excluded only where the project has ' +
+            'already settled that its contrast is not checked, and it is marked open only where ' +
+            'that question is genuinely unresolved and is being counted as open. If you believe ' +
+            'this slot belongs in one of those, open an issue rather than adding it to either ' +
+            'record.');
+    }
+    return { open: openSlots, excluded: excludedSlots };
+}

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

@@ -0,0 +1,17 @@
+import { type Adjacency } from './adjacency-source.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"];
+export type CoverageCategory = (typeof MINIMUM_COVERAGE_CATEGORIES)[number];
+export declare function coverageCategories(adjacency?: readonly Adjacency[]): Record<CoverageCategory, boolean>;
+export declare function assertCoverageFloor(adjacency?: readonly Adjacency[]): void;
+export declare function shippedSurfaces(slots?: readonly string[]): readonly string[];
+export declare function assertShippedSurfaceCountProvenance(surfaces?: readonly string[]): void;
+export interface ForbiddenAdjacencyRule {
+    entry: number;
+    description: string;
+    forbids: (subject: string, against: string) => boolean;
+}
+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;

package/dist/lib/theming/adjacency.js

@@ -0,0 +1,133 @@
+import { ADJACENCY } from "./adjacency-source.js";
+import { SEMANTIC_SLOTS } from "./semantics.js";
+export { ADJACENCY, ADJACENCY_EXCLUSIONS, ADJACENCY_OPEN, assertNoOrphanedSemanticSlot, } from "./adjacency-source.js";
+const MINIMUM_COVERAGE_CATEGORIES = [
+    'contentOnSurface',
+    'inversePair',
+    'onActionOnAction',
+    'textOnFeedback',
+    'sunken',
+    'borderControl',
+    'borderFocus',
+    'filledAction',
+    'filledFeedback',
+];
+export function coverageCategories(adjacency = ADJACENCY) {
+    return {
+        contentOnSurface: adjacency.some((a) => a.subject.startsWith('content.') && a.against.startsWith('surface.')),
+        inversePair: adjacency.some((a) => a.subject === 'content.inverse' && a.against === 'surface.inverse'),
+        onActionOnAction: adjacency.some((a) => a.subject === 'on-action.primary'),
+        textOnFeedback: adjacency.some((a) => a.subject.startsWith('on-feedback.')),
+        sunken: adjacency.some((a) => a.against === 'surface.sunken'),
+        borderControl: adjacency.some((a) => a.subject === 'border.control'),
+        borderFocus: adjacency.some((a) => a.subject === 'border.focus'),
+        filledAction: adjacency.some((a) => a.subject === 'action.primary' && a.class === 'non-text'),
+        filledFeedback: adjacency.some((a) => a.subject === 'feedback.danger' && a.class === 'non-text'),
+    };
+}
+const COVERAGE_FLOOR_VIOLATION_REASON = 'missing from the declared adjacency set. This set has a required minimum: every ' +
+    'category in it keeps at least one declared pair, so that dropping coverage is a ' +
+    'visible decision rather than a quiet one. Restore the declaration. If you believe ' +
+    'the category should no longer be required, that is a decision for the maintainers ' +
+    'and not a change to make here: open an issue naming the category and why, and ' +
+    'leave the removal out of the pull request until that issue is answered.';
+export function assertCoverageFloor(adjacency = ADJACENCY) {
+    const coverage = coverageCategories(adjacency);
+    for (const category of MINIMUM_COVERAGE_CATEGORIES) {
+        if (!coverage[category]) {
+            throw new Error(`Adjacency coverage violation: the required coverage category "${category}" is ${COVERAGE_FLOOR_VIOLATION_REASON}`);
+        }
+    }
+}
+const SHIPPED_SURFACE_PROVENANCE = {
+    count: 5,
+    citation: 'Two documented contrast requirements quantify over the shipped surfaces: ' +
+        'border.control against every surface.* a control sits on, and border.focus ' +
+        'against every shipped surface.* and against the action.* fills it can land on. ' +
+        'This record pins the surface.* half of both and nothing else: the five surface ' +
+        'slots the shipped build declares (surface.base, surface.raised, surface.overlay, ' +
+        'surface.sunken, surface.inverse). The border.focus half is unconditioned where ' +
+        "border.control's is conditioned, which is deliberate and stricter. The action.* " +
+        'half is deliberately never declared, because a focusable slot may not be declared ' +
+        'adjacent to an action fill.',
+};
+export function shippedSurfaces(slots = SEMANTIC_SLOTS) {
+    return slots.filter((slot) => slot.startsWith('surface.'));
+}
+export function assertShippedSurfaceCountProvenance(surfaces = shippedSurfaces()) {
+    if (surfaces.length !== SHIPPED_SURFACE_PROVENANCE.count) {
+        throw new Error(`Shipped surface provenance: ${surfaces.length} shipped surface(s) ` +
+            `(${surfaces.join(', ')}) no longer match the frozen count ` +
+            `${SHIPPED_SURFACE_PROVENANCE.count}. ${SHIPPED_SURFACE_PROVENANCE.citation} ` +
+            'Review whether border.control and border.focus need a matching new pair. This ' +
+            'coverage list is the minimum set of pairs this project documents a contrast ' +
+            'floor for, so narrowing it changes what is documented and is not yours to ' +
+            'change here: open an issue. Bumping the count to make the build pass is not ' +
+            'the route.');
+    }
+}
+const isFillSlot = (slot, family) => slot.startsWith(family) && !slot.endsWith('.foreground');
+const FORBIDDEN_ADJACENCY_RULES = [
+    {
+        entry: 1,
+        description: '`content.secondary` adjacent to `surface.inverse`',
+        forbids: (subject, against) => subject === 'content.secondary' && against === 'surface.inverse',
+    },
+    {
+        entry: 2,
+        description: 'any `content.*` adjacent to a feedback FILL',
+        forbids: (subject, against) => subject.startsWith('content.') && isFillSlot(against, 'feedback.'),
+    },
+    {
+        entry: 3,
+        description: 'any filled `action.*` or `feedback.*` adjacent to `surface.inverse`',
+        forbids: (subject, against) => (isFillSlot(subject, 'action.') || isFillSlot(subject, 'feedback.')) &&
+            against === 'surface.inverse',
+    },
+    {
+        entry: 4,
+        description: '`content.inverse` adjacent to `action.secondary`',
+        forbids: (subject, against) => subject === 'content.inverse' && against === 'action.secondary',
+    },
+];
+export function findForbiddenAdjacencyRule(subject, against) {
+    return FORBIDDEN_ADJACENCY_RULES.find((rule) => rule.forbids(subject, against) || rule.forbids(against, subject));
+}
+const FORBIDDEN_ADJACENCY_REASON = 'The rules in this file record decisions about which colour ' +
+    'pairs this design system will declare and test; they are not a list to edit 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.';
+export function assertNoForbiddenAdjacency(adjacency = ADJACENCY) {
+    for (const pair of adjacency) {
+        const rule = findForbiddenAdjacencyRule(pair.subject, pair.against);
+        if (rule) {
+            throw new Error(`Adjacency rule violation (rule ${rule.entry}): the pair (${pair.subject}, ` +
+                `${pair.against}) is declared, and rule ${rule.entry} forbids it: ` +
+                `${rule.description}. ${FORBIDDEN_ADJACENCY_REASON}`);
+        }
+    }
+}
+const FOCUSABLE_SLOTS = new Set(['border.focus']);
+const isActionFill = (slot) => slot.startsWith('action.');
+const FOCUSABLE_ADJACENT_TO_ACTION_FILL_REASON = 'A focus indicator is drawn offset outside the control ' +
+    "it belongs to, so it lands on whatever sits behind that control, not on the control's " +
+    'own fill; a declaration putting one against an action fill therefore describes a ' +
+    'focusable element sitting ON that fill, which is a composition rather than a colour ' +
+    'pairing. 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.';
+export function assertNoFocusableAdjacentToActionFill(adjacency = ADJACENCY) {
+    for (const pair of adjacency) {
+        const isFocusableSubject = FOCUSABLE_SLOTS.has(pair.subject);
+        const isFocusableAgainst = FOCUSABLE_SLOTS.has(pair.against);
+        if ((isFocusableSubject && isActionFill(pair.against)) ||
+            (isFocusableAgainst && isActionFill(pair.subject))) {
+            const focusable = isFocusableSubject ? pair.subject : pair.against;
+            const fill = isFocusableSubject ? pair.against : pair.subject;
+            throw new Error(`Adjacency rule violation: the focusable slot "${focusable}" is declared adjacent ` +
+                `to the action fill "${fill}". ${FOCUSABLE_ADJACENT_TO_ACTION_FILL_REASON}`);
+        }
+    }
+}

package/dist/lib/theming/build-record.d.ts

@@ -0,0 +1,45 @@
+import type { MeasuredOpenSlots } from './adjacency.ts';
+import type { Oklch } from './color-math.ts';
+import type { PipelineResult, Seeds } from './pipeline.ts';
+import type { SeedInput, SeedInputs } from './seed-input.ts';
+declare const TARGET_GAMUT: {
+    readonly gamut: "srgb";
+    readonly assumption: string;
+};
+interface SeedBuildRecord {
+    input: SeedInput;
+    resolved: Oklch;
+    intensityScalar: number;
+    sLightness: number;
+    substitutions: {
+        lightnessBandClamped: {
+            applied: boolean;
+            reason?: string | undefined;
+        };
+        normalized: {
+            applied: boolean;
+            reason?: string | undefined;
+        };
+    };
+    achromatic: boolean;
+    seedColourAppearsInRamp: boolean;
+    seedColourStep?: number | undefined;
+}
+export interface BuildRecord {
+    spec: string;
+    targetGamut: typeof TARGET_GAMUT;
+    seeds: Record<'danger' | 'primary', SeedBuildRecord>;
+    achromaticBranch: {
+        reason?: string | undefined;
+        seed?: Oklch | undefined;
+        selected: boolean;
+        substitutedSlots: readonly string[];
+    };
+    tint: {
+        hue: number;
+        source: 'declared-default' | 'primary-seed';
+    };
+    openAdjacencySlots?: MeasuredOpenSlots;
+}
+export declare function composeBuildRecord(seeds: Seeds, result: PipelineResult, openAdjacencySlots?: MeasuredOpenSlots, seedInputs?: SeedInputs): BuildRecord;
+export {};

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

@@ -0,0 +1,87 @@
+import { ACHROMATIC_BRANCH_SLOTS } from "./semantics.js";
+const TARGET_GAMUT = {
+    gamut: 'srgb',
+    assumption: 'sRGB is the target gamut, stated as an explicit assumption. Every generated ' +
+        'value is expressible in sRGB and no wide-gamut colour function is emitted. Wide-gamut ' +
+        '(display-p3) output is a deliberate v1 non-goal: a future wide-gamut output regenerates ' +
+        'the ramp rather than reusing this one.',
+};
+const NORMALIZED_REASON = 'seed chroma reduced at constant lightness and hue to bring it inside sRGB, once, at ' +
+    'ingest; naive per-channel clipping and any lightness-adjusting map are rejected';
+const MAPPED_TO_WHITE_REASON = 'seed lightness is at or above 1, where no sRGB colour has any chroma, so it was mapped ' +
+    'to white, once, at ingest, as CSS Color 4 gamut mapping does';
+const MAPPED_TO_BLACK_REASON = 'seed lightness is at or below 0, where no sRGB colour has any chroma, so it was mapped ' +
+    'to black, once, at ingest, as CSS Color 4 gamut mapping does';
+const BAND_CLAMP_REASON = 'the lightness used to compute the intensity scalar was clamped into the band [0.20, 0.90]; ' +
+    "the seed's own lightness, hue and the emitted ramp lightnesses are untouched";
+const ACHROMATIC_REASON = 'the primary seed carries exactly zero chroma, which is a legal input rather than an error ' +
+    'and selects the achromatic branch of the semantic mapping: the slots below are re-pointed ' +
+    'at the neutral ramp at the resolve-semantics stage';
+const SAME_COLOUR_TOLERANCE = 1e-4;
+function findSeedColourStep(seed, ramp) {
+    const found = ramp.steps.find((step) => Math.abs(step.l - seed.l) < SAME_COLOUR_TOLERANCE &&
+        Math.abs(step.c - seed.c) < SAME_COLOUR_TOLERANCE);
+    return found?.step;
+}
+function normalizedReason(normalization) {
+    switch (normalization) {
+        case 'chroma-reduced': {
+            return NORMALIZED_REASON;
+        }
+        case 'mapped-to-black': {
+            return MAPPED_TO_BLACK_REASON;
+        }
+        case 'mapped-to-white': {
+            return MAPPED_TO_WHITE_REASON;
+        }
+        default: {
+            return undefined;
+        }
+    }
+}
+function seedBuildRecord(input, record, ramp) {
+    const seedColourStep = findSeedColourStep(record.usedSeed, ramp);
+    return {
+        input,
+        resolved: record.usedSeed,
+        intensityScalar: record.s,
+        sLightness: record.sLightness,
+        substitutions: {
+            lightnessBandClamped: {
+                applied: record.bandClamped,
+                reason: record.bandClamped ? BAND_CLAMP_REASON : undefined,
+            },
+            normalized: {
+                applied: record.normalized,
+                reason: normalizedReason(record.normalization),
+            },
+        },
+        achromatic: record.achromatic,
+        seedColourAppearsInRamp: seedColourStep !== undefined,
+        seedColourStep,
+    };
+}
+export function composeBuildRecord(seeds, result, openAdjacencySlots, seedInputs = {}) {
+    const isBranch = result.records.achromaticBranch;
+    const primaryInput = seedInputs.primary ?? { form: 'oklch', value: seeds.primary };
+    const dangerInput = seedInputs.danger ?? { form: 'oklch', value: seeds.danger };
+    return {
+        spec: 'documented in this package\'s README ("Theming")',
+        targetGamut: TARGET_GAMUT,
+        seeds: {
+            primary: seedBuildRecord(primaryInput, result.records.primary, result.primaryRamp),
+            danger: seedBuildRecord(dangerInput, result.records.danger, result.dangerRamp),
+        },
+        achromaticBranch: {
+            reason: isBranch ? ACHROMATIC_REASON : undefined,
+            seed: isBranch ? result.records.primary.usedSeed : undefined,
+            selected: isBranch,
+            substitutedSlots: isBranch ? ACHROMATIC_BRANCH_SLOTS : [],
+        },
+        tint: {
+            hue: result.records.tintHue,
+            source: isBranch ? 'declared-default' : 'primary-seed',
+        },
+        ...(openAdjacencySlots !== undefined && { openAdjacencySlots }),
+    };
+}

package/dist/lib/theming/build-step.d.ts

@@ -0,0 +1,14 @@
+import type { OutputFile } from '../builder.ts';
+import type { Seeds } from './pipeline.ts';
+export interface ThemingBuildOptions {
+    distDir?: string;
+    env?: ReadonlyMap<number, number>;
+    seeds?: Seeds;
+    tokensSourcePaths?: readonly string[];
+}
+export interface ThemingComposition {
+    css: string;
+    files: OutputFile[];
+}
+export declare function composeThemingOutputs(options?: ThemingBuildOptions): ThemingComposition;
+export declare function withThemingLayer(outputs: readonly OutputFile[], options?: ThemingBuildOptions): OutputFile[];

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

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { collectDescriptionsFromSources } from "../dtcg-descriptions.js";
+import { assertCoverageFloor, assertNoFocusableAdjacentToActionFill, assertNoForbiddenAdjacency, assertNoOrphanedSemanticSlot, 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";
+import { assertDescriptionsAreClean, assertHarnessFramingIsClean, assertNoticeIsClean, assertNoticeIsEmitted, FEEDBACK_SHARED_IDENTITY_NOTICE, RETHEMING_NOTICE, } from "./copy-lint.js";
+import { buildCoreContractManifest } from "./core-source.js";
+import { SLOT_DESCRIPTIONS } from "./descriptions.js";
+import { emitCss } from "./emit.js";
+import { assertLadderOrder } from "./ladder.js";
+import { assertNeutralChromaCeilingWithinMargin } from "./neutral.js";
+import { assertOnStarShape } from "./on-star.js";
+import { composePaletteRecord } from "./palette-record.js";
+import { runPipeline } from "./pipeline.js";
+import { ADVERSARIAL_SEEDS, DEFAULT_ENV } from "./ramp.js";
+import { SEMANTIC_SLOTS } from "./semantics.js";
+import { SHIPPED_SEEDS } from "./shipped-seeds.js";
+import { TOKENS_JSON_PATH } from "./tokens-source.js";
+function runSourceGuards(tokensSourcePaths) {
+    assertNoForbiddenAdjacency();
+    assertNoFocusableAdjacentToActionFill();
+    assertCoverageFloor();
+    const orphanCheck = assertNoOrphanedSemanticSlot(SEMANTIC_SLOTS);
+    assertOnStarShape();
+    assertLadderOrder();
+    assertNoticeIsClean();
+    assertNoticeIsClean(FEEDBACK_SHARED_IDENTITY_NOTICE, 'Feedback notice');
+    assertHarnessFramingIsClean();
+    assertFloorProvenance();
+    assertNeutralChromaCeilingWithinMargin();
+    assertShippedSurfaceCountProvenance();
+    assertDescriptionsAreClean(SLOT_DESCRIPTIONS, ...collectDescriptionsFromSources(tokensSourcePaths));
+    return orphanCheck;
+}
+function runResultGuards(result) {
+    assertContrastFloors(runContrastHarness(result));
+    assertNoSameStepViolations(checkSameStepLint(result, 'nave'));
+}
+function contactSheetColumns(seeds, shipped, env) {
+    const columns = [
+        { name: 'teal (shipped default)', seed: seeds.primary, result: shipped },
+    ];
+    for (const { name, seed } of ADVERSARIAL_SEEDS) {
+        columns.push({ name, seed, result: runPipeline({ ...seeds, primary: seed }, {}, env) });
+    }
+    return columns;
+}
+const json = (value) => JSON.stringify(value, undefined, 2);
+export function composeThemingOutputs(options = {}) {
+    const { distDir = 'dist', env = DEFAULT_ENV, seeds = SHIPPED_SEEDS, tokensSourcePaths = [TOKENS_JSON_PATH], } = options;
+    const orphanCheck = runSourceGuards(tokensSourcePaths);
+    const result = runPipeline(seeds, {}, env);
+    runResultGuards(result);
+    const { css } = emitCss(result);
+    assertNoticeIsEmitted(css, FEEDBACK_SHARED_IDENTITY_NOTICE, 'Feedback notice');
+    assertNoticeIsEmitted(css, RETHEMING_NOTICE, 'Retheming notice');
+    return {
+        css,
+        files: [
+            {
+                destination: path.join(distDir, 'palette-record.json'),
+                content: json(composePaletteRecord(result)),
+            },
+            {
+                destination: path.join(distDir, 'core-contract.json'),
+                content: json(buildCoreContractManifest()),
+            },
+            {
+                destination: path.join(distDir, 'build-record.json'),
+                content: json(composeBuildRecord(seeds, result, orphanCheck.open)),
+            },
+            {
+                destination: path.join(distDir, 'contact-sheet.html'),
+                content: composeContactSheet(contactSheetColumns(seeds, result, env)).html,
+            },
+        ],
+    };
+}
+export function withThemingLayer(outputs, options = {}) {
+    const theming = composeThemingOutputs(options);
+    const cssName = `${path.sep}tokens.css`;
+    const withLayer = outputs.map((file) => file.destination.endsWith(cssName) || file.destination === 'tokens.css'
+        ? { ...file, content: `${file.content}\n${theming.css}` }
+        : file);
+    if (withLayer.every((file) => !file.content.includes('/* Nave theming'))) {
+        throw new Error('No composed tokens.css to append the semantic colour layer to — the theming layer ' +
+            'would be dropped silently. Open an issue rather than working around this check.');
+    }
+    return [...withLayer, ...theming.files];
+}

package/dist/lib/theming/color-math.d.ts

@@ -0,0 +1,33 @@
+export interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+}
+export interface LinearRgb {
+    r: number;
+    g: number;
+    b: number;
+}
+export interface Srgb {
+    r: number;
+    g: number;
+    b: number;
+}
+export declare function srgbToLinearRgb(rgb: Srgb): LinearRgb;
+export declare function oklchToSrgb(c: Oklch): Srgb;
+export declare function oklabToOklch(lab: {
+    a: number;
+    b: number;
+    l: number;
+}): Oklch;
+export declare function srgbToOklch(rgb: Srgb): Oklch;
+export declare function isOklchInGamut(c: Oklch): boolean;
+export declare function maxChroma(l: number, h: number, precision?: number): number;
+export type SeedNormalization = 'chroma-reduced' | 'mapped-to-black' | 'mapped-to-white' | 'none';
+export declare function normalizeSeed(seed: Oklch): {
+    normalization: SeedNormalization;
+    normalized: boolean;
+    seed: Oklch;
+};
+export declare function formatOklch(c: Oklch): string;
+export declare function contrastRatio(a: Oklch, b: Oklch): number;

package/dist/lib/theming/color-math.js

@@ -0,0 +1,125 @@
+function linearSrgbToOklab(rgb) {
+    const l = 0.4122214708 * rgb.r + 0.5363325363 * rgb.g + 0.0514459929 * rgb.b;
+    const m = 0.2119034982 * rgb.r + 0.6806995451 * rgb.g + 0.1073969566 * rgb.b;
+    const s = 0.0883024619 * rgb.r + 0.2817188376 * rgb.g + 0.6299787005 * rgb.b;
+    const l_ = Math.cbrt(l);
+    const m_ = Math.cbrt(m);
+    const s_ = Math.cbrt(s);
+    return {
+        l: 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_,
+        a: 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_,
+        b: 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_,
+    };
+}
+function oklabToLinearSrgb(lab) {
+    const l_ = lab.l + 0.3963377774 * lab.a + 0.2158037573 * lab.b;
+    const m_ = lab.l - 0.1055613458 * lab.a - 0.0638541728 * lab.b;
+    const s_ = lab.l - 0.0894841775 * lab.a - 1.291485548 * lab.b;
+    const l = l_ ** 3;
+    const m = m_ ** 3;
+    const s = s_ ** 3;
+    return {
+        r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+        g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+        b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+    };
+}
+function linearToGamma(c) {
+    const abs = Math.abs(c);
+    if (abs <= 0.0031308)
+        return 12.92 * c;
+    return Math.sign(c) * (1.055 * abs ** (1 / 2.4) - 0.055);
+}
+function gammaToLinear(c) {
+    const abs = Math.abs(c);
+    if (abs <= 0.04045)
+        return c / 12.92;
+    return Math.sign(c) * ((abs + 0.055) / 1.055) ** 2.4;
+}
+function linearRgbToSrgb(rgb) {
+    return { r: linearToGamma(rgb.r), g: linearToGamma(rgb.g), b: linearToGamma(rgb.b) };
+}
+export function srgbToLinearRgb(rgb) {
+    return { r: gammaToLinear(rgb.r), g: gammaToLinear(rgb.g), b: gammaToLinear(rgb.b) };
+}
+function oklchToOklab(c) {
+    const hRad = (c.h * Math.PI) / 180;
+    return { l: c.l, a: c.c * Math.cos(hRad), b: c.c * Math.sin(hRad) };
+}
+function oklchToLinearSrgb(c) {
+    return oklabToLinearSrgb(oklchToOklab(c));
+}
+export function oklchToSrgb(c) {
+    return linearRgbToSrgb(oklchToLinearSrgb(c));
+}
+export function oklabToOklch(lab) {
+    const c = Math.hypot(lab.a, lab.b);
+    const h = c === 0 ? 0 : ((((Math.atan2(lab.b, lab.a) * 180) / Math.PI) % 360) + 360) % 360;
+    return { l: lab.l, c, h };
+}
+export function srgbToOklch(rgb) {
+    const lab = linearSrgbToOklab(srgbToLinearRgb(rgb));
+    if (rgb.r === rgb.g && rgb.g === rgb.b)
+        return { c: 0, h: 0, l: lab.l };
+    return oklabToOklch(lab);
+}
+const GAMUT_EPSILON = 1e-4;
+function isSrgbInGamut(rgb) {
+    return (rgb.r >= -GAMUT_EPSILON &&
+        rgb.r <= 1 + GAMUT_EPSILON &&
+        rgb.g >= -GAMUT_EPSILON &&
+        rgb.g <= 1 + GAMUT_EPSILON &&
+        rgb.b >= -GAMUT_EPSILON &&
+        rgb.b <= 1 + GAMUT_EPSILON);
+}
+export function isOklchInGamut(c) {
+    return isSrgbInGamut(oklchToSrgb(c));
+}
+export function maxChroma(l, h, precision = 1e-5) {
+    if (l <= 0 || l >= 1)
+        return 0;
+    let lo = 0;
+    let hi = 0.4;
+    while (isOklchInGamut({ l, c: hi, h }) && hi < 2)
+        hi *= 2;
+    while (hi - lo > precision) {
+        const mid = (lo + hi) / 2;
+        if (isOklchInGamut({ l, c: mid, h }))
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+export function normalizeSeed(seed) {
+    if (isOklchInGamut(seed))
+        return { normalization: 'none', normalized: false, seed };
+    if (seed.l >= 1)
+        return { normalization: 'mapped-to-white', normalized: true, seed: { c: 0, h: 0, l: 1 } };
+    if (seed.l <= 0)
+        return { normalization: 'mapped-to-black', normalized: true, seed: { c: 0, h: 0, l: 0 } };
+    const cap = maxChroma(seed.l, seed.h);
+    return {
+        normalization: 'chroma-reduced',
+        normalized: true,
+        seed: { l: seed.l, c: Math.min(seed.c, cap), h: seed.h },
+    };
+}
+export function formatOklch(c) {
+    return `oklch(${roundTo(c.l, 4)} ${roundTo(c.c, 4)} ${roundTo(c.h, 2)})`;
+}
+function roundTo(n, d) {
+    const f = 10 ** d;
+    return Math.round(n * f) / f;
+}
+function relativeLuminance(rgb) {
+    const lin = srgbToLinearRgb(rgb);
+    return 0.2126 * lin.r + 0.7152 * lin.g + 0.0722 * lin.b;
+}
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(oklchToSrgb(a));
+    const lb = relativeLuminance(oklchToSrgb(b));
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+}

package/dist/lib/theming/comment-open-tracker.d.ts

@@ -0,0 +1 @@
+export declare function linesThatBeginInsideAnUnclosedComment(lines: readonly string[]): ReadonlySet<number>;