Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/.github/pages/assets/manifest.json b/.github/pages/assets/manifest.json
index 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.css
index 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.css
index 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.mjs
new file mode 100644
index 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.mjs
index 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`,
);