@astryxdesign/cli 0.7.1-canary.ff40b78 → 0.7.2-canary.c68f5e8

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @xds/cli
 
+# 0.7.1
+
+#### Fixes
+
+- `CommandPaletteInput` now exposes the semantics and name that its visible state promises. (#7321)
+  - A standalone field with no popup attributes was `role="combobox"` with `aria-expanded="true"` and `aria-autocomplete="list"`; it is now `role="searchbox"` with no popup state. Pass `role="combobox"`, or your popup's own ARIA attributes, to keep the old semantics. A field that already passes popup attributes (`aria-expanded`, `aria-controls`, `aria-owns`, `aria-haspopup`, and the like) stays a `combobox` and keeps them, and a field inside `CommandPalette` is unchanged.
+
+  - The field's default accessible name was its placeholder (`Search…`, or the caller's `placeholder`); it is now `Search commands`, translated. Pass `label` to keep a specific name, for example `label="Search…"` for the old default. A caller whose custom `placeholder` served as the name keeps working code and hears the generic name until it passes `label`.
+
+  - The CLI's async-search CommandPalette block names its field `Search files`.
+
+  - `endContent={true}` no longer renders an empty trailing slot, and `endContent={0}` renders inside the trailing slot instead of after it.
+- Stone, Y2K, and Gothic set `CodeBlock`'s diff row slots in their own syntax palettes, so a reader of a diff on those themes gets added and removed rows whose code, line numbers, and `+`/`-` glyphs stay readable: every syntax token keeps at least 4.5:1 on the tinted rows in Stone (light and dark) and Y2K (light and dark), and in Gothic the rows take a deep green and a deep red at the background's own luminance, so every token keeps the contrast it has on the plain background. Line numbers and glyphs on changed rows use each theme's own green and red. The CLI's bundled copies of the three themes (`astryx theme eject`) carry the same palettes. (#7428)
+- A `secondary` Selector, MultiSelector, or ComplexSelector now matches the theme's secondary Button: under butter, chocolate, gothic, stone, and y2k it takes that Button's border, fill, text color, and hover instead of the default borderless neutral fill, so a toolbar mixing secondary buttons and selectors reads as one set of controls. Disabled and read-only triggers keep a still fill on hover, as a disabled Button does, and a Selector or MultiSelector inside an InputGroup keeps the group's neutral fill and edges. The default theme is unchanged, the selector docs now say `secondary` follows the theme's secondary Button, and themes added with the CLI get the same parity. (#7548)
+- `astryx theme build --watch` stops as soon as it is interrupted (Ctrl-C or SIGTERM). A change saved while a rebuild was running no longer starts another rebuild after "Stopped watching.", and a rebuild in progress stops with the watcher instead of keeping the process alive. (#7508)
+
+#### Performance
+
+- `astryx search` and `astryx build`, and the `search` and `build` API functions, read each source directory once per call instead of once per candidate. Results are unchanged. A warm `search` drops from about 1.9 s to 0.4 s on macOS. (#7421)
+
+#### Documentation
+
+- The generated token docs list the five diff row slots of the syntax vocabulary — `--color-syntax-added`, `--color-syntax-removed`, `--color-syntax-diff-header`, `--color-syntax-added-marker`, `--color-syntax-removed-marker` — with their defaults, so `astryx docs tokens` describes nineteen syntax slots. (#7389)
+- The Tailwind and migration setup docs now say that `globals.css` (or a `layers.css` holding only the `@layer` line) must be the first import in the root layout or app entry, before the `astryx-themes` module or any component that imports theme CSS; otherwise Tailwind preflight overrides Astryx base styles and theme overrides lose. The Tailwind v3 coexistence snippet moves its `@layer` line into a `layers.css` imported first, because Next.js (webpack or Turbopack) hoists CSS imports above an inline `@layer` line. (#7534)
+- Grid's `columns` docs now lead with the shape that reflows: a numeric `columns` is exactly N columns at every width and never reflows, and `columns={{minWidth, max}}` is the form for columns that must survive a phone. The `astryx docs layout/responsive` topic gains a "Columns that reflow" section with a reflowing stat row beside a fixed week row. No behavior changes. (#7340)
+- The styling setup docs now load the prebuilt stylesheets on every path. The "StyleX from source" path becomes "StyleX for your own code": it keeps `astryx.css` and points the StyleX compiler at your own and swizzled source only. A new "Other Astryx packages" section lists each package's stylesheet (`richtext.css`, `lab.css`, `charts.css`) and where to import it. Getting started no longer lists the two example setups that compile Astryx source; the remaining examples all load `astryx.css`. (#7587)
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+
+---
+
 # 0.7.0
 
 #### Breaking Changes

package/api/build/_adapter.d.mts

@@ -66,6 +66,7 @@ export function isWeightsFile(file: any): file is import("./kit/weights.mjs").We
  * @returns {string[]} Setup notes (empty when the template needs nothing).
  */
 export function templateSetupNotes(template: PageTemplate, cwd: string): string[];
+export { withListingCache } from "../../foundation/fs/listing-cache.mjs";
 /**
  * A page template the kit can recommend starting from.
  */

package/api/build/_adapter.mjs

@@ -23,6 +23,13 @@ import {componentKeywords} from '../search/search.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {analyzeTemplateNeeds} from '../../foundation/discovery/template-needs.mjs';
 
+/**
+ * Runs one build with a single directory listing per path: the kit resolves
+ * every candidate's source and docs by walking the same tree, which does not
+ * change during the call.
+ */
+export {withListingCache} from '../../foundation/fs/listing-cache.mjs';
+
 /**
  * A page template the kit can recommend starting from.
  * @typedef {object} PageTemplate

package/api/build/build.mjs

@@ -17,6 +17,7 @@ import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {buildHelp} from './help/help.mjs';
 import {buildKit} from './kit/kit.mjs';
+import {withListingCache} from './_adapter.mjs';
 
 // Barrel: surface the leaves alongside the dispatcher for the fractal shape.
 export {buildHelp, buildKit};
@@ -40,5 +41,7 @@ export async function build(query, options = {}) {
       ERROR_CODES.ERR_INVALID_ARGUMENT,
     );
   }
-  return buildKit(query, options);
+  // The kit resolves every candidate's source and docs by walking the same
+  // tree; read each directory once for this call.
+  return withListingCache(() => buildKit(query, options));
 }

package/api/search/search.mjs

@@ -79,6 +79,7 @@
  * queries they have nothing to do with.
  */
 
+import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
 import {readDocView} from '../../foundation/doc-compiler/read.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
@@ -1769,6 +1770,17 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
  * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export async function search(query, options = {}) {
+  // Every candidate resolves its source and docs by walking the same tree;
+  // read each directory once for this call.
+  return withListingCache(() => searchOnce(query, options));
+}
+
+/**
+ * @param {string} query
+ * @param {NonNullable<Parameters<typeof search>[1]>} options
+ * @returns {ReturnType<typeof search>}
+ */
+async function searchOnce(query, options) {
   const {cwd = process.cwd(), type, limit = 20} = options;
 
   if (!query || !String(query).trim()) {

package/api/template/table-filter-view-tabs.test.mjs

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression coverage for the table-filter page's compact view-options tabs.
+ * @input The shipped table-filter page template source.
+ * @output Assertions that the shared tabpanel is labelled by its selected tab.
+ * @position Template contract test for the tabs relationship in the narrow-view sheet.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+const sourcePath = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../assets/templates/pages/table-filter/page.tsx',
+);
+const source = fs.readFileSync(sourcePath, 'utf8');
+const sheet = source.match(
+  /const viewOptionsSheet = \(([\s\S]*?)\n {2}\);/,
+)?.[1];
+const tab = sheet?.match(/<Tab\b([\s\S]*?)\/>/)?.[1];
+const panel = sheet?.match(/<VStack\b([^>]*?role="tabpanel"[^>]*?)>/)?.[1];
+
+describe('table-filter view-options tabs', () => {
+  it('finds the compact sheet, its tab and its panel', () => {
+    expect(sheet).toBeDefined();
+    expect(tab).toBeDefined();
+    expect(panel).toBeDefined();
+  });
+
+  it('gives every tab an id derived from the panel id and its section', () => {
+    expect(tab).toContain('id={`${viewPanelId}-tab-${section.key}`}');
+    expect(tab).toContain('panelId={viewPanelId}');
+  });
+
+  it('labels the shared panel by the selected tab, not a fixed string', () => {
+    expect(panel).toContain('id={viewPanelId}');
+    expect(panel).toContain(
+      'aria-labelledby={`${viewPanelId}-tab-${viewSection}`}',
+    );
+    expect(panel).not.toContain('aria-label=');
+  });
+});

package/api/theme/build/build.core-on-demand.test.mjs

@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The theme build imports Core when a build runs, not when the CLI starts.
+ *
+ * The CLI loads the theme build module for every command, and Core's root
+ * entry pulls in all of Core and React. So a command that builds no theme must
+ * not ask for either, or `astryx --version` pays for them whenever a Core is
+ * installed. A resolve hook in a real subprocess records every request for
+ * Core or React and the module that made it, whether or not the request
+ * resolves.
+ */
+
+import {afterAll, beforeAll, describe, expect, it} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const BIN = fileURLToPath(
+  new URL('../../../clients/cli/bin/astryx.mjs', import.meta.url),
+);
+
+/** @type {string} */
+let dir;
+/** @type {string} */
+let register;
+/** @type {string} */
+let log;
+
+beforeAll(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-on-demand-'));
+  log = path.join(dir, 'requests.jsonl');
+  const hooks = path.join(dir, 'hooks.mjs');
+  fs.writeFileSync(
+    hooks,
+    [
+      "import {appendFileSync} from 'node:fs';",
+      `const LOG = ${JSON.stringify(log)};`,
+      'const WATCHED = /^(?:@astryxdesign\\/core|react|react-dom)(?:\\/|$)/;',
+      'export async function resolve(specifier, context, nextResolve) {',
+      '  if (WATCHED.test(specifier)) {',
+      '    const parent = context.parentURL ?? null;',
+      "    appendFileSync(LOG, JSON.stringify({specifier, parent}) + '\\n');",
+      '  }',
+      '  return nextResolve(specifier, context);',
+      '}',
+      '',
+    ].join('\n'),
+  );
+  register = path.join(dir, 'register.mjs');
+  fs.writeFileSync(
+    register,
+    `import {register} from 'node:module';\nregister(${JSON.stringify(pathToFileURL(hooks).href)});\n`,
+  );
+  // A plain theme object: the file itself never imports Core, so a request for
+  // Core can only come from the build.
+  fs.writeFileSync(
+    path.join(dir, 'ocean.mjs'),
+    "export default {name: 'ocean', tokens: {'--color-bg': '#0a0a0a'}};\n",
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/**
+ * Run the CLI and return each Core or React specifier it asked for, mapped to
+ * the first module that asked.
+ * @param {string[]} args
+ * @returns {{status: number | null, requested: Record<string, string | null>}}
+ */
+function run(args) {
+  fs.rmSync(log, {force: true});
+  const res = spawnSync(
+    process.execPath,
+    ['--import', pathToFileURL(register).href, BIN, ...args],
+    {cwd: dir, encoding: 'utf-8', timeout: 20_000},
+  );
+  /** @type {Record<string, string | null>} */
+  const requested = {};
+  const lines = fs.existsSync(log)
+    ? fs.readFileSync(log, 'utf-8').split('\n').filter(Boolean)
+    : [];
+  for (const line of lines) {
+    const {specifier, parent} = JSON.parse(line);
+    if (!(specifier in requested)) requested[specifier] = parent;
+  }
+  return {status: res.status, requested};
+}
+
+describe('theme build imports Core on demand', () => {
+  it('astryx --version asks for neither Core nor React', () => {
+    const {status, requested} = run(['--version']);
+    expect(status).toBe(0);
+    expect(requested).toEqual({});
+  });
+
+  it('theme build imports Core from the theme build module', () => {
+    const {requested} = run([
+      'theme',
+      'build',
+      'ocean.mjs',
+      '--check',
+      '--json',
+    ]);
+    expect(requested['@astryxdesign/core/theme']).toMatch(
+      /\/api\/theme\/build\/build\.mjs$/,
+    );
+  });
+});

package/api/theme/build/build.d.mts

@@ -163,6 +163,19 @@ export function themeBuildFamily(files: string[], options: {
         checked?: undefined;
     };
 }>;
+/**
+ * The bindings one Core provides: the namespaces interception spreads, the
+ * functions the build calls, and why the import failed, if it did.
+ */
+export type CoreBindings = {
+    themeModule: any;
+    rootModule: any;
+    importError: any;
+    defineTheme: any;
+    generateThemeRulesSplit: any;
+    generateOnMediaCSS: any;
+    generateAdaptationCSS: any;
+};
 /**
  * How one `prop:value` pair on a component target is classified — the single
  * vocabulary both the root and adaptation paths reason in.
@@ -210,16 +223,3 @@ export type ThemeBuildTrailer = {
      */
     fontNotices: string[];
 };
-/**
- * The bindings one Core provides: the namespaces interception spreads, the
- * functions the build calls, and why the import failed, if it did.
- */
-export type CoreBindings = {
-    themeModule: any;
-    rootModule: any;
-    importError: any;
-    defineTheme: any;
-    generateThemeRulesSplit: any;
-    generateOnMediaCSS: any;
-    generateAdaptationCSS: any;
-};

package/api/theme/build/build.mjs

@@ -37,6 +37,10 @@
  * general compatibility scheme for every export an arbitrary older core might
  * lack.
  *
+ * Core is imported on first use, never when this module loads: the CLI loads
+ * this module for every command, and Core's root entry pulls in all of Core
+ * and React.
+ *
  * With `{check: true}`, it compiles the same outputs in memory but writes
  * nothing: it compares each generated file against what is on disk (ignoring
  * only the volatile `@generated` `Command:` line) and returns a
@@ -91,6 +95,8 @@ import {resolveIconImports} from './icon-imports.mjs';
 // action). A built, resolvable `@astryxdesign/core` is a hard requirement.
 // A built, resolvable `@astryxdesign/core` is a hard requirement. These are
 // populated from a dynamic import (a runtime boundary), so `any` is intentional.
+// That import runs the first time a build needs Core (see `loadCliCore`), not
+// when this module loads.
 //
 // The CLI and core are independently versioned optional peers, so this import
 // can succeed against a core OLDER than the CLI. Only the exports every theme
@@ -120,27 +126,6 @@ import {resolveIconImports} from './icon-imports.mjs';
  */
 /** @type {any} */ let _coreRootModule = null;
 /** @type {any} */ let _coreImportError = null;
-try {
-  const coreTheme = await import('@astryxdesign/core/theme');
-  _coreThemeModule = coreTheme;
-  _defineTheme = coreTheme.defineTheme;
-  _generateThemeRulesSplit = coreTheme.generateThemeRulesSplit;
-  _generateOnMediaCSS = coreTheme.generateOnMediaCSS;
-  _generateAdaptationCSS = coreTheme.generateAdaptationCSS;
-  try {
-    _coreRootModule = await import('@astryxdesign/core');
-  } catch {
-    // A core without a usable root entry still builds themes; interception
-    // falls back to the theme namespace for the root specifier.
-  }
-} catch (e) {
-  // Capture the reason so the theme action can surface a precise, actionable
-  // error. We don't throw here: this module is imported eagerly by the CLI
-  // entrypoint for every command, and a throw at load time would break
-  // unrelated commands (the entry wraps loads in try/catch and degrades the
-  // command to a stub). The hard failure happens when `theme build` runs.
-  _coreImportError = e;
-}
 
 /**
  * The bindings one Core provides: the namespaces interception spreads, the
@@ -157,19 +142,65 @@ try {
  */
 
 /**
- * The bindings exactly as the CLI's own import left them, kept so each build
- * can choose between them and the project's installed Core.
- * @type {CoreBindings}
+ * Import the CLI's own Core: the `@astryxdesign/core` this module resolves.
+ * Never throws. A failed import is kept as `importError`, so the build can
+ * surface a precise, actionable error when it runs.
+ * @returns {Promise<CoreBindings>}
  */
-const _cliCore = {
-  themeModule: _coreThemeModule,
-  rootModule: _coreRootModule,
-  importError: _coreImportError,
-  defineTheme: _defineTheme,
-  generateThemeRulesSplit: _generateThemeRulesSplit,
-  generateOnMediaCSS: _generateOnMediaCSS,
-  generateAdaptationCSS: _generateAdaptationCSS,
-};
+async function importCliCore() {
+  /** @type {CoreBindings} */
+  const core = {
+    themeModule: null,
+    rootModule: null,
+    importError: null,
+    defineTheme: null,
+    generateThemeRulesSplit: null,
+    generateOnMediaCSS: null,
+    generateAdaptationCSS: null,
+  };
+  try {
+    const coreTheme = await import('@astryxdesign/core/theme');
+    core.themeModule = coreTheme;
+    core.defineTheme = coreTheme.defineTheme;
+    core.generateThemeRulesSplit = coreTheme.generateThemeRulesSplit;
+    core.generateOnMediaCSS = coreTheme.generateOnMediaCSS;
+    core.generateAdaptationCSS = coreTheme.generateAdaptationCSS;
+    try {
+      core.rootModule = await import('@astryxdesign/core');
+    } catch {
+      // A core without a usable root entry still builds themes; interception
+      // falls back to the theme namespace for the root specifier.
+    }
+  } catch (e) {
+    // Capture the reason so the theme action can surface a precise, actionable
+    // error. The hard failure happens when `theme build` runs.
+    core.importError = e;
+  }
+  return core;
+}
+
+/**
+ * The CLI's own Core, imported once, the first time a build needs it. The CLI
+ * loads this module for every command, and Core's root entry loads all of Core
+ * and React, so an import at module load would make every command
+ * (`--version` included) pay for that whenever a Core resolves.
+ * @type {Promise<CoreBindings> | null}
+ */
+let _cliCorePromise = null;
+
+/**
+ * The CLI's own Core, kept so each build can choose between it and the
+ * project's installed Core. The first call also points the build at it, so a
+ * step that runs before any build has chosen a Core reads the CLI's own.
+ * @returns {Promise<CoreBindings>}
+ */
+function loadCliCore() {
+  _cliCorePromise ??= importCliCore().then(core => {
+    setCore(core);
+    return core;
+  });
+  return _cliCorePromise;
+}
 
 /**
  * Point the build at one Core: the module-level bindings every step reads.
@@ -248,13 +279,14 @@ function realOrSelf(file) {
  * repository, a bare directory), the same Core, or one that does not load.
  *
  * @param {string} cwd
+ * @param {CoreBindings} cliCore - The CLI's own Core, from {@link loadCliCore}.
  * @returns {Promise<CoreBindings | null>}
  */
-async function loadProjectCore(cwd) {
+async function loadProjectCore(cwd, cliCore) {
   const dir = findInstalledPackage(cwd, '@astryxdesign/core');
   const themeFile = dir ? importTarget(dir, './theme') : null;
   if (!dir || !themeFile) return null;
-  if (_cliCore.themeModule) {
+  if (cliCore.themeModule) {
     try {
       const own = fileURLToPath(
         import.meta.resolve('@astryxdesign/core/theme'),
@@ -301,9 +333,10 @@ const _projectCores = new Map();
  * @param {string} cwd
  */
 async function selectCore(cwd) {
+  const cliCore = await loadCliCore();
   if (!_projectCores.has(cwd))
-    _projectCores.set(cwd, await loadProjectCore(cwd));
-  setCore(_projectCores.get(cwd) ?? _cliCore);
+    _projectCores.set(cwd, await loadProjectCore(cwd, cliCore));
+  setCore(_projectCores.get(cwd) ?? cliCore);
 }
 
 /**
@@ -1694,6 +1727,8 @@ export async function validateThemePrivateInputs(
     );
   }
 
+  // The CLI's own Core, unless a build in this process already chose one.
+  await loadCliCore();
   const interception = interceptCore(_coreThemeModule, _coreRootModule);
   let theme;
   try {

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

@@ -185,16 +185,6 @@ const overrides = stylex.create({
               'Next.js + Tailwind bridge',
               '[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)',
             ],
-            [
-              'Next.js Source',
-              'Next.js importing from source',
-              '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)',
-            ],
-            [
-              'Vite',
-              'Vite',
-              '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)',
-            ],
             [
               'Vite + Tailwind',
               'Vite + Tailwind bridge',

package/assets/docs/styling-overview.doc.mjs

@@ -4,7 +4,8 @@
  * @file `astryx docs styling-overview`
  *
  * One question: "How do I set up CSS?"
- * Three paths, each with its exact imports.
+ * Three paths, each with its exact imports. Every path loads the prebuilt
+ * stylesheets (spec:AST-080 FR5); none compiles Astryx package source.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -14,7 +15,7 @@ export const docs = {
   title: 'Styling overview',
   category: 'guide',
   description:
-    'How to set up CSS — exact imports for three paths: plain, Tailwind, and StyleX from source.',
+    'How to set up CSS — exact imports for three paths: plain, Tailwind, and StyleX for your own code — plus the stylesheet each Astryx package ships.',
   keywords: [
     'styling',
     'CSS',
@@ -46,15 +47,15 @@ export const docs = {
               "None beyond Tailwind's own.",
             ],
             [
-              'StyleX from source',
-              'Swizzled (ejected) components. Raw StyleX source needs a compiler plugin.',
-              'Yes \u2014 a StyleX bundler plugin.',
+              'StyleX for your own code',
+              'Your own `stylex.create()` styles and swizzled (ejected) components. Astryx itself stays prebuilt.',
+              'Yes \u2014 a StyleX plugin for your own code.',
             ],
           ],
         },
         {
           type: 'prose',
-          text: 'All three resolve to the same design tokens and support theming and dark mode. You can mix them in one app.',
+          text: 'All three load the same prebuilt Astryx stylesheets, resolve to the same design tokens, and support theming and dark mode. None of them compiles Astryx package source. You can mix them in one app.',
         },
       ],
     },
@@ -117,12 +118,12 @@ export const docs = {
       ],
     },
     {
-      id: 'stylex-from-source',
-      title: 'StyleX from source',
+      id: 'stylex-own-code',
+      title: 'StyleX for your own code',
       content: [
         {
           type: 'prose',
-          text: 'Only needed when you swizzle a component (`astryx swizzle <Component>`) or write your own StyleX. The plain path already supports `xstyle` overrides \u2014 this path is for editing component internals. Some built-in page templates also use StyleX for layout; if you scaffold one and see "Unexpected stylex.create call at runtime", add the compiler plugin for your bundler below.',
+          text: 'Only needed when you write your own StyleX (`stylex.create()`) or swizzle a component (`astryx swizzle <Component>`), which copies its StyleX source into your app. The plain path already supports `xstyle` overrides \u2014 this path is for your own StyleX code. Some built-in page templates also use StyleX for layout; if you scaffold one and see "Unexpected stylex.create call at runtime", add the compiler plugin for your bundler below.',
         },
         {
           type: 'code',
@@ -134,14 +135,13 @@ export const docs = {
           type: 'code',
           lang: 'css',
           label: 'globals.css',
-          code: `@layer reset, astryx-base, astryx-theme;
-
-@import "@astryxdesign/core/reset.css";
+          code: `@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
 @import "@astryxdesign/theme-neutral/theme.css";`,
         },
         {
           type: 'prose',
-          text: 'No `astryx.css` \u2014 the StyleX compiler produces component styles from source. Add the plugin for your bundler:',
+          text: 'Keep `astryx.css`: Astryx component styles always come from the prebuilt stylesheets. Point the StyleX compiler at your own source only, never at `node_modules/@astryxdesign`. Add the plugin for your bundler:',
         },
         {
           type: 'table',
@@ -149,7 +149,10 @@ export const docs = {
           rows: [
             ['Webpack', '@stylexjs/webpack-plugin'],
             ['Vite / Rollup', '@stylexjs/rollup-plugin'],
-            ['Babel (any)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],
+            [
+              'Babel (any)',
+              '@stylexjs/babel-plugin + @stylexjs/postcss-plugin',
+            ],
             ['Next.js (keep next/font)', '@stylexswc/nextjs-plugin'],
           ],
         },
@@ -159,6 +162,37 @@ export const docs = {
         },
       ],
     },
+    {
+      id: 'other-packages',
+      title: 'Other Astryx packages',
+      content: [
+        {
+          type: 'prose',
+          text: 'Every Astryx package whose components carry styles ships its own prebuilt stylesheet. Import it after `astryx.css` for each package you use. All of them place their rules in the same `astryx-base` layer, so your theme overrides win over every package.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'globals.css',
+          code: `@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/richtext/richtext.css"; /* Rich Text */
+@import "@astryxdesign/lab/lab.css"; /* Lab */
+@import "@astryxdesign/charts/charts.css"; /* Charts */
+@import "@astryxdesign/theme-neutral/theme.css";`,
+        },
+        {
+          type: 'table',
+          headers: ['Package', 'Stylesheet'],
+          rows: [
+            ['@astryxdesign/core', '@astryxdesign/core/astryx.css'],
+            ['@astryxdesign/richtext', '@astryxdesign/richtext/richtext.css'],
+            ['@astryxdesign/lab', '@astryxdesign/lab/lab.css'],
+            ['@astryxdesign/charts', '@astryxdesign/charts/charts.css'],
+          ],
+        },
+      ],
+    },
     {
       id: 'what-each-file-does',
       title: 'What each import does',
@@ -175,7 +209,12 @@ export const docs = {
             [
               'astryx.css',
               'astryx-base',
-              'Pre-compiled component styles. Required for plain and Tailwind. Omit when compiling from source.',
+              'Prebuilt component styles. Required on every path.',
+            ],
+            [
+              'richtext.css, lab.css, charts.css',
+              'astryx-base',
+              'Prebuilt styles for each other Astryx package you use. Load after astryx.css.',
             ],
             [
               'theme.css',