@navecss/tokens 0.1.0

package/dist/lib/theming/css-color-4.d.ts

@@ -0,0 +1,19 @@
+import type { Oklch } from './color-math.ts';
+export interface CieLab {
+    l: number;
+    a: number;
+    b: number;
+}
+export interface CieLch {
+    l: number;
+    c: number;
+    h: number;
+}
+export interface DisplayP3 {
+    r: number;
+    g: number;
+    b: number;
+}
+export declare function labToOklch(lab: CieLab): Oklch;
+export declare function lchToOklch(lch: CieLch): Oklch;
+export declare function displayP3ToOklch(p3: DisplayP3): Oklch;

package/dist/lib/theming/css-color-4.js

@@ -0,0 +1,66 @@
+import { oklabToOklch, srgbToLinearRgb } from "./color-math.js";
+const D50_WHITE = [0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585];
+const KAPPA = 24_389 / 27;
+const EPSILON = 216 / 24_389;
+const D50_TO_D65 = [
+    [0.955473421488075, -0.02309845494876471, 0.06325924320057072],
+    [-0.0283697093338637, 1.0099953980813041, 0.021041441191917323],
+    [0.012314014864481998, -0.020507649298898964, 1.330365926242124],
+];
+const LIN_P3_TO_XYZ = [
+    [608_311 / 1_250_200, 189_793 / 714_400, 198_249 / 1_000_160],
+    [35_783 / 156_275, 247_089 / 357_200, 198_249 / 2_500_400],
+    [0, 32_229 / 714_400, 5_220_557 / 5_000_800],
+];
+const XYZ_TO_LMS = [
+    [0.819022437996703, 0.3619062600528904, -0.1288737815209879],
+    [0.0329836539323885, 0.9292868615863434, 0.0361446663506424],
+    [0.0481771893596242, 0.2642395317527308, 0.6335478284694309],
+];
+const LMS_TO_OKLAB = [
+    [0.210454268309314, 0.7936177747023054, -0.0040720430116193],
+    [1.9779985324311684, -2.4285922420485799, 0.450593709617411],
+    [0.0259040424655478, 0.7827717124575296, -0.8086757549230774],
+];
+function multiply(m, v) {
+    return [
+        m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+        m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+        m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
+    ];
+}
+function labToXyzD50(lab) {
+    const fy = (lab.l + 16) / 116;
+    const fx = lab.a / 500 + fy;
+    const fz = fy - lab.b / 200;
+    const x = fx ** 3 > EPSILON ? fx ** 3 : (116 * fx - 16) / KAPPA;
+    const y = lab.l > KAPPA * EPSILON ? ((lab.l + 16) / 116) ** 3 : lab.l / KAPPA;
+    const z = fz ** 3 > EPSILON ? fz ** 3 : (116 * fz - 16) / KAPPA;
+    return [x * D50_WHITE[0], y * D50_WHITE[1], z * D50_WHITE[2]];
+}
+function xyzD65ToOklch(xyz) {
+    const lms = multiply(XYZ_TO_LMS, xyz);
+    const [l, a, b] = multiply(LMS_TO_OKLAB, [
+        Math.cbrt(lms[0]),
+        Math.cbrt(lms[1]),
+        Math.cbrt(lms[2]),
+    ]);
+    return oklabToOklch({ a, b, l });
+}
+export function labToOklch(lab) {
+    const result = xyzD65ToOklch(multiply(D50_TO_D65, labToXyzD50(lab)));
+    if (lab.a === 0 && lab.b === 0)
+        return { c: 0, h: 0, l: result.l };
+    return result;
+}
+export function lchToOklch(lch) {
+    const hRad = (lch.h * Math.PI) / 180;
+    return labToOklch({ a: lch.c * Math.cos(hRad), b: lch.c * Math.sin(hRad), l: lch.l });
+}
+export function displayP3ToOklch(p3) {
+    const linear = srgbToLinearRgb(p3);
+    const result = xyzD65ToOklch(multiply(LIN_P3_TO_XYZ, [linear.r, linear.g, linear.b]));
+    if (p3.r === p3.g && p3.g === p3.b)
+        return { c: 0, h: 0, l: result.l };
+    return result;
+}

