Skip to content

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

TypeScript

[CLI] Make the theme build report short by default; --detail full keeps the full report (#7203)

Joeybbeffca1a6f0
diff --git a/.changeset/theme-build-batch-report.md b/.changeset/theme-build-batch-report.md
new file mode 100644
index 0000000000..36f57420d5
--- /dev/null
+++ b/.changeset/theme-build-batch-report.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx theme build` prints one line per built theme, plus one line naming fonts the themes do not load. Before, every theme printed the same install example and font recipe, so a build of many themes printed the same blocks again and again. `--detail full` prints the install example and font recipe, once for a batch instead of once per theme; for one theme it prints what the default printed before. Only the text report changes: `--json` output, `--check`, exit codes and written files are unchanged.
+
+@josephfarina
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index ff9060047d..13573fe8bc 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -74,7 +74,11 @@ import {
collectThemingTargets,
targetValidationRegistry,
} from '../../../foundation/discovery/theming-targets.mjs';
-import {collectUnloadedFonts, formatFontLoadingHelp} from './font-warning.mjs';
+import {
+ collectUnloadedFonts,
+ formatBatchFontLoadingHelp,
+ formatFontLoadingHelp,
+} from './font-warning.mjs';
import {interceptCore} from './core-interception.mjs';
import {generateFamilyCSS, resolveThemeFamily} from './family.mjs';
import {resolveIconImports} from './icon-imports.mjs';
@@ -2339,6 +2343,7 @@ async function themeBuildInternal(
file,
options = {},
{cwd = process.cwd()} = {},
+ /** @type {{compact?: boolean, trailers?: ThemeBuildTrailer[]}} */ report = {},
) {
const filePath = path.resolve(cwd, file);
@@ -2350,7 +2355,11 @@ async function themeBuildInternal(
);
}
- logger.log(`\nBuilding theme from ${path.relative(cwd, filePath)}...`);
+ if (!report.compact) {
+ logger.log(`\nBuilding theme from ${path.relative(cwd, filePath)}...`);
+ }
+ // A compact report has no per-theme heading, so each warning names its file.
+ const source = report.compact ? `${path.relative(cwd, filePath)}: ` : '';
await selectCore(cwd);
@@ -2469,18 +2478,18 @@ async function themeBuildInternal(
const noticeMessages = [];
for (const w of warnings) {
warningMessages.push(w);
- logger.warn(` [warn] ${w}`);
+ logger.warn(` [warn] ${source}${w}`);
}
// Validate no private vars are set directly
const privateVarErrors = validatePrivateVars(themeDef);
for (const e of privateVarErrors) {
warningMessages.push(e);
- logger.error(` [error] ${e}`);
+ logger.error(` [error] ${source}${e}`);
}
if (privateVarErrors.length > 0) {
logger.error(
- `\n ${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`,
+ `\n ${source}${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`,
);
}
@@ -2719,7 +2728,7 @@ async function themeBuildInternal(
for (const message of droppedDeclarations) {
const w = `Declaration ${message}. The generated CSS omits it; fix the value in the theme source.`;
warningMessages.push(w);
- logger.warn(` [warn] ${w}`);
+ logger.warn(` [warn] ${source}${w}`);
}
const unemittedHeadingTypes = headingTypesWithoutEmittedRule(
customHeadingTypes(themeDef),
@@ -2741,7 +2750,7 @@ async function themeBuildInternal(
);
}
if (cssParts.length === 0) {
- logger.log('No overrides found; nothing to build.');
+ logger.log(`${source}No overrides found; nothing to build.`);
return null;
}
// The data-token defaults are theme-independent and go in @layer
@@ -2933,19 +2942,21 @@ async function themeBuildInternal(
writeBuildOutputs(writes);
- logger.log(`\n[ok] ${path.relative(cwd, outPath)}`);
- logger.log(`[ok] ${path.relative(cwd, cssDtsPath)}`);
- logger.log(
- ` ${tokenCount} token overrides, ${componentCount} component overrides`,
- );
- logger.log(` ${size} KB`);
- logger.log(`[ok] ${path.relative(cwd, jsPath)}`);
- logger.log(`[ok] ${path.relative(cwd, dtsPath)}`);
- if (variantDtsPath && variantDecl) {
- const augCount = (variantDecl.match(/': true;/g) || []).length;
+ if (!report.compact) {
+ logger.log(`\n[ok] ${path.relative(cwd, outPath)}`);
+ logger.log(`[ok] ${path.relative(cwd, cssDtsPath)}`);
logger.log(
- `[ok] ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
+ ` ${tokenCount} token overrides, ${componentCount} component overrides`,
);
+ logger.log(` ${size} KB`);
+ logger.log(`[ok] ${path.relative(cwd, jsPath)}`);
+ logger.log(`[ok] ${path.relative(cwd, dtsPath)}`);
+ if (variantDtsPath && variantDecl) {
+ const augCount = (variantDecl.match(/': true;/g) || []).length;
+ logger.log(
+ `[ok] ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
+ );
+ }
}
const relOutDir = path.relative(cwd, outDir) || '.';
@@ -2953,27 +2964,6 @@ async function themeBuildInternal(
const jsImport = importSpecifier(relOutDir, baseName);
const cssImport = importSpecifier(relOutDir, cssBase) + '.css';
const exportName = `${toIdentifier(baseName)}Theme`;
- logger.log(`
-Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
-
- import { Theme } from '@astryxdesign/core';
- import { ${exportName} } from '${jsImport}';
- import '${cssImport}';
-
- <Theme theme={${exportName}}>
- <App />
- </Theme>
-
-Or with a <link> tag:
-
- import { Theme } from '@astryxdesign/core';
- import { ${exportName} } from '${jsImport}';
-
- <link rel="stylesheet" href="${cssImport}" />
- <Theme theme={${exportName}}>
- <App />
- </Theme>
-`);
// Fonts the theme names but nothing loads (#5015). Resolved tokens and
// component overrides carry the final font-family values on both load
@@ -2987,15 +2977,27 @@ Or with a <link> tag:
// permanently in violation of its own "compiles with no warnings" guard).
// Adaptation rules are resolved theme writes in their own right, so a family
// named only inside one needs the same notice as one named at the root.
+ /** @type {string[]} */
+ const fontNotices = [];
for (const family of unloadedFonts) {
const msg = `Font "${family}" is named by this theme but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)`;
noticeMessages.push(msg);
- logger.log(` note: ${msg}`);
- }
- if (unloadedFonts.length > 0) {
- logger.log(formatFontLoadingHelp(themeDef.name, unloadedFonts));
+ fontNotices.push(msg);
}
+ /** @type {ThemeBuildTrailer} */
+ const trailer = {
+ themeName: themeDef.name,
+ exportName,
+ jsImport,
+ cssImport,
+ unloadedFonts,
+ fontNotices,
+ };
+ // A batch or compact report prints this once for the whole run instead.
+ if (report.trailers) report.trailers.push(trailer);
+ else printBuildTrailer(trailer);
+
return {
type: 'theme.build',
data: {
@@ -3018,6 +3020,166 @@ Or with a <link> tag:
};
}
+/**
+ * What a standalone build prints after its [ok] lines, kept as data so a
+ * batch can print it once for every theme.
+ * @typedef {object} ThemeBuildTrailer
+ * @property {string} themeName The theme's name.
+ * @property {string} exportName The built module's theme export.
+ * @property {string} jsImport Import specifier of the built JS module.
+ * @property {string} cssImport Import specifier of the built CSS.
+ * @property {string[]} unloadedFonts Font families the theme names but does not load.
+ * @property {string[]} fontNotices One notice per unloaded font family.
+ */
+
+/**
+ * Print a standalone build's install snippet and font guidance.
+ * @param {ThemeBuildTrailer} trailer
+ */
+function printBuildTrailer(trailer) {
+ logger.log(`
+Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
+
+ import { Theme } from '@astryxdesign/core';
+ import { ${trailer.exportName} } from '${trailer.jsImport}';
+ import '${trailer.cssImport}';
+
+ <Theme theme={${trailer.exportName}}>
+ <App />
+ </Theme>
+
+Or with a <link> tag:
+
+ import { Theme } from '@astryxdesign/core';
+ import { ${trailer.exportName} } from '${trailer.jsImport}';
+
+ <link rel="stylesheet" href="${trailer.cssImport}" />
+ <Theme theme={${trailer.exportName}}>
+ <App />
+ </Theme>
+`);
+ for (const msg of trailer.fontNotices) logger.log(` note: ${msg}`);
+ if (trailer.unloadedFonts.length > 0) {
+ logger.log(formatFontLoadingHelp(trailer.themeName, trailer.unloadedFonts));
+ }
+}
+
+/**
+ * Print the install snippet and font guidance once for a batch: the first
+ * theme as the full example, one import line per built theme, and one font
+ * recipe naming every family the themes do not load.
+ * @param {ThemeBuildTrailer[]} trailers
+ */
+export function printBatchTrailer(trailers) {
+ if (trailers.length === 0) return;
+ const [first] = trailers;
+ logger.log(`
+Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
+
+ import { Theme } from '@astryxdesign/core';
+ import { ${first.exportName} } from '${first.jsImport}';
+ import '${first.cssImport}';
+
+ <Theme theme={${first.exportName}}>
+ <App />
+ </Theme>
+
+Or with a <link> tag:
+
+ import { Theme } from '@astryxdesign/core';
+ import { ${first.exportName} } from '${first.jsImport}';
+
+ <link rel="stylesheet" href="${first.cssImport}" />
+ <Theme theme={${first.exportName}}>
+ <App />
+ </Theme>
+`);
+ if (trailers.length > 1) {
+ logger.log('Each built theme imports the same way:');
+ for (const trailer of trailers) {
+ logger.log(
+ ` import { ${trailer.exportName} } from '${trailer.jsImport}'; import '${trailer.cssImport}';`,
+ );
+ }
+ }
+ const fonts = groupUnloadedFonts(trailers);
+ if (fonts.length > 0) logger.log(formatBatchFontLoadingHelp(fonts));
+}
+
+/**
+ * Print what a short report keeps after its one line per theme: one line
+ * naming the fonts the themes do not load, and, when the caller chose no
+ * detail level, where the install example and font recipe are.
+ * @param {ThemeBuildTrailer[]} trailers
+ * @param {{hint?: boolean}} [options]
+ */
+export function printCompactTrailer(trailers, {hint = false} = {}) {
+ if (trailers.length === 0) return;
+ const fonts = groupUnloadedFonts(trailers);
+ if (fonts.length > 0) {
+ const named = fonts
+ .map(({family, themes}) =>
+ trailers.length > 1
+ ? `"${family}" (${themes.join(', ')})`
+ : `"${family}"`,
+ )
+ .join(', ');
+ logger.log(
+ `[note] Fonts named but not loaded: ${named}. Load them in your app (recipe: astryx docs typography).`,
+ );
+ }
+ if (hint) {
+ logger.log(
+ 'Run with --detail full for the install example and font recipe.',
+ );
+ }
+}
+
+/**
+ * Each font family the themes name but do not load, with the themes that
+ * name it, in first-seen order.
+ * @param {ThemeBuildTrailer[]} trailers
+ * @returns {Array<{family: string, themes: string[]}>}
+ */
+function groupUnloadedFonts(trailers) {
+ /** @type {Map<string, {family: string, themes: string[]}>} */
+ const byFamily = new Map();
+ for (const trailer of trailers) {
+ for (const family of trailer.unloadedFonts) {
+ const key = family.toLowerCase();
+ const entry = byFamily.get(key) ?? {family, themes: []};
+ entry.themes.push(trailer.themeName);
+ byFamily.set(key, entry);
+ }
+ }
+ return [...byFamily.values()];
+}
+
+/**
+ * Build one theme for a batch or compact CLI report. Same build, outputs, and
+ * receipt as {@link themeBuild}; the install snippet and font guidance come
+ * back as `trailer` instead of being printed, and `compact` leaves out the
+ * per-file progress lines. CLI-internal: not exported from the API entry.
+ * @param {string} file
+ * @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options]
+ * @param {{cwd?: string}} [ctx]
+ * @param {{compact?: boolean}} [report]
+ * @returns {Promise<{receipt: import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null, trailer: ThemeBuildTrailer | null}>}
+ */
+export async function themeBuildForReport(
+ file,
+ options = {},
+ ctx = {},
+ {compact = false} = {},
+) {
+ /** @type {ThemeBuildTrailer[]} */
+ const trailers = [];
+ const receipt = /** @type {any} */ (
+ await themeBuildInternal(file, options, ctx, {compact, trailers})
+ );
+ return {receipt, trailer: trailers[0] ?? null};
+}
+
/** @param {string} file @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options] @param {{cwd?: string}} [ctx] @returns {Promise<import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null>} */
export async function themeBuild(file, options = {}, ctx = {}) {
return /** @type {any} */ (themeBuildInternal(file, options, ctx));
diff --git a/packages/cli/api/theme/build/font-warning.mjs b/packages/cli/api/theme/build/font-warning.mjs
index e1828a0894..e8af33a7ad 100644
--- a/packages/cli/api/theme/build/font-warning.mjs
+++ b/packages/cli/api/theme/build/font-warning.mjs
@@ -202,6 +202,33 @@ export function collectUnloadedFonts(resolvedTheme) {
*/
export function formatFontLoadingHelp(themeName, families) {
const named = families.map(f => `"${f}"`).join(', ');
+ return `
+[note] Theme "${themeName}" names fonts it does not load: ${named}
+${fontLoadingRecipe(families)}`;
+}
+
+/**
+ * The same fix once for a batch build: each family the built themes name but
+ * do not load, with the themes that name it, then one recipe for all of them.
+ *
+ * @param {Array<{family: string, themes: string[]}>} entries
+ * @returns {string}
+ */
+export function formatBatchFontLoadingHelp(entries) {
+ const named = entries
+ .map(({family, themes}) => ` "${family}" (${themes.join(', ')})`)
+ .join('\n');
+ return `
+[note] The built themes name fonts they do not load:
+${named}
+${fontLoadingRecipe(entries.map(entry => entry.family))}`;
+}
+
+/**
+ * @param {string[]} families
+ * @returns {string}
+ */
+function fontLoadingRecipe(families) {
const cssHref =
'https://fonts.googleapis.com/css2?' +
families
@@ -210,9 +237,7 @@ export function formatFontLoadingHelp(themeName, families) {
'&display=swap';
const first = families[0];
const slug = first.toLowerCase().replace(/ /g, '-');
- return `
-[note] Theme "${themeName}" names fonts it does not load: ${named}
- The built CSS only sets font-family; load these in your app, or every
+ return ` The built CSS only sets font-family; load these in your app, or every
browser quietly falls back.
Google Fonts (add :wght@... axes as your theme's weights require):
diff --git a/packages/cli/assets/docs/theme.doc.zh.mjs b/packages/cli/assets/docs/theme.doc.zh.mjs
index c2619a7cc5..ef6a06abcc 100644
--- a/packages/cli/assets/docs/theme.doc.zh.mjs
+++ b/packages/cli/assets/docs/theme.doc.zh.mjs
@@ -11,7 +11,7 @@ export const docsZh = {
content: [
{
type: 'prose',
- text: '安装主题包,用 `<Theme>` 包裹应用,选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。',
+ text: "安装主题包,用 `<Theme>`(`import {Theme} from '@astryxdesign/core'`)包裹应用,选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。",
},
],
},
diff --git a/packages/cli/assets/docs/use-a-theme.doc.mjs b/packages/cli/assets/docs/use-a-theme.doc.mjs
index 9b43c97b0c..32155d4b7d 100644
--- a/packages/cli/assets/docs/use-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/use-a-theme.doc.mjs
@@ -31,7 +31,7 @@ export const docs = {
type: 'code',
lang: 'tsx',
label: 'Switch among added themes',
- code: "import {useState} from 'react';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
+ code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
},
{
type: 'prose',
diff --git a/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs b/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs
index e30e24927c..a438e2a2af 100644
--- a/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs
@@ -353,7 +353,7 @@ describe('theme build adaptations', () => {
expect(rebuiltCss).toContain('light-dark(#111111, #eeeeee)');
expect(rebuiltCss).toContain(':root { color-scheme: light dark; }');
expect(`${rebuilt.stdout}${rebuilt.stderr}`).toContain(
- 'Font "Revision Webfont" is named by this theme but not loaded',
+ '[note] Fonts named but not loaded: "Revision Webfont".',
);
});
diff --git a/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs b/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs
index 3e31d6662a..5e51474b1f 100644
--- a/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs
@@ -72,7 +72,17 @@ function run(args) {
describe('theme command human output is plain ASCII', () => {
it('a standalone build: ok, warning, error, notice, and font help lines', async () => {
- const result = await run(['build', 'ocean.mjs']);
+ const short = await run(['build', 'ocean.mjs']);
+ expect(short.code).toBe(0);
+ expect(short.stdout).toContain(
+ '[note] Fonts named but not loaded: "Inter"',
+ );
+ expect(nonAscii(short)).toEqual([]);
+
+ const result = await runCli(
+ ['--detail', 'full', 'theme', 'build', 'ocean.mjs'],
+ dir,
+ );
expect(result.code).toBe(0);
expect(result.stdout).toContain('[ok] ocean.css');
diff --git a/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs b/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs
new file mode 100644
index 0000000000..ef0d358778
--- /dev/null
+++ b/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs
@@ -0,0 +1,335 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The human report of `astryx theme build`.
+ *
+ * By default the report is one line per built theme, one line naming the
+ * fonts the themes do not load, and a hint. `--detail full` adds the install
+ * example and the font recipe: once for one theme, as the report always had,
+ * and once for a batch instead of once per theme. `--detail compact|brief`
+ * prints the short report without the hint. `--json` and `--check` keep their
+ * output at every detail level.
+ *
+ * `astryx theme build` needs a compiled @astryxdesign/core, so this suite
+ * builds core once via the shared ensureCoreBuilt() helper.
+ */
+
+import {describe, it, expect, beforeAll, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const GOLDEN = path.resolve(import.meta.dirname, '../../../test/__golden__');
+
+const NAMES = [
+ 'amber',
+ 'basil',
+ 'cedar',
+ 'dune',
+ 'ember',
+ 'fjord',
+ 'grove',
+ 'harbor',
+ 'iris',
+ 'juniper',
+ 'kelp',
+ 'lagoon',
+ 'meadow',
+ 'nimbus',
+ 'orchid',
+];
+const BODY_FONTS = [
+ '"Space Grotesk", sans-serif',
+ '"Space Grotesk", sans-serif',
+ 'Figtree, sans-serif',
+ '"JetBrains Mono", monospace',
+ 'system-ui, sans-serif',
+];
+const FILES = NAMES.map(name => `themes/${name}.mjs`);
+const FONT_NOTE =
+ '[note] Fonts named but not loaded: ' +
+ '"Space Grotesk" (amber, basil, fjord, grove, kelp, lagoon), ' +
+ '"JetBrains Mono" (amber, dune, grove, iris, juniper, meadow, nimbus), ' +
+ '"Figtree" (cedar, harbor, meadow). Load them in your app (recipe: astryx docs typography).';
+const HINT = 'Run with --detail full for the install example and font recipe.';
+const OK_LINE =
+ /^\[ok\] themes\/([a-z]+)\.css \(\d+(\.\d+)? KB, \d+ token overrides, \d+ component overrides\)$/;
+
+/** @type {string[]} */
+const dirs = [];
+
+/** A fresh project holding the fifteen theme sources. */
+function project() {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-batch-'));
+ fs.mkdirSync(path.join(dir, 'themes'));
+ NAMES.forEach((name, i) => {
+ /** @type {Record<string, string>} */
+ const tokens = {
+ '--color-bg': `#${[13, 29, 47]
+ .map(n => ((i * n) % 256).toString(16).padStart(2, '0'))
+ .join('')}`,
+ '--font-family-body': BODY_FONTS[i % BODY_FONTS.length],
+ };
+ if (i % 3 === 0) {
+ tokens['--font-family-code'] = '"JetBrains Mono", monospace';
+ }
+ fs.writeFileSync(
+ path.join(dir, 'themes', `${name}.mjs`),
+ `export default ${JSON.stringify({name, tokens})};\n`,
+ );
+ });
+ dirs.push(dir);
+ return dir;
+}
+
+/** @param {string} text @param {string} pattern */
+function count(text, pattern) {
+ return text.split(pattern).length - 1;
+}
+
+/** @param {string} stdout */
+function lines(stdout) {
+ return stdout.split('\n').filter(Boolean);
+}
+
+/** @param {string} stdout The sizes follow Core's CSS, so goldens keep the shape. */
+function normalized(stdout) {
+ return stdout.replace(/\d+(\.\d+)? KB/g, '<size> KB');
+}
+
+/** Bytes of the full report printed by one invocation per theme. */
+async function separateFullReports(dir) {
+ let bytes = 0;
+ for (const file of FILES) {
+ const one = await runCli(['--detail', 'full', 'theme', 'build', file], dir);
+ expect(one.status).toBe(0);
+ expect(one.stdout).toContain('Install in your app');
+ bytes += Buffer.byteLength(one.stdout);
+ }
+ return bytes;
+}
+
+beforeAll(() => {
+ ensureCoreBuilt();
+}, 200_000);
+
+afterEach(() => {
+ for (const dir of dirs.splice(0)) {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+});
+
+describe('theme build report', () => {
+ it('prints one line per theme, one font note and a hint by default', async () => {
+ const dir = project();
+ const batch = await runCli(['theme', 'build', ...FILES], dir);
+ expect(batch.status).toBe(0);
+
+ const out = lines(batch.stdout);
+ expect(out).toHaveLength(NAMES.length + 3);
+ NAMES.forEach((name, i) => {
+ expect(out[i]).toMatch(OK_LINE);
+ expect(out[i]).toContain(`themes/${name}.css`);
+ });
+ expect(out.slice(NAMES.length)).toEqual([
+ FONT_NOTE,
+ HINT,
+ '[ok] Built 15 themes.',
+ ]);
+ expect(batch.stdout).not.toContain('Building theme from');
+ expect(batch.stdout).not.toContain('Install in your app');
+ expect(batch.stdout).not.toContain('fonts.googleapis.com');
+ expect(fs.existsSync(path.join(dir, 'themes', 'orchid.js'))).toBe(true);
+ await expect(normalized(batch.stdout)).toMatchFileSnapshot(
+ path.join(GOLDEN, 'theme-build-batch.txt'),
+ );
+
+ const separate = await separateFullReports(dir);
+ expect(Buffer.byteLength(batch.stdout)).toBeLessThan(separate * 0.1);
+ }, 300_000);
+
+ it('--detail full prints the install example once and each unloaded font once', async () => {
+ const dir = project();
+ const batch = await runCli(
+ ['--detail', 'full', 'theme', 'build', ...FILES],
+ dir,
+ );
+ expect(batch.status).toBe(0);
+ const out = batch.stdout;
+
+ for (const name of NAMES) {
+ expect(out).toContain(`Building theme from themes/${name}.mjs...`);
+ expect(out).toContain(`[ok] themes/${name}.css\n`);
+ expect(out).toContain(
+ ` import { ${name}Theme } from './themes/${name}'; import './themes/${name}.css';`,
+ );
+ }
+ expect(count(out, 'Install in your app')).toBe(1);
+ expect(count(out, 'Or with a <link> tag:')).toBe(1);
+ expect(count(out, "import { Theme } from '@astryxdesign/core';")).toBe(2);
+ expect(count(out, '[note]')).toBe(1);
+ expect(count(out, 'note: Font')).toBe(0);
+ expect(count(out, 'fonts.googleapis.com/css2')).toBe(1);
+ expect(out).toContain(
+ ' "Space Grotesk" (amber, basil, fjord, grove, kelp, lagoon)\n' +
+ ' "JetBrains Mono" (amber, dune, grove, iris, juniper, meadow, nimbus)\n' +
+ ' "Figtree" (cedar, harbor, meadow)\n',
+ );
+ expect(out).toContain(
+ 'family=Space+Grotesk&family=JetBrains+Mono&family=Figtree&display=swap',
+ );
+ expect(out).not.toContain(HINT);
+ expect(out.trimEnd().endsWith('[ok] Built 15 themes.')).toBe(true);
+ await expect(normalized(out)).toMatchFileSnapshot(
+ path.join(GOLDEN, 'theme-build-batch-full.txt'),
+ );
+
+ const separate = await separateFullReports(dir);
+ expect(Buffer.byteLength(out)).toBeLessThan(separate * 0.3);
+ }, 300_000);
+
+ it.each(['compact', 'brief'])(
+ '--detail %s prints the short report without the hint',
+ async detail => {
+ const dir = project();
+ const r = await runCli(
+ ['--detail', detail, 'theme', 'build', ...FILES],
+ dir,
+ );
+ expect(r.status).toBe(0);
+ const out = lines(r.stdout);
+ expect(out).toHaveLength(NAMES.length + 2);
+ NAMES.forEach((_, i) => expect(out[i]).toMatch(OK_LINE));
+ expect(out.slice(NAMES.length)).toEqual([
+ FONT_NOTE,
+ '[ok] Built 15 themes.',
+ ]);
+ },
+ 120_000,
+ );
+
+ it('prints one line for one theme, and a font note only when fonts are missing', async () => {
+ const dir = project();
+ const ember = await runCli(
+ ['--detail', 'brief', 'theme', 'build', 'themes/ember.mjs'],
+ dir,
+ );
+ expect(ember.status).toBe(0);
+ expect(lines(ember.stdout)).toHaveLength(1);
+ expect(ember.stdout).toMatch(
+ /^\[ok\] themes\/ember\.css \(\d+(\.\d+)? KB, 2 token overrides, 0 component overrides\)\n$/,
+ );
+
+ const amber = await runCli(['theme', 'build', 'themes/amber.mjs'], dir);
+ expect(amber.status).toBe(0);
+ expect(lines(amber.stdout).slice(1)).toEqual([
+ '[note] Fonts named but not loaded: "Space Grotesk", "JetBrains Mono". Load them in your app (recipe: astryx docs typography).',
+ HINT,
+ ]);
+ }, 120_000);
+
+ it('--detail full keeps the standalone report for one theme', async () => {
+ const dir = project();
+ const r = await runCli(
+ ['--detail', 'full', 'theme', 'build', 'themes/amber.mjs'],
+ dir,
+ );
+ expect(r.status).toBe(0);
+ expect(r.stdout).toContain('Building theme from themes/amber.mjs...');
+ expect(r.stdout).toContain("import { amberTheme } from './themes/amber';");
+ expect(r.stdout).toContain('Or with a <link> tag:');
+ expect(r.stdout).toContain('note: Font "Space Grotesk"');
+ expect(r.stdout).toContain(
+ '[note] Theme "amber" names fonts it does not load: "Space Grotesk", "JetBrains Mono"',
+ );
+ expect(r.stdout).not.toContain('Each built theme imports the same way');
+ expect(r.stdout).not.toContain(HINT);
+ }, 120_000);
+
+ it('keeps the guidance for themes already written when a batch fails', async () => {
+ const dir = project();
+ fs.writeFileSync(
+ path.join(dir, 'themes', 'broken.mjs'),
+ 'export default {\n',
+ );
+ const files = ['themes/amber.mjs', 'themes/basil.mjs', 'themes/broken.mjs'];
+
+ const short = await runCli(['theme', 'build', ...files], dir);
+ expect(short.status).toBe(1);
+ expect(short.stderr).toContain('themes/broken.mjs: ');
+ expect(short.stdout).toContain(
+ '[note] Fonts named but not loaded: "Space Grotesk" (amber, basil), "JetBrains Mono" (amber).',
+ );
+ expect(short.stdout).not.toContain('Built 3 themes');
+
+ const full = await runCli(
+ ['--detail', 'full', 'theme', 'build', ...files],
+ dir,
+ );
+ expect(full.status).toBe(1);
+ expect(count(full.stdout, 'Install in your app')).toBe(1);
+ expect(full.stdout).toContain(
+ " import { basilTheme } from './themes/basil'; import './themes/basil.css';",
+ );
+ expect(full.stdout).toContain(' "Space Grotesk" (amber, basil)\n');
+ expect(full.stdout).not.toContain('Built 3 themes');
+ }, 120_000);
+
+ it('names the file on each warning in the short report', async () => {
+ const dir = project();
+ fs.writeFileSync(
+ path.join(dir, 'themes', 'warny.mjs'),
+ `export default ${JSON.stringify({
+ name: 'warny',
+ tokens: {'--color-bg': '#123456'},
+ components: {notAComponent: {base: {color: 'red'}}},
+ })};\n`,
+ );
+ const short = await runCli(
+ ['theme', 'build', 'themes/amber.mjs', 'themes/warny.mjs'],
+ dir,
+ );
+ expect(short.status).toBe(0);
+ expect(short.stderr).toMatch(
+ /\[warn\] themes\/warny\.mjs: Unknown component "notAComponent"/,
+ );
+
+ const full = await runCli(
+ ['--detail', 'full', 'theme', 'build', 'themes/warny.mjs'],
+ dir,
+ );
+ expect(full.stderr).toContain(' [warn] Unknown component "notAComponent"');
+ }, 120_000);
+
+ it('keeps --json and --check the same at every detail level', async () => {
+ const dir = project();
+ const plain = await runCli(['--json', 'theme', 'build', ...FILES], dir);
+ expect(plain.status).toBe(0);
+ for (const detail of ['full', 'compact', 'brief']) {
+ const r = await runCli(
+ ['--json', '--detail', detail, 'theme', 'build', ...FILES],
+ dir,
+ );
+ expect(r.status).toBe(0);
+ expect(JSON.parse(r.stdout)).toEqual(JSON.parse(plain.stdout));
+ }
+ expect(
+ JSON.parse(plain.stdout).data.results[0].receipt.data.notices,
+ ).toEqual([
+ 'Font "Space Grotesk" is named by this theme but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)',
+ 'Font "JetBrains Mono" is named by this theme but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)',
+ ]);
+
+ const check = await runCli(['theme', 'build', '--check', ...FILES], dir);
+ expect(check.status).toBe(0);
+ for (const detail of ['full', 'brief']) {
+ const r = await runCli(
+ ['--detail', detail, 'theme', 'build', '--check', ...FILES],
+ dir,
+ );
+ expect(r.stdout).toBe(check.stdout);
+ }
+ }, 180_000);
+});
diff --git a/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjs b/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjs
index 042afe4980..bed176ad7f 100644
--- a/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.font-warning.test.mjs
@@ -2,11 +2,12 @@
/**
* @file End-to-end test for the `astryx theme build` font-loading warning
- * (#5015). A theme that names webfont families gets, AFTER the install
- * instructions, a stdout notice naming the fonts plus the copy-pasteable
- * fix — the Google Fonts <link> pair and a self-hosted @font-face with
- * font-display: swap — and still exits 0 (it is a warning, not an error).
- * Themes that only name generics or known system stacks get none of it.
+ * (#5015). A theme that names webfont families gets a one-line stdout notice
+ * naming the fonts; with `--detail full` it gets, AFTER the install
+ * instructions, the copy-pasteable fix — the Google Fonts <link> pair and a
+ * self-hosted @font-face with font-display: swap. It still exits 0 (it is a
+ * warning, not an error). Themes that only name generics or known system
+ * stacks get none of it.
*/
import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
@@ -54,7 +55,7 @@ describe('theme build font-loading warning', () => {
);
const result = await runCli(
- ['theme', 'build', path.relative(project, themeFile)],
+ ['--detail', 'full', 'theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -84,6 +85,34 @@ describe('theme build font-loading warning', () => {
expect(result.stderr).not.toContain('Font "');
});
+ it('names the unloaded fonts in one line by default', async () => {
+ const project = path.join(tmpDir, 'project');
+ const themeFile = writeTheme(
+ project,
+ 'fonty',
+ `export default {
+ name: 'fonty',
+ typography: {
+ body: {family: 'Space Grotesk', fallbacks: 'Arial, sans-serif'},
+ code: {family: 'JetBrains Mono'},
+ },
+};\n`,
+ );
+
+ const result = await runCli(
+ ['theme', 'build', path.relative(project, themeFile)],
+ project,
+ );
+
+ expect(result.code).toBe(0);
+ expect(result.stdout).toContain(
+ '[note] Fonts named but not loaded: "Space Grotesk", "JetBrains Mono". Load them in your app (recipe: astryx docs typography).\n',
+ );
+ expect(result.stdout).not.toContain('fonts.googleapis.com');
+ expect(result.stdout).not.toContain('@font-face');
+ expect(result.stdout).toContain('Run with --detail full');
+ });
+
it('keeps --json stdout one valid envelope: notices inside, snippet suppressed', async () => {
const project = path.join(tmpDir, 'project');
const themeFile = writeTheme(
@@ -127,7 +156,7 @@ describe('theme build font-loading warning', () => {
);
const result = await runCli(
- ['theme', 'build', path.relative(project, themeFile)],
+ ['--detail', 'full', 'theme', 'build', path.relative(project, themeFile)],
project,
);
diff --git a/packages/cli/clients/cli/commands/build-theme.import-path.test.mjs b/packages/cli/clients/cli/commands/build-theme.import-path.test.mjs
index 60a3b21341..e8b2d5cc6a 100644
--- a/packages/cli/clients/cli/commands/build-theme.import-path.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.import-path.test.mjs
@@ -52,7 +52,7 @@ describe('theme build install-instructions import path', () => {
const themeFile = writeTheme(project, 'cwd-theme');
const result = await runCli(
- ['theme', 'build', path.relative(project, themeFile)],
+ ['--detail', 'full', 'theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -70,7 +70,7 @@ describe('theme build install-instructions import path', () => {
const themeFile = writeTheme(path.join(project, 'themes'), 'sub-theme');
const result = await runCli(
- ['theme', 'build', path.relative(project, themeFile)],
+ ['--detail', 'full', 'theme', 'build', path.relative(project, themeFile)],
project,
);
@@ -89,7 +89,7 @@ describe('theme build install-instructions import path', () => {
);
const result = await runCli(
- ['theme', 'build', path.relative(project, themeFile)],
+ ['--detail', 'full', 'theme', 'build', path.relative(project, themeFile)],
project,
);
diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjs
index 72ad3d5e16..ba8aca66ed 100644
--- a/packages/cli/clients/cli/commands/build-theme.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.mjs
@@ -63,8 +63,11 @@ import {
} from '../../../api/theme/palette/generate/generate.mjs';
import {
importSpecifier,
+ printBatchTrailer,
+ printCompactTrailer,
themeBuild,
themeBuildFamily,
+ themeBuildForReport,
} from '../../../api/theme/build/build.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
@@ -105,13 +108,17 @@ function resolveCliBin() {
* Resolves with the child's exit code; never rejects.
*
* @param {string} file - The theme file argument, as the user passed it.
- * @param {{out?: string, iconsSpecifier?: string}} options - Parsed command
- * options that affect generated output.
+ * @param {{out?: string, iconsSpecifier?: string, detail?: string}} options -
+ * Parsed command options that affect generated output, plus the detail
+ * level the user chose.
* @returns {Promise<number>}
*/
function runThemeBuildOnceChild(file, options) {
const cliBin = resolveCliBin();
- const args = [cliBin, 'theme', 'build', file];
+ // A detail level the user chose applies to every rebuild.
+ const args = options.detail
+ ? [cliBin, '--detail', options.detail, 'theme', 'build', file]
+ : [cliBin, 'theme', 'build', file];
if (options.out) args.push('--out', options.out);
if (options.iconsSpecifier)
args.push('--icons-specifier', options.iconsSpecifier);
@@ -135,7 +142,7 @@ function runThemeBuildOnceChild(file, options) {
*
* @param {Array<{file: string, filePath: string}>} entries - The theme file
* arguments as the user passed them, with their resolved absolute paths.
- * @param {{out?: string, iconsSpecifier?: string}} options - Parsed command options.
+ * @param {{out?: string, iconsSpecifier?: string, detail?: string}} options - Parsed command options, plus the detail level the user chose.
* @returns {Promise<void>} Resolves when the watcher is stopped (Ctrl-C).
*/
async function runThemeBuildWatch(entries, options) {
@@ -534,6 +541,13 @@ export function registerTheme(program) {
/** @type {{out?: string, watch?: boolean, check?: boolean, iconsSpecifier?: string, family?: boolean, familyKey?: string}} */ options,
) => {
const json = program.opts().json || false;
+ // The report is one line per theme unless the user asks for
+ // `--detail full`, which prints the install example and the font
+ // guidance: once for one theme, as it always has, and once for the whole
+ // batch rather than per theme.
+ const detailChosen = program.getOptionValueSource('detail') !== 'default';
+ const detail = detailChosen ? program.opts().detail : undefined;
+ const compact = detail !== 'full';
const entries = files.map(file => ({
file,
filePath: path.resolve(process.cwd(), file),
@@ -609,7 +623,7 @@ export function registerTheme(program) {
code: ERROR_CODES.ERR_THEME_INVALID,
});
}
- await runThemeBuildWatch(entries, options);
+ await runThemeBuildWatch(entries, {...options, detail});
return NO_RESULT_SET;
}
@@ -646,20 +660,44 @@ export function registerTheme(program) {
}
}
+ // --json and --check keep their own output at every detail level.
+ const report = !json && !options.check && (entries.length > 1 || compact);
+ /** @type {import('../../../api/theme/build/build.mjs').ThemeBuildTrailer[]} */
+ const trailers = [];
+
/** @type {Array<{file: string, receipt: import('../../../api/theme/theme.type.mjs').ThemeBuildResponse | import('../../../api/theme/theme.type.mjs').ThemeBuildCheckResponse | null}>} */
const results = [];
let stale = false;
for (const entry of entries) {
try {
- const result = await themeBuild(
- entry.file,
- {
- out: options.out,
- check: options.check,
- iconsSpecifier: options.iconsSpecifier,
- },
- {cwd: process.cwd()},
- );
+ const buildOptions = {
+ out: options.out,
+ check: options.check,
+ iconsSpecifier: options.iconsSpecifier,
+ };
+ let result;
+ if (report) {
+ const built = await themeBuildForReport(
+ entry.file,
+ buildOptions,
+ {cwd: process.cwd()},
+ {compact},
+ );
+ result = built.receipt;
+ if (built.trailer) trailers.push(built.trailer);
+ if (compact && result?.type === 'theme.build') {
+ const {outputs, sizeKB, tokenCount, componentCount} = result.data;
+ emit(
+ text(
+ `[ok] ${outputs.css} (${sizeKB} KB, ${tokenCount} token overrides, ${componentCount} component overrides)`,
+ ),
+ );
+ }
+ } else {
+ result = await themeBuild(entry.file, buildOptions, {
+ cwd: process.cwd(),
+ });
+ }
results.push({file: entry.file, receipt: result ?? null});
if (
options.check &&
@@ -674,7 +712,10 @@ export function registerTheme(program) {
/** @type {import('../../../api/error.mjs').AstryxError} */ (e);
// Stop at the first failure, as a shell loop under `set -e` does.
// With several themes in flight the message alone rarely says which
- // one broke, so name it.
+ // one broke, so name it. Themes already written keep their install
+ // and font guidance.
+ if (report && compact) printCompactTrailer(trailers);
+ else if (report) printBatchTrailer(trailers);
return cliError(
entries.length > 1 ? `${entry.file}: ${err.message}` : err.message,
{suggestions: err.suggestions, code: err.code},
@@ -695,7 +736,14 @@ export function registerTheme(program) {
};
jsonOut(batch);
}
- } else if (entries.length > 1) {
+ } else {
+ if (report && compact) {
+ printCompactTrailer(trailers, {hint: !detailChosen});
+ } else if (report) {
+ printBatchTrailer(trailers);
+ }
+ }
+ if (!json && entries.length > 1) {
emit(
text(
options.check
diff --git a/packages/cli/clients/cli/commands/build-theme.watch.test.mjs b/packages/cli/clients/cli/commands/build-theme.watch.test.mjs
index 49fb2db0f3..14d494b5e6 100644
--- a/packages/cli/clients/cli/commands/build-theme.watch.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.watch.test.mjs
@@ -157,6 +157,39 @@ describe('theme build --watch', () => {
expect(stdout).toMatch(/Stopped watching/);
}, 30_000);
+ it.each([
+ [[], false],
+ [['--detail', 'full'], true],
+ ])(
+ 'keeps the detail level for each build (%j)',
+ async (detail, full) => {
+ fs.writeFileSync(
+ path.join(tmpDir, 'wd.mjs'),
+ `export default { name: 'wd', tokens: { '--color-bg': '#ffffff' } };\n`,
+ );
+ const child = spawn(
+ process.execPath,
+ [CLI_BIN, ...detail, 'theme', 'build', 'wd.mjs', '--watch'],
+ {cwd: tmpDir, env: {...process.env, FORCE_COLOR: '0'}},
+ );
+ let stdout = '';
+ child.stdout.on('data', d => (stdout += d.toString()));
+ child.stderr.on('data', d => (stdout += d.toString()));
+ try {
+ expect(await waitFor(() => /Watching/i.test(stdout))).toBe(true);
+ } finally {
+ child.kill('SIGINT');
+ }
+ await new Promise(resolve => {
+ child.on('exit', resolve);
+ setTimeout(resolve, 4000);
+ });
+ expect(stdout.includes('Install in your app')).toBe(full);
+ expect(/\[ok\] wd\.css \(/.test(stdout)).toBe(!full);
+ },
+ 30_000,
+ );
+
it('watches every file it was given and rebuilds only the one that changed', async () => {
const first = path.join(tmpDir, 'w1.mjs');
const second = path.join(tmpDir, 'w2.mjs');
diff --git a/packages/cli/clients/cli/commands/theme-build.doc.mjs b/packages/cli/clients/cli/commands/theme-build.doc.mjs
index d008038fd4..a1c86a6ab1 100644
--- a/packages/cli/clients/cli/commands/theme-build.doc.mjs
+++ b/packages/cli/clients/cli/commands/theme-build.doc.mjs
@@ -21,7 +21,9 @@ export const doc = {
'theme. --family combines one selected extension tree into the three files named by ' +
'the required --family-key, ready for one CSS load and identity-only switching. ' +
'With --check it writes nothing and reports source drift. --icons-specifier keeps ' +
- 'its existing generated-module behavior.',
+ 'its existing generated-module behavior. It prints one line per built theme and ' +
+ 'one line naming fonts the themes do not load; --detail full adds the install ' +
+ 'example and the font recipe, once for a batch.',
fn: 'themeBuild',
args: [{name: 'files', param: 'file', required: true, variadic: true}],
options: [
diff --git a/packages/cli/clients/cli/index.mjs b/packages/cli/clients/cli/index.mjs
index cde360e5a7..d0e8bb62d8 100644
--- a/packages/cli/clients/cli/index.mjs
+++ b/packages/cli/clients/cli/index.mjs
@@ -362,7 +362,7 @@ export async function createProgram() {
.addOption(
new Option(
'--detail <level>',
- 'Detail level for component, hook, and docs tree reads (e.g. docs cli/commands/build). Lists default to brief',
+ 'Detail level for component, hook, and docs tree reads (e.g. docs cli/commands/build), and for theme build reports. Lists default to brief; theme build prints one line per built theme unless full, which adds the install example and font recipe',
)
.choices(['full', 'compact', 'brief'])
.default('full'),
diff --git a/packages/cli/test/__golden__/theme-build-batch-full.txt b/packages/cli/test/__golden__/theme-build-batch-full.txt
new file mode 100644
index 0000000000..a6e385aceb
--- /dev/null
+++ b/packages/cli/test/__golden__/theme-build-batch-full.txt
@@ -0,0 +1,198 @@
+
+Building theme from themes/amber.mjs...
+
+[ok] themes/amber.css
+[ok] themes/amber.css.d.ts
+ 3 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/amber.js
+[ok] themes/amber.d.ts
+
+Building theme from themes/basil.mjs...
+
+[ok] themes/basil.css
+[ok] themes/basil.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/basil.js
+[ok] themes/basil.d.ts
+
+Building theme from themes/cedar.mjs...
+
+[ok] themes/cedar.css
+[ok] themes/cedar.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/cedar.js
+[ok] themes/cedar.d.ts
+
+Building theme from themes/dune.mjs...
+
+[ok] themes/dune.css
+[ok] themes/dune.css.d.ts
+ 3 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/dune.js
+[ok] themes/dune.d.ts
+
+Building theme from themes/ember.mjs...
+
+[ok] themes/ember.css
+[ok] themes/ember.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/ember.js
+[ok] themes/ember.d.ts
+
+Building theme from themes/fjord.mjs...
+
+[ok] themes/fjord.css
+[ok] themes/fjord.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/fjord.js
+[ok] themes/fjord.d.ts
+
+Building theme from themes/grove.mjs...
+
+[ok] themes/grove.css
+[ok] themes/grove.css.d.ts
+ 3 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/grove.js
+[ok] themes/grove.d.ts
+
+Building theme from themes/harbor.mjs...
+
+[ok] themes/harbor.css
+[ok] themes/harbor.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/harbor.js
+[ok] themes/harbor.d.ts
+
+Building theme from themes/iris.mjs...
+
+[ok] themes/iris.css
+[ok] themes/iris.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/iris.js
+[ok] themes/iris.d.ts
+
+Building theme from themes/juniper.mjs...
+
+[ok] themes/juniper.css
+[ok] themes/juniper.css.d.ts
+ 3 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/juniper.js
+[ok] themes/juniper.d.ts
+
+Building theme from themes/kelp.mjs...
+
+[ok] themes/kelp.css
+[ok] themes/kelp.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/kelp.js
+[ok] themes/kelp.d.ts
+
+Building theme from themes/lagoon.mjs...
+
+[ok] themes/lagoon.css
+[ok] themes/lagoon.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/lagoon.js
+[ok] themes/lagoon.d.ts
+
+Building theme from themes/meadow.mjs...
+
+[ok] themes/meadow.css
+[ok] themes/meadow.css.d.ts
+ 3 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/meadow.js
+[ok] themes/meadow.d.ts
+
+Building theme from themes/nimbus.mjs...
+
+[ok] themes/nimbus.css
+[ok] themes/nimbus.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/nimbus.js
+[ok] themes/nimbus.d.ts
+
+Building theme from themes/orchid.mjs...
+
+[ok] themes/orchid.css
+[ok] themes/orchid.css.d.ts
+ 2 token overrides, 0 component overrides
+ <size> KB
+[ok] themes/orchid.js
+[ok] themes/orchid.d.ts
+
+Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
+
+ import { Theme } from '@astryxdesign/core';
+ import { amberTheme } from './themes/amber';
+ import './themes/amber.css';
+
+ <Theme theme={amberTheme}>
+ <App />
+ </Theme>
+
+Or with a <link> tag:
+
+ import { Theme } from '@astryxdesign/core';
+ import { amberTheme } from './themes/amber';
+
+ <link rel="stylesheet" href="./themes/amber.css" />
+ <Theme theme={amberTheme}>
+ <App />
+ </Theme>
+
+Each built theme imports the same way:
+ import { amberTheme } from './themes/amber'; import './themes/amber.css';
+ import { basilTheme } from './themes/basil'; import './themes/basil.css';
+ import { cedarTheme } from './themes/cedar'; import './themes/cedar.css';
+ import { duneTheme } from './themes/dune'; import './themes/dune.css';
+ import { emberTheme } from './themes/ember'; import './themes/ember.css';
+ import { fjordTheme } from './themes/fjord'; import './themes/fjord.css';
+ import { groveTheme } from './themes/grove'; import './themes/grove.css';
+ import { harborTheme } from './themes/harbor'; import './themes/harbor.css';
+ import { irisTheme } from './themes/iris'; import './themes/iris.css';
+ import { juniperTheme } from './themes/juniper'; import './themes/juniper.css';
+ import { kelpTheme } from './themes/kelp'; import './themes/kelp.css';
+ import { lagoonTheme } from './themes/lagoon'; import './themes/lagoon.css';
+ import { meadowTheme } from './themes/meadow'; import './themes/meadow.css';
+ import { nimbusTheme } from './themes/nimbus'; import './themes/nimbus.css';
+ import { orchidTheme } from './themes/orchid'; import './themes/orchid.css';
+
+[note] The built themes name fonts they do not load:
+ "Space Grotesk" (amber, basil, fjord, grove, kelp, lagoon)
+ "JetBrains Mono" (amber, dune, grove, iris, juniper, meadow, nimbus)
+ "Figtree" (cedar, harbor, meadow)
+ The built CSS only sets font-family; load these in your app, or every
+ browser quietly falls back.
+
+ Google Fonts (add :wght@... axes as your theme's weights require):
+
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Space+Grotesk&family=JetBrains+Mono&family=Figtree&display=swap" />
+
+ Self-hosted (repeat per family and weight):
+
+ @font-face {
+ font-family: "Space Grotesk";
+ src: url('/fonts/space-grotesk.woff2') format('woff2');
+ font-display: swap;
+ }
+
+ Recipe and fallback-stack guidance: astryx docs typography
+
+
+[ok] Built 15 themes.
diff --git a/packages/cli/test/__golden__/theme-build-batch.txt b/packages/cli/test/__golden__/theme-build-batch.txt
new file mode 100644
index 0000000000..59e5ccd9f4
--- /dev/null
+++ b/packages/cli/test/__golden__/theme-build-batch.txt
@@ -0,0 +1,19 @@
+[ok] themes/amber.css (<size> KB, 3 token overrides, 0 component overrides)
+[ok] themes/basil.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/cedar.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/dune.css (<size> KB, 3 token overrides, 0 component overrides)
+[ok] themes/ember.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/fjord.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/grove.css (<size> KB, 3 token overrides, 0 component overrides)
+[ok] themes/harbor.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/iris.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/juniper.css (<size> KB, 3 token overrides, 0 component overrides)
+[ok] themes/kelp.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/lagoon.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/meadow.css (<size> KB, 3 token overrides, 0 component overrides)
+[ok] themes/nimbus.css (<size> KB, 2 token overrides, 0 component overrides)
+[ok] themes/orchid.css (<size> KB, 2 token overrides, 0 component overrides)
+[note] Fonts named but not loaded: "Space Grotesk" (amber, basil, fjord, grove, kelp, lagoon), "JetBrains Mono" (amber, dune, grove, iris, juniper, meadow, nimbus), "Figtree" (cedar, harbor, meadow). Load them in your app (recipe: astryx docs typography).
+Run with --detail full for the install example and font recipe.
+
+[ok] Built 15 themes.
diff --git a/packages/cli/test/taught-core-imports.test.mjs b/packages/cli/test/taught-core-imports.test.mjs
index f4e3a43f64..b71f31582e 100644
--- a/packages/cli/test/taught-core-imports.test.mjs
+++ b/packages/cli/test/taught-core-imports.test.mjs
@@ -8,7 +8,8 @@
* names a subpath Core does not export, or names it with the wrong case, fails
* in the user's app, so every specifier must match an entry in Core's
* package.json `exports`. Wherever command output shows the `<Theme>` wrapper,
- * it also shows where `Theme` comes from.
+ * it also shows where `Theme` comes from, and so does every doc page that shows
+ * it.
*
* @position packages/cli/test — taught imports
*/
@@ -16,6 +17,7 @@
import {describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
const CLI = path.resolve(import.meta.dirname, '..');
const CORE_PACKAGE = path.resolve(CLI, '..', 'core', 'package.json');
@@ -62,6 +64,25 @@ function isExported(keys, subpath) {
});
}
+const THEME_IMPORT =
+ /\{\s*Theme\s*\}\s+from\s+'@astryxdesign\/core(?:\/theme)?'/;
+
+/**
+ * Every code block (`{type: 'code', code}`) reachable from a doc module.
+ * @param {unknown} value
+ * @param {string[]} [found]
+ * @returns {string[]}
+ */
+function codeBlocks(value, found = [], seen = new Set()) {
+ if (!value || typeof value !== 'object' || seen.has(value)) return found;
+ seen.add(value);
+ const node = /** @type {Record<string, unknown>} */ (value);
+ if (node.type === 'code' && typeof node.code === 'string')
+ found.push(node.code);
+ for (const child of Object.values(node)) codeBlocks(child, found, seen);
+ return found;
+}
+
/** @param {string} source */
function coreSpecifiers(source) {
return [
@@ -130,4 +151,31 @@ describe('taught @astryxdesign/core imports', () => {
});
},
);
+ it('every doc page that shows the <Theme> wrapper shows where Theme comes from', () => {
+ const pages = docFiles(path.join(CLI, 'assets', 'docs')).filter(file =>
+ /<Theme[\s>]/.test(fs.readFileSync(file, 'utf8')),
+ );
+ expect(pages.length).toBeGreaterThan(0);
+ const missing = pages
+ .filter(file => !THEME_IMPORT.test(fs.readFileSync(file, 'utf8')))
+ .map(file => path.relative(CLI, file));
+ expect(missing).toEqual([]);
+ });
+
+ it('every doc example with imports and the wrapper imports Theme', async () => {
+ /** @type {string[]} */
+ const missing = [];
+ for (const file of docFiles(path.join(CLI, 'assets', 'docs'))) {
+ const blocks = codeBlocks(await import(pathToFileURL(file).href));
+ for (const block of blocks) {
+ // A continuation snippet (no imports) builds on the page's full example.
+ if (!/<Theme theme=/.test(block) || !/^\s*import\s/m.test(block))
+ continue;
+ if (!THEME_IMPORT.test(block)) {
+ missing.push(`${path.relative(CLI, file)}: ${block.split('\n')[0]}`);
+ }
+ }
+ }
+ expect(missing).toEqual([]);
+ });
});