Skip to content

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

TypeScript

fix(cli): the unloaded-font advisory is a notice, not a warning (#5090)

Cindy Zhangda6ea6710bd9
diff --git a/.changeset/font-advisory-is-a-notice.md b/.changeset/font-advisory-is-a-notice.md
new file mode 100644
index 0000000000..cc46ec3bff
--- /dev/null
+++ b/.changeset/font-advisory-is-a-notice.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] The unloaded-font advisory is a notice, not a warning. A theme file cannot load a font — Astryx sets `--font-family-*` and loading is the app's job — so #5045's advisory fires on any theme naming a webfont, including a perfectly correct one. As a warning that made a clean build read as defective, and it put the shipped template permanently in violation of its own "compiles with no warnings" guard (#5079 had to allowlist the template's two font names in that assertion).
+
+The `theme.build` receipt now separates the two: `warnings` are defects the author should fix, `notices` are advisories about a correct theme. The font advisory moves to `notices` and to stdout with the rest of the build's progress; stderr stays for defects. The template guard is back to `warnings` being empty, and no longer needs to know which fonts the template names.
+
+Programmatic callers reading `data.warnings` for font advisories should read `data.notices`; the message text is unchanged.
+
+@cixzhang
diff --git a/packages/cli/api/theme/build/build.font-warning.test.mjs b/packages/cli/api/theme/build/build.font-warning.test.mjs
index ae925b4562..148419ac41 100644
--- a/packages/cli/api/theme/build/build.font-warning.test.mjs
+++ b/packages/cli/api/theme/build/build.font-warning.test.mjs
@@ -1,13 +1,18 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * API-contract tests for the font-loading warning in `themeBuild()` (#5015):
+ * API-contract tests for the font-loading advisory in `themeBuild()` (#5015):
* a theme that names font families it does not load gets one entry per family
- * in the `theme.build` receipt's `warnings` array, on BOTH load paths — a raw
+ * in the `theme.build` receipt's `notices` array, on BOTH load paths — a raw
* typography config (resolved through core's defineTheme) and an
* already-resolved theme that sets `--font-family-*` tokens directly. Themes
- * that only name generics or known system families warn about nothing, and
- * the warning never breaks the API's silence contract (default noopLogger).
+ * that only name generics or known system families say nothing, and the
+ * advisory never breaks the API's silence contract (default noopLogger).
+ *
+ * `notices`, not `warnings`: a theme file cannot load a font — that is the
+ * app's job by design — so this fires on correct themes and is context, not a
+ * defect to fix. Every assertion here also pins it OUT of `warnings`, since
+ * the whole point is that a good theme builds warning-free.
*
* Needs a built core — the `node` project's globalSetup
* (vitest.global-setup.node.mjs) builds it once before workers fork.
@@ -45,15 +50,16 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
const result = await themeBuild('fonty.mjs', {}, {cwd: tmpDir});
expect(result?.type).toBe('theme.build');
- const warnings = result?.data.warnings ?? [];
- expect(warnings).toEqual(
+ const notices = result?.data.notices ?? [];
+ expect(notices).toEqual(
expect.arrayContaining([
expect.stringContaining('Font "Space Grotesk"'),
expect.stringContaining('Font "JetBrains Mono"'),
]),
);
- // Heading inherits body's family; the shared family warns exactly once.
- expect(warnings.filter(w => w.includes('Space Grotesk'))).toHaveLength(1);
+ // Heading inherits body's family; the shared family is named exactly once.
+ expect(notices.filter(w => w.includes('Space Grotesk'))).toHaveLength(1);
+ expect(result?.data.warnings).toEqual([]);
});
it('warns for an already-resolved theme: font-family tokens and component overrides, nothing else', async () => {
@@ -74,13 +80,14 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
// Exactly the two named families — a non-family --font-* token must not
// produce a bogus "Font \\"1rem\\"" entry, and the components half of the
// feature must survive the real themeBuild path, not just the unit helper.
- const fontWarnings = (result?.data.warnings ?? []).filter(w =>
+ const fontNotices = (result?.data.notices ?? []).filter(w =>
w.startsWith('Font "'),
);
- expect(fontWarnings).toEqual([
+ expect(fontNotices).toEqual([
expect.stringContaining('Font "Bungee"'),
expect.stringContaining('Font "Orbitron"'),
]);
+ expect(result?.data.warnings).toEqual([]);
});
it('warns for a family named only inside a pseudo-class component override (defineTheme path)', async () => {
@@ -102,13 +109,14 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
const result = await themeBuild('pseudo.mjs', {}, {cwd: tmpDir});
- const fontWarnings = (result?.data.warnings ?? []).filter(w =>
+ const fontNotices = (result?.data.notices ?? []).filter(w =>
w.startsWith('Font "'),
);
// Exactly the hidden family — Helvetica/Arial are system fonts.
- expect(fontWarnings).toEqual([
+ expect(fontNotices).toEqual([
expect.stringContaining('Font "Rubik Doodle"'),
]);
+ expect(result?.data.warnings).toEqual([]);
});
it('warns about nothing when every named family is a generic or known system font', async () => {
@@ -126,10 +134,11 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
const result = await themeBuild('sys.mjs', {}, {cwd: tmpDir});
expect(result?.type).toBe('theme.build');
+ expect(result?.data.notices).toEqual([]);
expect(result?.data.warnings).toEqual([]);
});
- it('stays silent under the default noopLogger even when font warnings fire', async () => {
+ it('stays silent under the default noopLogger even when font notices fire', async () => {
fs.writeFileSync(
path.join(tmpDir, 'loud.mjs'),
`export default { name: 'loud', tokens: { '--font-family-body': '"Orbitron", sans-serif' } };\n`,
@@ -144,7 +153,7 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
try {
const result = await themeBuild('loud.mjs', {}, {cwd: tmpDir});
- expect(result?.data.warnings).toEqual(
+ expect(result?.data.notices).toEqual(
expect.arrayContaining([expect.stringContaining('Font "Orbitron"')]),
);
expect(logSpy).not.toHaveBeenCalled();
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index b2991d1a77..1933163f95 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -1114,6 +1114,8 @@ export async function themeBuild(
// Validate component overrides
const warnings = await validateComponentOverrides(themeDef);
const warningMessages = [];
+ /** Advisories about a correct theme — see the `notices` note on the receipt. */
+ const noticeMessages = [];
for (const w of warnings) {
warningMessages.push(w);
logger.warn(` ⚠ ${w}`);
@@ -1412,11 +1414,18 @@ Or with a <link> tag:
// Fonts the theme names but nothing loads (#5015). Resolved tokens and
// component overrides carry the final font-family values on both load
// paths, so this sees jiti-resolved and legacy themes alike.
+ //
+ // A NOTICE, not a warning: naming a font a theme file cannot load is how
+ // the API is meant to be used — Astryx sets `--font-family-*` and loading
+ // is the app's job, which no theme can do for it. So this fires on any
+ // theme with a webfont, including a perfect one, and as a warning it made
+ // every such build read as defective (it also put the shipped template
+ // permanently in violation of its own "compiles with no warnings" guard).
const unloadedFonts = collectUnloadedFonts(resolvedTheme);
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)`;
- warningMessages.push(msg);
- logger.warn(` ⚠ ${msg}`);
+ noticeMessages.push(msg);
+ logger.log(` note: ${msg}`);
}
if (unloadedFonts.length > 0) {
logger.log(formatFontLoadingHelp(themeDef.name, unloadedFonts));
@@ -1438,6 +1447,7 @@ Or with a <link> tag:
: {}),
},
warnings: warningMessages,
+ notices: noticeMessages,
},
};
}
diff --git a/packages/cli/api/theme/build/build.test.mjs b/packages/cli/api/theme/build/build.test.mjs
index 47b469d20f..3cb722c2f4 100644
--- a/packages/cli/api/theme/build/build.test.mjs
+++ b/packages/cli/api/theme/build/build.test.mjs
@@ -299,11 +299,10 @@ describe('themeBuild() — component override validation', () => {
describe('themeBuild() — the shipped theme template', () => {
// `assets/theme.template.ts` is what `astryx theme template` puts in a
// consumer's project. It is the one theme file we hand out, so it has to
- // compile as shipped — and cleanly apart from the font warnings it earns on
- // purpose: a template that greets its first reader with warnings teaches them
- // to ignore warnings. The claims its comments make are checked separately by
- // scripts/check-theme-template.test.mjs.
- it('compiles as shipped, warning only about the fonts it deliberately names', async () => {
+ // compile as shipped — and cleanly: a template that greets its first reader
+ // with warnings teaches them to ignore warnings. The claims its comments make
+ // are checked separately by scripts/check-theme-template.test.mjs.
+ it('compiles as shipped, with no warnings', async () => {
const src = path.resolve(
import.meta.dirname,
'../../../assets/theme.template.ts',
@@ -312,14 +311,12 @@ describe('themeBuild() — the shipped theme template', () => {
const result = await themeBuild('theme.template.ts', {}, {cwd: tmpDir});
- // The template names Inter and Geist Mono to teach "SHIP THE FONTS YOU
- // NAME", and loads neither — so the unloaded-font warning firing here is
- // the lesson landing, not a defect. Any OTHER warning still fails.
- const unexpected = (result?.data.warnings ?? []).filter(
- w => !/^Font "(Inter|Geist Mono)" is named by this theme but not loaded/.test(w),
- );
- expect(unexpected).toEqual([]);
- expect(result?.data.warnings).toHaveLength(2);
+ expect(result?.data.warnings).toEqual([]);
+ // It DOES name Inter and Geist Mono without loading them, to teach "SHIP
+ // THE FONTS YOU NAME" — advisories about a correct file, which is why they
+ // are notices. Asserted here so moving them out of `warnings` cannot
+ // quietly become dropping them.
+ expect(result?.data.notices).toHaveLength(2);
expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);
// The template teaches custom variants; the augmentation it promises the
// reader has to actually be generated.
diff --git a/packages/cli/api/theme/theme.type.mjs b/packages/cli/api/theme/theme.type.mjs
index 5b2f9b71d3..fd84d60232 100644
--- a/packages/cli/api/theme/theme.type.mjs
+++ b/packages/cli/api/theme/theme.type.mjs
@@ -22,7 +22,10 @@
* xds --json theme build <file>
* @typedef {object} ThemeBuildResponse
* @property {'theme.build'} type
- * @property {{name: string, tokenCount: number, componentCount: number, sizeKB: number, outputs: {css: string, js: string, dts: string, variantsDts?: string}, warnings: string[]}} data
+ * `warnings` are defects the theme author should fix. `notices` are advisories
+ * about a correct theme — most of them cannot be fixed in a theme file at all,
+ * so folding them into `warnings` makes a clean build look dirty.
+ * @property {{name: string, tokenCount: number, componentCount: number, sizeKB: number, outputs: {css: string, js: string, dts: string, variantsDts?: string}, warnings: string[], notices: string[]}} data
*/
/**
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 0b60c29799..042afe4980 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
@@ -75,13 +75,16 @@ describe('theme build font-loading warning', () => {
expect(result.stdout).toContain('@font-face');
expect(result.stdout).toContain('font-display: swap');
expect(result.stdout).toContain('astryx docs typography');
- // The one-line summaries follow the CLI's stream contract: warnings on
- // stderr, like the override-validation warnings in the same build.
- expect(result.stderr).toContain('Font "Space Grotesk"');
- expect(result.stderr).toContain('Font "JetBrains Mono"');
+ // The one-line summaries follow the CLI's stream contract. These are
+ // NOTICES about a correct theme, not warnings, so they go to stdout with
+ // the rest of the build's progress — stderr stays for the defects an
+ // author has to fix.
+ expect(result.stdout).toContain('note: Font "Space Grotesk"');
+ expect(result.stdout).toContain('note: Font "JetBrains Mono"');
+ expect(result.stderr).not.toContain('Font "');
});
- it('keeps --json stdout one valid envelope: warnings inside, snippet suppressed', async () => {
+ it('keeps --json stdout one valid envelope: notices inside, snippet suppressed', async () => {
const project = path.join(tmpDir, 'project');
const themeFile = writeTheme(
project,
@@ -100,7 +103,7 @@ describe('theme build font-loading warning', () => {
// contract, not just substring presence.
const envelope = JSON.parse(result.stdout);
expect(envelope.type).toBe('theme.build');
- expect(envelope.data.warnings).toEqual(
+ expect(envelope.data.notices).toEqual(
expect.arrayContaining([expect.stringContaining('Font "Space Grotesk"')]),
);
expect(result.stdout).not.toContain('fonts.googleapis.com');