@astryxdesign/cli 0.0.15 → 0.1.0-canary.08d4cf4

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @xds/cli
 
+# 0.1.0
+
+#### Breaking Changes
+
+- Read project config from `astryx.config.mjs` (was `xds.config.mjs`)
+  The CLI now resolves its optional project config from `astryx.config.mjs`
+  instead of `xds.config.mjs` — a hard cut, no fallback. Consumers with an
+  `xds.config.mjs` must rename it to `astryx.config.mjs` (the config shape and
+  all fields are unchanged). Part of removing `xds` naming from the public API.
+- Rename the CLI command/bin from `xds` to `astryx`
+  The CLI binary is now `astryx` (was `xds`); `bin/xds.mjs` is renamed to
+  `bin/astryx.mjs`, the dual `xds`+`astryx` bin entries collapse to a single
+  `astryx`, and the program/manifest name is `astryx`. Invoke the CLI as
+  `npx astryx <command>` (e.g. `npx astryx component Button`). The swizzle
+  default output dir moves from `./components/xds` to `./components/astryx`.
+  Consumers using `npx xds`, an `xds` npm-script alias, or the `xds` MCP server
+  name should switch to `astryx`. Part of removing `xds` naming from the public API.
+- Rename the exported `XDSError` class to `AstryxError`
+  The CLI's programmatic API error class is renamed `XDSError` -> `AstryxError`
+  (exported from `@xds/cli` + declared in its types). Consumers that catch or
+  reference `XDSError` from the CLI's API should switch to `AstryxError`. Part of
+  removing `xds` naming from the public API.
+- Remove the XDS-prefix compatibility layer — astryx is now the only public surface
+  This release erases all `xds` naming from the public API; there is no compatibility
+  window. Consumers must migrate (we own all consumers pre-OSS):
+- Remove the daily, brutalist, and default themes; neutral is the new baseline
+  Three theme packages are removed from the repo and will no longer be published:
+
+#### Fixes
+
+- `theme build` generates valid bare type imports (IconRegistry/DefinedTheme)
+  `astryx theme build` emitted `.d.ts` files importing `XDSIconRegistry` /
+  `XDSDefinedTheme` from `@xds/core`, but those aliases were removed — the
+  generated types failed to resolve. Generate `IconRegistry` / `DefinedTheme`
+  (the bare names `@xds/core` now exports) instead.
+
+#### Documentation
+
+- Update CLI theme docs to the current theme set
+  Refreshes the `astryx docs theme`, `getting-started`, `styling`,
+  `styling-libraries`, and `migration` reference docs to reflect the published
+  themes: `neutral`, `butter`, `chocolate`, `gothic`, `matcha`, `stone`, and
+  `y2k`. The removed `theme-default`, `theme-brutalist`, and `theme-daily`
+  packages are dropped from the docs, and install/import examples now use
+  `@astryxdesign/theme-neutral` as the recommended starting theme.
+
+#### Other Changes
+
+- **Component names:** the `XDS*` aliases are gone — use bare names (`Button` not
+  `XDSButton`, `useTheme` not `useXDSTheme`, `ButtonProps` not `XDSButtonProps`). The
+  `drop-xds-prefix-imports` codemod automates this.
+- **CSS classes:** components emit only `.astryx-*` (the dual `.xds-*` class is gone).
+  Update custom CSS selectors `.xds-button` -> `.astryx-button` (prop/state value classes
+  like `.primary`/`.sm` are unchanged).
+- **data attributes:** only `data-astryx-theme` / `data-astryx-media` are written; update
+  custom selectors and SSR root attributes off `data-xds-*`.
+- **CSS layers:** `@layer xds-base` / `xds-theme` are renamed to `astryx-base` /
+  `astryx-theme`; update your `@layer` order line and any PostCSS `layersBefore` config.
+  `@astryxdesign/build`'s default library layer is now `astryx-base`.
+- **Pre-compiled stylesheet:** the `@astryxdesign/core/xds.css` export is removed — import
+  `@astryxdesign/core/astryx.css`.
+- **CSS custom properties:** the `--xds-*` padding fallback is gone; set `--astryx-*`.
+- **CLI config key:** `@astryxdesign/cli` reads the package.json `"astryx"` field (was `"xds"`).
+  Rename the block; a stale `"xds"` key silently drops the package from discovery.
+- `@astryxdesign/theme-daily`
+- `@astryxdesign/theme-brutalist`
+- `@astryxdesign/theme-default`
+- import {defaultTheme} from '@astryxdesign/theme-default/built';
+  - import {neutralTheme} from '@astryxdesign/theme-neutral/built';
+- <Theme theme={defaultTheme}>...</Theme>
+  - <Theme theme={neutralTheme}>...</Theme>
+  ```
+
+  ```
+- Remove the internal `drop-xds-meta-prefix` codemod from the OSS repo (#2970)
+  This codemod has been moved to its own package's tooling, where it belongs. It was registered as an optional, version-independent transform and is not part of any standard upgrade path, so removing it does not affect the public `0.0.13 → 0.0.15` migration.
+- Rename the npm package scope from `@xds/*` to `@astryxdesign/*`
+  All published packages move to the new `@astryxdesign` scope (e.g. `@xds/core` → `@astryxdesign/core`), along with the workspace lockfile, build/runtime scope-directory scans, and docsite slug derivation. Consumers must update their imports and dependency names. The internal ESLint plugin namespace (`@xds/*` rules) is intentionally untouched and tracked separately. Existing `@xds/*` codemods continue to target the old scope so projects still on `@xds/*` can migrate.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @ejhammond
+
+---
+
 # 0.0.15
 
 #### Breaking Changes

package/README.md

@@ -11,7 +11,7 @@ npx astryx docs migration
 npx astryx template --list
 ```
 
-### Finding things: `astryx search`
+## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
 or a template, search across all of them at once. Results are ranked by
@@ -50,20 +50,20 @@ Options:
 
 ## Commands
 
-| Command       | Description                                                                             |
-| ------------- | --------------------------------------------------------------------------------------- |
+| Command       | Description                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
 | `init`        | Initialize the design system in your project: installs packages, sets up theming, adds AI agent docs |
-| `component`   | List components or print detailed docs, props, usage examples, and source               |
-| `search`      | Find components, hooks, docs, and templates in one ranked, cross-domain result set       |
-| `docs`        | Print reference documentation (tokens, theme, color, typography, spacing, etc.)         |
-| `template`    | Inject page or block templates into your project                                        |
-| `hook`        | List hooks and print hook documentation                                                 |
-| `swizzle`     | Copy component source into your project for deep customization                          |
-| `upgrade`     | Run codemods to migrate between versions                                                |
-| `theme build` | Compile a defineTheme file to production CSS and JS                                     |
-| `discover`    | Discover external packages and components                                               |
-| `gap-report`  | Report a gap when a component doesn't meet your needs                                   |
-| `doctor`      | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)      |
+| `component`   | List components or print detailed docs, props, usage examples, and source                            |
+| `search`      | Find components, hooks, docs, and templates in one ranked, cross-domain result set                   |
+| `docs`        | Print reference documentation (tokens, theme, color, typography, spacing, etc.)                      |
+| `template`    | Inject page or block templates into your project                                                     |
+| `hook`        | List hooks and print hook documentation                                                              |
+| `swizzle`     | Copy component source into your project for deep customization                                       |
+| `upgrade`     | Run codemods to migrate between versions                                                             |
+| `theme build` | Compile a defineTheme file to production CSS and JS                                                  |
+| `discover`    | Discover external packages and components                                                            |
+| `gap-report`  | Report a gap when a component doesn't meet your needs                                                |
+| `doctor`      | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)                   |
 
 ### Global options
 
@@ -122,46 +122,46 @@ if (isError(result)) {
 
 ### Error codes
 
-| Code | Meaning |
-| --- | --- |
-| `ERR_UNKNOWN` | Generic fallback for any error without a more specific code. |
-| `ERR_UNKNOWN_COMMAND` | A top-level command name was not recognized (e.g. `astryx bogus`). |
-| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a group was not recognized (e.g. `astryx theme bogus`). |
-| `ERR_INVALID_OPTION` | An unknown flag was passed, or `--json` was used on a command that doesn't support it. |
-| `ERR_INVALID_ARGUMENT` | An option/argument value was rejected, or required flags were missing. |
-| `ERR_MISSING_ARGUMENT` | A required positional argument was omitted (e.g. `astryx theme build` with no file). |
-| `ERR_INVALID_LANG` | `--lang` was given a value outside its choices (`en`, `zh`, `dense`). |
-| `ERR_INVALID_DETAIL` | `--detail` was given a value outside its choices (`full`, `compact`, `brief`). |
-| `ERR_NODE_VERSION` | The running Node.js version is below the supported minimum. |
-| `ERR_CORE_NOT_FOUND` | `@astryxdesign/core` could not be located (not installed / not in a monorepo). |
-| `ERR_UNKNOWN_COMPONENT` | No component matched the requested name. |
-| `ERR_UNKNOWN_HOOK` | No hook matched the requested name. |
-| `ERR_UNKNOWN_TOPIC` | No docs topic matched the requested name. |
-| `ERR_UNKNOWN_SECTION` | A docs topic exists but the requested section within it does not. |
-| `ERR_UNKNOWN_CATEGORY` | A `--category` filter value did not match any known category. |
-| `ERR_UNKNOWN_TEMPLATE` | No template matched the requested name. |
-| `ERR_UNKNOWN_PACKAGE` | No package matched the requested name (discover). |
-| `ERR_UNKNOWN_AGENT` | An unrecognized `--agent` value was passed (agent docs / init). |
-| `ERR_UNKNOWN_FEATURE` | An unrecognized `--features` value was passed to `init`. |
-| `ERR_UNKNOWN_CODEMOD` | A `--codemod` value did not match any registered codemod (upgrade). |
-| `ERR_NOT_FOUND` | A discover/lookup query matched nothing in any package. |
-| `ERR_NO_DOC` | A component exists but has no typed `.doc.mjs` file. |
-| `ERR_NO_SHOWCASE` | No showcase exists for the requested component. |
-| `ERR_NO_SOURCE` | No source file could be located for the component/template. |
-| `ERR_INVALID_DOC` | A component's docs failed validation (malformed `.doc.mjs`). |
-| `ERR_FILE_NOT_FOUND` | A required input file did not exist. |
-| `ERR_FILE_EXISTS` | Refused to overwrite an existing file in non-interactive mode. |
-| `ERR_PATH_TRAVERSAL` | A path escaped its allowed root, or a name contained traversal markers. |
-| `ERR_WRITE_FAILED` | Writing output files failed (and was rolled back). |
-| `ERR_THEME_INVALID` | A theme definition was missing a required property (e.g. `name`). |
-| `ERR_THEME_LOAD` | A theme file could not be loaded / parsed into a `defineTheme` result. |
-| `ERR_TEMPLATE_CONFIG` | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id). |
-| `ERR_TEMPLATE_GET` | A configured `template.get` threw or returned an invalid value. |
-| `ERR_VERSION_DETECT` | The current `@astryxdesign/core` version could not be detected. |
-| `ERR_INVALID_VERSION` | A `--from`/`--to` value was not a valid semver string. |
-| `ERR_DEP_MISSING` | A required external dependency (e.g. jscodeshift) is missing. |
-| `ERR_GH_CLI` | GitHub CLI (`gh`) is not installed or not authenticated. |
-| `ERR_GAP_REPORT_FAILED` | Filing a gap report failed (disabled, or the integration errored). |
+| Code                     | Meaning                                                                                |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| `ERR_UNKNOWN`            | Generic fallback for any error without a more specific code.                           |
+| `ERR_UNKNOWN_COMMAND`    | A top-level command name was not recognized (e.g. `astryx bogus`).                     |
+| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a group was not recognized (e.g. `astryx theme bogus`).             |
+| `ERR_INVALID_OPTION`     | An unknown flag was passed, or `--json` was used on a command that doesn't support it. |
+| `ERR_INVALID_ARGUMENT`   | An option/argument value was rejected, or required flags were missing.                 |
+| `ERR_MISSING_ARGUMENT`   | A required positional argument was omitted (e.g. `astryx theme build` with no file).   |
+| `ERR_INVALID_LANG`       | `--lang` was given a value outside its choices (`en`, `zh`, `dense`).                  |
+| `ERR_INVALID_DETAIL`     | `--detail` was given a value outside its choices (`full`, `compact`, `brief`).         |
+| `ERR_NODE_VERSION`       | The running Node.js version is below the supported minimum.                            |
+| `ERR_CORE_NOT_FOUND`     | `@astryxdesign/core` could not be located (not installed / not in a monorepo).         |
+| `ERR_UNKNOWN_COMPONENT`  | No component matched the requested name.                                               |
+| `ERR_UNKNOWN_HOOK`       | No hook matched the requested name.                                                    |
+| `ERR_UNKNOWN_TOPIC`      | No docs topic matched the requested name.                                              |
+| `ERR_UNKNOWN_SECTION`    | A docs topic exists but the requested section within it does not.                      |
+| `ERR_UNKNOWN_CATEGORY`   | A `--category` filter value did not match any known category.                          |
+| `ERR_UNKNOWN_TEMPLATE`   | No template matched the requested name.                                                |
+| `ERR_UNKNOWN_PACKAGE`    | No package matched the requested name (discover).                                      |
+| `ERR_UNKNOWN_AGENT`      | An unrecognized `--agent` value was passed (agent docs / init).                        |
+| `ERR_UNKNOWN_FEATURE`    | An unrecognized `--features` value was passed to `init`.                               |
+| `ERR_UNKNOWN_CODEMOD`    | A `--codemod` value did not match any registered codemod (upgrade).                    |
+| `ERR_NOT_FOUND`          | A discover/lookup query matched nothing in any package.                                |
+| `ERR_NO_DOC`             | A component exists but has no typed `.doc.mjs` file.                                   |
+| `ERR_NO_SHOWCASE`        | No showcase exists for the requested component.                                        |
+| `ERR_NO_SOURCE`          | No source file could be located for the component/template.                            |
+| `ERR_INVALID_DOC`        | A component's docs failed validation (malformed `.doc.mjs`).                           |
+| `ERR_FILE_NOT_FOUND`     | A required input file did not exist.                                                   |
+| `ERR_FILE_EXISTS`        | Refused to overwrite an existing file in non-interactive mode.                         |
+| `ERR_PATH_TRAVERSAL`     | A path escaped its allowed root, or a name contained traversal markers.                |
+| `ERR_WRITE_FAILED`       | Writing output files failed (and was rolled back).                                     |
+| `ERR_THEME_INVALID`      | A theme definition was missing a required property (e.g. `name`).                      |
+| `ERR_THEME_LOAD`         | A theme file could not be loaded / parsed into a `defineTheme` result.                 |
+| `ERR_TEMPLATE_CONFIG`    | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id).                 |
+| `ERR_TEMPLATE_GET`       | A configured `template.get` threw or returned an invalid value.                        |
+| `ERR_VERSION_DETECT`     | The current `@astryxdesign/core` version could not be detected.                        |
+| `ERR_INVALID_VERSION`    | A `--from`/`--to` value was not a valid semver string.                                 |
+| `ERR_DEP_MISSING`        | A required external dependency (e.g. jscodeshift) is missing.                          |
+| `ERR_GH_CLI`             | GitHub CLI (`gh`) is not installed or not authenticated.                               |
+| `ERR_GAP_REPORT_FAILED`  | Filing a gap report failed (disabled, or the integration errored).                     |
 
 ## Capability manifest (agent discovery)
 
@@ -186,25 +186,59 @@ Shape:
     "version": "0.0.14",
     "description": "Design system CLI — components, themes, and tooling",
     "globalOptions": [
-      {"flag": "--json", "type": "boolean", "description": "Output as typed JSON…"},
-      {"flag": "--lang <locale>", "type": "enum", "choices": ["en", "zh", "dense"]},
-      {"flag": "--detail <level>", "type": "enum", "choices": ["full", "compact", "brief"], "default": "full"}
+      {
+        "flag": "--json",
+        "type": "boolean",
+        "description": "Output as typed JSON…",
+      },
+      {
+        "flag": "--lang <locale>",
+        "type": "enum",
+        "choices": ["en", "zh", "dense"],
+      },
+      {
+        "flag": "--detail <level>",
+        "type": "enum",
+        "choices": ["full", "compact", "brief"],
+        "default": "full",
+      },
     ],
     "commands": [
       {
         "name": "component",
         "description": "List components or print component docs",
-        "arguments": [{"name": "name", "required": false, "variadic": false, "description": ""}],
-        "options": [{"flag": "--props", "type": "boolean", "description": "Print only the props table"}],
+        "arguments": [
+          {
+            "name": "name",
+            "required": false,
+            "variadic": false,
+            "description": "",
+          },
+        ],
+        "options": [
+          {
+            "flag": "--props",
+            "type": "boolean",
+            "description": "Print only the props table",
+          },
+        ],
         "json": true,
-        "responseTypes": ["component.list", "component.detail", "component.detail.props", "…"],
-        "examples": ["astryx component Button --props --json"]
-      }
+        "responseTypes": [
+          "component.list",
+          "component.detail",
+          "component.detail.props",
+          "…",
+        ],
+        "examples": ["astryx component Button --props --json"],
+      },
       // …one entry per command; subcommands (e.g. `theme build`) nest under `subcommands`
     ],
     "jsonSupported": ["component", "docs", "…"],
-    "responseTypes": {"component": ["component.list", "…"], "theme build": ["theme.build"]}
-  }
+    "responseTypes": {
+      "component": ["component.list", "…"],
+      "theme build": ["theme.build"],
+    },
+  },
 }
 ```
 
@@ -225,7 +259,15 @@ For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest
 The same logic that powers `xds --json` is available as importable, type-safe functions:
 
 ```typescript
-import {component, docs, discover, template, hook, search, AstryxError} from '@astryxdesign/cli/api';
+import {
+  component,
+  docs,
+  discover,
+  template,
+  hook,
+  search,
+  AstryxError,
+} from '@astryxdesign/cli/api';
 
 // Same result as: xds --json component Button
 const btn = await component('Button');
@@ -341,7 +383,7 @@ astryx doctor — diagnosing your setup
       @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
   ⚠ Theme packages
       No @astryxdesign/theme-* packages are installed.
-      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-default`, then import its CSS or set xds.theme.
+      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.
   ℹ astryx.config.mjs
       No astryx.config.mjs found — using defaults.
   ℹ AI agent docs
@@ -359,16 +401,16 @@ No failures — but review the ⚠ warnings above when you can.
 
 ### Checks
 
-| Check                | Status it can return | What it verifies                                            |
-| -------------------- | -------------------- | ----------------------------------------------------------- |
-| Node.js version      | pass / fail          | Running Node meets the CLI's minimum                        |
-| @astryxdesign/core installed  | pass / fail          | `@astryxdesign/core` is resolvable from the project                  |
-| Version alignment    | pass / warn / info   | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli`            |
-| Theme packages       | pass / warn          | An `@astryxdesign/theme-*` package is installed and a theme is wired |
-| astryx.config.mjs       | pass / fail / info   | Config (if present) loads cleanly with a valid shape        |
-| AI agent docs        | pass / warn / info   | Agent docs exist and contain the XDS section markers        |
-| Peer dependencies    | pass / warn / info   | `@astryxdesign/core`'s peer deps (react, …) are installed            |
-| Package manager      | info                 | Reports the detected package manager                        |
+| Check                        | Status it can return | What it verifies                                                     |
+| ---------------------------- | -------------------- | -------------------------------------------------------------------- |
+| Node.js version              | pass / fail          | Running Node meets the CLI's minimum                                 |
+| @astryxdesign/core installed | pass / fail          | `@astryxdesign/core` is resolvable from the project                  |
+| Version alignment            | pass / warn / info   | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli`   |
+| Theme packages               | pass / warn          | An `@astryxdesign/theme-*` package is installed and a theme is wired |
+| astryx.config.mjs            | pass / fail / info   | Config (if present) loads cleanly with a valid shape                 |
+| AI agent docs                | pass / warn / info   | Agent docs exist and contain the XDS section markers                 |
+| Peer dependencies            | pass / warn / info   | `@astryxdesign/core`'s peer deps (react, …) are installed            |
+| Package manager              | info                 | Reports the detected package manager                                 |
 
 ### CI gate
 

package/bin/astryx.mjs

@@ -12,10 +12,25 @@
 //
 // `node-version.mjs` is intentionally dependency-free so it loads on the
 // unsupported runtimes this guard protects against.
-import {
-  isNodeVersionSupported,
-  unsupportedNodeMessage,
-} from '../src/lib/node-version.mjs';
+//
+// Sibling `src/` modules are resolved by this bin's REAL path. When the CLI is
+// installed as a package, `npx astryx` runs this file through the
+// `node_modules/.bin/astryx` symlink, and some Node versions resolve relative
+// specifiers from the symlink's directory (→ `node_modules/src/...`) rather
+// than the real package — breaking bare `../src/...` imports with a cryptic
+// ERR_MODULE_NOT_FOUND. realpath-ing `import.meta.url` makes these imports
+// resolve correctly however the bin is invoked (symlink, copy, or Windows
+// shim). Uses only built-ins, so the version gate below still runs first.
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {realpathSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+
+const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+const importSrc = rel =>
+  import(pathToFileURL(join(binDir, '..', 'src', rel)).href);
+
+const {isNodeVersionSupported, unsupportedNodeMessage} =
+  await importSrc('lib/node-version.mjs');
 
 if (!isNodeVersionSupported(process.versions.node)) {
   const msg = unsupportedNodeMessage(process.versions.node);
@@ -39,9 +54,9 @@ if (!isNodeVersionSupported(process.versions.node)) {
 
 // Imports that transitively load `styleText` must happen AFTER the gate above,
 // so they are dynamically imported here rather than at the top of the module.
-const {program} = await import('../src/index.mjs');
-const {isJsonMode, toErrorEnvelope} = await import('../src/lib/json.mjs');
-const {handleCommanderError} = await import('../src/lib/json-shim.mjs');
+const {program} = await importSrc('index.mjs');
+const {isJsonMode, toErrorEnvelope} = await importSrc('lib/json.mjs');
+const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
 
 /**
  * Top-level error boundary (contract guarantee #4): an uncaught throw must

package/docs/getting-started.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/core, @astryxdesign/theme-default, and @astryxdesign/cli in this project. Run `npx astryx init` to set up agent docs. Read the generated files to learn the conventions.',
+          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project. Run `npx astryx init` to set up agent docs. Read the generated files to learn the conventions.',
         },
       ],
     },
@@ -36,7 +36,7 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `npm install @astryxdesign/core @astryxdesign/theme-default @astryxdesign/cli`,
+          code: `npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli`,
         },
         {
           type: 'prose',
@@ -63,11 +63,11 @@ export const docs = {
           label: 'globals.css',
           code: `@import '@astryxdesign/core/reset.css';
 @import '@astryxdesign/core/astryx.css';
-@import '@astryxdesign/theme-default/theme.css';`,
+@import '@astryxdesign/theme-neutral/theme.css';`,
         },
         {
           type: 'prose',
-          text: 'Available themes: @astryxdesign/theme-default (blue accent), @astryxdesign/theme-neutral (grayscale), @astryxdesign/theme-brutalist (zero radius, monospace). See `npx astryx docs theme` for the full theming guide.',
+          text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `npx astryx docs theme` for the full theming guide.',
         },
       ],
     },
@@ -88,7 +88,7 @@ import {VStack} from '@astryxdesign/core/Layout';
 export default function Page() {
   return (
     <VStack gap={2}>
-      <Button label="Hello XDS" onClick={() => alert('Hi!')} />
+      <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
     </VStack>
   );
 }`,
@@ -96,11 +96,11 @@ export default function Page() {
       ],
     },
     {
-      title: 'Customize with xstyle',
+      title: 'Customize with StyleX',
       content: [
         {
           type: 'prose',
-          text: 'Every component accepts an `xstyle` prop for StyleX style overrides created via `stylex.create()`.',
+          text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](/docs/styling) for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
         },
         {
           type: 'code',
@@ -127,19 +127,19 @@ const overrides = stylex.create({
           type: 'table',
           headers: ['Example', 'Stack', 'Path'],
           rows: [
-            ['Next.js', 'Next.js + theme CSS', 'apps/example-nextjs'],
-            ['Next.js + StyleX', 'Next.js + StyleX for custom styles', 'apps/example-nextjs-stylex'],
-            ['Next.js + Tailwind', 'Next.js + Tailwind bridge', 'apps/example-nextjs-tailwind'],
-            ['Next.js Source', 'Next.js importing from source', 'apps/example-nextjs-source'],
-            ['Vite', 'Vite', 'apps/example-vite'],
+            ['Next.js', 'Next.js + theme CSS', '[apps/example-nextjs](https://github.com/facebook/astryx/tree/main/apps/example-nextjs)'],
+            ['Next.js + StyleX', 'Next.js + StyleX for custom styles', '[apps/example-nextjs-stylex](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-stylex)'],
+            ['Next.js + Tailwind', '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)'],
           ],
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Clone and run an example',
-          code: `git clone https://github.com/facebookexperimental/xds.git
-cd xds/apps/example-nextjs
+          code: `git clone https://github.com/facebook/astryx.git
+cd astryx/apps/example-nextjs
 pnpm install
 pnpm dev`,
         },
@@ -157,7 +157,7 @@ pnpm dev`,
           lang: 'json',
           label: 'package.json',
           code: `"scripts": {
-  "xds": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+  "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
 }`,
         },
         {

package/docs/icons.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Icons reference doc: semantic icon names available in XDS
+ * @file Icons reference doc: semantic icon names available in Astryx
  */
 
 /** @type {import('../../core/src/docs-types').ReferenceDoc} */

package/docs/migration.doc.mjs

@@ -91,15 +91,15 @@ npx astryx component Button --json`,
           lang: 'tsx',
           label: 'Root provider with explicit mode',
           code: `import {Theme} from '@astryxdesign/core/theme';
-import {defaultTheme} from '@astryxdesign/theme-default/built';
+import {neutralTheme} from '@astryxdesign/theme-neutral/built';
 import {useState} from 'react';
-import '@astryxdesign/theme-default/theme.css';
+import '@astryxdesign/theme-neutral/theme.css';
 
 export function AppRoot({children}: {children: React.ReactNode}) {
   const [mode, setMode] = useState<'system' | 'light' | 'dark'>('system');
 
   return (
-    <Theme theme={defaultTheme} mode={mode}>
+    <Theme theme={neutralTheme} mode={mode}>
       <SettingsContext.Provider value={{mode, setMode}}>
         {children}
       </SettingsContext.Provider>
@@ -121,7 +121,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
 @import "tailwindcss/preflight.css" layer(base);
 @import "@astryxdesign/core/reset.css";
 @import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-default/theme.css";
+@import "@astryxdesign/theme-neutral/theme.css";
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },
@@ -234,7 +234,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: `We are migrating this existing Tailwind/shadcn app to XDS incrementally.
+          code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
 
 First run:
 - npx astryx docs migration --dense
@@ -242,7 +242,7 @@ First run:
 - npx astryx docs styling --dense
 - npx astryx template AppShellTopNavWithSideNav --skeleton
 
-Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with XDS components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
+Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
         },
       ],
     },

package/docs/shape.doc.mjs

@@ -44,7 +44,7 @@ export const docs = {
           type: 'code',
           lang: 'css',
           label: 'Concentric radius formula',
-          code: `/* Automatic in XDS Card */
+          code: `/* Automatic in Astryx Card */
 --card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
         },
       ],

package/docs/styling-libraries.doc.mjs

@@ -162,7 +162,7 @@ const styles = stylex.create({
 @import "tailwindcss/preflight.css" layer(base);
 @import "@astryxdesign/core/reset.css";
 @import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-default/theme.css";
+@import "@astryxdesign/theme-neutral/theme.css";
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },
@@ -374,9 +374,9 @@ tokens: {
           lang: 'ts',
           label: 'Resolve tokens without React context',
           code: `import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';
-import {defaultTheme} from '@astryxdesign/theme-default';
+import {neutralTheme} from '@astryxdesign/theme-neutral';
 
-const tokens = resolveThemeTokens(defaultTheme, {mode: 'light'});
+const tokens = resolveThemeTokens(neutralTheme, {mode: 'light'});
 
 const chartOptions = {
   textColor: tokens['--color-text-primary'],

package/docs/styling.doc.mjs

@@ -22,9 +22,8 @@ export const docs = {
           type: 'table',
           headers: ['Approach', 'Use for', 'Example'],
           rows: [
-            ['xstyle prop', 'Overriding a specific component', 'xstyle={styles.override}'],
+            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', 'const styles = stylex.create(...); <Button xstyle={styles.save} />'],
             ['Tailwind utilities', 'Layout, wrappers, and utility styling', 'className="flex gap-3 p-4"'],
-            ['stylex.create', 'Reusable styles, pseudo-classes, typed tokens', 'stylex.create({ card: { ... } })'],
             ['className', 'Integrating with external CSS or Tailwind on components', 'className="my-card shadow-lg"'],
             ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "colors.surface = 'var(--color-background-surface)'"],
           ],
@@ -104,7 +103,7 @@ const overrides = stylex.create({
 @import "tailwindcss/preflight.css" layer(base);
 @import "@astryxdesign/core/reset.css";
 @import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-default/theme.css";
+@import "@astryxdesign/theme-neutral/theme.css";
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },
@@ -232,7 +231,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'When external CSS needs to target an XDS component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
+          text: 'When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
         },
         {
           type: 'code',
@@ -274,7 +273,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'XDS still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
+          text: 'Astryx still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
         },
         {
           type: 'code',

package/docs/theme.doc.dense.mjs

@@ -5,8 +5,8 @@
 export const docsDense = {
   description: 'Theme provider, custom themes, light/dark, component overrides',
   sections: [
-    { title: 'Quick Start', content: [null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
-    { title: 'Themes', content: [null, { type: 'prose', text: '@astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
+    { title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
+    { 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).' }] },
     { title: 'Props', content: [null] },
     { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
     { 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] },