@astryxdesign/cli 0.4.1 → 0.4.2-canary.356d2f9

package/api/theme/build/font-warning.test.mjs

@@ -0,0 +1,242 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Unit tests for the font-loading warning helpers behind `astryx theme build`
+ * (#5015). `collectUnloadedFonts()` reads a RESOLVED theme — `--font-family-*`
+ * tokens plus component-override `fontFamily` values (typography configs are
+ * already collapsed into tokens by the time the build sees the theme) — and
+ * returns the families the theme names but nothing loads. CSS generics,
+ * CSS-wide keywords, `var()` references, and known preinstalled system
+ * families are treated as loaded; anything unrecognized is assumed to be a
+ * webfont, because a missed warning is worse than a spurious one.
+ * `formatFontLoadingHelp()` renders the human snippet (<link> pair +
+ * @font-face) printed after the install instructions.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {collectUnloadedFonts, formatFontLoadingHelp} from './font-warning.mjs';
+
+describe('collectUnloadedFonts', () => {
+  it('returns webfont families from font-family tokens, skipping known fallbacks', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': '"Fraunces", Georgia, serif'},
+      }),
+    ).toEqual(['Fraunces']);
+  });
+
+  it('returns nothing for the default system stacks', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body':
+            '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+          '--font-family-code': '"SF Mono", Monaco, Consolas, monospace',
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it('treats bare system keywords like ui-monospace as loaded', () => {
+    expect(
+      collectUnloadedFonts({tokens: {'--font-family-code': 'ui-monospace'}}),
+    ).toEqual([]);
+  });
+
+  it('handles single-quoted and unquoted multi-word family names', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': "'JetBrains Mono', monospace",
+          '--font-family-heading': 'Space Grotesk, sans-serif',
+        },
+      }),
+    ).toEqual(['JetBrains Mono', 'Space Grotesk']);
+  });
+
+  it('dedupes case-insensitively across roles, keeping the first casing', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': '"Space Grotesk", sans-serif',
+          '--font-family-heading': '"space grotesk", serif',
+        },
+      }),
+    ).toEqual(['Space Grotesk']);
+  });
+
+  it('skips var() references and CSS-wide keywords', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-heading': 'var(--font-family-body)',
+          '--font-family-code': 'inherit',
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it("strips whole var() calls — fallback arguments are not this theme's declarations", () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': 'var(--x, "Web Font")',
+          '--font-family-heading': 'var(--x, "Web Font", serif)',
+        },
+      }),
+    ).toEqual([]);
+    // Families outside the var() call still count.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-code': 'var(--x), Bungee'},
+      }),
+    ).toEqual(['Bungee']);
+  });
+
+  it('keeps a comma inside a quoted name whole, even mid-list', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': 'Georgia, "Foo, Bar", serif'},
+      }),
+    ).toEqual(['Foo, Bar']);
+  });
+
+  it('ignores an empty font-family token', () => {
+    expect(collectUnloadedFonts({tokens: {'--font-family-body': ''}})).toEqual(
+      [],
+    );
+  });
+
+  it('collects component-override fontFamily values, any style key', () => {
+    expect(
+      collectUnloadedFonts({
+        components: {
+          Button: {base: {fontFamily: '"Orbitron", sans-serif'}},
+          Card: {'variant:hero': {fontFamily: 'Bungee'}},
+        },
+      }),
+    ).toEqual(['Orbitron', 'Bungee']);
+  });
+
+  it('matches known system families case-insensitively', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': 'arial, sans-serif'},
+      }),
+    ).toEqual([]);
+  });
+
+  it('returns nothing for a theme with no tokens or components', () => {
+    expect(collectUnloadedFonts({})).toEqual([]);
+  });
+
+  it('returns nothing for a null or undefined resolved theme', () => {
+    // Older build.mjs consumers guard with `resolvedTheme || themeDef` — if
+    // a path ever hands the collector nothing, it must shrug, not throw.
+    expect(collectUnloadedFonts(null)).toEqual([]);
+    expect(collectUnloadedFonts(undefined)).toEqual([]);
+  });
+
+  it('ignores non-string values without throwing: numeric or object-valued', () => {
+    // The generator only allows object values under ':pseudo' keys, so an
+    // object-valued fontFamily is not a family declaration — skip, not crash.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': 42},
+        components: {
+          button: {base: {fontFamily: 700}},
+          card: {base: {fontFamily: {default: '"Sneaky"'}}},
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it('collects fontFamily nested under a pseudo-class block', () => {
+    // generateThemeRules accepts {':hover': {fontFamily}} inside a style
+    // key — a family named only there must still warn.
+    expect(
+      collectUnloadedFonts({
+        components: {
+          button: {base: {':hover': {fontFamily: '"Rubik Doodle", cursive'}}},
+        },
+      }),
+    ).toEqual(['Rubik Doodle']);
+  });
+
+  it('strips a var() whose fallback list contains another var()', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': 'var(--brand, var(--fallback), "Web Font")',
+        },
+      }),
+    ).toEqual([]);
+    // …and still keeps a family declared outside the nested call.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-code': 'var(--a, var(--b, serif)), Bungee'},
+      }),
+    ).toEqual(['Bungee']);
+  });
+
+  it('matches generic keywords case-insensitively', () => {
+    expect(
+      collectUnloadedFonts({
+        tokens: {
+          '--font-family-body': 'Sans-Serif',
+          '--font-family-heading': 'SERIF',
+          '--font-family-code': 'Ui-Monospace',
+        },
+      }),
+    ).toEqual([]);
+  });
+
+  it('collapses newlines and whitespace runs inside a family name', () => {
+    // Template-literal theme sources wrap long stacks across lines.
+    expect(
+      collectUnloadedFonts({
+        tokens: {'--font-family-body': '"Space\n      Grotesk",\n  serif'},
+      }),
+    ).toEqual(['Space Grotesk']);
+  });
+});
+
+describe('formatFontLoadingHelp', () => {
+  const help = formatFontLoadingHelp('ocean', ['Fraunces', 'JetBrains Mono']);
+
+  it('names the theme and every family in the headline', () => {
+    expect(help).toContain('⚠');
+    expect(help).toContain('ocean');
+    expect(help).toContain('"Fraunces"');
+    expect(help).toContain('"JetBrains Mono"');
+  });
+
+  it('includes the Google Fonts recipe: preconnect pair + the exact css2 URL', () => {
+    expect(help).toContain(
+      '<link rel="preconnect" href="https://fonts.googleapis.com"',
+    );
+    expect(help).toContain('https://fonts.gstatic.com');
+    // The whole href, so a malformed URL cannot hide behind fragment checks.
+    expect(help).toContain(
+      'href="https://fonts.googleapis.com/css2?family=Fraunces&family=JetBrains+Mono&display=swap"',
+    );
+  });
+
+  it('includes a self-hosted @font-face alternative with font-display: swap', () => {
+    expect(help).toContain('@font-face');
+    expect(help).toContain('font-family: "Fraunces"');
+    expect(help).toContain('woff2');
+    expect(help).toContain('font-display: swap');
+  });
+
+  it('points at the docs recipe', () => {
+    expect(help).toContain('astryx docs typography');
+  });
+
+  it('percent-encodes family names in the css2 URL', () => {
+    const spiced = formatFontLoadingHelp('spice', ['P&Co Sans', 'Sömething']);
+    expect(spiced).toContain(
+      'href="https://fonts.googleapis.com/css2?family=P%26Co+Sans&family=S%C3%B6mething&display=swap"',
+    );
+  });
+});