package/dist/lib/theming/css-named-colours.d.ts

@@ -0,0 +1 @@
+export declare const CSS_NAMED_COLOURS: Set<string>;

package/dist/lib/theming/css-named-colours.js

@@ -0,0 +1,151 @@
+export const CSS_NAMED_COLOURS = new Set([
+    'aliceblue',
+    'antiquewhite',
+    'aqua',
+    'aquamarine',
+    'azure',
+    'beige',
+    'bisque',
+    'black',
+    'blanchedalmond',
+    'blue',
+    'blueviolet',
+    'brown',
+    'burlywood',
+    'cadetblue',
+    'chartreuse',
+    'chocolate',
+    'coral',
+    'cornflowerblue',
+    'cornsilk',
+    'crimson',
+    'cyan',
+    'darkblue',
+    'darkcyan',
+    'darkgoldenrod',
+    'darkgray',
+    'darkgreen',
+    'darkgrey',
+    'darkkhaki',
+    'darkmagenta',
+    'darkolivegreen',
+    'darkorange',
+    'darkorchid',
+    'darkred',
+    'darksalmon',
+    'darkseagreen',
+    'darkslateblue',
+    'darkslategray',
+    'darkslategrey',
+    'darkturquoise',
+    'darkviolet',
+    'deeppink',
+    'deepskyblue',
+    'dimgray',
+    'dimgrey',
+    'dodgerblue',
+    'firebrick',
+    'floralwhite',
+    'forestgreen',
+    'fuchsia',
+    'gainsboro',
+    'ghostwhite',
+    'gold',
+    'goldenrod',
+    'gray',
+    'green',
+    'greenyellow',
+    'grey',
+    'honeydew',
+    'hotpink',
+    'indianred',
+    'indigo',
+    'ivory',
+    'khaki',
+    'lavender',
+    'lavenderblush',
+    'lawngreen',
+    'lemonchiffon',
+    'lightblue',
+    'lightcoral',
+    'lightcyan',
+    'lightgoldenrodyellow',
+    'lightgray',
+    'lightgreen',
+    'lightgrey',
+    'lightpink',
+    'lightsalmon',
+    'lightseagreen',
+    'lightskyblue',
+    'lightslategray',
+    'lightslategrey',
+    'lightsteelblue',
+    'lightyellow',
+    'lime',
+    'limegreen',
+    'linen',
+    'magenta',
+    'maroon',
+    'mediumaquamarine',
+    'mediumblue',
+    'mediumorchid',
+    'mediumpurple',
+    'mediumseagreen',
+    'mediumslateblue',
+    'mediumspringgreen',
+    'mediumturquoise',
+    'mediumvioletred',
+    'midnightblue',
+    'mintcream',
+    'mistyrose',
+    'moccasin',
+    'navajowhite',
+    'navy',
+    'oldlace',
+    'olive',
+    'olivedrab',
+    'orange',
+    'orangered',
+    'orchid',
+    'palegoldenrod',
+    'palegreen',
+    'paleturquoise',
+    'palevioletred',
+    'papayawhip',
+    'peachpuff',
+    'peru',
+    'pink',
+    'plum',
+    'powderblue',
+    'purple',
+    'rebeccapurple',
+    'red',
+    'rosybrown',
+    'royalblue',
+    'saddlebrown',
+    'salmon',
+    'sandybrown',
+    'seagreen',
+    'seashell',
+    'sienna',
+    'silver',
+    'skyblue',
+    'slateblue',
+    'slategray',
+    'slategrey',
+    'snow',
+    'springgreen',
+    'steelblue',
+    'tan',
+    'teal',
+    'thistle',
+    'tomato',
+    'transparent',
+    'turquoise',
+    'violet',
+    'wheat',
+    'white',
+    'whitesmoke',
+    'yellow',
+    'yellowgreen',
+]);

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

