An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): stop requiring fallbacks for raw data-token uses in astryx upgrade (#7912)
EJ Hammond1f3559072e40
diff --git a/.changeset/data-token-upgrade-no-fallbacks.md b/.changeset/data-token-upgrade-no-fallbacks.mdnew file mode 100644index 0000000000..54e77160bf--- /dev/null+++ b/.changeset/data-token-upgrade-no-fallbacks.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx upgrade --from` a version before 0.7.0 no longer fails on `var(--color-data-*)` uses without a fallback. Prebuilt `@astryxdesign/core/astryx.css` defines all 56 data-color defaults, and source builds read data colors through `dataVars`, so the upgrade no longer asks for fallbacks. A graph-based source build, such as `@astryxdesign/build/vite`, that reads raw `var(--color-data-*)` strings without a `dataVars` import should import `dataVars` from `@astryxdesign/core/theme/dataTokens.stylex`; the upgrade no longer reports those uses. Stale generated theme CSS that still emits the defaults at `:root` still fails the upgrade.++@ejhammonddiff --git a/docs/specs/AST-066-theme-data-boundary/spec.md b/docs/specs/AST-066-theme-data-boundary/spec.mdindex 7b59576c30..abf4464fc1 100644--- a/docs/specs/AST-066-theme-data-boundary/spec.md+++ b/docs/specs/AST-066-theme-data-boundary/spec.md@@ -37,8 +37,9 @@ Astryx owns one canonical 56-token data palette in the same public StyleX tokensystem as its other design tokens. Components import the public StyleX variableobject instead of constructing literal `var(--color-data-*)` strings. TheStyleX compiler emits the canonical group when a source-compiled consumer uses it-and omits the group from source graphs that do not use it. Core's prebuilt-`astryx.css` includes the group for consumers of the compiled public entry.+and omits the group from graph-based source builds that do not use it. Core's+prebuilt `astryx.css` and the `@astryxdesign/build` PostCSS integration include+the group whether or not a consumer imports it.A concrete theme emits only data-token values that the theme explicitly authors,inside its existing theme donut. It never carries the canonical defaults or a@@ -50,9 +51,10 @@ JavaScript marker, and three existing global `color-scheme` rules remain stable.Runtime and built theme compilation produce the same sparse scoped override.StyleX 0.19 tree-shakes `defineVars` at the module/group boundary, not per-property. The 56 data variables intentionally form one semantic group: a source-build emits zero data defaults when the module is unused and all 56 when any member-is used. The prebuilt Core stylesheet always includes the complete group. The+property. The 56 data variables intentionally form one semantic group: a+graph-based source build emits zero data defaults when the module is unused and+all 56 when any member is used. The prebuilt Core stylesheet and the+`@astryxdesign/build` PostCSS integration always include the complete group. Thecontract does not claim token-granular pruning that the compiler does not provide.## Non-goals@@ -65,7 +67,8 @@ contract does not claim token-granular pruning that the compiler does not providselectors.- Changing scoped prose defaults, non-data token declarations, componentoverrides, adaptations, MediaTheme rules, icon output, or type augmentation.-- Defining the separate `@astryxdesign/build` source-build composition contract.+- Defining the separate `@astryxdesign/build` source-build composition contract,+ beyond FR3's data-group guarantee for its PostCSS integration.- Release scheduling and versioning beyond the breaking-minor requirement inFR17.- Equivalent internal implementations remain valid when they satisfy this@@ -112,18 +115,25 @@ contract does not claim token-granular pruning that the compiler does not providreferences; loading `@astryxdesign/core/astryx.css` MUST supply their defaultswithout requiring a consumer StyleX compilation step.-- **FR3 — Tree-shaking is truthful at the group boundary.** A source-compiled- graph with no value import from the data StyleX subpath MUST emit no- `--color-data-*` default declarations. A graph that retains any `dataVars`+- **FR3 — Tree-shaking is truthful at the group boundary.** A graph-based+ source compilation, one that compiles the modules reachable from the+ product's imports, with no value import from the data StyleX subpath MUST emit+ no `--color-data-*` default declarations. A graph that retains any `dataVars`value import MUST emit one canonical StyleX variable group containing all 56defaults. Importing one member is not required to prune the other 55.+ The `@astryxdesign/build` PostCSS integration compiles every module Core+ publishes rather than a reachable graph. Its output MUST contain exactly one+ canonical 56-variable group, with every canonical name and value, whether or+ not the product imports `dataVars`.+Core's prebuilt `@astryxdesign/core/astryx.css` MUST contain exactly onecanonical 56-variable group even when no Core component consumes it. Thepackage's compiled public `dataVars` entry exposes CSS references that thisstylesheet MUST define; consumer imports cannot trigger extraction from thealready-compiled entry. This exception applies only to the prebuilt Core- stylesheet, not to source-compiled graphs or concrete themes.+ stylesheet and the PostCSS integration above, not to graph-based source+ compilation or concrete themes.Distribution output MUST remain dependency-aware: referenced cross-packageStyleX variable dependencies appear exactly once across a satellite stylesheet@@ -152,11 +162,14 @@ contract does not claim token-granular pruning that the compiler does not providFR13. The generated compatibility view keeps that resolver derived from thesame canonical `.stylex.ts` source.- Raw CSS and generated examples that cannot consume a TypeScript object MAY- reference the same stable custom-property names only when their setup already- guarantees that a source-compiled data-variable consumer retained the group or- that the prebuilt Core stylesheet is loaded, or when they provide an explicit- local fallback. Documentation MUST not imply that a theme stylesheet itself+ In prebuilt mode, raw CSS and consumer code MAY reference the stable+ `var(--color-data-*)` names with no fallback: the prebuilt Core stylesheet+ defines the complete group under FR3. A source-built product reads data colors+ through `dataVars`, which retains the group in the source graph. The+ `@astryxdesign/build` PostCSS integration always emits the group under FR3; a+ graph-based source build that does not import `dataVars` leaves raw+ references undefined, which is unsupported. An explicit local fallback remains valid in+ every mode. Documentation MUST not imply that a theme stylesheet itselfmaterializes the defaults.- **FR5 — Direct SVG and DOM values paint correctly.** A `dataVars` value passed@@ -238,10 +251,12 @@ contract does not claim token-granular pruning that the compiler does not provid### Availability and JavaScript compatibility- **FR12 — Availability follows the compilation mode, not Theme presence.** A- source graph without a compiled consumer retaining `dataVars` contains no- data-variable defaults. Core's prebuilt stylesheet always retains the group- under FR3, because the compiled public entry alone cannot emit definitions.- In either mode, standard StyleX 0.19 output declares the complete group on+ graph-based source build without a compiled consumer retaining `dataVars`+ contains no data-variable defaults. Core's prebuilt stylesheet always retains+ the group under FR3, because the compiled public entry alone cannot emit+ definitions, and the `@astryxdesign/build` PostCSS integration always retains+ it because it compiles all published Core source. In every mode, standard+ StyleX 0.19 output declares the complete group on`:root` plus its variable-group class, exactly like existing canonical StyleXtoken groups. This global declaration is an accepted compiler consequence ofthe chosen canonical token system; it MUST NOT be attributed to or duplicated@@ -316,10 +331,10 @@ contract does not claim token-granular pruning that the compiler does not provid- **FR18 — Migration prefers public imports, not compatibility CSS.** Astryxcomponent, fixture, example, and test migrations MUST replace constructibleliteral strings with `dataVars` references when the source is StyleX-capable.- Upgrade tooling and regeneration MUST reject stale raw root defaults, identify- direct raw consumers, and recommend the public StyleX import when appropriate.- Raw CSS and generated templates that already carry explicit fallbacks remain- valid after review. Migration MUST NOT add a legacy global-data theme mode,+ Upgrade tooling and regeneration MUST reject stale raw root defaults. Upgrade+ tooling does not inspect direct raw consumers and MUST NOT require a fallback+ for them. Raw CSS and generated templates that already carry explicit+ fallbacks remain valid. Migration MUST NOT add a legacy global-data theme mode,provider prop, sidecar stylesheet, arbitrary Theme wrapper, or inventedfallback color.@@ -331,11 +346,12 @@ contract does not claim token-granular pruning that the compiler does not providstill contains the canonical root block or a theme-scoped un-authored default.- **FR20 — Consumer docs distinguish three paths.** Documentation MUST show:- (1) `dataVars` for StyleX-capable component code; (2) JavaScript token- resolution for APIs that need concrete mode-resolved values; and (3) raw CSS- custom-property use only with an explicit availability guarantee or fallback.- It MUST state whole-group tree-shaking honestly and keep `@astryxdesign/build`,- color-scheme compatibility, and release work outside this change.+ (1) `dataVars` for StyleX-capable component code, the path a source build+ uses; (2) JavaScript token resolution for APIs that need concrete+ mode-resolved values; and (3) raw CSS custom-property use in prebuilt mode,+ where `@astryxdesign/core/astryx.css` supplies the defaults, or with an+ explicit fallback. It MUST state whole-group tree-shaking honestly and keep+ color-scheme compatibility and release work outside this change.### Platform support@@ -348,10 +364,11 @@ contract does not claim token-granular pruning that the compiler does not provid## Current-state impactThe public StyleX data group owns canonical CSS defaults; the compatibility,-type, validation, and documentation views derive from it. Source compilation-retains whole-group tree-shaking. Core's prebuilt stylesheet supplies the same-group for the compiled public `dataVars` entry, without a consumer compilation-step or runtime Theme injection.+type, validation, and documentation views derive from it. Graph-based source+compilation retains whole-group tree-shaking. Core's prebuilt stylesheet supplies+the same group for the compiled public `dataVars` entry, without a consumer+compilation step or runtime Theme injection, and the `@astryxdesign/build`+PostCSS integration always emits it.Concrete standalone and family themes contain only authored scoped overrides.Nested themes inherit omissions, JavaScript resolution remains compatible, and@@ -361,19 +378,19 @@ outputs are unchanged.`architecture:theme-compilation` owns runtime/static sparse theme output.`architecture:theme-application` owns provider nesting and style lifetime.`architecture:theme-tokens` owns the shared vocabulary and derived compatibility-views; this record's FR3 owns the prebuilt data-group availability guarantee.-This record does not govern `@astryxdesign/build`.+views; this record's FR3 owns the prebuilt and PostCSS data-group availability+guarantees. Beyond that guarantee, `spec:AST-080` governs `@astryxdesign/build`.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| --------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | generator drift, public export, graph-aware compiler, and package CSS tests | source graphs without imports; prebuilt Core; one retained member; cross-package provider pair; raw/gzip size | plain defaults drift; public key changes; unused source graph emits data vars; prebuilt Core omits any; one use emits fewer/more than 56; duplicate group |-| FR4–FR5 | source audit, compiler fixture, component tests, real Chromium | direct SVG fill/stroke; DOM style; Canvas concrete resolution; explicit props; canonical green/red; authored override | literal construction remains; direct CSS value does not retain definitions; Canvas receives `var()`; body paints black or wick disappears |-| FR6–FR7 | runtime/static/family structure and layer-order tests | zero/one/many authored names; all 56 canonical names; `:root`/html/body scan; theme CSS before/after component CSS | omitted default serialized; authored value outside donut; raw defaults remain; layer order flips |-| FR8–FR11 | real-browser cascade matrix | same/different nesting; parent/child subsets; siblings; dynamic switch; light/dark/system/MediaTheme; portals; layered and unlayered source CSS | omission resets; sibling leaks; order/mode changes winner; unlayered root silently claims override parity |-| FR12–FR16 | compiler/runtime/build parity and environment-policy tests | no data consumer; retained layered group; runtime and built themes; standalone and family color-scheme composition | Theme presence emits defaults; built/runtime differ; family repeats defaults; global policy diverges |-| FR17–FR20 | Changeset, codemod, CLI check, docs, and regeneration fixtures | literal component/fixture use; raw CSS with/without fallback; old root artifact; ordinary/family build | no breaking note; unsafe auto-rewrite; stale artifact passes; docs claim theme CSS supplies defaults or token-granular pruning |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR3 | generator drift, public export, graph-aware compiler, PostCSS integration, and package CSS tests | graph-based source graphs without imports; PostCSS build without a `dataVars` import, development and production; prebuilt Core; one retained member; cross-package provider pair; raw/gzip size | plain defaults drift; public key changes; unused graph-based source emits data vars; prebuilt Core or PostCSS build omits or changes any; one use emits fewer/more than 56; duplicate group |+| FR4–FR5 | source audit, compiler fixture, component tests, real Chromium | direct SVG fill/stroke; DOM style; Canvas concrete resolution; explicit props; canonical green/red; authored override | literal construction remains; direct CSS value does not retain definitions; Canvas receives `var()`; body paints black or wick disappears |+| FR6–FR7 | runtime/static/family structure and layer-order tests | zero/one/many authored names; all 56 canonical names; `:root`/html/body scan; theme CSS before/after component CSS | omitted default serialized; authored value outside donut; raw defaults remain; layer order flips |+| FR8–FR11 | real-browser cascade matrix | same/different nesting; parent/child subsets; siblings; dynamic switch; light/dark/system/MediaTheme; portals; layered and unlayered source CSS | omission resets; sibling leaks; order/mode changes winner; unlayered root silently claims override parity |+| FR12–FR16 | compiler/runtime/build parity and environment-policy tests | no data consumer; retained layered group; runtime and built themes; standalone and family color-scheme composition | Theme presence emits defaults; built/runtime differ; family repeats defaults; global policy diverges |+| FR17–FR20 | Changeset, codemod, CLI check, docs, and regeneration fixtures | literal component/fixture use; raw CSS with/without fallback in prebuilt and source builds; old root artifact; ordinary/family build | no breaking note; unsafe auto-rewrite; stale artifact passes; raw use fails upgrade; docs claim theme CSS supplies defaults or token-granular pruning |Real-browser verification MUST independently assert canonical and authored values,not reuse generator output as the oracle. It MUST reproduce the@@ -387,10 +404,14 @@ Canvas assignment never receives a `var()` reference. An unlayered StyleX outputMUST be a red arm: it must demonstrate why the supported integration wrapscanonical defaults in `astryx-base` rather than being reported as equivalent.-Compiler verification MUST compile an unused entry and a one-member consumer.-The unused output contains zero `--color-data-*` defaults; the retained output-contains every canonical name exactly once in the StyleX variable group. It MUST-not claim per-property pruning. Distribution verification MUST prove Core's+Compiler verification MUST compile an unused entry and a one-member consumer+through a graph-based pipeline. The unused output contains zero+`--color-data-*` defaults; the retained output contains every canonical name+exactly once in the StyleX variable group. It MUST not claim per-property+pruning. PostCSS integration verification MUST run the documented configuration+over a product that does not import `dataVars`, in development and production+modes, and compare the output with the canonical source: every name and value+exactly once, declared on `:root` inside `@layer astryx-base`. Distribution verification MUST prove Core'sprebuilt stylesheet defines all 56 canonical values exactly once and asatellite/provider pair does not duplicate the group. A production applicationusing only the prebuilt CSS and the compiled public `dataVars` entry MUST paint@@ -412,7 +433,8 @@ Conformance requires:- one canonical `.stylex.ts` source, a public `dataVars` export, and generatedcompatibility/type/validation views;-- truthful whole-group source tree-shaking and the explicit prebuilt-Core+- truthful whole-group tree-shaking in graph-based source builds, the complete+ group in PostCSS integration output, and the explicit prebuilt-Coreavailability guarantee, with dependency-aware satellite deduplication;- migrated Astryx consumers with no constructible raw data-var strings;- sparse donut overrides and zero theme-build raw defaults across runtime,@@ -449,7 +471,8 @@ cannot prune individual object properties. One data palette group matches theexisting `colorVars` model, keeps the public API coherent, and gives an honestsource-compiled zero-or-56 boundary. Precompiled package CSS remains graph-awareacross packages, with the explicit Core distribution exception in FR3; it does-not use a repository-wide file scan.+not use a repository-wide file scan. DEC-10 scopes the boundary to graph-based+source builds.Rejected: claiming token-granular pruning, or splitting the palette across manyfiles solely to simulate it. Both would make the API and maintenance cost exceed@@ -487,9 +510,9 @@ default.`stylex.defineVars(defaults)` emits its group on `:root` plus a variable-groupclass. This is the same canonical mechanism as existing token groups. The strict-boundary in this decision is therefore ownership: unused source graphs emit-nothing, Core distribution retains the group under FR3, and theme build never-emits data defaults globally.+boundary in this decision is therefore ownership: unused graph-based source+graphs emit nothing, Core distribution and the PostCSS integration retain the+group under FR3 (DEC-10), and theme build never emits data defaults globally.Rejected: promising that retained canonical StyleX variables are absent fromunthemed DOM. Standard `defineVars` cannot make that promise; a manually scoped@@ -539,13 +562,32 @@ this decision removes and make runtime/static ownership mode-dependent.The prebuilt public `dataVars` entry contains CSS `var()` references with nosurviving `defineVars()` call. A prebuilt-CSS consumer cannot retain defaults byimporting that already-compiled object. Core's stylesheet therefore includes the-single canonical group, like its other public token defaults. Source-compiled-graphs retain the zero-or-56 rule; themes contain only authored deltas. The fixed+single canonical group, like its other public token defaults. Graph-based+source compilation retains the zero-or-56 rule (DEC-10); themes contain only+authored deltas. The fixedcost is one group of 56 declarations, not a second source or a new runtime mode.Rejected: requiring prebuilt consumers to compile the source token entry, becauseit defeats the prebuilt-CSS contract and its documented import path.+### DEC-10 — Source builds read data colors through `dataVars`++**Reference:** `spec:AST-066/DEC-10`+**Decider:** `cixzhang`, `<pending>`++Raw `var(--color-data-*)` strings are the prebuilt path: Core's stylesheet+defines the group (FR3, DEC-9). A source build reads data colors through+`dataVars`, which retains the group in a graph-based pipeline and keeps DEC-2's+zero-or-56 boundary there. The `@astryxdesign/build` PostCSS integration+compiles every module Core publishes, so its output always carries the complete+group in `astryx-base`. This decision scopes DEC-2's source boundary and DEC-5's+unused-graph rule to graph-based source builds. Upgrade tooling requires no+fallback for raw consumers (FR18); raw strings in a graph-based source build+without a `dataVars` import are unsupported (FR4).++Rejected: an upgrade check that infers the build mode and requires fallbacks,+since no project signal reliably separates prebuilt from source builds.+## Deprecation and cleanup records### IFIX-0009 — Themes stop emitting raw global data-color defaults@@ -562,7 +604,7 @@ it defeats the prebuilt-CSS contract and its documented import path.| matrix | Theme with no authored data colors: every canonical default before; none after. Authored override: emitted before and after, scoped to its theme. StyleX `dataVars` consumers: same painted values before and after. Global `color-scheme` rules: unchanged || coexistence | The public `dataVars` group supplies canonical values through retained source compilation or the prebuilt Core stylesheet; a compiled import alone does not emit CSS. || migration | Read data colors through the public `dataVars` group, or author the needed values in the theme. Regenerate built theme CSS |-| codemod | `astryx upgrade` runs a validator that reports direct raw consumers and stale generated CSS; the rewrite depends on whether the consumer compiles StyleX |+| codemod | `astryx upgrade` runs a validator that rejects stale generated CSS; direct raw consumers need no codemod || downstream | Maintained docs and templates read data colors through `dataVars` || rollback | Restore the raw default block in runtime and `theme build` output from the final-patch baseline || harm of delay | Every theme keeps shipping a second global palette that survives without any consumer and can disagree with the canonical StyleX group |diff --git a/packages/build/src/postcss.data-defaults.test.mjs b/packages/build/src/postcss.data-defaults.test.mjsnew file mode 100644index 0000000000..cf6b33cfbd--- /dev/null+++ b/packages/build/src/postcss.data-defaults.test.mjs@@ -0,0 +1,168 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file postcss.data-defaults.test.mjs+ * @input The documented `postcss(rootDir, overrides)` config, run in+ * development and production modes over an app that has the real Core+ * package installed and never imports `dataVars`+ * @output Proves the PostCSS source build declares Core's canonical 56+ * data-token defaults, names and values from the canonical source, once, on+ * `:root` inside `@layer astryx-base`+ * @position Regression test for spec:AST-066 FR3 in @astryxdesign/build+ *+ * The PostCSS helper compiles every module each installed Astryx package+ * publishes, so Core's `theme/dataTokens.stylex.ts` is always among them and+ * its variable group is always emitted. Raw `var(--color-data-*)` CSS in a+ * PostCSS source build relies on this.+ */++import {afterAll, beforeAll, describe, expect, it} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {createRequire} from 'node:module';+import {fileURLToPath} from 'node:url';+import {parseDataTokenDefaults} from '../../../scripts/generate-data-tokens.mjs';++const require = createRequire(import.meta.url);+const {postcss} = require('./config.js');++const REPO_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../..',+);+const CORE_PACKAGE = path.join(REPO_ROOT, 'packages/core');++/** The canonical names and values, read from Core's StyleX source. */+const CANONICAL = new Map(+ parseDataTokenDefaults(+ fs.readFileSync(+ path.join(CORE_PACKAGE, 'src/theme/dataTokens.stylex.ts'),+ 'utf8',+ ),+ ),+);++const appDirs = [];+/** @type {Record<'development' | 'production', string>} */+const output = {development: '', production: ''};++/**+ * Run the documented config over a fresh app. Each mode gets its own app+ * folder: the plugin caches compiled files by path, so a shared folder would+ * reuse the first mode's rules.+ * @param {boolean} dev+ */+async function compile(dev) {+ const appDir = fs.realpathSync(+ fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-postcss-data-')),+ );+ appDirs.push(appDir);+ fs.mkdirSync(path.join(appDir, 'node_modules/@astryxdesign'), {+ recursive: true,+ });+ fs.symlinkSync(+ CORE_PACKAGE,+ path.join(appDir, 'node_modules/@astryxdesign/core'),+ 'dir',+ );+ fs.mkdirSync(path.join(appDir, 'src'));+ fs.writeFileSync(+ path.join(appDir, 'src/page.tsx'),+ [+ "import * as stylex from '@stylexjs/stylex';",+ "export const styles = stylex.create({page: {color: 'red'}});",+ '',+ ].join('\n'),+ );++ const config = postcss(appDir, {dev});+ const [pluginPath, options] = Object.entries(config.plugins)[0];+ const plugin = require(pluginPath)(options);+ let css = '';+ const atRule = {+ name: 'stylex',+ params: '',+ replaceWith(next) {+ css = next;+ },+ };+ const root = {walkAtRules: visit => visit(atRule)};+ for (const run of plugin.plugins) {+ await run(root, {+ opts: {from: path.join(appDir, 'src/app.css')},+ messages: [],+ });+ }+ return css;+}++beforeAll(async () => {+ output.development = await compile(true);+ output.production = await compile(false);+}, 180_000);++afterAll(() => {+ for (const dir of appDirs) fs.rmSync(dir, {recursive: true, force: true});+});++/** The slice of a stylesheet inside a given top-level layer block. */+function layerBlock(css, name) {+ const start = css.indexOf(`@layer ${name} {`);+ expect(start, `@layer ${name} is not in the output`).toBeGreaterThan(-1);+ let depth = 0;+ for (let i = css.indexOf('{', start); i < css.length; i++) {+ if (css[i] === '{') depth++;+ else if (css[i] === '}' && --depth === 0) return css.slice(start, i + 1);+ }+ throw new Error(`@layer ${name} is unterminated`);+}++/** Every rule whose declarations include a data-token default. */+function dataRules(css) {+ return [...css.matchAll(/([^{}]+)\{([^{}]*--color-data-[^{}]*)\}/g)].map(+ ([, selector, body]) => ({+ selectors: selector+ .trim()+ .split(',')+ .map(part => part.trim()),+ declarations: body+ .split(';')+ .map(part => part.trim())+ .filter(Boolean)+ .map(part => {+ const colon = part.indexOf(':');+ return [part.slice(0, colon).trim(), part.slice(colon + 1).trim()];+ }),+ }),+ );+}++describe('the PostCSS source build, without a dataVars import', () => {+ it('reads 56 canonical tokens from Core source', () => {+ expect(CANONICAL.size).toBe(56);+ });++ for (const mode of /** @type {const} */ (['development', 'production'])) {+ describe(`in ${mode} mode`, () => {+ it('declares the canonical names and values once, in one group', () => {+ const rules = dataRules(output[mode]);+ expect(rules).toHaveLength(1);+ const [{declarations}] = rules;+ expect(declarations).toHaveLength(56);+ expect(new Map(declarations)).toEqual(CANONICAL);+ });++ it('declares the group on :root', () => {+ const [{selectors}] = dataRules(output[mode]);+ expect(selectors).toContain(':root');+ });++ it('places the group in the library layer, not the product layer', () => {+ const css = output[mode];+ expect(dataRules(layerBlock(css, 'astryx-base'))).toHaveLength(1);+ expect(dataRules(layerBlock(css, 'product'))).toHaveLength(0);+ });+ });+ }+});diff --git a/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs b/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjsindex 99e9e1b4dd..e137baa958 100644--- a/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs+++ b/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs@@ -1,95 +1,148 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, expect, it} from 'vitest';-import transform from '../validate-data-token-ownership.mjs';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {afterAll, describe, expect, it} from 'vitest';+import transform, {meta} from '../validate-data-token-ownership.mjs';+import {upgrade} from '../../../../../api/upgrade/upgrade.mjs';-async function run(source, file = 'test.tsx') {- const jscodeshift = (await import('jscodeshift')).default;- const parser =- file.endsWith('.ts') || file.endsWith('.tsx') ? 'tsx' : 'babel';- const api = {- jscodeshift: jscodeshift.withParser(parser),- stats: () => {},- report: () => {},+const SLOW = 30_000;+const tempRoots = [];++afterAll(() => {+ for (const root of tempRoots) fs.rmSync(root, {recursive: true, force: true});+});++const STALE_THEME = `/* @generated by \`astryx theme build\` */+@layer astryx-base {+ :root { --color-data-categorical-green: #008000; }+}`;++const RAW_USES = {+ 'src/chart.tsx': `export const fill = 'var(--color-data-categorical-green)';+export const border = \`1px solid var(--color-data-blue-3)\`;+`,+ 'src/chart.css': '.bar { fill: var(--color-data-categorical-green); }\n',+};++/**+ * A project with Core 0.7.0 installed and the given files, as a repository.+ * @param {Record<string, string | object>} files+ */+function project(files) {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-data-token-'));+ tempRoots.push(root);+ fs.mkdirSync(path.join(root, '.git'));+ const all = {+ 'node_modules/@astryxdesign/core/package.json': {+ name: '@astryxdesign/core',+ version: '0.7.0',+ },+ ...files,};- return transform({source, path: file}, api);+ for (const [rel, contents] of Object.entries(all)) {+ const file = path.join(root, rel);+ fs.mkdirSync(path.dirname(file), {recursive: true});+ fs.writeFileSync(+ file,+ typeof contents === 'string' ? contents : JSON.stringify(contents),+ );+ }+ return root;}-describe('validate-data-token-ownership', () => {- it('reports direct string and static-template consumers with both migration paths', async () => {- for (const source of [- `const fill = 'var(--color-data-categorical-green)';`,- 'const fill = `var(--color-data-categorical-green)`;',- `const border = '1px solid var(--color-data-categorical-green)';`,- 'const border = `${width}px solid var(--color-data-categorical-green)`;',- ]) {- await expect(run(source)).rejects.toThrow(- /CSS-capable code imports dataVars.*Canvas.*resolveThemeToken/s,- );- }- });+const PREBUILT = {+ 'package.json': {dependencies: {'@astryxdesign/core': '0.7.3'}},+ 'src/main.tsx': "import '@astryxdesign/core/astryx.css';\n",+};+const SOURCE_BUILT = {+ 'package.json': {+ dependencies: {'@astryxdesign/core': '0.7.3'},+ devDependencies: {'@astryxdesign/build': '0.7.3'},+ },+ 'vite.config.ts':+ "import {astryxStylex} from '@astryxdesign/build/vite';\nexport default {plugins: [...astryxStylex()]};\n",+};- it('reports prebuilt CSS availability without requiring a source compile step', async () => {- await expect(- run('const fill = "var(--color-data-categorical-blue)";'),- ).rejects.toThrow(- /in prebuilt mode, loads @astryxdesign\/core\/astryx\.css/,- );- await expect(- run('.bar { fill: var(--color-data-categorical-blue); }', 'chart.css'),- ).rejects.toThrow(/load @astryxdesign\/core\/astryx\.css in prebuilt mode/);- });+const runUpgrade = root =>+ upgrade(+ {from: '0.6.9', codemod: 'validate-data-token-ownership', apply: true},+ {cwd: root},+ );- it('leaves fallbacks, dataVars access, and comments unchanged', async () => {- const source = `-// var(--color-data-categorical-green)-const fallback = 'var(--color-data-categorical-green, #008000)';-const fill = dataVars['--color-data-categorical-green'];-`;- expect(await run(source)).toBeUndefined();+describe('validate-data-token-ownership', () => {+ it('reads only stylesheets', () => {+ expect(meta.fileExtensions).toEqual(['.css']);});- it('reports stale generated theme CSS with root data defaults', async () => {- const source = `/* @generated by \`astryx theme build\` */-@layer astryx-base {- :root { --color-data-categorical-green: #008000; }-}`;- await expect(run(source, 'theme.css')).rejects.toThrow(+ it('fails on stale generated theme CSS with root data defaults', () => {+ expect(() => transform({source: STALE_THEME, path: 'theme.css'})).toThrow(/Rebuild it with `astryx theme build`/,);});- it('reports raw stylesheet uses without a fallback', async () => {- await expect(- run('.bar { fill: var(--color-data-categorical-green); }', 'chart.css'),- ).rejects.toThrow(/Raw var\(--color-data-categorical-green\).*line 1/s);- });-- it('leaves stylesheet uses with a fallback, and comments, unchanged', async () => {- expect(- await run(- `/* var(--color-data-categorical-green) */-.bar { fill: var(--color-data-categorical-green, #008000); }`,- 'chart.css',- ),- ).toBeUndefined();+ it('passes raw data-token uses with or without a fallback', () => {+ for (const source of [+ '.bar { fill: var(--color-data-categorical-green); }',+ '.bar { fill: var(--color-data-categorical-green, #008000); }',+ `/* @generated by \`astryx theme build\` */+.bar { fill: var(--color-data-blue-3); }`,+ ]) {+ expect(transform({source, path: 'chart.css'})).toBeUndefined();+ }});- it('does not claim ownership of hand-authored CSS or sparse theme overrides', async () => {+ it('does not claim ownership of hand-authored CSS or sparse theme overrides', () => {expect(- await run(- ':root { --color-data-categorical-green: #008000; }',- 'app.css',- ),+ transform({+ source: ':root { --color-data-categorical-green: #008000; }',+ path: 'app.css',+ }),).toBeUndefined();expect(- await run(- `/* @generated by \`astryx theme build\` */+ transform({+ source: `/* @generated by \`astryx theme build\` */@scope ([data-astryx-theme="ocean"]) {:scope { --color-data-categorical-green: #008000; }}`,- 'theme.css',- ),+ path: 'theme.css',+ }),).toBeUndefined();});++ it(+ 'completes `astryx upgrade --apply` over raw uses in a prebuilt project',+ async () => {+ const root = project({...PREBUILT, ...RAW_USES});+ const res = await runUpgrade(root);+ expect(res.data.complete).toBe(true);+ expect(res.data.errors ?? []).toEqual([]);+ expect(res.data.modifiedFiles ?? []).toEqual([]);+ },+ SLOW,+ );++ it(+ 'completes `astryx upgrade --apply` over raw uses in a source-built project',+ async () => {+ const root = project({...SOURCE_BUILT, ...RAW_USES});+ const res = await runUpgrade(root);+ expect(res.data.complete).toBe(true);+ expect(res.data.errors ?? []).toEqual([]);+ expect(res.data.modifiedFiles ?? []).toEqual([]);+ },+ SLOW,+ );++ it(+ 'fails `astryx upgrade --apply` on stale generated theme CSS',+ async () => {+ const root = project({...PREBUILT, 'src/theme.css': STALE_THEME});+ await expect(runUpgrade(root)).rejects.toMatchObject({+ code: 'ERR_CODEMOD_FAILED',+ });+ },+ SLOW,+ );});diff --git a/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs b/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjsindex 51a5fd5541..ad56b8dd62 100644--- a/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs+++ b/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs@@ -1,13 +1,17 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Report data-token consumers that need an ownership migration.+ * @file Reject stale generated theme CSS that still owns data-token defaults.*- * @input Consumer JavaScript/TypeScript source and generated theme CSS- * @output No rewritten source; actionable upgrade errors for fallback-less- * `var(--color-data-*)` uses (in JS strings, embedded or whole, and in CSS)- * and stale generated root-default artifacts- * @position Next-release upgrade validation for spec:AST-066+ * @input Generated theme CSS+ * @output No rewritten source; an upgrade error for a generated theme+ * stylesheet that still declares data-color defaults at `:root`+ * @position Next-release upgrade validation for spec:AST-066 FR19+ *+ * Raw `var(--color-data-*)` uses are not checked: prebuilt+ * `@astryxdesign/core/astryx.css` and the `@astryxdesign/build` PostCSS+ * integration define all 56 defaults, and other source builds read data+ * colors through `dataVars` (spec:AST-066 FR3/FR4).*/import * as path from 'node:path';@@ -15,87 +19,25 @@ import * as path from 'node:path';export const meta = {title: 'Validate data-token ownership',description:- 'Reports fallback-less data-token var() uses in source strings and stylesheets for manual CSS/non-CSS migration, and stale generated theme CSS that still owns root defaults.',- fileExtensions: ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.css'],+ 'Reports generated theme CSS that still emits the canonical data-color defaults at :root, so it can be rebuilt with `astryx theme build`.',+ fileExtensions: ['.css'],};-// A use without a fallback; `var(--color-data-x, <fallback>)` stays valid.-const DIRECT_DATA_VAR = /var\(\s*(--color-data-[a-z0-9-]+)\s*\)/u;-const CSS_COMMENT = /\/\*[\s\S]*?\*\//gu;const GENERATED_THEME_HEADER = '@generated by `astryx theme build`';const ROOT_DATA_DECLARATION = /:root\s*\{[^}]*--color-data-/su;-/** @param {any} node */-function staticString(node) {- if (- (node?.type === 'StringLiteral' || node?.type === 'Literal') &&- typeof node.value === 'string'- ) {- return node.value;- }- if (node?.type === 'TemplateLiteral') {- // Each static chunk of the template; a use can sit between expressions.- return (node.quasis ?? [])- .map((/** @type {any} */ q) => q?.value?.cooked ?? q?.value?.raw ?? '')- .join('\u0000');- }- return undefined;-}-/*** @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file- * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api* @returns {undefined}*/-export default function validateDataTokenOwnership(file, api) {- if (!file.source.includes('--color-data-')) return undefined;-- if (path.extname(file.path) === '.css') {- if (- file.source.includes(GENERATED_THEME_HEADER) &&- ROOT_DATA_DECLARATION.test(file.source)- ) {- throw new Error(- 'This generated theme CSS still emits canonical data defaults at :root. Rebuild it with `astryx theme build`; defaults come from source-compiled dataVars consumers or @astryxdesign/core/astryx.css in prebuilt mode.',- );- }- const uncommented = file.source.replace(CSS_COMMENT, comment =>- comment.replace(/[^\n]/gu, ' '),- );- const cssMatch = DIRECT_DATA_VAR.exec(uncommented);- if (cssMatch) {- const line = uncommented.slice(0, cssMatch.index).split('\n').length;- throw new Error(- `Raw var(${cssMatch[1]}) without a fallback at line ${line} needs an availability check: load @astryxdesign/core/astryx.css in prebuilt mode, ensure a source-compiled dataVars consumer retains the group, or add an explicit fallback. CSS-capable code imports dataVars from @astryxdesign/core/theme/dataTokens.stylex.`,- );- }- return undefined;- }-- const j = api.jscodeshift;- const root = j(file.source);- /** @type {{token: string, line: number|null}|null} */- let found = null;- const inspect = (/** @type {any} */ node) => {- if (found) return;- const value = staticString(node);- const match =- typeof value === 'string' ? value.match(DIRECT_DATA_VAR) : null;- if (match) {- found = {token: match[1], line: node.loc?.start?.line ?? null};- }- };-- /** @param {any} nodePath */- const inspectPath = nodePath => inspect(nodePath.node);- root.find(j.StringLiteral).forEach(inspectPath);- root.find(j.Literal).forEach(inspectPath);- root.find(j.TemplateLiteral).forEach(inspectPath);-- if (found) {- const {token, line} = found;+export default function validateDataTokenOwnership(file) {+ if (+ path.extname(file.path) === '.css' &&+ file.source.includes(GENERATED_THEME_HEADER) &&+ ROOT_DATA_DECLARATION.test(file.source)+ ) {throw new Error(- `Direct var(${token})${line == null ? '' : ` at line ${line}`} needs manual migration: CSS-capable code imports dataVars from @astryxdesign/core/theme/dataTokens.stylex and, in prebuilt mode, loads @astryxdesign/core/astryx.css; Canvas and other non-CSS APIs use resolveThemeToken() or useTheme().token().`,+ 'This generated theme CSS still emits canonical data defaults at :root. Rebuild it with `astryx theme build`; defaults come from @astryxdesign/core/astryx.css in prebuilt mode, and in a source build from the @astryxdesign/build PostCSS integration or dataVars imports.',);}return undefined;