package/api/theme/template/template.d.mts

@@ -0,0 +1,21 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Write the annotated theme template into a project.
+ *
+ * Refuses to overwrite without `overwrite`: an edited copy is the consumer's
+ * work, and this command is safe to re-run (init calls it on every setup).
+ *
+ * @param {{targetPath?: string, overwrite?: boolean, cwd?: string}} [options]
+ * @returns {import('../theme.type.mjs').ThemeTemplateResponse}
+ */
+export function themeTemplate(options?: {
+    targetPath?: string;
+    overwrite?: boolean;
+    cwd?: string;
+}): import("../theme.type.mjs").ThemeTemplateResponse;
+/** The annotated `defineTheme` reference that ships with the CLI. */
+export const THEME_TEMPLATE_SRC: string;
+/** Where it lands when the caller does not say. */
+export const THEME_TEMPLATE_DEFAULT_PATH: "theme.template.ts";

package/api/theme/template/template.mjs

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx theme template` leaf — writes the annotated theme template into the
+ * consumer's project.
+ *
+ * Sibling of `theme add`: both answer "put a theme starting point in my
+ * project", and they split on where you start. `add` copies a theme we ship
+ * (you like stone, you want to own it); `template` writes the blank annotated
+ * reference (you want your own, and need to know what the surface contains).
+ *
+ * The template is a doc that happens to compile, so it is one file at the
+ * project root by default rather than a package under src/themes/ — you read
+ * it, copy what you need into your own theme file, and delete it.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {stripCopyrightHeader} from '../../../foundation/text/copyright-header.mjs';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+
+/** The annotated `defineTheme` reference that ships with the CLI. */
+export const THEME_TEMPLATE_SRC = path.join(CLI_ROOT, 'assets', 'theme.template.ts');
+
+/** Where it lands when the caller does not say. */
+export const THEME_TEMPLATE_DEFAULT_PATH = 'theme.template.ts';
+
+/**
+ * Write the annotated theme template into a project.
+ *
+ * Refuses to overwrite without `overwrite`: an edited copy is the consumer's
+ * work, and this command is safe to re-run (init calls it on every setup).
+ *
+ * @param {{targetPath?: string, overwrite?: boolean, cwd?: string}} [options]
+ * @returns {import('../theme.type.mjs').ThemeTemplateResponse}
+ */
+export function themeTemplate(options = {}) {
+  const {
+    targetPath = THEME_TEMPLATE_DEFAULT_PATH,
+    overwrite = false,
+    cwd = process.cwd(),
+  } = options;
+
+  let resolved;
+  try {
+    resolved = assertWithin(targetPath, cwd, {label: 'theme template path'});
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+
+  const relative = path.relative(cwd, resolved) || targetPath;
+
+  if (fs.existsSync(resolved) && !overwrite) {
+    return {type: 'theme.template', data: {path: relative, written: false, reason: 'exists'}};
+  }
+
+  // Our repo header has no business in someone else's source tree.
+  const contents = stripCopyrightHeader(fs.readFileSync(THEME_TEMPLATE_SRC, 'utf-8'));
+  fs.mkdirSync(path.dirname(resolved), {recursive: true});
+  fs.writeFileSync(resolved, contents);
+
+  return {type: 'theme.template', data: {path: relative, written: true, reason: null}};
+}

package/api/theme/template/template.test.mjs

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct API tests for `themeTemplate()` — the function behind
+ * `astryx theme template` and `astryx init --features theme`.
+ *
+ * What matters here is that it never destroys work: the template lands once,
+ * a second run leaves an edited copy alone, and a path that escapes the
+ * project is refused.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {themeTemplate, THEME_TEMPLATE_DEFAULT_PATH} from './template.mjs';
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-template-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('themeTemplate()', () => {
+  it('writes the template and returns a theme.template receipt', () => {
+    const res = themeTemplate({cwd: tmpDir});
+
+    expect(res).toEqual({
+      type: 'theme.template',
+      data: {path: THEME_TEMPLATE_DEFAULT_PATH, written: true, reason: null},
+    });
+    const written = fs.readFileSync(path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH), 'utf-8');
+    expect(written).toMatch(/defineTheme/);
+  });
+
+  it('does not carry our copyright header into the consumer tree', () => {
+    themeTemplate({cwd: tmpDir});
+    const written = fs.readFileSync(path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH), 'utf-8');
+    expect(written).not.toMatch(/Copyright \(c\) Meta Platforms/);
+    expect(written.startsWith('/**')).toBe(true);
+  });
+
+  it('leaves an existing file alone and says so', () => {
+    const dest = path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH);
+    fs.writeFileSync(dest, '// mine\n');
+
+    const res = themeTemplate({cwd: tmpDir});
+
+    expect(res.data).toEqual({
+      path: THEME_TEMPLATE_DEFAULT_PATH,
+      written: false,
+      reason: 'exists',
+    });
+    expect(fs.readFileSync(dest, 'utf-8')).toBe('// mine\n');
+  });
+
+  it('overwrites when asked', () => {
+    const dest = path.join(tmpDir, THEME_TEMPLATE_DEFAULT_PATH);
+    fs.writeFileSync(dest, '// mine\n');
+
+    const res = themeTemplate({cwd: tmpDir, overwrite: true});
+
+    expect(res.data.written).toBe(true);
+    expect(fs.readFileSync(dest, 'utf-8')).toMatch(/defineTheme/);
+  });
+
+  it('honors a custom path and creates its directory', () => {
+    const res = themeTemplate({cwd: tmpDir, targetPath: 'src/themes/starter.ts'});
+
+    expect(res.data.path).toBe(path.join('src', 'themes', 'starter.ts'));
+    expect(fs.existsSync(path.join(tmpDir, 'src/themes/starter.ts'))).toBe(true);
+  });
+
+  it('refuses a path that escapes the project', () => {
+    expect(() => themeTemplate({cwd: tmpDir, targetPath: '../escaped.ts'})).toThrow(
+      /theme template path/,
+    );
+    expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
+  });
+});

package/api/theme/theme.d.mts

@@ -2,6 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 export { themeAdd } from "./add/add.mjs";
+export { themeTemplate } from "./template/template.mjs";
 export { themeList } from "./list/list.mjs";
 export { listThemes } from "./_adapter.mjs";
 export { themeBuild, importSpecifier } from "./build/build.mjs";

package/api/theme/theme.mjs

@@ -10,5 +10,6 @@
 
 export {themeBuild, importSpecifier} from './build/build.mjs';
 export {themeAdd} from './add/add.mjs';
+export {themeTemplate} from './template/template.mjs';
 export {themeList} from './list/list.mjs';
 export {listThemes} from './_adapter.mjs';

package/api/theme/theme.type.d.mts

@@ -66,3 +66,16 @@ export type ThemeAddResponse = {
         files: string[];
     };
 };
+/**
+ * xds --json theme template
+ * `written: false` with `reason: 'exists'` is a success: the command is safe to
+ * re-run, and an edited template is the consumer's file to keep.
+ */
+export type ThemeTemplateResponse = {
+    type: "theme.template";
+    data: {
+        path: string;
+        written: boolean;
+        reason: "exists" | null;
+    };
+};

package/api/theme/theme.type.mjs

@@ -12,9 +12,10 @@
  * xds --json theme build <file> --check     -> theme.build.check
  * xds --json theme list                     -> theme.list
  * xds --json theme add <slug>               -> theme.add
+ * xds --json theme template                 -> theme.template
  * (file not found / parse error)            -> CLIError
  *
- * @position api — colocated typedefs for api/theme/{theme,build,add,list,_adapter}
+ * @position api — colocated typedefs for api/theme/{theme,build,add,list,template,_adapter}
  */
 
 /**
@@ -54,6 +55,15 @@
  * @property {{slug: string, displayName: string, maintained: boolean, outputDir: string, entry: string, exportName: string, files: string[]}} data
  */
 
+/**
+ * xds --json theme template
+ * `written: false` with `reason: 'exists'` is a success: the command is safe to
+ * re-run, and an edited template is the consumer's file to keep.
+ * @typedef {object} ThemeTemplateResponse
+ * @property {'theme.template'} type
+ * @property {{path: string, written: boolean, reason: 'exists' | null}} data
+ */
+
 // Make this a module so the @typedefs above are importable as types via
 // `import('./theme.type.mjs').ThemeBuildResponse` (and re-exportable from a .d.ts).
 export {};

package/api/theme/themeTemplate.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `themeTemplate()` / `astryx theme template`. Colocated with the
+ * API function it documents; the response-shape source of truth stays in
+ * `theme.type.mjs`.
+ * @position packages/cli/api/theme — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/theme/themeTemplate.doc.mjs

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `themeTemplate()` / `astryx theme template`. Colocated with the
+ * API function it documents; the response-shape source of truth stays in
+ * `theme.type.mjs`.
+ * @position packages/cli/api/theme — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'themeTemplate',
+  displayName: 'themeTemplate()',
+  summary: 'Write the annotated theme template into a project.',
+  description:
+    'Writes theme.template.ts: the annotated reference for the whole theme surface — every ' +
+    'defineTheme field, the token families, the component override syntax, and how a theme is ' +
+    'consumed — with the CLI command that prints the authoritative reference for each section. ' +
+    'Read it, copy what you need into your own theme file, delete it. Where `theme add` starts ' +
+    'you from a theme we ship, this starts you from a blank one. Refuses to overwrite without ' +
+    '`overwrite`, so it is safe to re-run.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'themeTemplate(options?: {targetPath?: string, overwrite?: boolean, cwd?: string}): ThemeNewResponse',
+  keywords: ['theme', 'template', 'starter', 'defineTheme', 'scaffold', 'reference', 'tokens'],
+  params: [
+    {
+      name: 'options.targetPath',
+      type: 'string',
+      description: 'Destination file. Must resolve within cwd.',
+      default: "'theme.template.ts'",
+    },
+    {
+      name: 'options.overwrite',
+      type: 'boolean',
+      description: 'Replace an existing file instead of reporting it untouched.',
+      default: 'false',
+    },
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description: 'Directory the target path resolves against.',
+    },
+  ],
+  returns: [
+    {
+      type: 'theme.template',
+      description:
+        'Receipt: the path (relative to cwd), whether it was written, and the reason it was not — `exists` when a file was already there, which is a success, not a failure.',
+    },
+  ],
+  throws: [{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'}],
+  examples: [
+    {label: 'Write it at the project root', code: 'themeTemplate();'},
+    {
+      label: 'Somewhere else, replacing what is there',
+      code: "themeTemplate({targetPath: 'src/themes/template.ts', overwrite: true});",
+    },
+  ],
+  command: 'theme template',
+  related: ['themeAdd', 'themeBuild', 'themeList'],
+};

package/assets/docs/getting-started.doc.mjs

@@ -20,9 +20,19 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          label: 'Paste this into your AI',
+          label: 'Set up the design system',
           code: 'Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
         },
+        {
+          type: 'prose',
+          text: 'Then give it a look. Every app gets a theme whether or not anyone picks one, so it is worth one question at setup rather than revisiting screens later that were built around the wrong look:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          label: 'Give it a look',
+          code: "Ask me what look and feel this app should have. Run `npx @astryxdesign/cli theme list` and start from the closest shipped theme with `theme add <slug>`, which copies it in as editable source; if none of them fit, run `npx @astryxdesign/cli theme template` and fill in the annotated template it writes. Default to neutral if I have no preference, and show me the result before moving on.",
+        },
       ],
     },
     {

package/assets/docs/theme.doc.dense.mjs

@@ -8,9 +8,9 @@ export const docsDense = {
     { section: 'Quick Start', title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
     { section: 'Available Themes', title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
     { section: 'Theme Props', title: 'Props', content: [null] },
-    { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
+    { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: '`theme list` + `theme add <slug>` to start from a shipped theme, or defineTheme from scratch. only override tokens that differ.' }, null, { type: 'prose', text: '`astryx theme template` writes theme.template.ts: every defineTheme field + token families + override syntax, annotated, with the CLI command that prints each reference.' }] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
-    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
+    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
     { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
     { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },

package/assets/docs/theme.doc.mjs

@@ -142,13 +142,17 @@ function App() {
       content: [
         {
           type: 'prose',
-          text: 'Use the CLI wizard (recommended) or create manually with defineTheme. Only override tokens that differ from defaults; omitted tokens use the design system defaults.',
+          text: 'Start from a theme we ship, or write one from scratch with defineTheme. Only override tokens that differ from defaults; omitted tokens use the design system defaults.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Scaffold with CLI',
-          code: 'astryx theme',
+          label: 'Browse, then copy a theme in as editable source',
+          code: 'astryx theme list\nastryx theme add stone',
+        },
+        {
+          type: 'prose',
+          text: 'For an annotated map of the whole surface — every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference — run `astryx theme template`. It writes `theme.template.ts` into your project to read and copy from (`astryx init --features theme` writes it as part of project setup).',
         },
       ],
     },
@@ -249,10 +253,15 @@ const brandTheme = defineTheme({
             ['tokens', 'Base tokens are copied first, then child tokens override on top.'],
             ['components', 'Deep-merged: child component rules override matching keys from the base.'],
             ['icons', 'Shallow-merged: child icons override matching names from the base.'],
-            ['fonts', 'Base fonts included first, then child fonts appended.'],
+            ['indicators', 'Shallow-merged: child indicators override matching names from the base.'],
+            ['onDark, onLight', "Deep-merged per surface: the base's resolved surface first, then the child's overrides."],
             ['typography, motion, radius, color', 'Child config replaces base entirely (these are scale inputs, not additive).'],
           ],
         },
+        {
+          type: 'prose',
+          text: 'Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme\'s CSS does not need to be loaded next to it. A base that is not a theme — most often an import that missed — is a build error rather than a theme that silently inherits nothing.',
+        },
       ],
     },
     {
@@ -275,14 +284,17 @@ const brandTheme = defineTheme({
     base: { borderRadius: '20px', padding: '24px' },
   },
   button: {
-    base: { borderRadius: '9999px', textTransform: 'uppercase' },
+    base: {
+      borderRadius: '9999px',
+      textTransform: 'uppercase',
+      // Some components have public CSS vars for properties that don't map
+      // to standard CSS. Set these directly. Take the name from
+      // \`astryx component <Name>\` — a var the component does not define
+      // compiles to CSS that never applies.
+      '--button-focus-offset': '3px',
+    },
     'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },
   },
-  // Some components have public CSS vars for properties that don't map
-  // to standard CSS. Set these directly.
-  button: {
-    base: { '--button-press-scale': 'scale(0.95)' },
-  },
 }`,
         },
         {
@@ -410,6 +422,10 @@ import './themes/ocean.css';
   <App />
 </Theme>`,
         },
+        {
+          type: 'prose',
+          text: 'The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add — the built CSS only sets font-family, so loading the font files stays the app\'s job. See `astryx docs typography` for the full recipe.',
+        },
       ],
     },
     {