Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(theme-neutral): generate selected palette refs (#7255)

rubyycheunge92e36ffb313
diff --git a/.changeset/stable-neutral-palette-refs.md b/.changeset/stable-neutral-palette-refs.md
new file mode 100644
index 0000000000..3f1e483dfb
--- /dev/null
+++ b/.changeset/stable-neutral-palette-refs.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/theme-neutral': patch
+---
+
+[fix] Generate Neutral's runtime palette references from the stops its theme uses, and fail verification when the package or CLI template copy drifts.
+
+@rubyycheung
diff --git a/package.json b/package.json
index b013eb06dc..890c0e65e9 100644
--- a/package.json
+++ b/package.json
@@ -6,6 +6,8 @@
"scripts": {
"build": "pnpm -F @astryxdesign/build build && pnpm -F @astryxdesign/core build && pnpm -F @astryxdesign/lab build && pnpm -F @astryxdesign/charts build && pnpm -F @astryxdesign/richtext build && pnpm -F @astryxdesign/vega build && pnpm -F @astryxdesign/theme-neutral build && pnpm -F @astryxdesign/theme-matcha build && pnpm -F @astryxdesign/theme-stone build && pnpm -F @astryxdesign/theme-gothic build && pnpm -F @astryxdesign/theme-chocolate build && pnpm -F @astryxdesign/theme-y2k build && pnpm -F @astryxdesign/theme-butter build && pnpm -F @astryxdesign/theme-probe build && pnpm bundle:cli-themes && pnpm -F @astryxdesign/cli sync:api-types",
"bundle:cli-themes": "node scripts/generate-cli-themes.mjs",
+ "generate:neutral-palette-refs": "node scripts/generate-neutral-palette-refs.mjs",
+ "check:neutral-palette-refs": "node scripts/generate-neutral-palette-refs.mjs --check",
"dev": "pnpm -F @astryxdesign/storybook dev",
"test": "vitest run",
"test:watch": "vitest",
@@ -13,7 +15,7 @@
"test:a11y-contract": "playwright test --config playwright.config.ts --project chromium",
"test:docsite-browser": "playwright test --config apps/docsite/playwright.config.ts",
"check:package-boundaries": "node scripts/check-package-boundaries.js",
- "check:repo": "pnpm check:visual-owner && pnpm check:sync && pnpm check:data-tokens && pnpm check:token-docs && pnpm check:knowledge && pnpm check:package-boundaries && pnpm check:changesets && pnpm check:demo-media && pnpm check:executable-bits && pnpm check:cli-structure && pnpm check:use-client && pnpm check:portable-scripts && pnpm check:i18n-runtime && pnpm check:i18n-catalog && pnpm check:cldr-weekdays && pnpm check:fixtures && pnpm check:setup-contract",
+ "check:repo": "pnpm check:visual-owner && pnpm check:sync && pnpm check:neutral-palette-refs && pnpm check:data-tokens && pnpm check:token-docs && pnpm check:knowledge && pnpm check:package-boundaries && pnpm check:changesets && pnpm check:demo-media && pnpm check:executable-bits && pnpm check:cli-structure && pnpm check:use-client && pnpm check:portable-scripts && pnpm check:i18n-runtime && pnpm check:i18n-catalog && pnpm check:cldr-weekdays && pnpm check:fixtures && pnpm check:setup-contract",
"check:visual-owner": "node scripts/check-visual-workflow-owner.mjs",
"check:fixtures": "node internal/vibe-tests/scripts/fixture-suite.mjs verify",
"generate:cldr-weekdays": "node scripts/generate-cldr-weekdays.mjs",
diff --git a/packages/cli/assets/templates/themes/neutral/neutralPaletteRefs.generated.ts b/packages/cli/assets/templates/themes/neutral/neutralPaletteRefs.generated.ts
index 720b072752..5de468265b 100644
--- a/packages/cli/assets/templates/themes/neutral/neutralPaletteRefs.generated.ts
+++ b/packages/cli/assets/templates/themes/neutral/neutralPaletteRefs.generated.ts
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// Generated from neutralPalettes.generated.ts for the stops used by
-// neutralTheme.ts. Keep the complete palette available for authoring and
-// audits, but do not make consumers pay for unused palette stops.
+// Generated from the committed full palette for the stops used by Neutral's
+// theme source. Regenerate with `pnpm generate:neutral-palette-refs`.
+// Keep the complete palette available for authoring and audits without
+// making consumers pay for unused palette stops.
// prettier-ignore
export const neutralPaletteRefs = {
purple: {
@@ -10,11 +11,11 @@ export const neutralPaletteRefs = {
dark: {25: '#4a2f51', 80: '#eaacf8'},
},
green: {
- light: {25: '#00490b', 30: '#0b5615', 40: '#237028', 45: '#2f7d33', 65: '#6ab26b', 75: '#90ca90', 80: '#a4d6a3'},
+ light: {25: '#00490b', 30: '#0b5615', 45: '#2f7d33', 65: '#6ab26b', 75: '#90ca90', 80: '#a4d6a3'},
dark: {25: '#2b422b', 80: '#aad4a9', 85: '#bce0bb'},
},
neutral: {
- light: {0: '#000000', 5: '#111111', 10: '#1b1b1b', 15: '#262626', 30: '#474747', 35: '#525252', 45: '#6a6a6a', 50: '#777777', 60: '#919191', 65: '#9e9e9e', 85: '#d4d4d4', 90: '#e2e2e2', 95: '#f1f1f1', 100: '#ffffff'},
+ light: {0: '#000000', 5: '#111111', 10: '#1b1b1b', 30: '#474747', 45: '#6a6a6a', 60: '#919191', 85: '#d4d4d4', 90: '#e2e2e2', 95: '#f1f1f1', 100: '#ffffff'},
dark: {0: '#000000', 5: '#111111', 10: '#1b1b1b', 15: '#262626', 20: '#303030', 35: '#525252', 65: '#9e9e9e', 85: '#d4d4d4', 90: '#e2e2e2', 95: '#f1f1f1', 100: '#ffffff'},
},
orange: {
@@ -26,11 +27,11 @@ export const neutralPaletteRefs = {
dark: {25: '#253c5a', 65: '#5aa0f8', 75: '#88bcff', 80: '#a1caff'},
},
red: {
- light: {25: '#76000c', 30: '#8a0011', 35: '#9e0015', 55: '#de4745', 65: '#fa6762', 70: '#ff7f77', 80: '#ffaea7', 85: '#ffc4be'},
+ light: {25: '#76000c', 30: '#8a0011', 55: '#de4745', 65: '#fa6762', 70: '#ff7f77', 80: '#ffaea7', 85: '#ffc4be'},
dark: {25: '#5b2b28', 65: '#ee736c', 75: '#ff9890', 80: '#ffaea7', 85: '#ffc4be'},
},
yellow: {
- light: {25: '#4b3900', 30: '#584400', 40: '#745b00', 65: '#c29900', 75: '#e2b623', 80: '#eec448', 85: '#f8d36a'},
+ light: {25: '#4b3900', 30: '#584400', 65: '#c29900', 75: '#e2b623', 80: '#eec448', 85: '#f8d36a'},
dark: {25: '#453a1c', 80: '#e3c36c', 90: '#fae19e'},
},
teal: {
@@ -39,10 +40,10 @@ export const neutralPaletteRefs = {
},
cyan: {
dark: {25: '#274046', 65: '#49adc4', 75: '#71c7dd', 80: '#85d5e9', 85: '#9ae2f4'},
- light: {25: '#004351', 30: '#00505f'},
+ light: {25: '#004351'},
},
pink: {
- light: {25: '#70003f', 30: '#83004b', 70: '#fc78b1', 85: '#ffc0d7'},
+ light: {25: '#70003f', 70: '#fc78b1', 85: '#ffc0d7'},
dark: {25: '#572b3d', 75: '#fd92bd', 80: '#ffa9ca'},
},
} as const;
diff --git a/packages/themes/neutral/neutral.spec.md b/packages/themes/neutral/neutral.spec.md
index 21dd1c61af..a42f93dcba 100644
--- a/packages/themes/neutral/neutral.spec.md
+++ b/packages/themes/neutral/neutral.spec.md
@@ -173,14 +173,14 @@ explicit maintenance command MUST discover every palette family, mode, and stop
referenced by Neutral's theme source, resolve each one from the committed full
palette, and regenerate the selected-stop module without changing token mappings.
A non-writing check MUST compare the complete generated module with the committed
-file and fail on missing, extra, stale, or invalid references. Normal theme builds
-MUST check this invariant but MUST NOT regenerate or adopt palette values.
+file and fail on missing, extra, stale, or invalid references. Theme verification
+MUST fail when the committed module differs from this deterministic projection.
+Normal theme builds MUST NOT regenerate or adopt palette values.
-The checked-in module currently contains 104 entries, while `neutralTheme.ts`
-references 95. The nine extras are superseded light-mode stops left behind when
-#6171 changed those mappings. The first supported regeneration MUST remove those
-nine unused private entries while preserving every referenced value, the complete
-authoring palette, all token mappings, rendered output, and public APIs.
+The selected-stop module MUST contain exactly the palette stops referenced by
+Neutral's theme source. Removing an unreferenced private entry preserves every
+referenced value, the complete authoring palette, all token mappings, rendered
+output, and public APIs.
## Verification map
@@ -283,15 +283,15 @@ explicit theme-local values.
**Decider:** `rubyycheung`, `2026-09-30`
Neutral's selected-stop module is generated from two existing sources of truth:
-the family, mode, and stop references used by `neutralTheme.ts`, and the exact
-values in `neutralPalettes.generated.ts`. Regeneration copies only those selected
+the family, mode, and stop references used by Neutral's theme source, and the exact
+values in the committed full palette. Regeneration copies only those selected
values into the runtime artifact. It neither chooses mappings nor regenerates the
full palette.
The generator has an explicit write mode for maintainers and a non-writing check
-for CI. The check compares the entire expected artifact, so a missing, extra,
-invalid, or stale selected reference fails before package output is accepted.
-Normal theme builds run the check rather than silently changing committed source.
+for verification. The check compares the entire expected artifact, so a missing,
+extra, invalid, or stale selected reference fails before package output is
+accepted. Normal theme builds never rewrite committed palette source.
Rejected: importing the complete palette at runtime, maintaining a second manual
selection manifest, or treating token-mapping assertions as proof that copied
diff --git a/packages/themes/neutral/package.json b/packages/themes/neutral/package.json
index 9754a34ffc..7a09c07162 100644
--- a/packages/themes/neutral/package.json
+++ b/packages/themes/neutral/package.json
@@ -55,7 +55,7 @@
"palette.config.json"
],
"scripts": {
- "build": "node ../../../scripts/clean-dist.mjs && astryx theme build src/neutralTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
+ "build": "node ../../../scripts/clean-dist.mjs && node ../../../scripts/generate-neutral-palette-refs.mjs --check && astryx theme build src/neutralTheme.ts -o dist/theme.css --icons-specifier ./icons.mjs && tsup && tsc --project tsconfig.build.json && node ../../../scripts/check-fully-specified.mjs"
},
"dependencies": {
"lucide-react": "^1.18.0"
diff --git a/packages/themes/neutral/src/neutralPaletteRefs.generated.ts b/packages/themes/neutral/src/neutralPaletteRefs.generated.ts
index 720b072752..5de468265b 100644
--- a/packages/themes/neutral/src/neutralPaletteRefs.generated.ts
+++ b/packages/themes/neutral/src/neutralPaletteRefs.generated.ts
@@ -1,8 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-// Generated from neutralPalettes.generated.ts for the stops used by
-// neutralTheme.ts. Keep the complete palette available for authoring and
-// audits, but do not make consumers pay for unused palette stops.
+// Generated from the committed full palette for the stops used by Neutral's
+// theme source. Regenerate with `pnpm generate:neutral-palette-refs`.
+// Keep the complete palette available for authoring and audits without
+// making consumers pay for unused palette stops.
// prettier-ignore
export const neutralPaletteRefs = {
purple: {
@@ -10,11 +11,11 @@ export const neutralPaletteRefs = {
dark: {25: '#4a2f51', 80: '#eaacf8'},
},
green: {
- light: {25: '#00490b', 30: '#0b5615', 40: '#237028', 45: '#2f7d33', 65: '#6ab26b', 75: '#90ca90', 80: '#a4d6a3'},
+ light: {25: '#00490b', 30: '#0b5615', 45: '#2f7d33', 65: '#6ab26b', 75: '#90ca90', 80: '#a4d6a3'},
dark: {25: '#2b422b', 80: '#aad4a9', 85: '#bce0bb'},
},
neutral: {
- light: {0: '#000000', 5: '#111111', 10: '#1b1b1b', 15: '#262626', 30: '#474747', 35: '#525252', 45: '#6a6a6a', 50: '#777777', 60: '#919191', 65: '#9e9e9e', 85: '#d4d4d4', 90: '#e2e2e2', 95: '#f1f1f1', 100: '#ffffff'},
+ light: {0: '#000000', 5: '#111111', 10: '#1b1b1b', 30: '#474747', 45: '#6a6a6a', 60: '#919191', 85: '#d4d4d4', 90: '#e2e2e2', 95: '#f1f1f1', 100: '#ffffff'},
dark: {0: '#000000', 5: '#111111', 10: '#1b1b1b', 15: '#262626', 20: '#303030', 35: '#525252', 65: '#9e9e9e', 85: '#d4d4d4', 90: '#e2e2e2', 95: '#f1f1f1', 100: '#ffffff'},
},
orange: {
@@ -26,11 +27,11 @@ export const neutralPaletteRefs = {
dark: {25: '#253c5a', 65: '#5aa0f8', 75: '#88bcff', 80: '#a1caff'},
},
red: {
- light: {25: '#76000c', 30: '#8a0011', 35: '#9e0015', 55: '#de4745', 65: '#fa6762', 70: '#ff7f77', 80: '#ffaea7', 85: '#ffc4be'},
+ light: {25: '#76000c', 30: '#8a0011', 55: '#de4745', 65: '#fa6762', 70: '#ff7f77', 80: '#ffaea7', 85: '#ffc4be'},
dark: {25: '#5b2b28', 65: '#ee736c', 75: '#ff9890', 80: '#ffaea7', 85: '#ffc4be'},
},
yellow: {
- light: {25: '#4b3900', 30: '#584400', 40: '#745b00', 65: '#c29900', 75: '#e2b623', 80: '#eec448', 85: '#f8d36a'},
+ light: {25: '#4b3900', 30: '#584400', 65: '#c29900', 75: '#e2b623', 80: '#eec448', 85: '#f8d36a'},
dark: {25: '#453a1c', 80: '#e3c36c', 90: '#fae19e'},
},
teal: {
@@ -39,10 +40,10 @@ export const neutralPaletteRefs = {
},
cyan: {
dark: {25: '#274046', 65: '#49adc4', 75: '#71c7dd', 80: '#85d5e9', 85: '#9ae2f4'},
- light: {25: '#004351', 30: '#00505f'},
+ light: {25: '#004351'},
},
pink: {
- light: {25: '#70003f', 30: '#83004b', 70: '#fc78b1', 85: '#ffc0d7'},
+ light: {25: '#70003f', 70: '#fc78b1', 85: '#ffc0d7'},
dark: {25: '#572b3d', 75: '#fd92bd', 80: '#ffa9ca'},
},
} as const;
diff --git a/scripts/generate-neutral-palette-refs.mjs b/scripts/generate-neutral-palette-refs.mjs
new file mode 100644
index 0000000000..8041113e2d
--- /dev/null
+++ b/scripts/generate-neutral-palette-refs.mjs
@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/* global process */
+
+/**
+ * @file Generates Neutral's runtime-sized palette reference module from the
+ * palette stops used by the theme source and the values in the committed full
+ * palette. The default mode writes both the package artifact and its CLI theme
+ * template copy; `--check` compares both without writing.
+ * @input Neutral's theme source and committed full palette.
+ * @output The selected runtime palette-reference module and matching CLI copy.
+ * @position Repository maintenance command and Neutral build drift guard.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import * as ts from 'typescript';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const THEME_SOURCE_REL = 'packages/themes/neutral/src/neutralTheme.ts';
+export const FULL_PALETTE_REL =
+ 'packages/themes/neutral/src/neutralPalettes.generated.ts';
+export const SELECTED_REFS_REL =
+ 'packages/themes/neutral/src/neutralPaletteRefs.generated.ts';
+export const TEMPLATE_REFS_REL =
+ 'packages/cli/assets/templates/themes/neutral/neutralPaletteRefs.generated.ts';
+
+const COPYRIGHT = '// Copyright (c) Meta Platforms, Inc. and affiliates.\n\n';
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+const HEX = /^#[0-9a-f]{6}$/u;
+
+function assertNoParseDiagnostics(file, label) {
+ const diagnostic = file.parseDiagnostics[0];
+ if (!diagnostic) return;
+ const position = file.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+ const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+ throw new Error(
+ `${label}:${position.line + 1}:${position.character + 1}: ${message}`,
+ );
+}
+
+function unwrap(expression) {
+ let current = expression;
+ while (
+ ts.isAsExpression(current) ||
+ ts.isSatisfiesExpression(current) ||
+ ts.isParenthesizedExpression(current)
+ ) {
+ current = current.expression;
+ }
+ return current;
+}
+
+function propertyName(name) {
+ if (
+ ts.isIdentifier(name) ||
+ ts.isStringLiteral(name) ||
+ ts.isNumericLiteral(name)
+ ) {
+ return name.text;
+ }
+ throw new Error(`Unsupported computed palette key: ${name.getText()}`);
+}
+
+function literalValue(expression) {
+ const value = unwrap(expression);
+ if (ts.isStringLiteral(value)) return value.text;
+ if (!ts.isObjectLiteralExpression(value)) {
+ throw new Error(
+ `Palette values must be object or string literals: ${value.getText()}`,
+ );
+ }
+
+ const result = {};
+ for (const property of value.properties) {
+ if (!ts.isPropertyAssignment(property)) {
+ throw new Error(`Unsupported palette member: ${property.getText()}`);
+ }
+ result[propertyName(property.name)] = literalValue(property.initializer);
+ }
+ return result;
+}
+
+/** Parse the `palette` object from its generated TypeScript source. */
+export function parseFullPalette(source) {
+ const file = ts.createSourceFile(
+ FULL_PALETTE_REL,
+ source,
+ ts.ScriptTarget.Latest,
+ true,
+ ts.ScriptKind.TS,
+ );
+ assertNoParseDiagnostics(file, FULL_PALETTE_REL);
+
+ let palette = null;
+ const visit = node => {
+ if (
+ ts.isVariableDeclaration(node) &&
+ ts.isIdentifier(node.name) &&
+ node.name.text === 'palette' &&
+ node.initializer
+ ) {
+ palette = literalValue(node.initializer);
+ }
+ ts.forEachChild(node, visit);
+ };
+ visit(file);
+
+ if (!palette || typeof palette !== 'object') {
+ throw new Error(`${FULL_PALETTE_REL} exports no literal palette object.`);
+ }
+ return palette;
+}
+
+function destructuredAliases(file) {
+ const aliases = new Map();
+ const visit = node => {
+ if (
+ ts.isVariableDeclaration(node) &&
+ ts.isObjectBindingPattern(node.name) &&
+ node.initializer &&
+ ts.isIdentifier(unwrap(node.initializer)) &&
+ unwrap(node.initializer).text === 'neutralPaletteRefs'
+ ) {
+ for (const element of node.name.elements) {
+ if (!ts.isIdentifier(element.name)) {
+ throw new Error(
+ 'Neutral palette reference aliases must be identifiers.',
+ );
+ }
+ const family = element.propertyName
+ ? propertyName(element.propertyName)
+ : element.name.text;
+ aliases.set(element.name.text, family);
+ }
+ }
+ ts.forEachChild(node, visit);
+ };
+ visit(file);
+ return aliases;
+}
+
+function paletteAccess(expression, aliases) {
+ if (!ts.isPropertyAccessExpression(expression)) return null;
+ const mode = expression.name.text;
+ if (mode !== 'light' && mode !== 'dark') return null;
+
+ const owner = expression.expression;
+ if (ts.isIdentifier(owner) && aliases.has(owner.text)) {
+ return {family: aliases.get(owner.text), mode};
+ }
+ if (
+ ts.isPropertyAccessExpression(owner) &&
+ ts.isIdentifier(owner.expression) &&
+ owner.expression.text === 'neutralPaletteRefs'
+ ) {
+ return {family: owner.name.text, mode};
+ }
+ return null;
+}
+
+function rootedInPalette(expression, aliases) {
+ const node = unwrap(expression);
+ if (ts.isIdentifier(node)) {
+ return node.text === 'neutralPaletteRefs' || aliases.has(node.text);
+ }
+ if (
+ ts.isPropertyAccessExpression(node) ||
+ ts.isElementAccessExpression(node)
+ ) {
+ return rootedInPalette(node.expression, aliases);
+ }
+ return false;
+}
+
+function isNonReferenceIdentifier(node) {
+ if (!ts.isIdentifier(node)) return false;
+ const parent = node.parent;
+ if (!parent) return false;
+ return (
+ (ts.isPropertyAccessExpression(parent) && parent.name === node) ||
+ (ts.isPropertyAssignment(parent) && parent.name === node) ||
+ (ts.isBindingElement(parent) && parent.propertyName === node) ||
+ ((ts.isMethodDeclaration(parent) ||
+ ts.isPropertyDeclaration(parent) ||
+ ts.isPropertySignature(parent) ||
+ ts.isMethodSignature(parent)) &&
+ parent.name === node)
+ );
+}
+
+function validatePaletteUses(file, aliases) {
+ const visit = node => {
+ const isPaletteExpression =
+ !isNonReferenceIdentifier(node) &&
+ (ts.isIdentifier(node) ||
+ ts.isPropertyAccessExpression(node) ||
+ ts.isElementAccessExpression(node)) &&
+ rootedInPalette(node, aliases);
+ const parent = node.parent;
+ const parentContinuesAccess =
+ parent != null &&
+ (ts.isPropertyAccessExpression(parent) ||
+ ts.isElementAccessExpression(parent)) &&
+ parent.expression === node;
+
+ if (isPaletteExpression && !parentContinuesAccess) {
+ const isBindingName =
+ ts.isIdentifier(node) &&
+ parent != null &&
+ ts.isBindingElement(parent) &&
+ parent.name === node;
+ const isImportName =
+ ts.isIdentifier(node) &&
+ parent != null &&
+ (ts.isImportSpecifier(parent) ||
+ ts.isImportClause(parent) ||
+ ts.isNamespaceImport(parent));
+ const isRootDestructure =
+ ts.isIdentifier(node) &&
+ node.text === 'neutralPaletteRefs' &&
+ parent != null &&
+ ts.isVariableDeclaration(parent) &&
+ parent.initializer === node &&
+ ts.isObjectBindingPattern(parent.name);
+ const isCompleteReference =
+ ts.isElementAccessExpression(node) &&
+ paletteAccess(node.expression, aliases) !== null;
+
+ if (
+ !isBindingName &&
+ !isImportName &&
+ !isRootDestructure &&
+ !isCompleteReference
+ ) {
+ throw new Error(
+ `Palette references must be used directly as family.light[25] or family.dark[25]; unsupported alias or escape: ${node.getText(file)}`,
+ );
+ }
+ }
+ ts.forEachChild(node, visit);
+ };
+ visit(file);
+}
+
+/**
+ * Discover selected palette references in lexical order. Family and mode order
+ * follow first use; stops are de-duplicated and sorted during rendering.
+ */
+export function discoverSelectedRefs(source, fullPalette) {
+ const file = ts.createSourceFile(
+ THEME_SOURCE_REL,
+ source,
+ ts.ScriptTarget.Latest,
+ true,
+ ts.ScriptKind.TS,
+ );
+ assertNoParseDiagnostics(file, THEME_SOURCE_REL);
+ const aliases = destructuredAliases(file);
+ validatePaletteUses(file, aliases);
+ const families = new Map();
+
+ const visit = node => {
+ if (ts.isElementAccessExpression(node)) {
+ const access = paletteAccess(node.expression, aliases);
+ if (access) {
+ const argument = node.argumentExpression;
+ if (!argument || !ts.isNumericLiteral(argument)) {
+ throw new Error(
+ `Palette references must use literal numeric stops: ${node.getText(file)}`,
+ );
+ }
+ const stop = Number(argument.text);
+ const value =
+ fullPalette?.[access.family]?.[access.mode]?.[String(stop)];
+ if (typeof value !== 'string' || !HEX.test(value)) {
+ throw new Error(
+ `Palette reference ${access.family}.${access.mode}[${stop}] is missing or invalid in the committed full palette.`,
+ );
+ }
+
+ if (!families.has(access.family))
+ families.set(access.family, new Map());
+ const modes = families.get(access.family);
+ if (!modes.has(access.mode)) modes.set(access.mode, new Set());
+ modes.get(access.mode).add(stop);
+ } else if (rootedInPalette(node.expression, aliases)) {
+ throw new Error(
+ `Palette references must use family.light[25] or family.dark[25] with literal keys: ${node.getText(file)}`,
+ );
+ }
+ }
+ ts.forEachChild(node, visit);
+ };
+ visit(file);
+
+ if (families.size === 0) {
+ throw new Error(
+ `${THEME_SOURCE_REL} contains no selected palette references.`,
+ );
+ }
+ return families;
+}
+
+function renderedKey(key) {
+ return IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}
+
+/** Render the complete selected-reference artifact. */
+export function renderSelectedRefs(themeSource, fullPaletteSource) {
+ const palette = parseFullPalette(fullPaletteSource);
+ const selected = discoverSelectedRefs(themeSource, palette);
+ const lines = [
+ COPYRIGHT.trimEnd(),
+ '',
+ "// Generated from the committed full palette for the stops used by Neutral's",
+ '// theme source. Regenerate with `pnpm generate:neutral-palette-refs`.',
+ '// Keep the complete palette available for authoring and audits without',
+ '// making consumers pay for unused palette stops.',
+ '// prettier-ignore',
+ 'export const neutralPaletteRefs = {',
+ ];
+
+ for (const [family, modes] of selected) {
+ lines.push(` ${renderedKey(family)}: {`);
+ for (const [mode, stops] of modes) {
+ const entries = [...stops]
+ .sort((a, b) => a - b)
+ .map(stop => `${stop}: '${palette[family][mode][String(stop)]}'`)
+ .join(', ');
+ lines.push(` ${mode}: {${entries}},`);
+ }
+ lines.push(' },');
+ }
+
+ lines.push('} as const;', '', 'export default neutralPaletteRefs;', '');
+ return {content: lines.join('\n'), selected};
+}
+
+/** Count unique family/mode/stop references. */
+export function countSelectedRefs(selected) {
+ let count = 0;
+ for (const modes of selected.values()) {
+ for (const stops of modes.values()) count += stops.size;
+ }
+ return count;
+}
+
+/** Write or compare generated outputs. Returns mismatch descriptions in check mode. */
+export function syncOutputs(content, outputs, {check}) {
+ const problems = [];
+ for (const output of outputs) {
+ if (!check) {
+ fs.mkdirSync(path.dirname(output), {recursive: true});
+ fs.writeFileSync(output, content);
+ continue;
+ }
+ if (!fs.existsSync(output)) {
+ problems.push({output, reason: 'is missing'});
+ } else if (fs.readFileSync(output, 'utf-8') !== content) {
+ problems.push({output, reason: 'differs'});
+ }
+ }
+ return problems;
+}
+
+export function generateNeutralPaletteRefs({root = ROOT, check = false} = {}) {
+ const themeSource = fs.readFileSync(
+ path.join(root, THEME_SOURCE_REL),
+ 'utf-8',
+ );
+ const fullPaletteSource = fs.readFileSync(
+ path.join(root, FULL_PALETTE_REL),
+ 'utf-8',
+ );
+ const {content, selected} = renderSelectedRefs(
+ themeSource,
+ fullPaletteSource,
+ );
+ const outputs = [SELECTED_REFS_REL, TEMPLATE_REFS_REL].map(relative =>
+ path.join(root, relative),
+ );
+ const problems = syncOutputs(content, outputs, {check});
+ return {content, selected, outputs, problems};
+}
+
+function main() {
+ const check = process.argv.includes('--check');
+ const result = generateNeutralPaletteRefs({check});
+ const count = countSelectedRefs(result.selected);
+
+ if (check && result.problems.length > 0) {
+ process.stderr.write(
+ `\nNeutral selected palette refs are out of sync:\n` +
+ result.problems
+ .map(
+ problem =>
+ ` - ${path.relative(ROOT, problem.output)} ${problem.reason}`,
+ )
+ .join('\n') +
+ `\nRun: pnpm generate:neutral-palette-refs\n\n`,
+ );
+ return 1;
+ }
+
+ if (check) {
+ process.stdout.write(
+ `Neutral selected palette refs are in sync (${count} stops).\n`,
+ );
+ } else {
+ for (const output of result.outputs) {
+ process.stdout.write(`Wrote ${path.relative(ROOT, output)}\n`);
+ }
+ process.stdout.write(`Selected ${count} referenced palette stops.\n`);
+ }
+ return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+ process.exit(main());
+}
diff --git a/scripts/generate-neutral-palette-refs.test.mjs b/scripts/generate-neutral-palette-refs.test.mjs
new file mode 100644
index 0000000000..58b5518f34
--- /dev/null
+++ b/scripts/generate-neutral-palette-refs.test.mjs
@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Exhaustive tests for Neutral's selected palette-reference projection.
+ * @input Theme source references, committed full-palette literals, and outputs.
+ * @output Proof that generation is deterministic and check mode fails on drift.
+ * @position Regression coverage for generate-neutral-palette-refs.mjs.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+import {
+ countSelectedRefs,
+ discoverSelectedRefs,
+ generateNeutralPaletteRefs,
+ parseFullPalette,
+ renderSelectedRefs,
+ syncOutputs,
+} from './generate-neutral-palette-refs.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const FULL_PALETTE = `export const palette = {
+ blue: {
+ name: 'Blue',
+ light: {25: '#112233', 80: '#445566'},
+ dark: {25: '#778899', 80: '#aabbcc'},
+ },
+ neutral: {
+ name: 'Neutral',
+ light: {100: '#ffffff'},
+ dark: {15: '#222222'},
+ },
+} as const;
+`;
+
+const THEME_SOURCE = `
+const {blue, neutral} = neutralPaletteRefs;
+export const theme = {
+ first: blue.dark[80],
+ direct: neutralPaletteRefs.blue.dark[25],
+ unrelated: {blue: 1},
+ second: blue.light[80],
+ third: blue.light[25],
+ repeated: blue.light[25],
+ surface: neutral.light[100],
+};
+`;
+
+describe('Neutral selected palette ref generation', () => {
+ it('uses first-reference family and mode order with unique sorted stops', () => {
+ const {content, selected} = renderSelectedRefs(THEME_SOURCE, FULL_PALETTE);
+
+ expect(countSelectedRefs(selected)).toBe(5);
+ expect(content.indexOf('blue: {')).toBeLessThan(
+ content.indexOf('neutral: {'),
+ );
+ expect(content.indexOf('dark: {25:')).toBeLessThan(
+ content.indexOf("light: {25: '#112233', 80: '#445566'}"),
+ );
+ expect(content.match(/25: '#112233'/gu)).toHaveLength(1);
+ });
+
+ it('rejects dynamic, missing, and invalid palette references', () => {
+ const palette = parseFullPalette(FULL_PALETTE);
+ expect(() =>
+ discoverSelectedRefs(
+ `const {blue} = neutralPaletteRefs; blue.light[stop];`,
+ palette,
+ ),
+ ).toThrow('literal numeric stops');
+ expect(() =>
+ discoverSelectedRefs(
+ `const {blue} = neutralPaletteRefs; blue[mode][25];`,
+ palette,
+ ),
+ ).toThrow('family.light[25] or family.dark[25]');
+ expect(() =>
+ discoverSelectedRefs(
+ `const {blue} = neutralPaletteRefs; const blueLight = blue.light; blueLight[25];`,
+ palette,
+ ),
+ ).toThrow('unsupported alias or escape');
+ expect(() =>
+ discoverSelectedRefs(
+ `const {blue} = neutralPaletteRefs; const b = blue; b.light[25];`,
+ palette,
+ ),
+ ).toThrow('unsupported alias or escape');
+ expect(() =>
+ discoverSelectedRefs(
+ `const blueLight = neutralPaletteRefs.blue.light; blueLight[25];`,
+ palette,
+ ),
+ ).toThrow('unsupported alias or escape');
+ expect(() =>
+ discoverSelectedRefs(
+ `const {blue} = neutralPaletteRefs; blue.light[30];`,
+ palette,
+ ),
+ ).toThrow('blue.light[30] is missing or invalid');
+ expect(() =>
+ discoverSelectedRefs(
+ `const {missing} = neutralPaletteRefs; missing.light[25];`,
+ palette,
+ ),
+ ).toThrow('missing.light[25] is missing or invalid');
+ });
+
+ it('rejects malformed theme and full-palette TypeScript', () => {
+ expect(() =>
+ parseFullPalette(
+ `export const palette = {blue: {light: {25: '#112233' 80: '#445566'}}} as const;`,
+ ),
+ ).toThrow('neutralPalettes.generated.ts:1:');
+ expect(() =>
+ discoverSelectedRefs(
+ `const {blue} = neutralPaletteRefs; const values = [blue.light[25] blue.light[80]];`,
+ parseFullPalette(FULL_PALETTE),
+ ),
+ ).toThrow('neutralTheme.ts:1:');
+ });
+
+ it('writes every output and check mode reports missing or stale bytes', () => {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-neutral-refs-'));
+ const first = path.join(root, 'first.ts');
+ const second = path.join(root, 'nested', 'second.ts');
+ try {
+ expect(
+ syncOutputs('expected\n', [first, second], {check: false}),
+ ).toEqual([]);
+ expect(syncOutputs('expected\n', [first, second], {check: true})).toEqual(
+ [],
+ );
+
+ fs.appendFileSync(first, 'stale\n');
+ fs.rmSync(second);
+ expect(syncOutputs('expected\n', [first, second], {check: true})).toEqual(
+ [
+ {output: first, reason: 'differs'},
+ {output: second, reason: 'is missing'},
+ ],
+ );
+ } finally {
+ fs.rmSync(root, {recursive: true, force: true});
+ }
+ });
+
+ it('projects exactly the 95 stops used by Neutral into both committed copies', () => {
+ const result = generateNeutralPaletteRefs({root: ROOT, check: true});
+ expect(result.problems).toEqual([]);
+ expect(countSelectedRefs(result.selected)).toBe(95);
+ for (const output of result.outputs) {
+ expect(fs.readFileSync(output, 'utf-8')).toBe(result.content);
+ }
+ });
+});