An open source design system that's fully customizable and agent ready
TypeScript
fix(css): every package stylesheet and reset.css register the Astryx layer order (#7585)
Cindy Zhang9f2cdc0b828b
diff --git a/.changeset/package-stylesheets-layer-order.md b/.changeset/package-stylesheets-layer-order.mdnew file mode 100644index 0000000000..d536952b96--- /dev/null+++ b/.changeset/package-stylesheets-layer-order.md@@ -0,0 +1,8 @@+---+'@astryxdesign/core': patch+'@astryxdesign/richtext': patch+---++[fix] `astryx.css`, `reset.css`, and every other package stylesheet (`richtext.css`, `lab.css`, `charts.css`) now open with `@layer reset, astryx-base, astryx-theme;`, the same line theme stylesheets carry. The Astryx layer order holds whichever Astryx stylesheet loads first: loading `reset.css` after `astryx.css` no longer lets the reset override component styles, and theme overrides keep winning. Setups that already declare the order on their own first line are unchanged.++@cixzhangdiff --git a/.github/pages/assets/manifest.json b/.github/pages/assets/manifest.jsonindex e54fe84006..f89fc22c20 100644--- a/.github/pages/assets/manifest.json+++ b/.github/pages/assets/manifest.json@@ -6,7 +6,7 @@},"files": {"reset.css": {- "sha256": "8423107ecd6d1ea308d277ebc83fb5d6115ccddece700ce0f489ba44d42d8461"+ "sha256": "67ea29d9956ef672bef552cfafb3a54dc936a1285296b03207bc0c46a735b41f"},"astryx.css": {"sha256": "bc66e60ffeb0eb3b2f2b303d89ba6bae1e7e922b10bb380f7b25624d73c765ba"diff --git a/.github/pages/assets/reset.css b/.github/pages/assets/reset.cssindex 845c4c32c5..69e9e131e9 100644--- a/.github/pages/assets/reset.css+++ b/.github/pages/assets/reset.css@@ -25,7 +25,8 @@* import '@astryxdesign/core/astryx.css'; // @layer astryx-base — component styles* import '@astryxdesign/theme-neutral/theme.css'; // @layer astryx-theme — theme overrides*- * Layer order: reset → astryx-base → astryx-theme+ * Layer order: reset → astryx-base → astryx-theme. This file registers that+ * order itself, like every Astryx stylesheet, so it holds in any load order.* Consumer styles (unlayered) always override all Astryx layers.* The reset has the lowest priority and can be overridden by any other layer.*@@ -36,6 +37,8 @@* - modern-normalize*/+@layer reset, astryx-base, astryx-theme;+@layer reset {/* ===========================================================================diff --git a/packages/core/src/reset.css b/packages/core/src/reset.cssindex 845c4c32c5..69e9e131e9 100644--- a/packages/core/src/reset.css+++ b/packages/core/src/reset.css@@ -25,7 +25,8 @@* import '@astryxdesign/core/astryx.css'; // @layer astryx-base — component styles* import '@astryxdesign/theme-neutral/theme.css'; // @layer astryx-theme — theme overrides*- * Layer order: reset → astryx-base → astryx-theme+ * Layer order: reset → astryx-base → astryx-theme. This file registers that+ * order itself, like every Astryx stylesheet, so it holds in any load order.* Consumer styles (unlayered) always override all Astryx layers.* The reset has the lowest priority and can be overridden by any other layer.*@@ -36,6 +37,8 @@* - modern-normalize*/+@layer reset, astryx-base, astryx-theme;+@layer reset {/* ===========================================================================diff --git a/scripts/build-css.layers.test.mjs b/scripts/build-css.layers.test.mjsnew file mode 100644index 0000000000..0ec662ea31--- /dev/null+++ b/scripts/build-css.layers.test.mjs@@ -0,0 +1,104 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file build-css.layers.test.mjs+ * spec:AST-080 FR3: every package stylesheet registers the Astryx layer order+ * and keeps every rule inside its one layer, `astryx-base`.+ */++import fs from 'node:fs/promises';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {beforeAll, describe, expect, it} from 'vitest';+import {ensureCoreBuilt} from '../packages/cli/clients/cli/commands/ensure-core-built.mjs';+import {ASTRYX_LAYER_ORDER, composePackageStylesheet} from './build-css.mjs';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');++/**+ * Split a stylesheet into its top-level statements, comments removed: each is+ * either an at-rule statement ending in `;` or a block (`prelude { … }`).+ */+function topLevelStatements(css) {+ const text = css.replace(/\/\*[\s\S]*?\*\//g, '');+ const statements = [];+ let depth = 0;+ let start = 0;+ for (let i = 0; i < text.length; i++) {+ const ch = text[i];+ if (ch === '{') depth++;+ else if (ch === '}') {+ depth--;+ if (depth === 0) {+ statements.push(text.slice(start, i + 1).trim());+ start = i + 1;+ }+ } else if (ch === ';' && depth === 0) {+ statements.push(text.slice(start, i + 1).trim());+ start = i + 1;+ }+ }+ expect(depth).toBe(0);+ expect(text.slice(start).trim()).toBe('');+ return statements.filter(Boolean);+}++/** Assert FR3's shape: the order line first, then exactly one block in `layer`. */+function expectOneAstryxLayer(css, layer) {+ const statements = topLevelStatements(css);+ expect(statements[0]).toBe(ASTRYX_LAYER_ORDER);+ expect(statements).toHaveLength(2);+ expect(statements[1].startsWith(`@layer ${layer} {`)).toBe(true);+}++describe('package stylesheets register the Astryx layer order (spec:AST-080 FR3)', () => {+ it('names the same order theme output registers', () => {+ expect(ASTRYX_LAYER_ORDER).toBe('@layer reset, astryx-base, astryx-theme;');+ });++ it('wraps compiled rules after the order line, inside astryx-base only', () => {+ const css = composePackageStylesheet(+ 'Probe',+ '.x1{color:red}\n@media (hover: hover){.x2:hover{color:blue}}',+ );+ expectOneAstryxLayer(css, 'astryx-base');+ expect(css).toContain('.x1{color:red}');+ expect(css).toContain('@media (hover: hover){.x2:hover{color:blue}}');+ });++ it('fails the shape check for an unlayered rule', () => {+ const css = `${composePackageStylesheet('Probe', '.x1{color:red}')}.x9{color:red}\n`;+ expect(() => expectOneAstryxLayer(css, 'astryx-base')).toThrow();+ });++ it('fails the shape check without the order line', () => {+ const css = composePackageStylesheet('Probe', '.x1{color:red}').replace(+ `${ASTRYX_LAYER_ORDER}\n`,+ '',+ );+ expect(() => expectOneAstryxLayer(css, 'astryx-base')).toThrow();+ });++ describe('the built Core stylesheet', () => {+ let astryxCss;+ beforeAll(async () => {+ ensureCoreBuilt();+ astryxCss = await fs.readFile(+ path.join(ROOT, 'packages/core/dist/astryx.css'),+ 'utf8',+ );+ }, 180_000);++ it('astryx.css is the order line plus one astryx-base block', () => {+ expectOneAstryxLayer(astryxCss, 'astryx-base');+ });+ });++ it('reset.css is the order line plus one reset block', async () => {+ const resetCss = await fs.readFile(+ path.join(ROOT, 'packages/core/src/reset.css'),+ 'utf8',+ );+ expectOneAstryxLayer(resetCss, 'reset');+ });+});diff --git a/scripts/build-css.mjs b/scripts/build-css.mjsindex fd9aa55c9e..63cf04db66 100644--- a/scripts/build-css.mjs+++ b/scripts/build-css.mjs@@ -12,7 +12,8 @@* This script:* 1. Runs Babel with the StyleX plugin over the target package's source files* 2. Collects all StyleX rules- * 3. Outputs a combined stylesheet with all rules in @layer astryx-base+ * 3. Outputs a combined stylesheet that registers the Astryx layer order and+ * places all rules in @layer astryx-base** Dist consumers import the full stylesheet, e.g.:* import '@astryxdesign/core/astryx.css';@@ -302,6 +303,26 @@ export async function collectStyleXCSS(target) {return allRules;}+/**+ * The cascade-layer order every Astryx stylesheet registers before its own+ * rules (spec:AST-080 FR3), the same line theme output carries+ * (spec:AST-066 FR7). Registering it in each file keeps+ * `reset < astryx-base < astryx-theme` whichever Astryx stylesheet loads first.+ */+export const ASTRYX_LAYER_ORDER = '@layer reset, astryx-base, astryx-theme;';++/**+ * Wrap a package's compiled StyleX rules as its prebuilt stylesheet: a banner,+ * the layer-order registration, then every rule inside `@layer astryx-base`.+ */+export function composePackageStylesheet(banner, css) {+ const body = css+ .split('\n')+ .map(line => ' ' + line)+ .join('\n');+ return `/* ${banner} */\n/* Auto-generated. Do not edit manually. */\n\n${ASTRYX_LAYER_ORDER}\n\n@layer astryx-base {\n${body}\n}\n`;+}+async function main() {const target = parseTarget();const allRules = await collectStyleXCSS(target);@@ -316,11 +337,11 @@ async function main() {const combinedCSS = stylexBabelPlugin.processStylexRules(allRules, false);const outPath = path.resolve(target.dist, target.outFile);- const combinedFileContents = `/* ${target.banner} */\n/* Auto-generated. Do not edit manually. */\n\n@layer astryx-base {\n${combinedCSS- .split('\n')- .map(line => ' ' + line)- .join('\n')}\n}\n`;- await fs.writeFile(outPath, combinedFileContents, 'utf8');+ await fs.writeFile(+ outPath,+ composePackageStylesheet(target.banner, combinedCSS),+ 'utf8',+ );console.log(`${target.outFile}: ${(combinedCSS.length / 1024).toFixed(1)} KB`,);