@@ -0,0 +1 @@
+export declare const SLOT_DESCRIPTIONS: ReadonlyMap<string, string>;

package/dist/lib/theming/descriptions.js

@@ -0,0 +1,21 @@
+export const SLOT_DESCRIPTIONS = new Map([
+    [
+        'border.control',
+        'Identifying boundary for a control (inputs, form boundaries, and the secondary action control).',
+    ],
+    ['border.default', 'Decorative dividers and card edges.'],
+    ['content.disabled', 'Text inside a disabled interactive component.'],
+    ['content.inverse', 'Declared foreground for surface.inverse.'],
+    [
+        'content.link',
+        "Do not distinguish a link by colour alone. Nave's own examples keep a non-colour distinction wherever this token is shown.",
+    ],
+    ['content.tertiary', 'Placeholder and hint text only.'],
+    ['feedback.danger', 'Solid-background role for a destructive control or error state.'],
+    ['feedback.danger.foreground', 'Foreground role for danger text and icons.'],
+    ['feedback.info', 'Alias of feedback.warning (shared tinted-neutral family).'],
+    ['feedback.success', 'Alias of feedback.warning (shared tinted-neutral family).'],
+    ['feedback.warning', 'Solid-background role for a warning state (shared tinted-neutral family).'],
+    ['feedback.warning.foreground', 'Foreground role for warning text and icons.'],
+    ['on-feedback.danger', 'Declared foreground for the solid feedback.danger background.'],
+]);

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

@@ -0,0 +1,10 @@
+import type { PipelineResult } from './pipeline.ts';
+export declare const TINT_PROPERTY = "--nave-color-tint";
+export declare const TINT_SEED_COMMENT_STEM = "/* Tint seed: ";
+export declare const FEEDBACK_TOKENS_COMMENT_STEM = "/* Feedback tokens: ";
+export declare function shippedThemingPropertyNames(): ReadonlySet<string>;
+export interface EmittedCss {
+    customProperties: ReadonlyMap<string, string>;
+    css: string;
+}
+export declare function emitCss(result: PipelineResult, layer?: string): EmittedCss;

package/dist/lib/theming/emit.js

@@ -0,0 +1,62 @@
+import { formatOklch } from "./color-math.js";
+import { FEEDBACK_SHARED_IDENTITY_NOTICE, RETHEMING_NOTICE } from "./copy-lint.js";
+import { ACTION_SECONDARY_BORDER, ACTION_SECONDARY_FOREGROUND, SEMANTIC_SLOTS, } from "./semantics.js";
+const PREFIX = '--nave-color-';
+export const TINT_PROPERTY = '--nave-color-tint';
+export const TINT_SEED_COMMENT_STEM = '/* Tint seed: ';
+export const FEEDBACK_TOKENS_COMMENT_STEM = '/* Feedback tokens: ';
+function slotCssName(slot) {
+    return PREFIX + slot.replaceAll('.', '-');
+}
+export function shippedThemingPropertyNames() {
+    return new Set([TINT_PROPERTY, ...SEMANTIC_SLOTS.map((slot) => slotCssName(slot))]);
+}
+function lightDarkDeclaration(result, slot) {
+    const light = result.slots.find((s) => s.slot === slot && s.branch === 'light');
+    const dark = result.slots.find((s) => s.slot === slot && s.branch === 'dark');
+    if (!light || !dark)
+        throw new Error(`Missing branch for slot ${slot}: no slot is allowed to lack a dark value. Open an issue.`);
+    return { name: slotCssName(slot), value: `light-dark(${light.css}, ${dark.css})` };
+}
+export function emitCss(result, layer = 'tokens.defaults') {
+    const props = new Map();
+    for (const slot of SEMANTIC_SLOTS) {
+        const { name, value } = lightDarkDeclaration(result, slot);
+        props.set(name, value);
+    }
+    void ACTION_SECONDARY_FOREGROUND;
+    void ACTION_SECONDARY_BORDER;
+    const tintDefault = formatOklch(result.records.achromaticBranch
+        ? { l: 0.7, c: 0.05, h: result.records.tintHue }
+        : {
+            l: result.records.primary.usedSeed.l,
+            c: result.records.primary.usedSeed.c,
+            h: result.records.primary.usedSeed.h,
+        });
+    const lines = [
+        '/* Nave theming — generated, do not edit. See this package\'s README ("Theming"). */',
+        '',
+        `@property ${TINT_PROPERTY} {`,
+        `  syntax: '<color>';`,
+        `  inherits: true;`,
+        `  initial-value: ${tintDefault};`,
+        `}`,
+        '',
+        `@layer ${layer} {`,
+        '  :root {',
+        `    /* color-scheme lives here, not in @navecss/core's reset, so`,
+        `     * light-dark() resolves even for a tokens-only consumer. */`,
+        `    color-scheme: light dark;`,
+        `    ${TINT_SEED_COMMENT_STEM}${RETHEMING_NOTICE} */`,
+        `    ${TINT_PROPERTY}: ${tintDefault};`,
+    ];
+    const feedbackWarningName = slotCssName('feedback.warning');
+    for (const [name, value] of props) {
+        if (name === feedbackWarningName) {
+            lines.push(`    ${FEEDBACK_TOKENS_COMMENT_STEM}${FEEDBACK_SHARED_IDENTITY_NOTICE} */`);
+        }
+        lines.push(`    ${name}: ${value};`);
+    }
+    lines.push('  }', '}', '');
+    return { customProperties: props, css: lines.join('\n') };
+}

