Skip to content

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.md
new file mode 100644
index 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 PR
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 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.
```bash
npx xds --help
@@ -9,6 +9,31 @@ npx xds docs tokens
npx 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 API
Every command supports `--json` for machine-readable output. Responses are typed envelopes:
@@ -26,12 +51,12 @@ Errors:
}
```
-### Programmatic API
+## Programmatic API
The 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 Button
const 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 utilities
If you're spawning the CLI as a subprocess rather than importing the API directly:
@@ -85,341 +110,47 @@ detail.data.name; // already narrowed
Every 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.mjs
deleted file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.',
],