Skip to content

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

TypeScript

fix(cli): make theme-build color-scheme decl mode-aware (#3660)

Minseon Kim57b277b8a3d1
diff --git a/.changeset/make-astryx-theme-build-s-color-scheme-declarati-18j5.md b/.changeset/make-astryx-theme-build-s-color-scheme-declarati-18j5.md
new file mode 100644
index 0000000000..e494b2b579
--- /dev/null
+++ b/.changeset/make-astryx-theme-build-s-color-scheme-declarati-18j5.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Make `astryx theme build`'s color-scheme declaration mode-aware, so built themes with `light-dark()` tokens no longer defeat `<Theme mode="light|dark">` forcing (#3660)
+@let-sunny
diff --git a/packages/cli/src/commands/build-theme.color-scheme.test.mjs b/packages/cli/src/commands/build-theme.color-scheme.test.mjs
new file mode 100644
index 0000000000..0ca6c20edd
--- /dev/null
+++ b/packages/cli/src/commands/build-theme.color-scheme.test.mjs
@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for the `color-scheme` declaration `astryx theme build`
+ * emits alongside `light-dark()` token output (see #3658).
+ *
+ * `astryx theme build` injects a `color-scheme` declaration into
+ * `@layer astryx-theme` whenever the generated CSS contains `light-dark()`,
+ * so LightningCSS/browsers can resolve it. That declaration must mirror
+ * reset.css's own `html[data-theme]` -> `color-scheme` mapping (a bare
+ * `:root { color-scheme: light dark; }` alone permanently pins the page to
+ * "light dark", defeating `<Theme mode="light|dark">` forcing regardless of
+ * `@layer astryx-theme` being declared after `@layer reset` in layer order):
+ *
+ * :root { color-scheme: light dark; }
+ * html[data-theme="light"] { color-scheme: light; }
+ * html[data-theme="dark"] { color-scheme: dark; }
+ *
+ * Themes that never use `light-dark()` have no `color-scheme` ambiguity to
+ * resolve, so none of the three rules should be emitted for them.
+ *
+ * Building `astryx theme build` requires a compiled @astryxdesign/core (there is no in-CLI
+ * fallback generator), so this suite builds core once in beforeAll via the
+ * shared ensureCoreBuilt() helper — which serializes concurrent Vitest workers
+ * behind a lock — to stay self-sufficient regardless of CI job ordering.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+const COLOR_SCHEME_ROOT_DECL = ':root { color-scheme: light dark; }';
+const COLOR_SCHEME_LIGHT_DECL = 'html[data-theme="light"] { color-scheme: light; }';
+const COLOR_SCHEME_DARK_DECL = 'html[data-theme="dark"] { color-scheme: dark; }';
+
+function runCli(args, cwd) {
+ try {
+ const out = execFileSync('node', [CLI_BIN, ...args], {
+ cwd,
+ encoding: 'utf-8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ env: {...process.env, FORCE_COLOR: '0'},
+ });
+ return {code: 0, stdout: out, stderr: ''};
+ } catch (e) {
+ return {
+ code: e.status ?? 1,
+ stdout: e.stdout?.toString() ?? '',
+ stderr: e.stderr?.toString() ?? '',
+ };
+ }
+}
+
+function writeTheme(dir, name, tokens) {
+ fs.mkdirSync(dir, {recursive: true});
+ // The CLI writes <basename>.css next to the source file, so use the
+ // theme name as the filename for unambiguous fixtures.
+ const file = path.join(dir, `${name}.mjs`);
+ fs.writeFileSync(
+ file,
+ `export default { name: ${JSON.stringify(name)}, tokens: ${JSON.stringify(tokens)} };\n`,
+ );
+ return file;
+}
+
+// `astryx theme build` imports the compiled @astryxdesign/core/theme entry. Build core
+// once if it isn't already present so the suite works in any CI job.
+beforeAll(() => {
+ ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-color-scheme-'));
+});
+afterEach(() => {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build color-scheme output', () => {
+ it('emits the mode-aware color-scheme rules in @layer astryx-theme for a light-dark() theme', () => {
+ const project = path.join(tmpDir, 'project');
+ const themesDir = path.join(project, 'themes');
+ // A raw light-dark() token value is what triggers the color-scheme
+ // injection in build-theme.mjs (it checks the generated CSS for the
+ // literal substring). `defineTheme.test.ts` already covers the separate
+ // [light, dark] tuple -> light-dark() conversion; this fixture writes
+ // the string directly so this test stays focused on the CLI's own
+ // color-scheme decision, not on that conversion.
+ const themeFile = writeTheme(themesDir, 'with-light-dark', {
+ '--color-accent': 'light-dark(#0077B6, #48CAE4)',
+ });
+
+ const result = runCli(
+ ['theme', 'build', path.relative(project, themeFile)],
+ project,
+ );
+
+ expect(result.code).toBe(0);
+
+ const cssPath = path.join(themesDir, 'with-light-dark.css');
+ expect(fs.existsSync(cssPath)).toBe(true);
+ const css = fs.readFileSync(cssPath, 'utf-8');
+
+ expect(css).toContain('light-dark(#0077B6, #48CAE4)');
+
+ // All 3 rules must be present...
+ expect(css).toContain(COLOR_SCHEME_ROOT_DECL);
+ expect(css).toContain(COLOR_SCHEME_LIGHT_DECL);
+ expect(css).toContain(COLOR_SCHEME_DARK_DECL);
+
+ // ...and specifically inside @layer astryx-theme, not @layer reset (the
+ // declaration must sit alongside the light-dark() token/component output
+ // it resolves, not the zero-specificity prose defaults).
+ const themeLayerStart = css.indexOf('@layer astryx-theme');
+ expect(themeLayerStart).toBeGreaterThanOrEqual(0);
+ const themeLayerBody = css.slice(themeLayerStart);
+ expect(themeLayerBody).toContain(COLOR_SCHEME_ROOT_DECL);
+ expect(themeLayerBody).toContain(COLOR_SCHEME_LIGHT_DECL);
+ expect(themeLayerBody).toContain(COLOR_SCHEME_DARK_DECL);
+ });
+
+ it('omits all color-scheme rules for a theme with no light-dark() tokens', () => {
+ const project = path.join(tmpDir, 'project');
+ const themesDir = path.join(project, 'themes');
+ const themeFile = writeTheme(themesDir, 'no-light-dark', {
+ '--color-accent': '#0077B6',
+ });
+
+ const result = runCli(
+ ['theme', 'build', path.relative(project, themeFile)],
+ project,
+ );
+
+ expect(result.code).toBe(0);
+
+ const cssPath = path.join(themesDir, 'no-light-dark.css');
+ expect(fs.existsSync(cssPath)).toBe(true);
+ const css = fs.readFileSync(cssPath, 'utf-8');
+
+ expect(css).not.toContain('light-dark(');
+ expect(css).not.toContain(COLOR_SCHEME_ROOT_DECL);
+ expect(css).not.toContain(COLOR_SCHEME_LIGHT_DECL);
+ expect(css).not.toContain(COLOR_SCHEME_DARK_DECL);
+ });
+});
diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjs
index a308300a6c..c7c1d149fb 100644
--- a/packages/cli/src/commands/build-theme.mjs
+++ b/packages/cli/src/commands/build-theme.mjs
@@ -939,8 +939,15 @@ export function registerTheme(program) {
if (component.length > 0) {
const componentInner = component.join('\n\n');
const componentScope = `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`;
+ // light-dark() needs a color-scheme declaration in this bundle, but a
+ // bare `:root { color-scheme: light dark }` outranks reset.css's
+ // `html[data-theme]` mapping (astryx-theme layer comes after reset),
+ // silently defeating `<Theme mode>` forcing on <html>. Mirror the
+ // attribute-keyed mapping so the declaration follows the active mode.
const colorSchemeDecl = componentScope.includes('light-dark(')
- ? ' :root { color-scheme: light dark; }\n\n'
+ ? ' :root { color-scheme: light dark; }\n' +
+ ' html[data-theme="light"] { color-scheme: light; }\n' +
+ ' html[data-theme="dark"] { color-scheme: dark; }\n\n'
: '';
cssParts.push(
`@layer astryx-theme {\n${colorSchemeDecl}${componentScope}\n}`,