package/dist/lib/theming/feedback-signal.d.ts

@@ -0,0 +1,11 @@
+export interface FeedbackArtifact {
+    file: string;
+    usesFeedbackToken: boolean;
+    hasStateLabel: boolean;
+    nonColourForm: string | undefined;
+}
+export interface FeedbackViolation {
+    file: string;
+    reason: string;
+}
+export declare function checkFeedbackSignal(artifacts: readonly FeedbackArtifact[]): FeedbackViolation[];

package/dist/lib/theming/feedback-signal.js

@@ -0,0 +1,23 @@
+export function checkFeedbackSignal(artifacts) {
+    const violations = [];
+    const forms = new Map();
+    for (const artifact of artifacts) {
+        if (!artifact.usesFeedbackToken)
+            continue;
+        if (!artifact.nonColourForm) {
+            violations.push({ file: artifact.file, reason: 'conveys a feedback state by colour alone' });
+            continue;
+        }
+        if (!artifact.hasStateLabel) {
+            violations.push({
+                file: artifact.file,
+                reason: 'has a non-colour element but no text label naming the state',
+            });
+            continue;
+        }
+        const seen = forms.get(artifact.nonColourForm) ?? new Set();
+        seen.add(artifact.file);
+        forms.set(artifact.nonColourForm, seen);
+    }
+    return violations;
+}

package/dist/lib/theming/guard-message-probes.d.ts

@@ -0,0 +1,6 @@
+export interface GuardMessageProbe {
+    label: string;
+    capture: () => string;
+}
+export declare const ACCESSIBILITY_GUARD_MESSAGE_PROBES: readonly GuardMessageProbe[];
+export declare const STRUCTURALLY_UNPROBEABLE_GUARD_MESSAGES: readonly GuardMessageProbe[];

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

