An open source design system that's fully customizable and agent ready
TypeScript
docs: replace stale XDS references with Astryx across docs, examples, and CLI (#3422)
EJ Hammond966989df5e2c
diff --git a/.changeset/fix-doctor-astryx-theme-hint.md b/.changeset/fix-doctor-astryx-theme-hint.mdnew file mode 100644index 0000000000..3dea82cd26--- /dev/null+++ b/.changeset/fix-doctor-astryx-theme-hint.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] Correct the `doctor` theme-wiring hint to reference the real `astryx.theme` config field (was `xds.theme`) and update the agent-docs check wording to say "Astryx".++@ejhammonddiff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.mdindex 142dee30e9..ba38320210 100644--- a/.claude/commands/create-component.md+++ b/.claude/commands/create-component.md@@ -1,6 +1,6 @@-# Create XDS Component+# Create Astryx Component-Create a new XDS component following the established protocols.+Create a new Astryx component following the established protocols.## Component Name@@ -8,19 +8,19 @@ $ARGUMENTS## Instructions-Follow the full component lifecycle documented on the XDS wiki:+Follow the full component lifecycle documented on the Astryx wiki:-- **Lifecycle Overview**: https://github.com/facebookexperimental/xds/wiki/Component-Lifecycle-- **Specification Protocol**: https://github.com/facebookexperimental/xds/wiki/Component-Specification-Protocol-- **Build Protocol**: https://github.com/facebookexperimental/xds/wiki/Component-Build-Protocol+- **Lifecycle Overview**: https://github.com/facebook/astryx/wiki/Component-Lifecycle+- **Specification Protocol**: https://github.com/facebook/astryx/wiki/Component-Specification-Protocol+- **Build Protocol**: https://github.com/facebook/astryx/wiki/Component-Build-Protocol### Quick reference- Read the spec thoroughly — it's the contract- Study sibling components in the same family for patterns- Create files in `packages/core/src/{ComponentName}/`:- - `XDS{ComponentName}.tsx` — main component- - `XDS{ComponentName}.test.tsx` — unit tests+ - `{ComponentName}.tsx` — main component+ - `{ComponentName}.test.tsx` — unit tests- `{ComponentName}.doc.mjs` — typed docs (ComponentDoc)- `index.ts` — public exports- Create `apps/storybook/stories/{ComponentName}.stories.tsx`@@ -33,9 +33,9 @@ Follow the full component lifecycle documented on the XDS wiki:### Key conventions-- **API Conventions**: https://github.com/facebookexperimental/xds/wiki/API-Conventions-- **Theming**: Use `xdsClassName()` for theme targets — see https://github.com/facebookexperimental/xds/wiki/Theming-Infrastructure-- **Compose, don't rebuild** — use existing XDS components (XDSField, XDSIcon, etc.)+- **API Conventions**: https://github.com/facebook/astryx/wiki/API-Conventions+- **Theming**: Use `stableClassName()` (or the `themeProps()` helper) for theme targets — see https://github.com/facebook/astryx/wiki/Theming-Infrastructure+- **Compose, don't rebuild** — use existing Astryx components (Field, Icon, etc.)- **displayName** — always set it- **:hover guards** — all `:hover` in `@media (hover: hover)`- **Spacing/elevation tokens** — never raw px or boxShadow stringsdiff --git a/.claude/commands/create-theme.md b/.claude/commands/create-theme.mdindex c6dca81130..b6d5bbf60e 100644--- a/.claude/commands/create-theme.md+++ b/.claude/commands/create-theme.md@@ -1,6 +1,6 @@-# Create XDS Theme+# Create Astryx Theme-Create a new XDS theme using `defineTheme`.+Create a new Astryx theme using `defineTheme`.## Theme Name@@ -26,7 +26,7 @@ packages/themes/{themeName}/"name": "@astryxdesign/theme-{themeName}","version": "0.0.1","private": false,- "description": "{Description} theme for XDS",+ "description": "{Description} theme for Astryx","license": "MIT","sideEffects": false,"main": "./src/index.ts",@@ -37,7 +37,7 @@ packages/themes/{themeName}/},"files": ["dist", "src"],"scripts": {- "build:theme": "xds build-theme src/index.ts -o dist/theme.css"+ "build:theme": "astryx theme build src/index.ts -o dist/theme.css"},"peerDependencies": {"@astryxdesign/core": "*"@@ -144,7 +144,7 @@ Component overrides generate scoped CSS:### Distribution-- **Unbuilt**: `XDSTheme` generates CSS and injects `<style>` at runtime+- **Unbuilt**: `Theme` generates CSS and injects `<style>` at runtime- **Built**: `npx astryx theme build` pre-compiles to a CSS file## Extending an Existing Themediff --git a/.claude/skills/dense-compression-protocol.md b/.claude/skills/dense-compression-protocol.mdindex fab1b3e34f..31eaa6c1c6 100644--- a/.claude/skills/dense-compression-protocol.md+++ b/.claude/skills/dense-compression-protocol.md@@ -1,6 +1,6 @@-# XDS Translation Protocol+# Astryx Translation Protocol-Apply this protocol to create a dense translation for an XDS component `.doc.mjs` file. The dense translation lives in the same file as a `docsDense` export and is the source the CLI reads when called with `--lang dense`.+Apply this protocol to create a dense translation for an Astryx component `.doc.mjs` file. The dense translation lives in the same file as a `docsDense` export and is the source the CLI reads when called with `--lang dense`.## Purpose@@ -19,9 +19,9 @@ export const docsDense = {// 1:1 with docs.usage.bestPractices — same length, same orderusage: {bestPractices: [- { guidance: true, description: 'compressed Do bullet 1' },- { guidance: true, description: 'compressed Do bullet 2' },- { guidance: false, description: 'compressed Don\'t bullet 1' },+ {guidance: true, description: 'compressed Do bullet 1'},+ {guidance: true, description: 'compressed Do bullet 2'},+ {guidance: false, description: "compressed Don't bullet 1"},],},propDescriptions: {@@ -30,9 +30,9 @@ export const docsDense = {},components: [{- name: 'XDSDialogHeader',+ name: 'DialogHeader',description: 'compressed sub-component desc',- propDescriptions: { title: 'compressed desc' },+ propDescriptions: {title: 'compressed desc'},},],};@@ -41,6 +41,7 @@ export const docsDense = {## Compression RulesDrop:+- Articles (`a`, `the`, `an`)- Filler verbs (`is used for`, `provides`, `supports`, `displays`, `whether`)- Subject when context is obvious@@ -60,22 +61,22 @@ Use fragments, not full sentences. Shorthand: `w/`, `w/o`, `+` for "and", `;` fo### 2. Signal words — keep these even when compressing-These words change *behavior*. They must survive compression.+These words change _behavior_. They must survive compression.-| Category | Words |-|---|---|-| Conditionals | `if`, `when`, `unless`, `only` |-| Constraints | `must`, `cannot`, `never`, `always`, `required` |-| Cross-references | `instead`, `instead of`, plus full component+prop refs like `XDSChatMessage's name prop` |-| Defaults & inheritance | `defaults to`, `override`, `inherit`, `context`, `automatically` |-| Accessibility | `keyboard`, `accessibility`, `aria-*`, `role=` |+| Category | Words |+| ---------------------- | ------------------------------------------------------------------------------------- |+| Conditionals | `if`, `when`, `unless`, `only` |+| Constraints | `must`, `cannot`, `never`, `always`, `required` |+| Cross-references | `instead`, `instead of`, plus full component+prop refs like `ChatMessage's name prop` |+| Defaults & inheritance | `defaults to`, `override`, `inherit`, `context`, `automatically` |+| Accessibility | `keyboard`, `accessibility`, `aria-*`, `role=` |❌ Bad: "use on first bubble in message"-✅ Good: "use on first bubble; **if** first child is raw, use XDSChatMessage's `name` **instead**"+✅ Good: "use on first bubble; **if** first child is raw, use ChatMessage's `name` **instead**"### 3. Cross-component references survive-If full prose says "use XDSFoo's `bar` prop instead", dense MUST keep both the component name (`XDSFoo`) and the prop name (`bar`) and the relationship word (`instead`).+If full prose says "use Foo's `bar` prop instead", dense MUST keep both the component name (`Foo`) and the prop name (`bar`) and the relationship word (`instead`).### 4. (required) markers preserved@@ -83,7 +84,7 @@ Required props must say so in dense propDescriptions, e.g. `'<desc> **(required)### 5. Sub-components are not optional-If `docs.components` includes hooks like `useXDSImperativeDialog` or `useXDSTableSelectionState`, `docsDense.components` must include them too. Hooks are part of the API.+If `docs.components` includes hooks like `useImperativeDialog` or `useTableSelectionState`, `docsDense.components` must include them too. Hooks are part of the API.## What NEVER Changes@@ -101,31 +102,31 @@ These patterns score as fidelity loss in vibe tests against the protocol. Do not### ❌ Synonym swaps that lose meaning-| Wrong (loses meaning) | Right (keeps signal) |-|---|---|-| `instead of X` → `not X` | `instead of X` → keep `instead` |-| `when X` → implicit (drop it) | `when X` → `if X` or keep `when` |-| `must` → drop word entirely | keep `must` or use `req'd` |-| `always provide X` → `provide X` | keep `always` |+| Wrong (loses meaning) | Right (keeps signal) |+| --------------------------------------------------------- | --------------------------------------------------- |+| `instead of X` → `not X` | `instead of X` → keep `instead` |+| `when X` → implicit (drop it) | `when X` → `if X` or keep `when` |+| `must` → drop word entirely | keep `must` or use `req'd` |+| `always provide X` → `provide X` | keep `always` || `never` → `don't` (when prose already starts with Don't:) | keep both: "Don't: never X" reads fine; or use `no` |The signal words list isn't suggestion — every word in it changes behavior. `instead` says "use this alternative." Replacing it with `not` or `,` removes the recommendation pointer.-### ❌ Truncating XDS component names+### ❌ Truncating component names-| Wrong | Right |-|---|---|-| `XDSChatSystemMessage` → `SystemMessage` | keep full name |-| `XDSChatMessageBubble` → `MessageBubble` or `bubble` | keep full name |-| `XDSChatMessage's name prop` → `bubble's name` | keep full ref |+| Wrong | Right |+| ------------------------------------------------- | -------------- |+| `ChatSystemMessage` → `SystemMessage` | keep full name |+| `ChatMessageBubble` → `MessageBubble` or `bubble` | keep full name |+| `ChatMessage's name prop` → `bubble's name` | keep full ref |-Cross-refs to other XDS components MUST keep the `XDS` prefix and the full PascalCase component name. The name is how an agent reaches the docs for it. `MessageBubble` is unsearchable; `XDSChatMessageBubble` is.+Cross-refs to other components MUST keep the full PascalCase component name. The name is how an agent reaches the docs for it. `MessageBubble` is unsearchable; `ChatMessageBubble` is.-The only acceptable shortening: in the second mention within the SAME bullet, you may drop the prefix. First mention always full.+The only acceptable shortening: in the second mention within the SAME bullet, you may drop the family prefix. First mention always full.-❌ Bad: "Don't use SystemMessage for sender content. Use XDSChatMessage instead."-✅ Good: "Don't use XDSChatSystemMessage for sender content. Use XDSChatMessage instead."-✅ Also fine: "Don't use XDSChatSystemMessage for sender content. Use XDSChatMessage instead — SystemMessage is for status only."+❌ Bad: "Don't use SystemMessage for sender content. Use ChatMessage instead."+✅ Good: "Don't use ChatSystemMessage for sender content. Use ChatMessage instead."+✅ Also fine: "Don't use ChatSystemMessage for sender content. Use ChatMessage instead — SystemMessage is for status only."### ✅ Acceptable compressionsdiff --git a/.claude/skills/writing-component-docs.md b/.claude/skills/writing-component-docs.mdindex 579fd615eb..9bc537a73d 100644--- a/.claude/skills/writing-component-docs.md+++ b/.claude/skills/writing-component-docs.md@@ -2,7 +2,7 @@## Overview-Every component directory has a `{Name}.doc.mjs` file with structured documentation. The XDS CLI reads these files to generate agent-friendly docs, skill files, and reference material.+Every component directory has a `{Name}.doc.mjs` file with structured documentation. The Astryx CLI reads these files to generate agent-friendly docs, skill files, and reference material.## Exports@@ -40,7 +40,7 @@ See `docs-types.ts` for the full type definition.export const docs = {name: 'Button',description:- 'XDSButton component with multiple variants, sizes, and isLoading state.',+ 'Button component with multiple variants, sizes, and isLoading state.',features: ['Variants: primary, secondary, ghost, destructive','Sizes: sm (28px), md (32px), lg (36px)',@@ -60,11 +60,11 @@ export const docs = {},],examples: [- {label: 'Basic', code: '<XDSButton label="Save" variant="primary" />'},+ {label: 'Basic', code: '<Button label="Save" variant="primary" />'},],accessibility: ['Uses native <button> with proper ARIA attributes.'],keyboard: 'Enter/Space activates; Tab moves focus.',- notes: ['Prefer XDSButton over <div onClick> for accessibility.'],+ notes: ['Prefer Button over <div onClick> for accessibility.'],};```diff --git a/.github/CODEOWNERS b/.github/CODEOWNERSindex 06af5ab81b..951c5212cf 100644--- a/.github/CODEOWNERS+++ b/.github/CODEOWNERS@@ -1,4 +1,4 @@-# Default reviewers for the XDS repository+# Default reviewers for the Astryx repository# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners# Cindy, Joey, and Dream review everything by defaultdiff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.ymlindex 8fd9f16ed1..5df9007ea8 100644--- a/.github/ISSUE_TEMPLATE/bug.yml+++ b/.github/ISSUE_TEMPLATE/bug.yml@@ -1,7 +1,7 @@# Copyright (c) Meta Platforms, Inc. and affiliates.name: Bug Report-description: Report a bug in an XDS component.+description: Report a bug in an Astryx component.title: "[Bug] "labels: ["bug"]body:@@ -29,7 +29,7 @@ body:- type: inputid: versionattributes:- label: XDS Version+ label: Astryx Versionplaceholder: "@astryxdesign/[email protected]"validations:required: truediff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.ymlindex d2114d7160..a50a2f99f5 100644--- a/.github/ISSUE_TEMPLATE/rfc.yml+++ b/.github/ISSUE_TEMPLATE/rfc.yml@@ -1,7 +1,7 @@# Copyright (c) Meta Platforms, Inc. and affiliates.name: "RFC: Component or Feature Proposal"-description: Propose a new component, feature, or significant API change for XDS.+description: Propose a new component, feature, or significant API change for Astryx.title: "[RFC] "labels: ["enhancement"]body:@@ -43,7 +43,7 @@ body:attributes:label: Why Existing Components Don't Cover Thisdescription: |- What have you tried with current XDS components? Show the composition attempt and where it breaks down. "I tried X but it requires Y lines of boilerplate / breaks accessibility / doesn't theme correctly."+ What have you tried with current Astryx components? Show the composition attempt and where it breaks down. "I tried X but it requires Y lines of boilerplate / breaks accessibility / doesn't theme correctly."placeholder: "I attempted to compose this using Card + VStack + ... but ..."validations:required: true@@ -95,7 +95,7 @@ body:required: true- label: I have read the [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)required: true- - label: I have checked that existing XDS components cannot compose to solve this+ - label: I have checked that existing Astryx components cannot compose to solve thisrequired: true- label: This is a general-purpose UI pattern (not specific to one product)required: truediff --git a/.github/SAMPLE_PR_COMMENT.md b/.github/SAMPLE_PR_COMMENT.mdindex 84f6ea2bdd..bdb480289f 100644--- a/.github/SAMPLE_PR_COMMENT.md+++ b/.github/SAMPLE_PR_COMMENT.md@@ -11,26 +11,26 @@ This is an example of what the PR enrichment workflow will post as a comment on<details><summary><strong>DatePicker</strong></summary>-| Metric | Value |-| ----------------- | ------------------------------ |-| Bundle Size (ESM) | 4.2KB |-| Exports | XDSDatePicker, DatePickerProps |-| Props Count | 12 |-| Has Tests | Yes |-| Has Stories | Yes |+| Metric | Value |+| ----------------- | --------------------------- |+| Bundle Size (ESM) | 4.2KB |+| Exports | DatePicker, DatePickerProps |+| Props Count | 12 |+| Has Tests | Yes |+| Has Stories | Yes |</details><details><summary><strong>TimePicker</strong></summary>-| Metric | Value |-| ----------------- | ------------- |-| Bundle Size (ESM) | 3.1KB |-| Exports | XDSTimePicker |-| Props Count | 8 |-| Has Tests | No |-| Has Stories | Yes |+| Metric | Value |+| ----------------- | ---------- |+| Bundle Size (ESM) | 3.1KB |+| Exports | TimePicker |+| Props Count | 8 |+| Has Tests | No |+| Has Stories | Yes |</details>@@ -56,8 +56,8 @@ This is an example of what the PR enrichment workflow will post as a comment on### Bundle Size Summary-| Package | Size (ESM) | Gzipped |-| --------- | ---------- | ------- |+| Package | Size (ESM) | Gzipped |+| ------------------ | ---------- | ------- || @astryxdesign/core | 45.2KB | 12.4KB |**Bundle size increased:** +850 bytes@@ -76,4 +76,4 @@ This is an example of what the PR enrichment workflow will post as a comment on----<sub>Generated by PR Enrichment workflow | [View full report](https://github.com/example/xds/actions/runs/12345)</sub>+<sub>Generated by PR Enrichment workflow | [View full report](https://github.com/example/astryx/actions/runs/12345)</sub>diff --git a/.github/scripts/api-cli-parity-test.mjs b/.github/scripts/api-cli-parity-test.mjsindex 525766966f..6848fb0a93 100644--- a/.github/scripts/api-cli-parity-test.mjs+++ b/.github/scripts/api-cli-parity-test.mjs@@ -6,7 +6,7 @@** Auto-discovers every component, doc topic, and CLI command,* then verifies the programmatic API returns identical results- * to `xds --json` for each one. Nothing is hardcoded.+ * to `astryx --json` for each one. Nothing is hardcoded.** Usage:* node .github/scripts/api-cli-parity-test.mjs # full run@@ -106,7 +106,7 @@ console.log(` ${allHooks.length} hooks, ${hookCategories.length} hook categorie// ─── Build cases ──────────────────────────────────────────────────────────────//// Each case: { label, cli, apiFn? }-// - cli: args for `xds --json ...`+// - cli: args for `astryx --json ...`// - apiFn: if present, called to get API result; compared with CLI result// - if apiFn is absent, CLI-only (still counted for coverage)diff --git a/.github/scripts/cli-smoke-test.mjs b/.github/scripts/cli-smoke-test.mjsindex 0859603e02..f51c46e9a3 100644--- a/.github/scripts/cli-smoke-test.mjs+++ b/.github/scripts/cli-smoke-test.mjs@@ -5,7 +5,7 @@* CLI smoke test — auto-discovers every command and checks for output + clean exit.** Nothing is hardcoded. Components are discovered from `astryx component --list`,- * doc topics from `astryx docs`, and detail levels from `xds --help`.+ * doc topics from `astryx docs`, and detail levels from `astryx --help`.** Catches regressions like:* - astryx component <name> crashing on bad importsdiff --git a/.github/workflows/cli-smoke-test.yml b/.github/workflows/cli-smoke-test.ymlindex a5e61b68ec..8aacf5857a 100644--- a/.github/workflows/cli-smoke-test.yml+++ b/.github/workflows/cli-smoke-test.yml@@ -1,6 +1,6 @@# Copyright (c) Meta Platforms, Inc. and affiliates.-# CLI smoke test — runs every xds command to catch regressions+# CLI smoke test — runs every astryx command to catch regressions# Auto-discovers components and doc topics, nothing hardcoded.name: CLI Smoke Testdiff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.ymlindex c4bbf293a3..e5e9043539 100644--- a/.github/workflows/deploy.yml+++ b/.github/workflows/deploy.yml@@ -193,7 +193,7 @@ jobs:echo "Restored reports"fi- # Copy XDS dist CSS for the landing page+ # Copy Astryx dist CSS for the landing pagemkdir -p deploy/assetscp packages/core/dist/astryx.css deploy/assets/astryx.csscp packages/core/src/reset.css deploy/assets/reset.css@@ -263,7 +263,7 @@ jobs:</div><span class="arrow">→</span></a>- <a class="card" href="https://github.com/facebookexperimental/xds">+ <a class="card" href="https://github.com/facebook/astryx"><div><div class="card-title">💻 GitHub</div><div class="card-desc">Source code, issues, and wiki</div>diff --git a/.gitignore b/.gitignoreindex 97e08cbe4a..f63b8f1d20 100644--- a/.gitignore+++ b/.gitignore@@ -45,7 +45,7 @@ e2e/playwright/.cache/# Vibe tests (large generated files)internal/vibe-tests/results/-# XDS agent docs (generated)+# Astryx agent docs (generated).astryx-docs/apps/sandbox/.next/apps/sandbox/out/diff --git a/CLAUDE.md b/CLAUDE.mdindex cbb6e24c19..de86c50a36 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,4 +1,4 @@-# XDS+# AstryxA design system for building internal tools and products.@@ -6,7 +6,7 @@ A design system for building internal tools and products.### `/vibe-test [count]` - Run vibeability tests-Tests how well AGENTS.md helps LLMs generate correct XDS component code.+Tests how well AGENTS.md helps LLMs generate correct Astryx component code.**Usage:**@@ -21,7 +21,7 @@ Tests how well AGENTS.md helps LLMs generate correct XDS component code.1. Run `pnpm -F @astryxdesign/vibe-tests interactive --sample <count>` to set up iteration2. Spawn parallel subagents (one per test prompt) to:- Read the task file from `results/<iteration>/tasks/{promptId}.json`- - Generate code for the prompt using XDS components (AGENTS.md auto-injected)+ - Generate code for the prompt using Astryx components (AGENTS.md auto-injected)- Self-evaluate for success/escape hatches- Write `.tsx` result to `results/<iteration>/results/{promptId}.tsx`- Write `.json` metadata to `results/<iteration>/results/{promptId}.json`@@ -50,7 +50,7 @@ Probes at turns 0, 6, 8, 10 to measure quality degradation. Results show a line## AI Context-For architectural context, decisions, and research, see the **[GitHub Wiki](https://github.com/facebookexperimental/xds/wiki)**:+For architectural context, decisions, and research, see the **[GitHub Wiki](https://github.com/facebook/astryx/wiki)**:- **Decisions** — API Conventions, Why StyleX, StyleX Distribution- **Architecture** — System Architecture, Component Authoring Guide@@ -111,32 +111,32 @@ Documentation lives in two places:|PATTERN: CSS fallback values -> stylex.firstThatWorks() (not manual fallback)|PATTERN: dynamic/runtime values -> stylex.create({ s: (val) => ({ prop: val }) }) (not inline styles)|PATTERN: conditional styles -> stylex.props(condition && styles.x) (not className toggling)-|PATTERN: link elements -> useXDSLinkComponent() (not hardcoded <a>). Consumers swap via XDSLinkProvider for framework routers (Next.js, React Router)+|PATTERN: link elements -> useLinkComponent() (not hardcoded <a>). Consumers swap via LinkProvider for framework routers (Next.js, React Router)|VERIFY: node internal/stylex-capabilities/scan.mjs<!-- STYLEX-CAPS:END -->-<!-- XDS-CLI:START -->+<!-- ASTRYX-CLI:START -->-XDS CLI|Run from repo root. Load agent docs before any component work.-XDS="node packages/cli/bin/astryx.mjs"+Astryx CLI|Run from repo root. Load agent docs before any component work.+ASTRYX="node packages/cli/bin/astryx.mjs"BOOTSTRAP (run every branch, <500ms):-$XDS help # discover all commands and options-$XDS docs # list available doc topics-$XDS docs principles --dense # design rules, anti-patterns, xstyle, tokens-$XDS docs tokens --dense # spacing, color, radius, typography, shadow-$XDS docs theme --dense # theme provider, light/dark, overrides-$XDS component --list # all components grouped by category-$XDS template --list # available page templates+$ASTRYX help # discover all commands and options+$ASTRYX docs # list available doc topics+$ASTRYX docs principles --dense # design rules, anti-patterns, xstyle, tokens+$ASTRYX docs tokens --dense # spacing, color, radius, typography, shadow+$ASTRYX docs theme --dense # theme provider, light/dark, overrides+$ASTRYX component --list # all components grouped by category+$ASTRYX template --list # available page templatesON DEMAND:-$XDS component <Name> --dense # props, variants, usage, anatomy for one component-$XDS template <name> # emit full page source-$XDS template <name> --skeleton # layout skeleton with spatial annotations-$XDS swizzle <Name> # eject component source for deep customization-$XDS upgrade --apply # run version migration codemods+$ASTRYX component <Name> --dense # props, variants, usage, anatomy for one component+$ASTRYX template <name> # emit full page source+$ASTRYX template <name> --skeleton # layout skeleton with spatial annotations+$ASTRYX swizzle <Name> # eject component source for deep customization+$ASTRYX upgrade --apply # run version migration codemodsOPTIONS: --detail compact|brief less output | --dense token-efficient | --zh ChineseRULE: always run bootstrap on each branch — docs reflect the branch's actual API-RULE: always run $XDS component <Name> --dense before modifying a component-RULE: after @astryxdesign/core bump, always run $XDS upgrade --apply+RULE: always run $ASTRYX component <Name> --dense before modifying a component+RULE: after @astryxdesign/core bump, always run $ASTRYX upgrade --apply-<!-- XDS-CLI:END -->+<!-- ASTRYX-CLI:END -->diff --git a/apps/docsite/README.md b/apps/docsite/README.mdindex 181db912e2..4e963d48da 100644--- a/apps/docsite/README.md+++ b/apps/docsite/README.md@@ -1,6 +1,6 @@-# XDS Docsite+# Astryx Docsite-The OSS documentation site for XDS. Built with Next.js and StyleX.+The OSS documentation site for Astryx. Built with Next.js and StyleX.## Quick Start@@ -24,17 +24,17 @@ from the monorepo and writes typed TypeScript registries to `src/generated/`.`scripts/generate-data.mjs` scans the monorepo and produces:-| Registry | Source | What it contains |-| ---------------------- | --------------------------------- | ------------------------------------------------------------- |-| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description, README for each published package |-| `componentRegistry.ts` | `*.doc.mjs` files | Props, usage docs, hooks, groups, per package |-| `blockRegistry.ts` | CLI `templates/blocks/` | Showcase and example blocks with metadata |-| `templateRegistry.ts` | CLI `templates/pages/` | Page-level templates (e.g. dashboard, settings) |-| `docsRegistry.ts` | CLI `docs/` | Long-form guide and foundation topics |-| `blogRegistry.ts` | `src/content/blog/posts/` | Human-authored blog posts (frontmatter validated) |+| Registry | Source | What it contains |+| ---------------------- | ------------------------------------------ | ------------------------------------------------------------- |+| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description, README for each published package |+| `componentRegistry.ts` | `*.doc.mjs` files | Props, usage docs, hooks, groups, per package |+| `blockRegistry.ts` | CLI `templates/blocks/` | Showcase and example blocks with metadata |+| `templateRegistry.ts` | CLI `templates/pages/` | Page-level templates (e.g. dashboard, settings) |+| `docsRegistry.ts` | CLI `docs/` | Long-form guide and foundation topics |+| `blogRegistry.ts` | `src/content/blog/posts/` | Human-authored blog posts (frontmatter validated) || `themeRegistry.ts` | Installed `@astryxdesign/theme-*` packages | Built theme objects, keyed by package name |-| `showcaseRegistry.ts` | Blocks with `isShowcase` | Copied showcase source files |-| `exampleRegistry.ts` | Blocks with `exampleFor` | Copied example blocks per component |+| `showcaseRegistry.ts` | Blocks with `isShowcase` | Copied showcase source files |+| `exampleRegistry.ts` | Blocks with `exampleFor` | Copied example blocks per component |The `src/generated/` directory is gitignored. Pages import from these registriesand render whatever the pipeline found, with no manual wiring needed.@@ -110,7 +110,7 @@ apps/docsite/├── src/│ ├── generated/ # gitignored — pipeline output│ ├── app/-│ │ ├── globals.css # CSS imports (reset, xds base, theme stylesheets)+│ │ ├── globals.css # CSS imports (reset, astryx base, theme stylesheets)│ │ ├── layout.tsx # Root layout│ │ ├── providers.tsx # Theme + client providers│ │ ├── (docs)/ # Main docs routes (components, packages, docs)diff --git a/apps/docsite/src/content/blog/README.md b/apps/docsite/src/content/blog/README.mdindex f5a65f876f..b76976277f 100644--- a/apps/docsite/src/content/blog/README.md+++ b/apps/docsite/src/content/blog/README.md@@ -1,6 +1,6 @@# Adding a Blog Post-The XDS docsite blog lives at `/blog` (index) and `/blog/<slug>` (post detail).+The Astryx docsite blog lives at `/blog` (index) and `/blog/<slug>` (post detail).Posts are human-authored. Adding one is intentionally close to "drop in oneMarkdown file."@@ -35,7 +35,7 @@ tags:---Write the post in human-authored prose here. Use any structure that fits —-headings, code blocks, lists, links. The body is rendered with `XDSMarkdown`.+headings, code blocks, lists, links. The body is rendered with `Markdown`.```## 2. Frontmatter referencediff --git a/apps/docsite/src/lib/analytics.ts b/apps/docsite/src/lib/analytics.tsindex 202ed71705..c37eb9b55a 100644--- a/apps/docsite/src/lib/analytics.ts+++ b/apps/docsite/src/lib/analytics.ts@@ -5,7 +5,7 @@* @position src/lib — typed analytics helpers wrapping @vercel/analytics.** Convention: small fixed set of event names, context pushed into properties.- * See https://github.com/facebookexperimental/xds/issues/2607 for the full spec.+ * See https://github.com/facebook/astryx/issues/2607 for the full spec.*/import {track} from '@vercel/analytics';diff --git a/apps/example-nextjs-source/README.md b/apps/example-nextjs-source/README.mdindex 6545a3df19..0bf2ca52a6 100644--- a/apps/example-nextjs-source/README.md+++ b/apps/example-nextjs-source/README.md@@ -1,21 +1,21 @@-# XDS Example: Next.js (Source Build)+# Astryx Example: Next.js (Source Build)Reference application for compiling **@astryxdesign/core** from raw TypeScript + StyleX source alongside product code. Uses `@astryxdesign/build` for independent CSS layer separation.## Why source build?-| | Source build | Dist build |-| ------------- | --------------------------------------------- | ---------------------------- |-| CSS output | Only styles for components you import (~22KB) | All component styles (~77KB) |-| Layer control | Full: reset < astryx-base < astryx-theme < product | Basic: import order |-| Build time | Slower (compiles XDS source through Babel) | Fast (pre-built CSS) |-| Setup | More config (babel + postcss + next.config) | Minimal (CSS imports) |+| | Source build | Dist build |+| ------------- | -------------------------------------------------- | ---------------------------- |+| CSS output | Only styles for components you import (~22KB) | All component styles (~77KB) |+| Layer control | Full: reset < astryx-base < astryx-theme < product | Basic: import order |+| Build time | Slower (compiles Astryx source through Babel) | Fast (pre-built CSS) |+| Setup | More config (babel + postcss + next.config) | Minimal (CSS imports) |## How it works`@astryxdesign/build` provides two plugins that work together:-1. **`@astryxdesign/build/babel`**: wraps the StyleX babel plugin, routing XDS library files to `xds` class prefix and product files to default `x` prefix+1. **`@astryxdesign/build/babel`**: wraps the StyleX babel plugin, routing Astryx library files to `astryx` class prefix and product files to default `x` prefix2. **`@astryxdesign/build/postcss`**: compiles StyleX CSS in two passes with different prefixes, wrapping each in its own `@layer`This creates completely independent class namespaces:@@ -54,8 +54,12 @@ module.exports = {enableInlinedConditionalMerge: true,treeshakeCompensation: true,aliases: {- '@astryxdesign/core/*': [path.join(__dirname, 'node_modules/@astryxdesign/core/*')],- '@astryxdesign/core': [path.join(__dirname, 'node_modules/@astryxdesign/core')],+ '@astryxdesign/core/*': [+ path.join(__dirname, 'node_modules/@astryxdesign/core/*'),+ ],+ '@astryxdesign/core': [+ path.join(__dirname, 'node_modules/@astryxdesign/core'),+ ],},unstable_moduleResolution: {type: 'commonJS'},},@@ -82,8 +86,12 @@ module.exports = {enableInlinedConditionalMerge: true,treeshakeCompensation: true,aliases: {- '@astryxdesign/core/*': [path.join(__dirname, 'node_modules/@astryxdesign/core/*')],- '@astryxdesign/core': [path.join(__dirname, 'node_modules/@astryxdesign/core')],+ '@astryxdesign/core/*': [+ path.join(__dirname, 'node_modules/@astryxdesign/core/*'),+ ],+ '@astryxdesign/core': [+ path.join(__dirname, 'node_modules/@astryxdesign/core'),+ ],},unstable_moduleResolution: {type: 'commonJS'},},@@ -131,21 +139,21 @@ export default nextConfig;This example includes a visual demo showing:-1. **astryx-base**: default XDS component styles+1. **astryx-base**: default Astryx component styles2. **astryx-theme**: theme overrides (secondary button background)3. **product**: app overrides (pill shape, green background, full-width)-4. **Class prefix verification**: XDS components use `xds` prefix, product uses `x`+4. **Class prefix verification**: Astryx components use `astryx` prefix, product uses `x`Open devtools → CSS layers panel to see the separation.## Gotchas-| Issue | Symptom | Fix |-| ------------------------ | -------------------------------------- | ------------------------------------------------------------------ |-| Missing `conditionNames` | XDS resolves to dist (no `xds` prefix) | Add `['source', 'import', 'require', 'default']` to webpack config |-| Missing `aliases` | `defineVars` resolution fails | Add aliases for `@astryxdesign/core` and `@astryxdesign/core/*` |-| `layers.css` inline | Layer order ignored | Keep as separate file (webpack hoists `@import`) |-| Missing `browserslist` | `light-dark()` gets lowered | Add `["last 1 Chrome version"]` |+| Issue | Symptom | Fix |+| ------------------------ | -------------------------------------------- | ------------------------------------------------------------------ |+| Missing `conditionNames` | Astryx resolves to dist (no `astryx` prefix) | Add `['source', 'import', 'require', 'default']` to webpack config |+| Missing `aliases` | `defineVars` resolution fails | Add aliases for `@astryxdesign/core` and `@astryxdesign/core/*` |+| `layers.css` inline | Layer order ignored | Keep as separate file (webpack hoists `@import`) |+| Missing `browserslist` | `light-dark()` gets lowered | Add `["last 1 Chrome version"]` |## Relateddiff --git a/apps/example-nextjs-source/src/app/page.tsx b/apps/example-nextjs-source/src/app/page.tsxindex 86e8f5db71..21ded899a4 100644--- a/apps/example-nextjs-source/src/app/page.tsx+++ b/apps/example-nextjs-source/src/app/page.tsx@@ -65,7 +65,7 @@ export default function Home() {<div {...stylex.props(styles.container)}><VStack gap={6}><VStack gap={2}>- <Heading level={1}>XDS + Next.js (Source Build)</Heading>+ <Heading level={1}>Astryx + Next.js (Source Build)</Heading><Text type="body" color="secondary">This example compiles{' '}<Text type="body" weight="bold">@@ -127,7 +127,7 @@ export default function Home() {3. product — product overrides theme</Text><Text type="supporting" color="secondary">- Product styles use a different class prefix (x vs xds) so+ Product styles use a different class prefix (x vs astryx) sothey don't collide with library classes in the base layer.</Text><HStack gap={3} vAlign="center">@@ -160,13 +160,14 @@ export default function Home() {<VStack gap={3}><Heading level={2}>Class Prefix Verification</Heading><Text type="body" color="secondary">- Inspect these elements in devtools. XDS library classes start with{' '}- <code>xds</code>, product classes start with <code>x</code>.+ Inspect these elements in devtools. Astryx library classes start+ with <code>astryx</code>, product classes start with{' '}+ <code>x</code>.</Text><Card padding={4}><VStack gap={2}><Text type="supporting" weight="bold">- This card is an XDS component → xds-prefixed classes+ This card is an Astryx component → astryx-prefixed classes</Text><div {...stylex.props(styles.prefixDemo)}>This div uses product StyleX → x-prefixed classes@@ -189,7 +190,7 @@ export default function Home() {<Switchlabel="Enable notifications"value={toggle}- onChange={(checked) => setToggle(checked)}+ onChange={checked => setToggle(checked)}/></VStack>@@ -215,9 +216,10 @@ export default function Home() {<div {...stylex.props(styles.card)}><VStack gap={2}><Text type="body">- <code>@astryxdesign/build/babel</code> wraps the StyleX babel plugin- and routes files to two internal instances with different{' '}- <code>classNamePrefix</code> values based on file path.+ <code>@astryxdesign/build/babel</code> wraps the StyleX babel+ plugin and routes files to two internal instances with+ different <code>classNamePrefix</code> values based on file+ path.</Text><Text type="body"><code>@astryxdesign/build/postcss</code> does the same for CSS@@ -226,7 +228,9 @@ export default function Home() {</Text><Text type="body">Open devtools → CSS layers panel to see:{' '}- <code>reset < astryx-base < astryx-theme < product</code>+ <code>+ reset < astryx-base < astryx-theme < product+ </code></Text></VStack></div>diff --git a/apps/example-nextjs-stylex/README.md b/apps/example-nextjs-stylex/README.mdindex de0bafb2f8..e3cbd4d504 100644--- a/apps/example-nextjs-stylex/README.md+++ b/apps/example-nextjs-stylex/README.md@@ -1,12 +1,12 @@-# XDS Example: Next.js + StyleX (Dist)+# Astryx Example: Next.js + StyleX (Dist)Reference application for consuming **@astryxdesign/core** as a pre-built dist package with **StyleX** for product-level styles.-XDS component CSS comes pre-built; there is no need to compile XDS source. StyleX is only used for your own app-level layout and custom styles, compiled at build time via the PostCSS plugin.+Astryx component CSS comes pre-built; there is no need to compile Astryx source. StyleX is only used for your own app-level layout and custom styles, compiled at build time via the PostCSS plugin.## CSS Layer Integration-This example uses StyleX's `useCSSLayers.before` option to declare XDS dist layers before the StyleX app layers:+This example uses StyleX's `useCSSLayers.before` option to declare Astryx dist layers before the StyleX app layers:```js// postcss.config.js@@ -21,17 +21,17 @@ This produces a layer order of:reset < astryx-base < astryx-theme < stylex.base < stylex.1 < stylex.2 < ...```-Product-level StyleX styles always win over XDS component defaults without needing `!important` or extra specificity.+Product-level StyleX styles always win over Astryx component defaults without needing `!important` or extra specificity.## Key Difference from Source Build-| | This example (dist + StyleX) | Source build |-| ------------------- | ------------------------------------------- | -------------------------------------------- |-| XDS CSS | Pre-built via `@import "@astryxdesign/core/astryx.css"` | Compiled from source via StyleX babel plugin |-| PostCSS `include` | `src/**/*` only (your code) | `src/**/*` + `node_modules/@astryxdesign/core/**/*` |-| StyleX `aliases` | Not needed | Required for `createTheme` resolution |-| `transpilePackages` | Not needed | Required in next.config |-| Layer ordering | `useCSSLayers.before` declares XDS layers | `useCSSLayers: true` (XDS layers mixed in) |+| | This example (dist + StyleX) | Source build |+| ------------------- | ------------------------------------------------------- | --------------------------------------------------- |+| Astryx CSS | Pre-built via `@import "@astryxdesign/core/astryx.css"` | Compiled from source via StyleX babel plugin |+| PostCSS `include` | `src/**/*` only (your code) | `src/**/*` + `node_modules/@astryxdesign/core/**/*` |+| StyleX `aliases` | Not needed | Required for `createTheme` resolution |+| `transpilePackages` | Not needed | Required in next.config |+| Layer ordering | `useCSSLayers.before` declares Astryx layers | `useCSSLayers: true` (Astryx layers mixed in) |## Setup Steps@@ -76,11 +76,11 @@ module.exports = {};```-> No `aliases` config needed; we're not compiling XDS source.+> No `aliases` config needed; we're not compiling Astryx source.### 4. PostCSS config-`postcss.config.js`: scan your app source, declare XDS layers before StyleX layers:+`postcss.config.js`: scan your app source, declare Astryx layers before StyleX layers:```jsmodule.exports = {diff --git a/apps/example-nextjs-tailwind/README.md b/apps/example-nextjs-tailwind/README.mdindex f983f69276..261ca6921f 100644--- a/apps/example-nextjs-tailwind/README.md+++ b/apps/example-nextjs-tailwind/README.md@@ -1,10 +1,10 @@-# XDS + Tailwind (Dist Build)+# Astryx + Tailwind (Dist Build)-Example Next.js app using XDS pre-built dist CSS alongside Tailwind CSS v4. No StyleX build plugin needed: XDS components are consumed as a regular npm package with a CSS import.+Example Next.js app using Astryx pre-built dist CSS alongside Tailwind CSS v4. No StyleX build plugin needed: Astryx components are consumed as a regular npm package with a CSS import.## How it works-XDS ships pre-compiled CSS (`astryx.css`) with all component styles as atomic classes in CSS cascade layers. Tailwind handles layout, spacing, and custom styling via utility classes. Both systems coexist through explicit layer ordering.+Astryx ships pre-compiled CSS (`astryx.css`) with all component styles as atomic classes in CSS cascade layers. Tailwind handles layout, spacing, and custom styling via utility classes. Both systems coexist through explicit layer ordering.## CSS Layer Order@@ -16,22 +16,22 @@ The key to coexistence is declaring **all** layers upfront in `globals.css`:This gives the correct priority (lowest → highest):-| Layer | Source | What it does |-|-------|--------|-------------|-| `reset` | XDS | CSS reset (`:where()` selectors, zero specificity) |-| `theme` | Tailwind | Theme variables (colors, fonts, spacing) |-| `base` | Tailwind | Preflight reset (element-level normalization) |-| `astryx-base` | XDS | Component styles (buttons, cards, inputs, etc.) |-| `astryx-theme` | XDS | Theme overrides (typography, color mappings) |-| `components` | Tailwind | Component classes (if any) |-| `utilities` | Tailwind | Utility classes: **wins over all layers** |-| *(unlayered)* | Consumer | Your custom CSS: highest priority |+| Layer | Source | What it does |+| -------------- | -------- | -------------------------------------------------- |+| `reset` | Astryx | CSS reset (`:where()` selectors, zero specificity) |+| `theme` | Tailwind | Theme variables (colors, fonts, spacing) |+| `base` | Tailwind | Preflight reset (element-level normalization) |+| `astryx-base` | Astryx | Component styles (buttons, cards, inputs, etc.) |+| `astryx-theme` | Astryx | Theme overrides (typography, color mappings) |+| `components` | Tailwind | Component classes (if any) |+| `utilities` | Tailwind | Utility classes: **wins over all layers** |+| _(unlayered)_ | Consumer | Your custom CSS: highest priority |-Without this declaration, XDS layers are created *after* Tailwind's declared layers, making XDS component styles outrank Tailwind utilities. That means `className="bg-red-500"` on an XDS component wouldn't work.+Without this declaration, Astryx layers are created _after_ Tailwind's declared layers, making Astryx component styles outrank Tailwind utilities. That means `className="bg-red-500"` on an Astryx component wouldn't work.## Usage patterns-### XDS for components, Tailwind for layout+### Astryx for components, Tailwind for layout```tsx<main className="flex min-h-screen items-center p-8">@@ -44,27 +44,27 @@ Without this declaration, XDS layers are created *after* Tailwind's declared lay</main>```-### XDS Tailwind Bridge (recommended)+### Astryx Tailwind Bridge (recommended)-Import `@astryxdesign/core/tailwind-theme.css` to register XDS tokens as Tailwind theme variables. This maps all XDS design tokens to native Tailwind utilities, with no `var()` needed:+Import `@astryxdesign/core/tailwind-theme.css` to register Astryx tokens as Tailwind theme variables. This maps all Astryx design tokens to native Tailwind utilities, with no `var()` needed:```tsx// Before (verbose arbitrary values):<div className="rounded-[var(--radius-container)] bg-[var(--color-background-surface)] p-[var(--spacing-4)]">- <p className="text-[var(--color-text-primary)]">Styled with XDS tokens</p>+ <p className="text-[var(--color-text-primary)]">Styled with Astryx tokens</p></div>// After (with tailwind-theme.css):<div className="rounded-lg bg-surface p-4">- <p className="text-primary">Styled with XDS tokens</p>+ <p className="text-primary">Styled with Astryx tokens</p></div>```-The bridge uses Tailwind v4's `@theme inline`: it tells Tailwind to generate utilities from XDS's existing CSS custom properties without emitting duplicate declarations. Theme switching just works.+The bridge uses Tailwind v4's `@theme inline`: it tells Tailwind to generate utilities from Astryx's existing CSS custom properties without emitting duplicate declarations. Theme switching just works.Available utilities include `text-primary`, `text-secondary`, `bg-surface`, `bg-card`, `border-strong`, `text-error`, `bg-success`, `bg-blue-subtle`, `text-blue-vivid`, `border-blue-ring`, and 80+ more.-### XDS tokens via arbitrary values (escape hatch)+### Astryx tokens via arbitrary values (escape hatch)If you need a token the bridge doesn't cover, you can still use Tailwind's bracket syntax:@@ -74,33 +74,35 @@ If you need a token the bridge doesn't cover, you can still use Tailwind's brack</div>```-### Tailwind overrides on XDS components+### Tailwind overrides on Astryx components-All XDS components accept `className`. Tailwind utilities in the `utilities` layer override XDS component styles in `astryx-base`:+All Astryx components accept `className`. Tailwind utilities in the `utilities` layer override Astryx component styles in `astryx-base`:```tsx<Button label="Custom" variant="primary" className="rounded-full shadow-xl" /><Text type="body" className="text-blue-600 italic">Custom styled text</Text>```-### Mixing XDS and Tailwind components+### Mixing Astryx and Tailwind components-Shadcn-style Tailwind components render correctly alongside XDS. Both resets are nearly identical (shared modern-normalize lineage), so there are no conflicts:+Shadcn-style Tailwind components render correctly alongside Astryx. Both resets are nearly identical (shared modern-normalize lineage), so there are no conflicts:```tsx<div className="grid grid-cols-2 gap-6"><Card>...</Card>- <div className="rounded-xl border border-gray-200 bg-white p-6 shadow-sm">...</div>+ <div className="rounded-xl border border-gray-200 bg-white p-6 shadow-sm">+ ...+ </div></div>```## Reset compatibility-XDS reset and Tailwind Preflight overlap ~80%. The meaningful differences:+Astryx reset and Tailwind Preflight overlap ~80%. The meaningful differences:-- **Font smoothing**: XDS enables `-webkit-font-smoothing: antialiased`; Tailwind doesn't-- **Color scheme**: XDS maps `data-theme` to `color-scheme` for light/dark mode-- **Placeholder color**: XDS uses `var(--color-text-secondary)` token; Tailwind uses `color-mix()`+- **Font smoothing**: Astryx enables `-webkit-font-smoothing: antialiased`; Tailwind doesn't+- **Color scheme**: Astryx maps `data-theme` to `color-scheme` for light/dark mode+- **Placeholder color**: Astryx uses `var(--color-text-secondary)` token; Tailwind uses `color-mix()`Both resets can run together without conflicts. Neither breaks the other's components.diff --git a/apps/example-nextjs/README.md b/apps/example-nextjs/README.mdindex aa84ec01a9..ef0f6c9390 100644--- a/apps/example-nextjs/README.md+++ b/apps/example-nextjs/README.md@@ -1,8 +1,8 @@-# XDS Example: Next.js (Dist)+# Astryx Example: Next.js (Dist)Reference application for consuming **@astryxdesign/core** as a pre-built dist package in a Next.js project.-No StyleX build plugin needed; XDS ships pre-compiled CSS and JS. This is the simplest way to get started.+No StyleX build plugin needed; Astryx ships pre-compiled CSS and JS. This is the simplest way to get started.## Setup Steps@@ -54,22 +54,22 @@ export function Providers({children}) {}```-`LinkProvider` wires up Next.js client-side navigation for all XDS link-based components (Link, Button with href, TopNav, SideNav, Breadcrumbs, TabList).+`LinkProvider` wires up Next.js client-side navigation for all Astryx link-based components (Link, Button with href, TopNav, SideNav, Breadcrumbs, TabList).## Gotchas-| Issue | Symptom | Fix |-| ----------------------------- | ------------------------------------------- | ------------------------------------------ |-| Wrong CSS import order | Missing theme tokens or broken layers | Import reset → xds → theme in that order |-| No `'use client'` on provider | Server component error from `createContext` | Mark the provider file with `'use client'` |+| Issue | Symptom | Fix |+| ----------------------------- | ------------------------------------------- | ------------------------------------------- |+| Wrong CSS import order | Missing theme tokens or broken layers | Import reset → astryx → theme in that order |+| No `'use client'` on provider | Server component error from `createContext` | Mark the provider file with `'use client'` |## Testing outside the monorepo-This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@astryxdesign/core` from npm. Monorepo workspace resolution can silently bypass issues that external consumers hit.+This example lives in the Astryx monorepo for convenience, but it should be representative of a real app consuming `@astryxdesign/core` from npm. Monorepo workspace resolution can silently bypass issues that external consumers hit.**Before merging changes to this example, test it as an external consumer.** See the [Testing Example Apps](https://github.com/facebook/astryx/wiki/Testing-Example-Apps) wiki page for the full procedure.## Related- [Issue #145: Add example-nextjs project](https://github.com/facebook/astryx/issues/145)-- [XDS + Tailwind example](../example-nextjs-tailwind/): same dist approach with Tailwind for custom layout styles+- [Astryx + Tailwind example](../example-nextjs-tailwind/): same dist approach with Tailwind for custom layout stylesdiff --git a/apps/example-vite/README.md b/apps/example-vite/README.mdindex fdc6124077..f45e425ef9 100644--- a/apps/example-vite/README.md+++ b/apps/example-vite/README.md@@ -1,8 +1,8 @@-# XDS Example: Vite+# Astryx Example: ViteReference application for consuming **@astryxdesign/core** as a source distribution in a Vite + React project.-XDS ships as raw TypeScript + StyleX source. Consumers compile it at the application level; there's no pre-built CSS or JS bundle. This example shows the complete setup using `@stylexjs/unplugin`, which handles both StyleX compilation and CSS extraction in a single Vite plugin.+Astryx ships as raw TypeScript + StyleX source. Consumers compile it at the application level; there's no pre-built CSS or JS bundle. This example shows the complete setup using `@stylexjs/unplugin`, which handles both StyleX compilation and CSS extraction in a single Vite plugin.## How it differs from Next.js@@ -25,7 +25,7 @@ npm install --save-dev @stylexjs/unplugin @vitejs/plugin-react typescript \### 2. Browserslist-Add a `browserslist` to `package.json` so that both Vite's CSS pipeline and the StyleX unplugin target modern browsers. XDS tokens use native `light-dark()` (baseline 2024); without modern targets, lightningcss lowers it into polyfill variables that break theming:+Add a `browserslist` to `package.json` so that both Vite's CSS pipeline and the StyleX unplugin target modern browsers. Astryx tokens use native `light-dark()` (baseline 2024); without modern targets, lightningcss lowers it into polyfill variables that break theming:```json{@@ -50,7 +50,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));// Required: tells the StyleX plugin's internal lightningcss transform// not to lower light-dark() into broken polyfill variables.-// XDS tokens use light-dark() which is baseline 2024.+// Astryx tokens use light-dark() which is baseline 2024.const lightningcssTargets = {chrome: 123 << 16,firefox: 120 << 16,@@ -67,7 +67,7 @@ export default defineConfig({{tag: 'style',children:- '@layer reset, priority1, priority2, priority3, priority4, priority5, priority6, priority7, priority8, priority9, xds.theme;',+ '@layer reset, priority1, priority2, priority3, priority4, priority5, priority6, priority7, priority8, priority9, astryx-theme;',injectTo: 'head-prepend',},];@@ -97,10 +97,13 @@ export default defineConfig({__dirname,'node_modules/@astryxdesign/core/src/theme/tokens.stylex.ts',),- '@astryxdesign/core': path.resolve(__dirname, 'node_modules/@astryxdesign/core/src'),+ '@astryxdesign/core': path.resolve(+ __dirname,+ 'node_modules/@astryxdesign/core/src',+ ),},},- // Prevent Vite from pre-bundling XDS with esbuild. XDS ships as source+ // Prevent Vite from pre-bundling Astryx with esbuild. Astryx ships as source// that must be compiled by the StyleX plugin — pre-bundling strips the// stylex.create/defineVars calls and causes a runtime error.optimizeDeps: {@@ -132,7 +135,7 @@ import './index.css';The CSS import order matters:1. `reset.css`: baseline resets (`@layer reset`)-2. `theme.css`: theme token overrides (`@layer xds.theme`)+2. `theme.css`: theme token overrides (`@layer astryx-theme`)3. `index.css`: StyleX extraction placeholder### 5. Theme provider@@ -165,18 +168,18 @@ npm run preview## Gotchas-| Issue | Symptom | Fix |-| ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |-| Missing `lightningcssOptions` | Colors broken: `light-dark()` gets lowered | Add `lightningcssOptions: { targets: lightningcssTargets }` to StyleX plugin |-| Vite pre-bundles XDS | `Unexpected stylex.defineVars at runtime` | Add `optimizeDeps: { exclude: ['@astryxdesign/core', '@astryxdesign/theme-neutral'] }` |-| Missing resolve aliases | Module not found errors for `@astryxdesign/core` | Add `resolve.alias` pointing to source directory |-| Missing CSS entry point | StyleX has no CSS asset to append to | Create a minimal `index.css` and import it in `main.tsx` |-| Plugin order | Styles not extracted or HMR broken | `stylex.vite()` must come before `react()` in the plugins array |-| Duplicate React types | JSX component type errors in monorepo | Known monorepo issue with `@types/react` hoisting; doesn't affect runtime |+| Issue | Symptom | Fix |+| ----------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------- |+| Missing `lightningcssOptions` | Colors broken: `light-dark()` gets lowered | Add `lightningcssOptions: { targets: lightningcssTargets }` to StyleX plugin |+| Vite pre-bundles Astryx | `Unexpected stylex.defineVars at runtime` | Add `optimizeDeps: { exclude: ['@astryxdesign/core', '@astryxdesign/theme-neutral'] }` |+| Missing resolve aliases | Module not found errors for `@astryxdesign/core` | Add `resolve.alias` pointing to source directory |+| Missing CSS entry point | StyleX has no CSS asset to append to | Create a minimal `index.css` and import it in `main.tsx` |+| Plugin order | Styles not extracted or HMR broken | `stylex.vite()` must come before `react()` in the plugins array |+| Duplicate React types | JSX component type errors in monorepo | Known monorepo issue with `@types/react` hoisting; doesn't affect runtime |## Testing outside the monorepo-This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@astryxdesign/core` from npm. Monorepo workspace symlinks can silently bypass issues that external consumers hit (Vite dep pre-bundling, missing dependencies, wrong resolve paths).+This example lives in the Astryx monorepo for convenience, but it should be representative of a real app consuming `@astryxdesign/core` from npm. Monorepo workspace symlinks can silently bypass issues that external consumers hit (Vite dep pre-bundling, missing dependencies, wrong resolve paths).**Before merging changes to this example, test it as an external consumer.** See the [Testing Example Apps](https://github.com/facebook/astryx/wiki/Testing-Example-Apps) wiki page for the full procedure.@@ -184,4 +187,4 @@ This example lives in the XDS monorepo for convenience, but it should be represe- [Issue #145: Example apps for source distribution consumers](https://github.com/facebook/astryx/issues/145)- [StyleX Vite React example](https://github.com/facebook/stylex/tree/main/examples/example-vite-react)-- [XDS Example: Next.js](../example-nextjs/)+- [Astryx Example: Next.js](../example-nextjs/)diff --git a/package.json b/package.jsonindex e2e8ec8e09..8a319dde19 100644--- a/package.json+++ b/package.json@@ -22,7 +22,7 @@"docsite": "pnpm -F @astryxdesign/docsite dev","sync:exports": "node scripts/sync-exports.js","sync:exports:check": "node scripts/sync-exports.js --check",- "xds": "pnpm -F @astryxdesign/cli xds",+ "astryx": "pnpm -F @astryxdesign/cli astryx","package:source": "node scripts/package-source.js","changeset": "changeset","changeset:new": "node scripts/changeset-new.mjs",diff --git a/packages/README.md b/packages/README.mdindex 59b7ec1acf..e21c72064f 100644--- a/packages/README.md+++ b/packages/README.md@@ -1,14 +1,14 @@# /packages-Published npm packages for the XDS design system.+Published npm packages for the Astryx design system.<!-- SYNC: When files in this directory change, update this document. -->-| Directory | Package | Purpose |-|-----------|---------|---------|-| `core/` | `@astryxdesign/core` | Core UI components, theme system, and utilities |-| `cli/` | `@astryxdesign/cli` | CLI tooling: component docs, templates, scaffolding, codemods |-| `build/` | `@astryxdesign/build` | Build plugins for StyleX source builds (Babel, PostCSS, Vite) |+| Directory | Package | Purpose |+| --------- | ----------------------- | ------------------------------------------------------------------ |+| `core/` | `@astryxdesign/core` | Core UI components, theme system, and utilities |+| `cli/` | `@astryxdesign/cli` | CLI tooling: component docs, templates, scaffolding, codemods |+| `build/` | `@astryxdesign/build` | Build plugins for StyleX source builds (Babel, PostCSS, Vite) || `themes/` | `@astryxdesign/theme-*` | Visual themes (default, neutral, daily, brutalist, meta, whatsapp) |-| `vega/` | `@astryxdesign/vega` | Vega/Vega-Lite chart wrapper (not published) |-| `lab/` | — | Experimental components (not published) |+| `vega/` | `@astryxdesign/vega` | Vega/Vega-Lite chart wrapper (not published) |+| `lab/` | — | Experimental components (not published) |diff --git a/packages/build/src/vite.ts b/packages/build/src/vite.tsindex e4de8dd078..183556e1f5 100644--- a/packages/build/src/vite.ts+++ b/packages/build/src/vite.ts@@ -79,9 +79,8 @@ export interface AstryxVitePluginOptions {* build uses a distinct prefix so library and product atoms never collide* across layers.*- * Configurable to support the Astryx-prefix migration: a consumer- * can rebrand the library atom prefix to `astryx` before the final cutover.- * Defaults to `xds` so existing consumers are unaffected.+ * Configurable if a consumer needs a custom library atom prefix.+ * Defaults to `astryx`.** @default 'astryx'*/@@ -209,7 +208,10 @@ export function astryxStylex(rootDir,'node_modules/@astryxdesign/core/src/theme/tokens.stylex.ts',),- '@astryxdesign/core': path.resolve(rootDir, 'node_modules/@astryxdesign/core/src'),+ '@astryxdesign/core': path.resolve(+ rootDir,+ 'node_modules/@astryxdesign/core/src',+ ),},},optimizeDeps: {diff --git a/packages/cli/README.md b/packages/cli/README.mdindex 1b81e9c4ad..7defb2713b 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -62,7 +62,7 @@ Options:| `upgrade` | Run codemods to migrate between versions || `theme build` | Compile a defineTheme file to production CSS and JS || `discover` | Discover external packages and components |-| `doctor` | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code) |+| `doctor` | Diagnose your Astryx setup and report problems with fixes (CI-friendly via exit code) |### Global options@@ -170,7 +170,7 @@ discriminators each command can emit. Think of it as an OpenAPI spec for the CLI```bashastryx manifest --json # dedicated surface — type: "manifest"-xds --json # bare invocation — embeds the same payload under data.manifest+astryx --json # bare invocation — embeds the same payload under data.manifest```Shape:@@ -180,7 +180,7 @@ Shape:"apiVersion": 1,"type": "manifest","data": {- "name": "xds",+ "name": "astryx","version": "0.0.14","description": "Design system CLI — components, themes, and tooling","globalOptions": [@@ -247,14 +247,14 @@ the `JSON_SUPPORTED` allowlist and a small declarative `RESPONSE_TYPES` map in`src/lib/manifest.mjs`, guarded by a drift test (`manifest.test.mjs`) so adding acommand without describing it fails CI.-**Backwards-compat:** the bare `xds --json` envelope keeps `type: "help"` and its+**Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and itsoriginal shallow fields (`name`, `version`, `commands` as a `string[]` of names,`jsonSupported`); the full structured manifest is additive under `data.manifest`.For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest --json`.## Programmatic API-The same logic that powers `xds --json` is available as importable, type-safe functions:+The same logic that powers `astryx --json` is available as importable, type-safe functions:```typescriptimport {@@ -267,20 +267,20 @@ import {AstryxError,} from '@astryxdesign/cli/api';-// Same result as: xds --json component Button+// Same result as: astryx --json component Buttonconst btn = await component('Button');btn.type; // 'component.detail'btn.data.name; // 'Button' (typed as ComponentDoc)-// Same result as: xds --json component --list+// Same result as: astryx --json component --listconst list = await component(undefined, {list: true});list.data; // Record<string, string[]>-// Same result as: xds --json docs principles+// Same result as: astryx --json docs principlesconst principles = await docs('principles');-principles.data.title; // 'XDS Principles'+principles.data.title; // 'Principles'-// Same result as: xds --json hook useMediaQuery+// Same result as: astryx --json hook useMediaQueryconst useMediaQuery = await hook('useMediaQuery');useMediaQuery.data.params; // typed as HookParamDoc[]@@ -294,7 +294,7 @@ try {}```-The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `xds --json` always return identical data.+The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `astryx --json` always return identical data.### Consumer utilities@@ -324,41 +324,41 @@ detail.data.name; // already narrowedEvery response has a `type` string that uniquely identifies it:-| Command | Type | Response |-| ---------------------------------------------- | --------------------------- | --------------------------------- |-| `xds --json component [--list]` | `component.list` | `ComponentListResponse` |-| `xds --json component --list --detail compact` | `component.brief` | `ComponentBriefResponse` |-| `xds --json component --list --detail full` | `component.full` | `ComponentFullResponse` |-| `xds --json component <name>` | `component.detail` | `ComponentDetailResponse` |-| `xds --json component <name> --props` | `component.detail.props` | `ComponentDetailPropsResponse` |-| `xds --json component <name> --source` | `component.detail.source` | `ComponentDetailSourceResponse` |-| `xds --json component <name> --showcase` | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |-| `xds --json component <name> --blocks` | `component.detail.blocks` | `ComponentDetailBlocksResponse` |-| `xds --json discover` | `discover.list` | `DiscoverListResponse` |-| `xds --json discover @scope/name` | `discover.detail` | `DiscoverDetailResponse` |-| `xds --json discover @scope/name/Comp` | `discover.detail.doc` | `DiscoverDetailDocResponse` |-| `xds --json discover <search>` | `discover.search` | `DiscoverSearchResponse` |-| `xds --json docs` | `docs.list` | `DocsListResponse` |-| `xds --json docs <topic>` | `docs.detail` | `DocsDetailResponse` |-| `xds --json docs <topic> <section>` | `docs.detail.section` | `DocsDetailSectionResponse` |-| `xds --json template [--list]` | `template.list` | `TemplateListResponse` |-| `xds --json template <name>` | `template.show` | `TemplateShowResponse` |-| `xds --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` |-| `xds --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` |-| `xds --json hook [--list]` | `hook.list` | `HookListResponse` |-| `xds --json hook --list --detail compact` | `hook.brief` | `HookBriefResponse` |-| `xds --json hook --list --detail full` | `hook.full` | `HookFullResponse` |-| `xds --json hook <name>` | `hook.detail` | `HookDetailResponse` |-| `xds --json hook <name> --params` | `hook.detail.params` | `HookDetailParamsResponse` |-| `xds --json search <query>` | `search` | `SearchResponse` |-| `xds --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` |-| `xds --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` |-| `xds --json theme build <file>` | `theme.build` | `ThemeBuildResponse` |-| `xds --json upgrade --list` | `upgrade.list` | `UpgradeListResponse` |-| `xds --json upgrade [--apply]` | `upgrade.run` | `UpgradeRunResponse` |-| `xds --json doctor` | `doctor` | `DoctorResponse` |-| any error | — | `CLIError` |-| unsupported command | — | `CLIUnsupportedError` |+| Command | Type | Response |+| ------------------------------------------------- | --------------------------- | --------------------------------- |+| `astryx --json component [--list]` | `component.list` | `ComponentListResponse` |+| `astryx --json component --list --detail compact` | `component.brief` | `ComponentBriefResponse` |+| `astryx --json component --list --detail full` | `component.full` | `ComponentFullResponse` |+| `astryx --json component <name>` | `component.detail` | `ComponentDetailResponse` |+| `astryx --json component <name> --props` | `component.detail.props` | `ComponentDetailPropsResponse` |+| `astryx --json component <name> --source` | `component.detail.source` | `ComponentDetailSourceResponse` |+| `astryx --json component <name> --showcase` | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |+| `astryx --json component <name> --blocks` | `component.detail.blocks` | `ComponentDetailBlocksResponse` |+| `astryx --json discover` | `discover.list` | `DiscoverListResponse` |+| `astryx --json discover @scope/name` | `discover.detail` | `DiscoverDetailResponse` |+| `astryx --json discover @scope/name/Comp` | `discover.detail.doc` | `DiscoverDetailDocResponse` |+| `astryx --json discover <search>` | `discover.search` | `DiscoverSearchResponse` |+| `astryx --json docs` | `docs.list` | `DocsListResponse` |+| `astryx --json docs <topic>` | `docs.detail` | `DocsDetailResponse` |+| `astryx --json docs <topic> <section>` | `docs.detail.section` | `DocsDetailSectionResponse` |+| `astryx --json template [--list]` | `template.list` | `TemplateListResponse` |+| `astryx --json template <name>` | `template.show` | `TemplateShowResponse` |+| `astryx --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` |+| `astryx --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` |+| `astryx --json hook [--list]` | `hook.list` | `HookListResponse` |+| `astryx --json hook --list --detail compact` | `hook.brief` | `HookBriefResponse` |+| `astryx --json hook --list --detail full` | `hook.full` | `HookFullResponse` |+| `astryx --json hook <name>` | `hook.detail` | `HookDetailResponse` |+| `astryx --json hook <name> --params` | `hook.detail.params` | `HookDetailParamsResponse` |+| `astryx --json search <query>` | `search` | `SearchResponse` |+| `astryx --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` |+| `astryx --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` |+| `astryx --json theme build <file>` | `theme.build` | `ThemeBuildResponse` |+| `astryx --json upgrade --list` | `upgrade.list` | `UpgradeListResponse` |+| `astryx --json upgrade [--apply]` | `upgrade.run` | `UpgradeRunResponse` |+| `astryx --json doctor` | `doctor` | `DoctorResponse` |+| any error | — | `CLIError` |+| unsupported command | — | `CLIUnsupportedError` |## Doctor@@ -379,7 +379,7 @@ astryx doctor — diagnosing your setup@astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.⚠ Theme packagesNo @astryxdesign/theme-* packages are installed.- → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, 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 astryx.theme.ℹ astryx.config.mjsNo astryx.config.mjs found — using defaults.ℹ AI agent docs@@ -404,7 +404,7 @@ No failures — but review the ⚠ warnings above when you can.| 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 |+| AI agent docs | pass / warn / info | Agent docs exist and contain the Astryx section markers || Peer dependencies | pass / warn / info | `@astryxdesign/core`'s peer deps (react, …) are installed || Package manager | info | Reports the detected package manager |diff --git a/packages/cli/src/api/doctor.mjs b/packages/cli/src/api/doctor.mjsindex 687a4e77cc..3057da38b6 100644--- a/packages/cli/src/api/doctor.mjs+++ b/packages/cli/src/api/doctor.mjs@@ -240,7 +240,7 @@ export function checkThemes(ctx) {label: 'Theme packages',status: 'warn',message: 'No @astryxdesign/theme-* packages are installed.',- fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, 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 astryx.theme.',};}@@ -354,7 +354,7 @@ export function checkAgentDocs(ctx) {label: 'AI agent docs',status: 'warn',message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,- fix: 'Add the XDS section to your agent docs with `astryx init --features agents`.',+ fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',};}@@ -362,7 +362,7 @@ export function checkAgentDocs(ctx) {id: 'agent-docs',label: 'AI agent docs',status: 'pass',- message: `XDS agent docs section present in ${withMarkers.join(', ')}.`,+ message: `Astryx agent docs section present in ${withMarkers.join(', ')}.`,};}diff --git a/scripts/prune-branches.sh b/scripts/prune-branches.shindex 7ecd8873e2..6b37311a33 100644--- a/scripts/prune-branches.sh+++ b/scripts/prune-branches.sh@@ -12,7 +12,7 @@set -euo pipefail-REPO="facebookexperimental/xds"+REPO="facebook/astryx"PROTECTED="main|gh-pages"MODE="${1:-dry-run}"PARALLEL=15