An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): refine docs for doc site — split README, add Tailwind, fix accuracy (#1905)
Cindy Zhang88fe5c6532d2
diff --git a/packages/cli/CONTRIBUTING.md b/packages/cli/CONTRIBUTING.mdnew file mode 100644index 0000000000..c95588eecf--- /dev/null+++ b/packages/cli/CONTRIBUTING.md@@ -0,0 +1,295 @@+# Contributing to @xds/cli++Architecture, conventions, and playbook for CLI contributors.++## Architecture++The CLI is a thin wrapper around type-safe API functions. Each command follows the same pattern:++```+User calls API function User runs CLI+ | |+ v v+ api/component.mjs ◄──────── commands/component/index.mjs+ | |+ v v+ { type, data } jsonOut(type, data) or formatText(data)+```++Both paths run identical code. The CLI handler just adds argument parsing and output formatting.++```+src/+ api/ # Programmatic API (exported as @xds/cli/api)+ index.mjs # barrel: component, docs, discover, template, XDSError+ component.mjs # component(name?, opts?) → { type, data }+ docs.mjs # docs(topic?, section?, opts?) → { type, data }+ discover.mjs # discover(query?, opts?) → { type, data }+ template.mjs # template(name?, opts?) → { type, data }+ error.mjs # XDSError class (carries .suggestions)+ commands/ # CLI wrappers (thin: parse args → call API → format output)+ component/index.mjs # calls api/component.mjs+ docs.mjs # calls api/docs.mjs+ discover.mjs # calls api/discover.mjs+ template.mjs # calls api/template.mjs+ hook/index.mjs # calls api/hook.mjs+ swizzle.mjs # CLI-only (side-effect: copies + rewrites imports)+ build-theme.mjs # CLI-only (side-effect: compiles theme to CSS)+ upgrade.mjs # CLI-only (side-effect: runs codemods)+ gap-report.mjs # CLI-only (side-effect: files GitHub issues)+ init.mjs # CLI-only (interactive prompts)+ lib/+ json.mjs # jsonOut(type, data), jsonError(msg) — internal+ parse.mjs # parseResponse, isError, assertResponse — consumer+ types/+ api.d.ts # API function signatures + XDSError+ base.d.ts # CLIError, CLIResult<T>, CLIAnyResponse, CLIResponseType+ component.d.ts # ComponentListResponse, ComponentDetailResponse, ...+ discover.d.ts # DiscoverListResponse, ...+ docs.d.ts # DocsListResponse, ...+ template.d.ts # TemplateListResponse, TemplateShowResponse, ...+ swizzle.d.ts # SwizzleListResponse, SwizzleCopyResponse+ theme.d.ts # ThemeBuildResponse+ upgrade.d.ts # UpgradeListResponse, UpgradeRunResponse+ gap-report.d.ts # GapReportCategoriesResponse, GapReportFileResponse+ index.d.ts # barrel re-export+```++## Adding a new command++### Does it need an API function?++**Yes** if the command returns data that consumers might want programmatically — component docs, template source, lists, search results. Put the logic in `src/api/`, export from `@xds/cli/api`, and make the CLI handler a thin wrapper.++**No** if the command is purely interactive or only makes sense in a terminal — `init` (interactive prompts), `gap-report setup` (config wizard). These can live entirely in `src/commands/`.++**Rule of thumb:** if it supports `--json`, it should have an API function. The parity test (`api-cli-parity-test.mjs`) will flag any `--json` type that doesn't have API coverage.++### 1. Write the API function++Add a file in `src/api/` with all the logic. It returns `{ type, data }` on success and throws `XDSError` on failure. The CLI handler should have zero logic — just arg parsing and text formatting:++```javascript+// src/api/my-command.mjs+import {XDSError} from './error.mjs';++export async function myCommand(name, options = {}) {+ if (!name) {+ return {type: 'my-command.list', data: getAllItems()};+ }++ const item = findItem(name);+ if (!item) {+ throw new XDSError(`Item "${name}" not found`, suggestions);+ }++ return {type: 'my-command.detail', data: item};+}+```++Export it from `src/api/index.mjs`:++```javascript+export {myCommand} from './my-command.mjs';+```++### 2. Create the CLI wrapper++The CLI handler just parses args, calls the API function, and formats the result. No business logic here:++```javascript+// src/commands/my-command.mjs+import {jsonOut, jsonError} from '../lib/json.mjs';+import {myCommand} from '../api/my-command.mjs';++export function registerMyCommand(program) {+ program+ .command('my-command [name]')+ .description('Does something')+ .action(async (name, options) => {+ const json = program.opts().json || false;++ let result;+ try {+ result = await myCommand(name, options);+ } catch (e) {+ if (json) return jsonError(e.message, e.suggestions);+ console.error(e.message);+ process.exit(1);+ }++ if (json) return jsonOut(result.type, result.data);+ console.log(formatText(result));+ });+}+```++### 3. Define response types++Create `src/types/my-command.d.ts`:++```typescript+/** xds --json my-command */+export interface MyCommandListResponse {+ type: 'my-command.list';+ data: MyCommandListEntry[];+}++export interface MyCommandListEntry {+ name: string;+ description: string;+}++/** xds --json my-command <name> */+export interface MyCommandDetailResponse {+ type: 'my-command.detail';+ data: {name: string; content: string};+}+```++### 4. Wire it up++Add to `src/types/index.d.ts`:++```typescript+export * from './my-command';+```++Add to `CLIAnyResponse` in `src/types/base.d.ts`:++```typescript+export type CLIAnyResponse =+ | ...existing types...+ | MyCommandListResponse+ | MyCommandDetailResponse;+```++### 5. That's it++If you skip the type steps, the command still works — the global fallback hook returns a clean `CLIUnsupportedError` when someone passes `--json`. No crashes, no broken output.++## Playbook — common changes++### Adding a prop to a component++Nothing to do in the CLI. Props come from `.doc.mjs` files in `packages/core/src/`. The CLI reads them at runtime. If the `.doc.mjs` is updated, the CLI and API automatically reflect the change.++### Adding a new component++1. Create the component in `packages/core/src/{Name}/`+2. Add a `{Name}.doc.mjs` in the same directory (or add to the parent's `.doc.mjs` if it's a sub-component)+3. Done — the CLI auto-discovers it, the API auto-discovers it, the parity test auto-discovers it++If the component has no `.doc.mjs`, `xds component {Name}` returns a clean error and CI's smoke test skips it.++### Adding a new doc topic++1. Add `{topic}.doc.mjs` in `packages/cli/docs/`+2. Done — auto-discovered by `xds docs` and the `docs()` API function++### Adding a new template++Every template is exactly **two files** — no exceptions:++```+packages/cli/templates/{name}/+├── page.tsx ← the template code (single self-contained file)+└── template.doc.mjs ← metadata (name, description, isReady)+```++1. Create `packages/cli/templates/{name}/page.tsx` with a default-exported React component+2. Create `packages/cli/templates/{name}/template.doc.mjs` with a `doc` export (`TemplateDoc`)+3. Done — auto-discovered by `xds template --list` and the `template()` API function++**Rules:**+- No extra files — no CSS, no images, no other assets. Everything lives in `page.tsx`.+- Images must use external URLs (e.g. Unsplash), not local imports.+- All styles must use StyleX or inline styles, not separate CSS files.++### Adding a new option to an existing API function++1. Add the option to the API function in `src/api/{command}.mjs`+2. Pass it through from the CLI handler in `src/commands/{command}.mjs`+3. Update the types in `src/types/api.d.ts` (add to the options interface)+4. If it produces a new response type, also update `src/types/{command}.d.ts` and `src/types/base.d.ts`++### Adding a new response type (e.g. `component.detail.variants`)++1. Add the logic in `src/api/{command}.mjs` — return `{type: 'component.detail.variants', data: ...}`+2. Add a TypeScript interface in `src/types/{command}.d.ts`+3. Add it to `CLIAnyResponse` in `src/types/base.d.ts`+4. Add it to the result union in `src/types/api.d.ts`+5. The parity test will auto-detect the new type and verify API=CLI++### Renaming or removing a response type++This is a breaking change for `@xds/cli/api` consumers. Bump the version.++### What CI catches automatically++- **New component without docs** → smoke test skips it with a message (not a failure)+- **New CLI `--json` type without API coverage** → parity test flags it as a coverage gap+- **API and CLI returning different data** → parity test fails with both payloads shown+- **Invalid JSON envelope shape** → json smoke test fails+- **Type mismatches** → `tsconfig.json-api.json` typecheck fails++## Naming conventions++### Response types: `{Command}{Mode}{SubMode?}Response`++| Part | Rule | Examples |+|---------|-------------------------|----------|+| Command | PascalCase command name | `Component`, `Discover`, `ThemeBuild` |+| Mode | What the response IS | `List`, `Brief`, `Detail`, `Search`, `Copy`, `Build`, `Run`, `Categories`, `File` |+| SubMode | Narrower view of Mode | `Props`, `Source`, `Doc`, `Section` |+| Suffix | Always `Response` | |++### Entry types: `{Command}{What}Entry`++Sub-objects in arrays. No `Response` suffix.++### Type discriminators: dot-separated lowercase++```+{command}.{mode} -> component.list+{command}.{mode}.{submode} -> component.detail.props+```++### How flags compose++`--json` is an output format, not a mode. All other flags still work:++- `--json + --category X` filters the same response type (no new type needed)+- `--json + --lang zh` applies translation before dumping+- `--json + --props` narrows to `component.detail.props` (sub-mode)+- `--json + --source` narrows to `component.detail.source` (sub-mode)++## How the fallback hook works++1. Command runs normally+2. If it called `jsonOut()` or `jsonError()`, `process.__xdsJsonHandled` is `true` → done+3. If not, the `postAction` hook fires and outputs `CLIUnsupportedError`+4. New commands that don't know about `--json` automatically get a clean error++## Suppressing stdout for --json++When `--json` is active, human-readable output must not contaminate stdout:++```javascript+// Simple commands: guard console.log+if (!json) console.log(`✓ Done`);++// Clack-based commands: skip Clack calls+if (!json) p.intro('Welcome');+if (!json) p.log.step('Running...');++// Side-effect commands: still run the work, just suppress output+// and collect results into a receipt object+```++## CI enforcement++- `tsconfig.json-api.json` typechecks `json.mjs` and `parse.mjs` against the `.d.ts` declarations+- `.github/scripts/cli-json-smoke-test.mjs` validates every `--json` command outputs valid JSON with correct envelope shape+- `.github/scripts/api-cli-parity-test.mjs` verifies the programmatic API returns identical data to `xds --json` for every command+- All three run in the `cli-smoke-test.yml` workflow on every PRdiff --git a/packages/cli/README.md b/packages/cli/README.mdindex ee7573c1ee..0fd8d0d883 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -1,6 +1,6 @@# @xds/cli-XDS design system CLI -- components, themes, and tooling.+The XDS CLI is the primary interface for working with the XDS design system — for humans and machines alike. It provides component documentation, design tokens, page templates, theming tools, and upgrade codemods, all accessible via terminal commands, a typed JSON API, or programmatic imports. AI agents and build tools use the same API that powers the CLI, enabling end-to-end frontend development loops.```bashnpx xds --help@@ -9,6 +9,31 @@ npx xds docs tokensnpx xds template --list```+## Commands++| Command | Description |+|---------|-------------|+| `init` | Initialize XDS in your project — installs packages, sets up theming, adds AI agent docs |+| `component` | List components or print detailed docs, props, usage examples, and source |+| `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 XDS versions |+| `theme build` | Compile a defineTheme file to production CSS and JS |+| `discover` | Discover external XDS packages and components |+| `gap-report` | Report a gap when a component doesn't meet your needs |++### Global options++These flags work with any command:++- `--json` — Output as typed JSON envelope: `{ type, data }`+- `--detail <level>` — Detail level: `full`, `compact`, or `brief`+- `--zh` — Output docs in Chinese Simplified+- `--dense` — Compressed format (token-efficient, useful for AI agents)+- `--lang <locale>` — Language/format shorthand (`en`, `zh`, `dense`)+## JSON APIEvery command supports `--json` for machine-readable output. Responses are typed envelopes:@@ -26,12 +51,12 @@ Errors:}```-### Programmatic API+## Programmatic APIThe same logic that powers `xds --json` is available as importable, type-safe functions:```typescript-import {component, docs, discover, XDSError} from '@xds/cli/api';+import {component, docs, discover, template, XDSError} from '@xds/cli/api';// Same result as: xds --json component Buttonconst btn = await component('Button');@@ -57,7 +82,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 `@xds/cli/api` and `xds --json` always return identical data.-### Consumer utilities (for parsing CLI stdout)+### Consumer utilitiesIf you're spawning the CLI as a subprocess rather than importing the API directly:@@ -85,341 +110,47 @@ 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 --detail brief` | `component.brief` | `ComponentBriefResponse` |-| `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 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 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 gap-report --list-categories` | `gap-report.categories` | `GapReportCategoriesResponse` |-| `xds --json gap-report --component X ...` | `gap-report.file` | `GapReportFileResponse` |-| any error | -- | `CLIError` |-| unsupported command | -- | `CLIUnsupportedError` |-------## Adding a new command--### Does it need an API function?--**Yes** if the command returns data that consumers might want programmatically — component docs, template source, lists, search results. Put the logic in `src/api/`, export from `@xds/cli/api`, and make the CLI handler a thin wrapper.--**No** if the command is purely interactive or only makes sense in a terminal — `init` (interactive prompts), `gap-report setup` (config wizard). These can live entirely in `src/commands/`.--**Rule of thumb:** if it supports `--json`, it should have an API function. The parity test (`api-cli-parity-test.mjs`) will flag any `--json` type that doesn't have API coverage.--### 1. Write the API function--Add a file in `src/api/` with all the logic. It returns `{ type, data }` on success and throws `XDSError` on failure. The CLI handler should have zero logic — just arg parsing and text formatting:+| Command | Type | Response |+|---------|------|----------|+| `xds --json component [--list]` | `component.list` | `ComponentListResponse` |+| `xds --json component --detail brief` | `component.brief` | `ComponentBriefResponse` |+| `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 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 <name>` | `hook.detail` | `HookDetailResponse` |+| `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 gap-report --list-categories` | `gap-report.categories` | `GapReportCategoriesResponse` |+| `xds --json gap-report --component X ...` | `gap-report.file` | `GapReportFileResponse` |+| any error | — | `CLIError` |+| unsupported command | — | `CLIUnsupportedError` |++## Configuration++The CLI reads from an optional `xds.config.mjs` in your project root:```javascript-// src/api/my-command.mjs-import {XDSError} from './error.mjs';--export async function myCommand(name, options = {}) {- if (!name) {- return {type: 'my-command.list', data: getAllItems()};- }-- const item = findItem(name);- if (!item) {- throw new XDSError(`Item "${name}" not found`, suggestions);- }-- return {type: 'my-command.detail', data: item};-}-```--Export it from `src/api/index.mjs`:--```javascript-export {myCommand} from './my-command.mjs';-```--### 2. Create the CLI wrapper--The CLI handler just parses args, calls the API function, and formats the result. No business logic here:--```javascript-// src/commands/my-command.mjs-import {jsonOut, jsonError} from '../lib/json.mjs';-import {myCommand} from '../api/my-command.mjs';--export function registerMyCommand(program) {- program- .command('my-command [name]')- .description('Does something')- .action(async (name, options) => {- const json = program.opts().json || false;-- let result;- try {- result = await myCommand(name, options);- } catch (e) {- if (json) return jsonError(e.message, e.suggestions);- console.error(e.message);- process.exit(1);- }-- if (json) return jsonOut(result.type, result.data);- console.log(formatText(result));- });-}-```--### 3. Define response types--Create `src/types/my-command.d.ts`:--```typescript-/**- * My-command JSON responses.- *- * Invocation -> type discriminator- * ------------------------------------------------------------------- * xds --json my-command -> my-command.list- * xds --json my-command <name> -> my-command.detail- * (not found) -> CLIError- */--/** xds --json my-command */-export interface MyCommandListResponse {- type: 'my-command.list';- data: MyCommandListEntry[];-}--export interface MyCommandListEntry {- name: string;- description: string;-}--/** xds --json my-command <name> */-export interface MyCommandDetailResponse {- type: 'my-command.detail';- data: {name: string; content: string};-}-```--### 3. Wire it up--Add to `src/types/index.d.ts`:--```typescript-export * from './my-command';-```--Add to `CLIAnyResponse` in `src/types/base.d.ts`:--```typescript-import type { MyCommandListResponse, MyCommandDetailResponse } from './my-command';--export type CLIAnyResponse =- | ...existing types...- | MyCommandListResponse- | MyCommandDetailResponse;-```--### 5. That's it--If you skip the type steps, the command still works — the global fallback hook returns a clean `CLIUnsupportedError` when someone passes `--json`. No crashes, no broken output.-------## Playbook — common changes--### Adding a prop to a component--Nothing to do in the CLI. Props come from `.doc.mjs` files in `packages/core/src/`. The CLI reads them at runtime. If the `.doc.mjs` is updated, the CLI and API automatically reflect the change.--### Adding a new component--1. Create the component in `packages/core/src/{Name}/`-2. Add a `{Name}.doc.mjs` in the same directory (or add to the parent's `.doc.mjs` if it's a sub-component)-3. Done — the CLI auto-discovers it, the API auto-discovers it, the parity test auto-discovers it--If the component has no `.doc.mjs`, `xds component {Name}` returns a clean error and CI's smoke test skips it.--### Adding a new doc topic--1. Add `{topic}.doc.mjs` in `packages/cli/docs/`-2. Done — auto-discovered by `xds docs` and the `docs()` API function--### Adding a new template--Every template is exactly **two files** — no exceptions:--```-packages/cli/templates/{name}/-├── page.tsx ← the template code (single self-contained file)-└── template.doc.mjs ← metadata (name, description, isReady)-```--1. Create `packages/cli/templates/{name}/page.tsx` with a default-exported React component-2. Create `packages/cli/templates/{name}/template.doc.mjs` with a `doc` export (`TemplateDoc`)-3. Done — auto-discovered by `xds template --list` and the `template()` API function--**Rules:**-- No extra files — no CSS, no images, no other assets. Everything lives in `page.tsx`.-- Images must use external URLs (e.g. Unsplash), not local imports.-- All styles must use stylex or inline styles, not separate CSS files.--### Adding a new option to an existing API function--1. Add the option to the API function in `src/api/{command}.mjs`-2. Pass it through from the CLI handler in `src/commands/{command}.mjs`-3. Update the types in `src/types/api.d.ts` (add to the options interface)-4. If it produces a new response type, also update `src/types/{command}.d.ts` and `src/types/base.d.ts`--### Adding a new response type (e.g. `component.detail.variants`)--1. Add the logic in `src/api/{command}.mjs` — return `{type: 'component.detail.variants', data: ...}`-2. Add a TypeScript interface in `src/types/{command}.d.ts`-3. Add it to `CLIAnyResponse` in `src/types/base.d.ts`-4. Add it to the result union in `src/types/api.d.ts`-5. The parity test will auto-detect the new type and verify API=CLI--### Renaming or removing a response type--This is a breaking change for `@xds/cli/api` consumers. Bump the version.--### What CI catches automatically--- **New component without docs** → smoke test skips it with a message (not a failure)-- **New CLI `--json` type without API coverage** → parity test flags it as a coverage gap-- **API and CLI returning different data** → parity test fails with both payloads shown-- **Invalid JSON envelope shape** → json smoke test fails-- **Type mismatches** → `tsconfig.json-api.json` typecheck fails-------## Naming conventions--### Response types: `{Command}{Mode}{SubMode?}Response`--| Part | Rule | Examples |-| ------- | ----------------------- | --------------------------------------------------------------------------------- |-| Command | PascalCase command name | `Component`, `Discover`, `ThemeBuild` |-| Mode | What the response IS | `List`, `Brief`, `Detail`, `Search`, `Copy`, `Build`, `Run`, `Categories`, `File` |-| SubMode | Narrower view of Mode | `Props`, `Source`, `Doc`, `Section` |-| Suffix | Always `Response` | |--### Entry types: `{Command}{What}Entry`--Sub-objects in arrays. No `Response` suffix.--### Type discriminators: dot-separated lowercase--```-{command}.{mode} -> component.list-{command}.{mode}.{submode} -> component.detail.props-```--### How flags compose--`--json` is an output format, not a mode. All other flags still work:--- `--json + --category X` filters the same response type (no new type needed)-- `--json + --lang zh` applies translation before dumping-- `--json + --props` narrows to `component.detail.props` (sub-mode)-- `--json + --source` narrows to `component.detail.source` (sub-mode)-------## Architecture--The CLI is a thin wrapper around type-safe API functions. Each command follows the same pattern:--```-User calls API function User runs CLI- | |- v v- api/component.mjs ◄──────── commands/component/index.mjs- | |- v v- { type, data } jsonOut(type, data) or formatText(data)-```--Both paths run identical code. The CLI handler just adds argument parsing and output formatting.--```-src/- api/ # Programmatic API (exported as @xds/cli/api)- index.mjs # barrel: component, docs, discover, template, XDSError- component.mjs # component(name?, opts?) → { type, data }- docs.mjs # docs(topic?, section?, opts?) → { type, data }- discover.mjs # discover(query?, opts?) → { type, data }- template.mjs # template(name?, opts?) → { type, data }- error.mjs # XDSError class (carries .suggestions)- commands/ # CLI wrappers (thin: parse args → call API → format output)- component/index.mjs # calls api/component.mjs- docs.mjs # calls api/docs.mjs- discover.mjs # calls api/discover.mjs- template.mjs # calls api/template.mjs- swizzle.mjs # CLI-only (side-effect: copies + rewrites imports)- build-theme.mjs # CLI-only (side-effect: compiles theme to CSS)- upgrade.mjs # CLI-only (side-effect: runs codemods)- gap-report.mjs # CLI-only (side-effect: files GitHub issues)- init.mjs # CLI-only (interactive prompts)- lib/- json.mjs # jsonOut(type, data), jsonError(msg) — internal- parse.mjs # parseResponse, isError, assertResponse — consumer- types/- api.d.ts # API function signatures + XDSError- base.d.ts # CLIError, CLIResult<T>, CLIAnyResponse, CLIResponseType- component.d.ts # ComponentListResponse, ComponentDetailResponse, ...- discover.d.ts # DiscoverListResponse, ...- docs.d.ts # DocsListResponse, ...- template.d.ts # TemplateListResponse, TemplateShowResponse, TemplateSkeletonResponse, TemplateCopyResponse- swizzle.d.ts # SwizzleListResponse, SwizzleCopyResponse- theme.d.ts # ThemeBuildResponse- upgrade.d.ts # UpgradeListResponse, UpgradeRunResponse- gap-report.d.ts # GapReportCategoriesResponse, GapReportFileResponse- index.d.ts # barrel re-export-```--### How the fallback hook works--1. Command runs normally-2. If it called `jsonOut()` or `jsonError()`, `process.__xdsJsonHandled` is `true` -> done-3. If not, the `postAction` hook fires and outputs `CLIUnsupportedError`-4. New commands that don't know about `--json` automatically get a clean error--### CI enforcement--- `tsconfig.json-api.json` typechecks `json.mjs` and `parse.mjs` against the `.d.ts` declarations-- `.github/scripts/cli-json-smoke-test.mjs` validates every `--json` command outputs valid JSON with correct envelope shape-- `.github/scripts/api-cli-parity-test.mjs` verifies the programmatic API returns identical data to `xds --json` for every command-- All three run in the `cli-smoke-test.yml` workflow on every PR--### Suppressing stdout for --json--When `--json` is active, human-readable output must not contaminate stdout:--```javascript-// Simple commands: guard console.log-if (!json) console.log(`✓ Done`);--// Clack-based commands: skip Clack calls-if (!json) p.intro('Welcome');-if (!json) p.log.step('Running...');--// Side-effect commands: still run the work, just suppress output-// and collect results into a receipt object+export default {+ templates: {+ get: async (id) => fetchTemplateFromAPI(id),+ },+ gapReport: {+ url: 'https://your-api.com/gaps',+ },+};```diff --git a/packages/cli/docs/cli-reference.doc.mjs b/packages/cli/docs/cli-reference.doc.mjsdeleted file mode 100644index 570c1d2080..0000000000--- a/packages/cli/docs/cli-reference.doc.mjs+++ /dev/null@@ -1,333 +0,0 @@-/** @type {import('../../core/src/docs-types').ReferenceDoc} */--export const docs = {- name: 'cli-reference',- title: 'CLI Reference',- description:- 'Complete command reference for the XDS CLI — every command, flag, and argument.',-- sections: [- {- title: 'Overview',- content: [- {- type: 'prose',- text: 'The XDS CLI (`npx xds` or `npx @xds/cli`) provides tools for scaffolding, theming, component discovery, documentation, upgrades, and gap reporting. All commands support `--help` for inline usage.',- },- {- type: 'code',- lang: 'bash',- label: 'Quick start',- code: `npx xds --help`,- },- ],- },- {- title: 'Global Options',- content: [- {- type: 'prose',- text: 'These flags apply to any command that outputs documentation or reference content.',- },- {- type: 'list',- style: 'unordered',- items: [- '`--zh` — Output docs in Chinese Simplified',- '`--dense` — Output docs in compressed dense format (token-efficient)',- '`--lang <locale>` — Output docs in specified language/format (en, zh, dense)',- '`--detail <level>` — Output detail level: full, compact, or brief (default: full)',- '`--json` — Output as typed JSON envelope: `{ type, data }`',- ],- },- ],- },- {- title: 'init',- content: [- {- type: 'prose',- text: 'Initialize XDS in your project. Installs packages, sets up theming, and optionally adds AI agent docs for Claude, Cursor, or Codex.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds init`,- },- {- type: 'list',- style: 'unordered',- items: [- '`--features <list>` — Comma-separated features to install (agents, theme, template)',- '`--all` — Install all features, no prompts',- '`--agent <tool>` — Target AI tool for agent docs: claude, cursor, codex, all',- '`--agent-docs-path <path...>` — Explicit file path(s) for agent docs',- '`--remove-agents` — Remove AI agent docs from all agent doc files',- ],- },- ],- },- {- title: 'component',- content: [- {- type: 'prose',- text: 'List components or print detailed component documentation including props, usage examples, and source code.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds component [name]-npx xds component --list-npx xds component Button --props`,- },- {- type: 'list',- style: 'unordered',- items: [- '`[name]` — Component name to look up',- '`--list` — List all components grouped by category',- '`--category <category>` — List components in a specific category',- '`--props` — Print only the props table',- '`--source` — Print component source code',- '`--showcase` — Print showcase source code',- ],- },- ],- },- {- title: 'docs',- content: [- {- type: 'prose',- text: 'Print XDS reference documentation. Topics include tokens, theme, color, typography, spacing, shape, elevation, motion, styling, and principles.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds docs [topic] [section]-npx xds docs tokens-npx xds docs theme "Defining a Theme"`,- },- ],- },- {- title: 'template',- content: [- {- type: 'prose',- text: 'Inject a page or block template into your project. Templates provide pre-built layouts and patterns.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds template [name] [path]-npx xds template --list-npx xds template dashboard ./src/app/dashboard`,- },- {- type: 'list',- style: 'unordered',- items: [- '`[name]` — Template name',- '`[path]` — Output path',- '`--list` — List available templates',- '`--type <type>` — Filter by template type: page or block',- '`--skeleton` — Show layout skeleton with spatial annotations (padding, gap, nesting)',- ],- },- {- type: 'prose',- text: 'Subcommand: `template get --id <id>` — Fetch a template by ID via the xds.config.mjs hook.',- },- ],- },- {- title: 'swizzle',- content: [- {- type: 'prose',- text: 'Copy component source into your project for deep customization. Optionally file a gap report explaining why the default component did not meet your needs.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds swizzle [component]-npx xds swizzle Button --output ./components/xds`,- },- {- type: 'list',- style: 'unordered',- items: [- '`[component]` — Component to swizzle',- '`--output <dir>` — Output directory (default: `./components/xds`)',- '`--list` — List available components',- '`--gap <reason>` — File a gap report explaining why you swizzled',- '`--gap-category <category>` — Gap category (for --gap mode)',- '`--no-report` — Suppress the interactive gap report prompt',- ],- },- ],- },- {- title: 'upgrade',- content: [- {- type: 'prose',- text: 'Run codemods to migrate between XDS versions. By default runs in dry-run mode — pass `--apply` to write changes to disk.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds upgrade --to 0.0.12-npx xds upgrade --apply --to 0.0.12-npx xds upgrade --list`,- },- {- type: 'list',- style: 'unordered',- items: [- '`--apply` — Write changes to disk (default: dry-run)',- '`--from <version>` — Previous version (overrides package.json detection)',- '`--to <version>` — Target version',- '`--force` — Run codemods even if versions appear up to date',- '`--codemod <name>` — Run a specific transform only',- '`--codemod-only` — Skip version bump and install, run codemods only',- '`--skip-install` — Skip package manager install after bumping deps',- '`--force-install` — Pass --force to package manager install',- '`--path <dir>` — Source directory to scan (default: `./src`)',- '`--install-deps` — Auto-install jscodeshift without prompting',- '`--list` — List available codemods',- ],- },- ],- },- {- title: 'theme build',- content: [- {- type: 'prose',- text: 'Compile a defineTheme file to CSS and JS output. Takes a theme definition and produces production-ready theme assets.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds theme build <file> --out theme.css`,- },- {- type: 'list',- style: 'unordered',- items: [- '`<file>` — Path to the defineTheme file (required)',- '`-o, --out <path>` — Output CSS file path',- '`--no-prose` — Skip prose mappings (h1, p, code, hr, etc.)',- ],- },- ],- },- {- title: 'discover',- content: [- {- type: 'prose',- text: 'Discover external XDS packages and components from the ecosystem.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds discover [query]-npx xds discover --components`,- },- {- type: 'list',- style: 'unordered',- items: [- '`[query]` — Search query',- '`--components` — List components only',- ],- },- ],- },- {- title: 'gap-report',- content: [- {- type: 'prose',- text: 'Report a gap in the XDS design system — when a component does not meet your needs and you need to customize or work around it.',- },- {- type: 'code',- lang: 'bash',- label: 'Usage',- code: `npx xds gap-report --component Button --category "missing-variant" --reason "Need a destructive variant"-npx xds gap-report --list-categories`,- },- {- type: 'list',- style: 'unordered',- items: [- '`--component <name>` — Component name',- '`--category <category>` — Gap category',- '`--reason <reason>` — What capability was missing',- '`--list-categories` — List valid gap categories',- ],- },- {- type: 'prose',- text: 'Subcommand: `gap-report setup` — Configure where gap reports are sent.',- },- ],- },- {- title: 'Configuration',- content: [- {- type: 'prose',- text: 'The CLI reads from an optional `xds.config.mjs` file in your project root. This file can customize template discovery, gap report destinations, and other CLI behaviors.',- },- {- type: 'code',- lang: 'js',- label: 'xds.config.mjs',- code: `export default {- // Custom template provider- templates: {- get: async (id) => fetchTemplateFromAPI(id),- },- // Gap report webhook- gapReport: {- url: 'https://your-api.com/gaps',- },-};`,- },- ],- },- {- title: 'Programmatic API',- content: [- {- type: 'prose',- text: 'The CLI is also available as a programmatic API via `@xds/cli/api`. This lets you embed CLI capabilities into build scripts, AI agents, or custom tooling.',- },- {- type: 'code',- lang: 'ts',- label: 'Programmatic usage',- code: `import { getComponent, listComponents, getDocs } from '@xds/cli/api';--const button = await getComponent('Button');-const allComponents = await listComponents();-const tokens = await getDocs('tokens');`,- },- ],- },- ],-};diff --git a/packages/cli/docs/color.doc.mjs b/packages/cli/docs/color.doc.mjsindex 8a2082a2ee..395759fc00 100644--- a/packages/cli/docs/color.doc.mjs+++ b/packages/cli/docs/color.doc.mjs@@ -39,7 +39,7 @@ export const docs = {lang: 'tsx',label: 'Applying color tokens',code: `import * as stylex from '@stylexjs/stylex';-import {colorVars} from '@xds/core';+import {colorVars} from '@xds/core/theme/tokens.stylex';const styles = stylex.create({container: {diff --git a/packages/cli/docs/icons.doc.mjs b/packages/cli/docs/icons.doc.mjsindex c7a0cf4960..931b6cc348 100644--- a/packages/cli/docs/icons.doc.mjs+++ b/packages/cli/docs/icons.doc.mjs@@ -26,8 +26,8 @@ export const docs = {['chevronLeft', 'Navigate back, previous'],['chevronRight', 'Navigate forward, next'],['check', 'Checkbox checked, confirm'],- ['checkCircle', 'Success status indicator'],- ['xCircle', 'Error status indicator'],+ ['success', 'Success status indicator'],+ ['error', 'Error status indicator'],['warning', 'Warning status indicator'],['info', 'Info status indicator, tooltips'],['calendar', 'Date pickers, scheduling'],@@ -81,7 +81,7 @@ import { HeartIcon } from 'lucide-react';type: 'code',lang: 'tsx',label: 'Registering theme icons',- code: `import { registerIcons } from '@xds/core';+ code: `import { registerIcons } from '@xds/core/Icon';import { XMarkIcon, ChevronDownIcon } from '@heroicons/react/24/outline';registerIcons({diff --git a/packages/cli/docs/principles.doc.dense.mjs b/packages/cli/docs/principles.doc.dense.mjsindex 77f3643c18..0ac79a636e 100644--- a/packages/cli/docs/principles.doc.dense.mjs+++ b/packages/cli/docs/principles.doc.dense.mjs@@ -1,12 +1,12 @@/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */export const docsDense = {- description: 'design rules + anti-patterns',+ description: 'core design principles + rules for XDS',sections: [- { title: 'Rules', content: [{ type: 'list', items: ['use XDS components', 'StyleX for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs'] }] },- { title: 'xstyle prop', content: [{ type: 'prose', text: 'xstyle accepts inline obj, stylex.create, or CSS class string.' }, null, null, null, { type: 'list', items: ['1-2 props: inline', '3+ props: stylex.create', 'pseudo-classes: stylex.create required', ':hover needs @media (hover: hover)'] }] },- { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors', 'no hardcoded spacing', 'no hardcoded <a> — use useXDSLinkComponent()', 'read docs before inventing props'] }] },- { title: 'StyleX', content: [null] },- { title: 'Token Quick Ref', content: [{ type: 'prose', text: 'see xds docs tokens' }, null] },+ { title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },+ { title: 'Rules', content: [{ type: 'list', items: ['use XDS components', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useXDSLinkComponent() for navigation'] }] },+ { title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See xds docs styling.' }] },+ { title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useXDSLinkComponent()', 'read docs before inventing props'] }] },+ { title: 'Tokens', content: [{ type: 'prose', text: 'run npx xds docs tokens for full reference' }] },],};diff --git a/packages/cli/docs/principles.doc.mjs b/packages/cli/docs/principles.doc.mjsindex c03ebd6df6..11f4500aa2 100644--- a/packages/cli/docs/principles.doc.mjs+++ b/packages/cli/docs/principles.doc.mjs@@ -3,9 +3,29 @@export const docs = {name: 'principles',title: 'XDS Principles',- description: 'Design principles, rules, and anti-patterns for XDS.',+ description:+ 'Core design principles and rules for building with XDS.',sections: [+ {+ title: 'Design Philosophy',+ content: [+ {+ type: 'prose',+ text: 'XDS is a design system that prioritizes consistency, adaptability, and developer experience. Every decision flows from a few core ideas:',+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ 'Components over primitives — use XDS components for everything they cover before reaching for raw HTML',+ 'Semantic tokens over hardcoded values — colors, spacing, and radii are named by purpose, not appearance',+ 'Theme-agnostic code — your app code never references specific colors or measurements, so themes and dark mode work automatically',+ 'Open internals — every primitive is exported and composable, so you can build on top of XDS without fighting it',+ ],+ },+ ],+ },{title: 'Rules',content: [@@ -14,59 +34,25 @@ export const docs = {style: 'ordered',items: ['Use XDS components for everything they cover',- 'StyleX for styling (not inline styles)',- 'Semantic tokens, not hardcoded values',- 'CSS variables for colors, not hex',+ 'StyleX or Tailwind for custom styling — both are first-class (see \`npx xds docs styling\`)',+ 'Semantic tokens, not hardcoded values (see \`npx xds docs tokens\`)',+ 'CSS custom properties for colors, not hex values','Form inputs are controlled (value + onChange)',+ 'Use useXDSLinkComponent() for navigation so consumers can plug in their framework router via XDSLinkProvider',],},],},{- title: 'Style Overrides: xstyle prop',+ title: 'Styling Approach',content: [{type: 'prose',- text: 'Most XDS components accept an xstyle prop for customizing styles. It supports three formats.',- },- {- type: 'code',- lang: 'tsx',- label: 'Inline styles',- code: `<XDSTextInput label="Name" xstyle={{ maxWidth: 300 }} />-<XDSCard xstyle={{ height: 200, padding: 16 }} />`,- },- {- type: 'code',- lang: 'tsx',- label: 'StyleX styles',- code: `import * as stylex from '@stylexjs/stylex';-const overrides = stylex.create({- hoverCard: {- boxShadow: {- default: 'none',- ':hover': {'@media (hover: hover)': '0 4px 12px rgba(0,0,0,0.15)'},- },- },-});-<XDSCard xstyle={overrides.hoverCard} />;`,+ text: 'XDS supports multiple styling approaches. Every component accepts an \`xstyle\` prop for overrides (inline objects, StyleX styles, or CSS class names). For layout and wrapper styling outside of components, use StyleX or Tailwind utilities — both resolve to the same XDS design tokens.',},{- type: 'code',- lang: 'tsx',- label: 'CSS class name',- code: `<XDSCard xstyle="my-custom-card" />-<XDSCard xstyle={styles.customCard} /> // CSS Module`,- },- {- type: 'list',- style: 'unordered',- items: [- '1-2 simple properties: use inline',- '3+ properties, reusable, or named: use stylex.create',- 'Pseudo-classes (:hover, :focus-visible): use stylex.create (required)',- 'All :hover MUST use @media (hover: hover) guards',- ],+ type: 'prose',+ text: 'See \`npx xds docs styling\` for the complete guide with examples.',},],},@@ -78,8 +64,8 @@ const overrides = stylex.create({style: 'dont',items: ['Inline styles on raw elements. Use xstyle on XDS components',- 'Hardcoded colors (#fff). Use var(--color-*)',- 'Hardcoded spacing (16px). Use spacing tokens or var(--spacing-*)',+ 'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',+ 'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities','Hardcoded <a> elements. Use useXDSLinkComponent() so consumers can swap in their framework router via XDSLinkProvider','Inventing props. Read component docs first',],@@ -87,41 +73,11 @@ const overrides = stylex.create({],},{- title: 'StyleX Usage',- content: [- {- type: 'code',- lang: 'tsx',- label: 'Basic StyleX pattern',- code: `import * as stylex from '@stylexjs/stylex';--const styles = stylex.create({- container: {- padding: 'var(--spacing-4)',- backgroundColor: 'var(--color-background-surface)',- borderRadius: 'var(--radius-element)',- },-});--<div {...stylex.props(styles.container)}>`,- },- ],- },- {- title: 'Quick Token Reference',+ title: 'Design Tokens',content: [{type: 'prose',- text: 'See `xds docs tokens` for the full list. Key values:',- },- {- type: 'table',- headers: ['Category', 'Values'],- rows: [- ['Spacing', '0=0px | 0.5=2px | 1=4px | 2=8px | 3=12px | 4=16px | 5=20px | 6=24px | 7=32px'],- ['Radius', 'rounded=pill | container=12px | element=8px | content=4px'],- ['Colors', 'accent, surface, wash, positive, negative, warning'],- ],+ text: 'XDS provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`npx xds docs tokens\` for the full reference with all values.',},],},diff --git a/packages/cli/docs/principles.doc.zh.mjs b/packages/cli/docs/principles.doc.zh.mjsindex d335ecf060..2fd9355c20 100644--- a/packages/cli/docs/principles.doc.zh.mjs+++ b/packages/cli/docs/principles.doc.zh.mjs@@ -1,12 +1,12 @@/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */export const docsZh = {- description: 'XDS 设计原则、规则和反模式。',+ description: 'XDS 核心设计原则和规则。',sections: [- { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '使用 StyleX 进行样式设置(不使用内联样式)', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)'] }] },- { title: '样式覆盖:xstyle 属性', content: [{ type: 'prose', text: '大多数 XDS 组件接受 xstyle 属性来自定义样式。支持三种格式。' }, null, null, null, { type: 'list', items: ['1-2 个简单属性:使用内联', '3+ 个属性、可复用或命名的:使用 stylex.create', '伪类(:hover、:focus-visible):必须使用 stylex.create', '所有 :hover 必须使用 @media (hover: hover) 守卫'] }] },- { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式。使用 XDS 组件的 xstyle', '不要硬编码颜色(#fff)。使用 var(--color-*)', '不要硬编码间距(16px)。使用间距令牌或 var(--spacing-*)', '不要自创属性。先阅读组件文档'] }] },- { title: 'StyleX 用法', content: [null] },- { title: '快速令牌参考', content: [{ type: 'prose', text: '完整列表请查看 `xds docs tokens`。主要值:' }, null] },+ { title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },+ { title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useXDSLinkComponent() 进行导航'] }] },+ { title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 xds docs styling。' }] },+ { title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useXDSLinkComponent()', '不要自创属性。先阅读组件文档'] }] },+ { title: '设计令牌', content: [{ type: 'prose', text: '运行 npx xds docs tokens 查看完整参考' }] },],};diff --git a/packages/cli/docs/styling.doc.mjs b/packages/cli/docs/styling.doc.mjsindex 9c9bac223b..65d90b0675 100644--- a/packages/cli/docs/styling.doc.mjs+++ b/packages/cli/docs/styling.doc.mjs@@ -4,9 +4,32 @@ export const docs = {name: 'styling',title: 'Styling XDS Components',description:- 'How to customize component appearance: xstyle prop, className, rest props, compound component patterns, and theming hooks.',+ 'How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, and theming hooks.',sections: [+ {+ title: 'Overview',+ content: [+ {+ type: 'prose',+ text: 'XDS gives you several ways to style things. Here is when to use each:',+ },+ {+ type: 'table',+ headers: ['Approach', 'Use for', 'Example'],+ rows: [+ ['xstyle prop', 'Overriding a specific XDS component', 'xstyle={{ maxWidth: 400 }}'],+ ['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"'],+ ],+ },+ {+ type: 'prose',+ text: 'All approaches resolve to the same XDS design tokens, so theming and dark mode work regardless of which you choose.',+ },+ ],+ },{title: 'xstyle Prop',content: [@@ -57,6 +80,35 @@ const overrides = stylex.create({},],},+ {+ title: 'Tailwind Integration',+ content: [+ {+ type: 'prose',+ text: 'XDS ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by XDS tokens — colors, spacing, radius, shadows, and typography all resolve to the active theme.',+ },+ {+ type: 'code',+ lang: 'css',+ label: 'globals.css — import the bridge',+ code: `@import "tailwindcss";+@import "@xds/core/tailwind-theme.css" layer(theme);`,+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Tailwind utilities alongside XDS components',+ code: `<div className="text-primary bg-surface rounded-container p-4 flex gap-3">+ <XDSButton label="Save" variant="primary" />+ <XDSButton label="Cancel" variant="secondary" />+</div>`,+ },+ {+ type: 'prose',+ text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that XDS components use.',+ },+ ],+ },{title: 'className and style Props',content: [@@ -67,12 +119,15 @@ const overrides = stylex.create({{type: 'code',lang: 'tsx',- label: 'className for Tailwind or utility classes',- code: `<XDSButton label="Save" className="my-app-save-btn" />`,+ label: 'className with Tailwind utilities',+ code: `<XDSCard className="shadow-lg hover:shadow-xl transition-shadow">+ ...+</XDSCard>+<XDSButton label="Save" className="my-app-save-btn" />`,},{type: 'prose',- text: 'Prefer xstyle over className + style. xstyle integrates with StyleX deduplication and the component\'s internal style pipeline. className and style are escape hatches for integration with external CSS systems.',+ text: 'For layout and wrapper styling, Tailwind utilities on className work well. For component-specific overrides (padding, colors, borders), prefer xstyle — it integrates with StyleX deduplication and the component\'s internal style pipeline.',},],},@@ -230,8 +285,8 @@ const styles = stylex.create({style: 'dont',items: ['style={{}} on raw <div> wrappers. Use xstyle on the XDS component directly.',- 'Hardcoded colors (#fff, rgb(...)). Use var(--color-*) tokens.',- 'Hardcoded spacing (16px, 1rem). Use var(--spacing-*) tokens.',+ 'Hardcoded colors (#fff, rgb(...)). Use var(--color-*) tokens or Tailwind semantic classes (text-primary, bg-surface).',+ 'Hardcoded spacing (16px, 1rem). Use var(--spacing-*) tokens or Tailwind spacing utilities (p-4, gap-3).','Wrapping an XDS component in a <div> just to add margin. Use xstyle={{ margin: ... }} on the component.','Using !important. If styles aren\'t applying, check specificity — xstyle is merged last.',],