@@ -0,0 +1,96 @@
+import { ADJACENCY, assertNoOrphanedSemanticSlot } from "./adjacency.js";
+import { assertContrastFloors, assertFloorProvenance, assertNoSameStepViolations, checkSameStepLint, runContrastHarness, } from "./contrast.js";
+import { assertNoticeIsEmitted, RETHEMING_NOTICE } from "./copy-lint.js";
+import { TINT_SEED_COMMENT_STEM } from "./emit.js";
+import { assertNeutralChromaCeilingWithinMargin } from "./neutral.js";
+function capturedFailureMessage(fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        return error.message;
+    }
+    throw new Error('capturedFailureMessage: the given function did not throw as expected.');
+}
+function pinnedSlot(slot, step) {
+    return {
+        slot,
+        branch: 'light',
+        resolved: { scale: 'neutral', step },
+        literal: { l: 0.18, c: 0, h: 0 },
+        css: 'oklch(0.18 0 0)',
+    };
+}
+function pinnedPair(slot, light, dark) {
+    return { dark: { ...pinnedSlot(slot, dark), branch: 'dark' }, light: pinnedSlot(slot, light) };
+}
+const NOTICE_PROBE_LABEL = 'Retheming notice';
+export const ACCESSIBILITY_GUARD_MESSAGE_PROBES = [
+    {
+        label: "the contrast harness's fail-closed output",
+        capture: () => capturedFailureMessage(() => runContrastHarness({}, [])),
+    },
+    {
+        label: 'the contrast-floor threshold-failure output',
+        capture: () => capturedFailureMessage(() => assertContrastFloors([
+            {
+                pair: { subject: 'content.primary', against: 'surface.base', class: 'text' },
+                scheme: 'light',
+                ratio: 1,
+                floor: 4.5,
+                threshold: 4.545,
+                pass: false,
+            },
+        ])),
+    },
+    {
+        label: 'the same-step lint fail-closed output',
+        capture: () => capturedFailureMessage(() => checkSameStepLint({}, 'nave', [])),
+    },
+    {
+        label: 'the floor-provenance mismatch output',
+        capture: () => capturedFailureMessage(() => assertFloorProvenance({ textFloor: 0, nonTextFloor: 0, margin: 0 })),
+    },
+    {
+        label: 'the neutral chroma-ceiling margin output',
+        capture: () => capturedFailureMessage(() => assertNeutralChromaCeilingWithinMargin(1)),
+    },
+    {
+        label: 'the orphaned-semantic-slot output',
+        capture: () => capturedFailureMessage(() => assertNoOrphanedSemanticSlot(['content.brandNew'])),
+    },
+    {
+        label: "the same-step lint's real violation output (build-step.ts's runResultGuards)",
+        capture: () => {
+            const pinned = pinnedSlot('content.primary', 900);
+            const result = {
+                slots: [pinned, { ...pinned, branch: 'dark' }],
+                actionSecondaryForeground: pinnedPair('action.secondary.foreground', 100, 200),
+                actionSecondaryBorder: pinnedPair('action.secondary.border', 500, 400),
+            };
+            const sameStep = checkSameStepLint(result, 'nave', ADJACENCY);
+            return capturedFailureMessage(() => assertNoSameStepViolations(sameStep));
+        },
+    },
+    {
+        label: "the emitted-notice guard's absent-notice refusal",
+        capture: () => capturedFailureMessage(() => assertNoticeIsEmitted(':root {\n}', RETHEMING_NOTICE, NOTICE_PROBE_LABEL)),
+    },
+    {
+        label: "the emitted-notice guard's multi-line-notice refusal",
+        capture: () => {
+            const split = `${RETHEMING_NOTICE.slice(0, 10)}\n${RETHEMING_NOTICE.slice(10)}`;
+            return capturedFailureMessage(() => assertNoticeIsEmitted(`:root {\n  ${TINT_SEED_COMMENT_STEM}${split} */\n}`, split, NOTICE_PROBE_LABEL));
+        },
+    },
+    {
+        label: "the emitted-notice guard's not-a-self-contained-comment refusal",
+        capture: () => capturedFailureMessage(() => assertNoticeIsEmitted(`:root {\n  /* wrapped, so\n   * ${RETHEMING_NOTICE} */\n}`, RETHEMING_NOTICE, NOTICE_PROBE_LABEL)),
+    },
+];
+export const STRUCTURALLY_UNPROBEABLE_GUARD_MESSAGES = [
+    {
+        label: "the emitted-notice guard's composed-comment-line refusal",
+        capture: () => capturedFailureMessage(() => assertNoticeIsEmitted(`:root {\n  /* meets ${TINT_SEED_COMMENT_STEM.slice(3)}${RETHEMING_NOTICE} */\n}`, RETHEMING_NOTICE, NOTICE_PROBE_LABEL)),
+    },
+];

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

@@ -0,0 +1,15 @@
+type UpgradePosture = 'fine' | 'unbounded-0x-bounded-1.0';
+export interface LadderRung {
+    rung: string;
+    situation: string;
+    whatYouWrite: string;
+    whereItLives: string;
+    cost: string;
+    preserves: string;
+    voids: string;
+    upgrade: UpgradePosture;
+    reserved?: true;
+}
+export declare const LADDER: readonly LadderRung[];
+export declare function assertLadderOrder(): void;
+export {};

package/dist/lib/theming/ladder.js

@@ -0,0 +1,81 @@
+export const LADDER = [
+    {
+        rung: '0',
+        situation: 'Just give me something that looks good.',
+        whatYouWrite: 'nothing',
+        whereItLives: 'a preset stylesheet import',
+        cost: 'one import',
+        preserves: 'everything, generated ahead of time from a seed Nave chose',
+        voids: 'nothing',
+        upgrade: 'fine',
+        reserved: true,
+    },
+    {
+        rung: '1a',
+        situation: 'Warm our greys up.',
+        whatYouWrite: 're-point the tint',
+        whereItLives: 'a CSS block in your app',
+        cost: 'one custom property',
+        preserves: 'everything; the neutral surface re-hues live, the accent does not move',
+        voids: 'nothing',
+        upgrade: 'fine',
+    },
+    {
+        rung: '1b',
+        situation: 'Our brand colour is this.',
+        whatYouWrite: 're-seed the accent',
+        whereItLives: 'one build command, output committed',
+        cost: 'one build command',
+        preserves: 'everything, generated from your seed',
+        voids: 'nothing',
+        upgrade: 'fine',
+    },
+    {
+        rung: '2',
+        situation: 'Our danger red is the corporate red.',
+        whatYouWrite: 'override a semantic slot',
+        whereItLives: 'a CSS block in your app',
+        cost: "generation, minus one role's link",
+        preserves: 'the rest of the generated mapping',
+        voids: 'the overridden slot, and anything that assumed the shipped value',
+        upgrade: 'fine',
+    },
+    {
+        rung: '3',
+        situation: 'Step 500 is muddy in our brand.',
+        whatYouWrite: 'override a step',
+        whereItLives: 'a JSON file in your repo',
+        cost: 'generation, minus one rung of one ramp',
+        preserves: 'every other step',
+        voids: 'contrast guarantees resting on the overridden step',
+        upgrade: 'fine',
+    },
+    {
+        rung: '4',
+        situation: 'Our lightness ramp is different.',
+        whatYouWrite: 'retheme through the build',
+        whereItLives: 'your build config',
+        cost: 'the semantic contract, not the ramp',
+        preserves: 'the required core contract',
+        voids: 'the shipped ramp shape',
+        upgrade: 'unbounded-0x-bounded-1.0',
+    },
+    {
+        rung: '5',
+        situation: 'We have our own token source.',
+        whatYouWrite: 'bring your own DTCG 2025.10',
+        whereItLives: 'your repo',
+        cost: 'nearly everything but the required core contract',
+        preserves: 'the required core contract only',
+        voids: 'every Nave-generated guarantee outside that contract',
+        upgrade: 'unbounded-0x-bounded-1.0',
+    },
+];
+export function assertLadderOrder() {
+    const order = LADDER.map((r) => r.rung);
+    const expected = ['0', '1a', '1b', '2', '3', '4', '5'];
+    if (JSON.stringify(order) !== JSON.stringify(expected)) {
+        throw new Error(`The theming-obligation ladder order is ${order.join(', ')}, expected ` +
+            `${expected.join(', ')}. Open an issue.`);
+    }
+}

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

@@ -0,0 +1,12 @@
+import { type Oklch } from './color-math.ts';
+export declare function computeNeutralChromaCeiling(): number;
+export declare function computeNeutralHueBandSpread(ceiling?: number): number;
+export declare function assertNeutralChromaCeilingWithinMargin(ceiling?: number): void;
+export interface NeutralStep {
+    step: number;
+    l: number;
+    c: number;
+}
+export declare function generateNeutralRampLiterals(ceiling?: number): readonly NeutralStep[];
+export declare function resolveNeutralStep(step: number, hue: number, literals?: readonly NeutralStep[]): Oklch;
+export declare function neutralRcsFormula(step: number, literals: readonly NeutralStep[]): string;

package/dist/lib/theming/neutral.js

@@ -0,0 +1,76 @@
+import { contrastRatio, maxChroma } from "./color-math.js";
+import { STEP_TABLE } from "./step-table.js";
+const HUE_SWEEP_STEP_DEG = 5;
+const SAFETY_FACTOR = 0.95;
+export function computeNeutralChromaCeiling() {
+    let min = Infinity;
+    for (const { l } of STEP_TABLE) {
+        if (l <= 0 || l >= 1)
+            continue;
+        for (let h = 0; h < 360; h += HUE_SWEEP_STEP_DEG) {
+            const cap = maxChroma(l, h);
+            if (cap < min)
+                min = cap;
+        }
+    }
+    return min * SAFETY_FACTOR;
+}
+const HUE_BAND_MARGIN = 0.01;
+const ACHROMATIC_WHITE = { l: 1, c: 0, h: 0 };
+const ACHROMATIC_BLACK = { l: 0, c: 0, h: 0 };
+function hueSweepSpreadAt(l, ceiling, anchor) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let h = 0; h < 360; h += HUE_SWEEP_STEP_DEG) {
+        const ratio = contrastRatio({ l, c: ceiling, h }, anchor);
+        if (ratio < min)
+            min = ratio;
+        if (ratio > max)
+            max = ratio;
+    }
+    return min > 0 ? max / min - 1 : 0;
+}
+export function computeNeutralHueBandSpread(ceiling = computeNeutralChromaCeiling()) {
+    let worst = 0;
+    for (const { l } of STEP_TABLE) {
+        if (l <= 0 || l >= 1)
+            continue;
+        for (const anchor of [ACHROMATIC_WHITE, ACHROMATIC_BLACK]) {
+            const spread = hueSweepSpreadAt(l, ceiling, anchor);
+            if (spread > worst)
+                worst = spread;
+        }
+    }
+    return worst;
+}
+const NEUTRAL_CHROMA_CEILING_MARGIN_REASON = 'at or past the 1 percent margin this build holds. That margin is a fixed constraint ' +
+    "of the palette's design and is not this build's to move: a pair clearing its floor " +
+    'only inside that margin is telling you about one tint, not about the token. ' +
+    'Re-measure the tinted-neutral arithmetic before shipping a ceiling change. If you ' +
+    'believe the margin itself is wrong, open an issue rather than widening it here.';
+export function assertNeutralChromaCeilingWithinMargin(ceiling = computeNeutralChromaCeiling()) {
+    const spread = computeNeutralHueBandSpread(ceiling);
+    if (spread >= HUE_BAND_MARGIN) {
+        throw new Error(`Neutral chroma ceiling: the ceiling ${ceiling} produces a worst-case hue-band spread ` +
+            `of ${(spread * 100).toFixed(3)} percent in the contrast values derived from it, ${NEUTRAL_CHROMA_CEILING_MARGIN_REASON}`);
+    }
+}
+export function generateNeutralRampLiterals(ceiling = computeNeutralChromaCeiling()) {
+    return STEP_TABLE.map(({ step, l }) => ({ step, l, c: l <= 0 || l >= 1 ? 0 : ceiling }));
+}
+export function resolveNeutralStep(step, hue, literals = generateNeutralRampLiterals()) {
+    const found = literals.find((s) => s.step === step);
+    if (!found)
+        throw new Error(`Neutral step ${step} is not in the shared step table.`);
+    return { l: found.l, c: found.c, h: hue };
+}
+export function neutralRcsFormula(step, literals) {
+    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)`;
+}
+function roundTo(n, d) {
+    const f = 10 ** d;
+    return Math.round(n * f) / f;
+}