Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(deslop): batch 1 - remove AI-slop tells from doc files (30 files) (#2656)

Joeyc95fe8acc61c
diff --git a/README.md b/README.md
index c81c907a3d..b067f19100 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
# XDS
-A design system for building internal tools and products, enabling the creation of high-quality product experiences.
+A design system for building internal tools and products.
## Overview
@@ -10,10 +10,10 @@ XDS is an open source design system born from years of building internal tools a
**What makes XDS different:**
-- **Open internals** — All primitives are exported and composable, not hidden. Build exactly what you need.
-- **Plugin architecture** — Transform and extend components through a unified plugin system
-- **Automatic spacing** — Context-aware spacing compensation eliminates "double padding" issues
-- **AI-ready** — JSDoc annotations with composition hints designed for LLM-assisted development
+- **Open internals:** All primitives are exported and composable, not hidden. Build exactly what you need.
+- **Plugin architecture:** Transform and extend components through a unified plugin system
+- **Automatic spacing:** Context-aware spacing compensation eliminates "double padding" issues
+- **AI-ready:** JSDoc annotations with composition hints for LLM-assisted development
## Getting Started
@@ -52,7 +52,7 @@ Then follow the [setup guide](packages/core/README.md#quick-start) to import sty
| Package | Description | README |
| ----------------------------------------------- | --------------------------------------------------- | ------------------------------------------- |
| [`@xds/core`](packages/core) | Components, theme system, and utilities | [README](packages/core/README.md) |
-| [`@xds/cli`](packages/cli) | CLI tooling — component docs, scaffolding, codemods | [README](packages/cli/README.md) |
+| [`@xds/cli`](packages/cli) | CLI tooling: component docs, scaffolding, codemods | [README](packages/cli/README.md) |
| [`@xds/build`](packages/build) | Build plugins for StyleX source builds | [README](packages/build/README.md) |
| [`@xds/vega`](packages/vega) | Vega/Vega-Lite chart wrapper | [README](packages/vega/README.md) |
| [`@xds/theme-default`](packages/themes/default) | Clean, professional default theme | [README](packages/themes/default/README.md) |
@@ -61,9 +61,9 @@ Then follow the [setup guide](packages/core/README.md#quick-start) to import sty
## Philosophy
-- **AI-First** — Built to produce better trajectories in AI-assisted development, with auto-documentation and patterns designed for LLM consumption
-- **Open Internals** — Unlike closed systems, all subcomponents are exported and recommended for use. Compose at any level.
-- **Themeable** — First-class theming with CSS variable cascade
+- **AI-First:** Built to produce better trajectories in AI-assisted development, with auto-documentation and patterns for LLM consumption
+- **Open Internals:** Unlike closed systems, all subcomponents are exported and recommended for use. Compose at any level.
+- **Themeable:** First-class theming with CSS variable cascade
## Architecture
diff --git a/apps/docsite/README.md b/apps/docsite/README.md
index 65dc81be34..00419649e1 100644
--- a/apps/docsite/README.md
+++ b/apps/docsite/README.md
@@ -27,7 +27,7 @@ from the monorepo and writes typed TypeScript registries to `src/generated/`.
| Registry | Source | What it contains |
| ---------------------- | --------------------------------- | ------------------------------------------------------------- |
| `packageRegistry.ts` | `packages/*/package.json` | Name, version, description, README for each published package |
-| `componentRegistry.ts` | `*.doc.mjs` files | Props, usage docs, hooks, groups — per package |
+| `componentRegistry.ts` | `*.doc.mjs` files | Props, usage docs, hooks, groups, per package |
| `blockRegistry.ts` | CLI `templates/blocks/` | Showcase and example blocks with metadata |
| `templateRegistry.ts` | CLI `templates/pages/` | Page-level templates (e.g. dashboard, settings) |
| `docsRegistry.ts` | CLI `docs/` | Long-form guide and foundation topics |
@@ -36,7 +36,7 @@ from the monorepo and writes typed TypeScript registries to `src/generated/`.
| `exampleRegistry.ts` | Blocks with `exampleFor` | Copied example blocks per component |
The `src/generated/` directory is gitignored. Pages import from these registries
-and render whatever the pipeline found — no manual wiring needed.
+and render whatever the pipeline found, with no manual wiring needed.
### The Rule
@@ -46,9 +46,9 @@ add it to `generate-data.mjs` and consume it from a registry.
This means:
-- No `import {fooTheme} from '@xds/theme-foo/built'` in page files — use `themeObjects` from the generated `themeRegistry`
-- No hand-maintained arrays of component names — use `componentRegistry`
-- No `if (pkg === '@xds/core')` switches — let the pipeline classify packages
+- No `import {fooTheme} from '@xds/theme-foo/built'` in page files; use `themeObjects` from the generated `themeRegistry`
+- No hand-maintained arrays of component names; use `componentRegistry`
+- No `if (pkg === '@xds/core')` switches; let the pipeline classify packages
## Adding a New Theme
@@ -56,7 +56,7 @@ This means:
2. Add `"@xds/theme-<name>": "*"` to `apps/docsite/package.json` dependencies
3. Add `@import "@xds/theme-<name>/theme.css"` to `src/app/globals.css`
4. Load the theme's fonts (see below)
-5. Run `pnpm generate` — the theme appears in `themeRegistry.ts`, `packageRegistry.ts`, the sidebar, craft page, and package detail page automatically
+5. Run `pnpm generate`; the theme appears in `themeRegistry.ts`, `packageRegistry.ts`, the sidebar, craft page, and package detail page automatically
> Only add **public** (non-private) theme packages to the docsite.
@@ -115,5 +115,5 @@ apps/docsite/
## Testing
Tests live in `src/__tests__/data-extraction.test.ts` and validate the generated
-registries — package discovery, component extraction, theme wiring, etc. Run
+registries: package discovery, component extraction, theme wiring, etc. Run
`pnpm generate` before running tests since they import from `src/generated/`.
diff --git a/apps/example-nextjs-source/README.md b/apps/example-nextjs-source/README.md
index 4d26626831..b161302fd1 100644
--- a/apps/example-nextjs-source/README.md
+++ b/apps/example-nextjs-source/README.md
@@ -1,4 +1,4 @@
-# XDS Example — Next.js (Source Build)
+# XDS Example: Next.js (Source Build)
Reference application for compiling **@xds/core** from raw TypeScript + StyleX source alongside product code. Uses `@xds/build` for independent CSS layer separation.
@@ -15,8 +15,8 @@ Reference application for compiling **@xds/core** from raw TypeScript + StyleX s
`@xds/build` provides two plugins that work together:
-1. **`@xds/build/babel`** — wraps the StyleX babel plugin, routing XDS library files to `xds` class prefix and product files to default `x` prefix
-2. **`@xds/build/postcss`** — compiles StyleX CSS in two passes with different prefixes, wrapping each in its own `@layer`
+1. **`@xds/build/babel`**: wraps the StyleX babel plugin, routing XDS library files to `xds` class prefix and product files to default `x` prefix
+2. **`@xds/build/postcss`**: compiles StyleX CSS in two passes with different prefixes, wrapping each in its own `@layer`
This creates completely independent class namespaces:
@@ -111,7 +111,7 @@ export default nextConfig;
### 5. CSS files
-`src/app/layers.css` — must be a separate file (webpack hoists `@import` content):
+`src/app/layers.css` must be a separate file (webpack hoists `@import` content):
```css
@layer reset, xds-base, xds-theme, product;
@@ -131,10 +131,10 @@ export default nextConfig;
This example includes a visual demo showing:
-1. **xds-base** — default XDS component styles
-2. **xds-theme** — theme overrides (secondary button background)
-3. **product** — app overrides (pill shape, green background, full-width)
-4. **Class prefix verification** — XDS components use `xds` prefix, product uses `x`
+1. **xds-base**: default XDS component styles
+2. **xds-theme**: theme overrides (secondary button background)
+3. **product**: app overrides (pill shape, green background, full-width)
+4. **Class prefix verification**: XDS components use `xds` prefix, product uses `x`
Open devtools → CSS layers panel to see the separation.
@@ -149,7 +149,7 @@ Open devtools → CSS layers panel to see the separation.
## Related
-- [Plain dist example](../example-nextjs/) — simplest setup
-- [Dist + Tailwind](../example-nextjs-tailwind/) — Tailwind for layout
-- [Dist + StyleX](../example-nextjs-stylex/) — StyleX for product only
-- [`@xds/build`](../../packages/build/) — the build plugin source
+- [Plain dist example](../example-nextjs/): simplest setup
+- [Dist + Tailwind](../example-nextjs-tailwind/): Tailwind for layout
+- [Dist + StyleX](../example-nextjs-stylex/): StyleX for product only
+- [`@xds/build`](../../packages/build/): the build plugin source
diff --git a/apps/example-nextjs-stylex/README.md b/apps/example-nextjs-stylex/README.md
index cd700977af..4e72cdec09 100644
--- a/apps/example-nextjs-stylex/README.md
+++ b/apps/example-nextjs-stylex/README.md
@@ -1,8 +1,8 @@
-# XDS Example — Next.js + StyleX (Dist)
+# XDS Example: Next.js + StyleX (Dist)
Reference application for consuming **@xds/core** as a pre-built dist package with **StyleX** for product-level styles.
-XDS component CSS comes pre-built — no need to compile XDS source. StyleX is only used for your own app-level layout and custom styles, compiled at build time via the PostCSS plugin.
+XDS component CSS comes pre-built; there is no need to compile XDS source. StyleX is only used for your own app-level layout and custom styles, compiled at build time via the PostCSS plugin.
## CSS Layer Integration
@@ -53,7 +53,7 @@ npm install --save-dev @stylexjs/babel-plugin @stylexjs/postcss-plugin \
### 3. Babel config
-`babel.config.js` — StyleX for app-level styles only:
+`babel.config.js`: StyleX for app-level styles only:
```js
module.exports = {
@@ -76,11 +76,11 @@ module.exports = {
};
```
-> No `aliases` config needed — we're not compiling XDS source.
+> No `aliases` config needed; we're not compiling XDS source.
### 4. PostCSS config
-`postcss.config.js` — scan your app source, declare XDS layers before StyleX layers:
+`postcss.config.js`: scan your app source, declare XDS layers before StyleX layers:
```js
module.exports = {
@@ -130,5 +130,5 @@ export function Providers({children}) {
## Related
-- [Plain dist example](../example-nextjs/) — no CSS framework, inline styles for layout
-- [Dist + Tailwind example](../example-nextjs-tailwind/) — Tailwind for layout styles
+- [Plain dist example](../example-nextjs/): no CSS framework, inline styles for layout
+- [Dist + Tailwind example](../example-nextjs-tailwind/): Tailwind for layout styles
diff --git a/apps/example-nextjs-tailwind/README.md b/apps/example-nextjs-tailwind/README.md
index 16bcaee417..0513a00e7c 100644
--- a/apps/example-nextjs-tailwind/README.md
+++ b/apps/example-nextjs-tailwind/README.md
@@ -1,6 +1,6 @@
# XDS + Tailwind (Dist Build)
-Example Next.js app using XDS pre-built dist CSS alongside Tailwind CSS v4. No StyleX build plugin needed — XDS components are consumed as a regular npm package with a CSS import.
+Example Next.js app using XDS pre-built dist CSS alongside Tailwind CSS v4. No StyleX build plugin needed: XDS components are consumed as a regular npm package with a CSS import.
## How it works
@@ -24,8 +24,8 @@ This gives the correct priority (lowest → highest):
| `xds-base` | XDS | Component styles (buttons, cards, inputs, etc.) |
| `xds-theme` | XDS | Theme overrides (typography, color mappings) |
| `components` | Tailwind | Component classes (if any) |
-| `utilities` | Tailwind | Utility classes — **wins over all layers** |
-| *(unlayered)* | Consumer | Your custom CSS — highest priority |
+| `utilities` | Tailwind | Utility classes: **wins over all layers** |
+| *(unlayered)* | Consumer | Your custom CSS: highest priority |
Without this declaration, XDS layers are created *after* Tailwind's declared layers, making XDS component styles outrank Tailwind utilities. That means `className="bg-red-500"` on an XDS component wouldn't work.
@@ -46,7 +46,7 @@ Without this declaration, XDS layers are created *after* Tailwind's declared lay
### XDS Tailwind Bridge (recommended)
-Import `@xds/core/tailwind-theme.css` to register XDS tokens as Tailwind theme variables. This maps all XDS design tokens to native Tailwind utilities — no `var()` needed:
+Import `@xds/core/tailwind-theme.css` to register XDS tokens as Tailwind theme variables. This maps all XDS design tokens to native Tailwind utilities, with no `var()` needed:
```tsx
// Before (verbose arbitrary values):
@@ -60,7 +60,7 @@ Import `@xds/core/tailwind-theme.css` to register XDS tokens as Tailwind theme v
</div>
```
-The bridge uses Tailwind v4's `@theme inline` — it tells Tailwind to generate utilities from XDS's existing CSS custom properties without emitting duplicate declarations. Theme switching just works.
+The bridge uses Tailwind v4's `@theme inline`: it tells Tailwind to generate utilities from XDS's existing CSS custom properties without emitting duplicate declarations. Theme switching just works.
Available utilities include `text-primary`, `text-secondary`, `bg-surface`, `bg-card`, `border-strong`, `text-error`, `bg-success`, `bg-blue-subtle`, `text-blue-vivid`, `border-blue-ring`, and 80+ more.
@@ -85,7 +85,7 @@ All XDS components accept `className`. Tailwind utilities in the `utilities` lay
### Mixing XDS and Tailwind components
-Shadcn-style Tailwind components render correctly alongside XDS — both resets are nearly identical (shared modern-normalize lineage), so there are no conflicts:
+Shadcn-style Tailwind components render correctly alongside XDS. Both resets are nearly identical (shared modern-normalize lineage), so there are no conflicts:
```tsx
<div className="grid grid-cols-2 gap-6">
@@ -98,9 +98,9 @@ Shadcn-style Tailwind components render correctly alongside XDS — both resets
XDS reset and Tailwind Preflight overlap ~80%. The meaningful differences:
-- **Font smoothing** — XDS enables `-webkit-font-smoothing: antialiased`; Tailwind doesn't
-- **Color scheme** — XDS maps `data-theme` to `color-scheme` for light/dark mode
-- **Placeholder color** — XDS uses `var(--color-text-secondary)` token; Tailwind uses `color-mix()`
+- **Font smoothing**: XDS enables `-webkit-font-smoothing: antialiased`; Tailwind doesn't
+- **Color scheme**: XDS maps `data-theme` to `color-scheme` for light/dark mode
+- **Placeholder color**: XDS uses `var(--color-text-secondary)` token; Tailwind uses `color-mix()`
Both resets can run together without conflicts. Neither breaks the other's components.
diff --git a/apps/example-nextjs/README.md b/apps/example-nextjs/README.md
index 375dd9a8a4..0a33d4f673 100644
--- a/apps/example-nextjs/README.md
+++ b/apps/example-nextjs/README.md
@@ -1,8 +1,8 @@
-# XDS Example — Next.js (Dist)
+# XDS Example: Next.js (Dist)
Reference application for consuming **@xds/core** as a pre-built dist package in a Next.js project.
-No StyleX build plugin needed — XDS ships pre-compiled CSS and JS. This is the simplest way to get started.
+No StyleX build plugin needed; XDS ships pre-compiled CSS and JS. This is the simplest way to get started.
## Setup Steps
@@ -15,7 +15,7 @@ npm install --save-dev @types/react @types/react-dom typescript
### 2. CSS imports
-`src/app/globals.css` — import the reset, component styles, and theme:
+In `src/app/globals.css`, import the reset, component styles, and theme:
```css
@import '@xds/core/reset.css';
@@ -25,9 +25,9 @@ npm install --save-dev @types/react @types/react-dom typescript
The CSS import order matters:
-1. `reset.css` — baseline resets (`@layer reset`)
-2. `xds.css` — all component styles (`@layer xds-base`)
-3. `theme.css` — theme token overrides (`@layer xds-theme`)
+1. `reset.css`: baseline resets (`@layer reset`)
+2. `xds.css`: all component styles (`@layer xds-base`)
+3. `theme.css`: theme token overrides (`@layer xds-theme`)
Import the CSS file in your root layout:
@@ -67,9 +67,9 @@ export function Providers({children}) {
This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@xds/core` from npm. Monorepo workspace resolution can silently bypass issues that external consumers hit.
-**Before merging changes to this example, test it as an external consumer** — see the [Testing Example Apps](https://github.com/facebookexperimental/xds/wiki/Testing-Example-Apps) wiki page for the full procedure.
+**Before merging changes to this example, test it as an external consumer.** See the [Testing Example Apps](https://github.com/facebookexperimental/xds/wiki/Testing-Example-Apps) wiki page for the full procedure.
## Related
-- [Issue #145 — Add example-nextjs project](https://github.com/facebookexperimental/xds/issues/145)
-- [XDS + Tailwind example](../example-nextjs-tailwind/) — same dist approach with Tailwind for custom layout styles
+- [Issue #145: Add example-nextjs project](https://github.com/facebookexperimental/xds/issues/145)
+- [XDS + Tailwind example](../example-nextjs-tailwind/): same dist approach with Tailwind for custom layout styles
diff --git a/apps/example-vite/README.md b/apps/example-vite/README.md
index dcaaa19d24..24e936134a 100644
--- a/apps/example-vite/README.md
+++ b/apps/example-vite/README.md
@@ -1,8 +1,8 @@
-# XDS Example — Vite
+# XDS Example: Vite
Reference application for consuming **@xds/core** as a source distribution in a Vite + React project.
-XDS ships as raw TypeScript + StyleX source. Consumers compile it at the application level — there's no pre-built CSS or JS bundle. This example shows the complete setup using `@stylexjs/unplugin`, which handles both StyleX compilation and CSS extraction in a single Vite plugin.
+XDS ships as raw TypeScript + StyleX source. Consumers compile it at the application level; there's no pre-built CSS or JS bundle. This example shows the complete setup using `@stylexjs/unplugin`, which handles both StyleX compilation and CSS extraction in a single Vite plugin.
## How it differs from Next.js
@@ -25,7 +25,7 @@ npm install --save-dev @stylexjs/unplugin @vitejs/plugin-react typescript \
### 2. Browserslist
-Add a `browserslist` to `package.json` so that both Vite's CSS pipeline and the StyleX unplugin target modern browsers. XDS tokens use native `light-dark()` (baseline 2024) — without modern targets, lightningcss lowers it into polyfill variables that break theming:
+Add a `browserslist` to `package.json` so that both Vite's CSS pipeline and the StyleX unplugin target modern browsers. XDS tokens use native `light-dark()` (baseline 2024); without modern targets, lightningcss lowers it into polyfill variables that break theming:
```json
{
@@ -37,7 +37,7 @@ Add a `browserslist` to `package.json` so that both Vite's CSS pipeline and the
### 3. Vite config
-`vite.config.ts` — configure the StyleX unplugin, React plugin, and resolve aliases:
+`vite.config.ts`: configure the StyleX unplugin, React plugin, and resolve aliases:
```ts
import path from 'path';
@@ -109,11 +109,11 @@ export default defineConfig({
});
```
-> **Important:** The `lightningcssOptions.targets` config is required — the StyleX unplugin's internal lightningcss defaults to `browserslist('>= 1%')` which includes Chrome 112, a browser that doesn't support `light-dark()`. Without explicit targets, all theming colors silently break. The `resolve.alias` points `@xds/core` to source so Vite compiles from TypeScript. Plugin order matters — `stylex.vite()` must come before `react()`.
+> **Important:** The `lightningcssOptions.targets` config is required; the StyleX unplugin's internal lightningcss defaults to `browserslist('>= 1%')` which includes Chrome 112, a browser that doesn't support `light-dark()`. Without explicit targets, all theming colors silently break. The `resolve.alias` points `@xds/core` to source so Vite compiles from TypeScript. Plugin order matters: `stylex.vite()` must come before `react()`.
### 4. CSS entry point
-`src/index.css` — a minimal CSS file so Vite emits a CSS asset for StyleX to append to:
+`src/index.css`: a minimal CSS file so Vite emits a CSS asset for StyleX to append to:
```css
:root {
@@ -131,9 +131,9 @@ import './index.css';
The CSS import order matters:
-1. `reset.css` — baseline resets (`@layer reset`)
-2. `theme.css` — theme token overrides (`@layer xds.theme`)
-3. `index.css` — StyleX extraction placeholder
+1. `reset.css`: baseline resets (`@layer reset`)
+2. `theme.css`: theme token overrides (`@layer xds.theme`)
+3. `index.css`: StyleX extraction placeholder
### 5. Theme provider
@@ -148,7 +148,7 @@ export default function App() {
}
```
-No `'use client'` needed — Vite doesn't have server/client boundaries.
+No `'use client'` needed; Vite doesn't have server/client boundaries.
## Commands
@@ -167,7 +167,7 @@ npm run preview
| Issue | Symptom | Fix |
| ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
-| Missing `lightningcssOptions` | Colors broken — `light-dark()` gets lowered | Add `lightningcssOptions: { targets: lightningcssTargets }` to StyleX plugin |
+| Missing `lightningcssOptions` | Colors broken: `light-dark()` gets lowered | Add `lightningcssOptions: { targets: lightningcssTargets }` to StyleX plugin |
| Vite pre-bundles XDS | `Unexpected stylex.defineVars at runtime` | Add `optimizeDeps: { exclude: ['@xds/core', '@xds/theme-default'] }` |
| Missing resolve aliases | Module not found errors for `@xds/core` | Add `resolve.alias` pointing to source directory |
| Missing CSS entry point | StyleX has no CSS asset to append to | Create a minimal `index.css` and import it in `main.tsx` |
@@ -178,10 +178,10 @@ npm run preview
This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@xds/core` from npm. Monorepo workspace symlinks can silently bypass issues that external consumers hit (Vite dep pre-bundling, missing dependencies, wrong resolve paths).
-**Before merging changes to this example, test it as an external consumer** — see the [Testing Example Apps](https://github.com/facebookexperimental/xds/wiki/Testing-Example-Apps) wiki page for the full procedure.
+**Before merging changes to this example, test it as an external consumer.** See the [Testing Example Apps](https://github.com/facebookexperimental/xds/wiki/Testing-Example-Apps) wiki page for the full procedure.
## Related
-- [Issue #145 — Example apps for source distribution consumers](https://github.com/facebookexperimental/xds/issues/145)
+- [Issue #145: Example apps for source distribution consumers](https://github.com/facebookexperimental/xds/issues/145)
- [StyleX Vite React example](https://github.com/facebook/stylex/tree/main/examples/example-vite-react)
-- [XDS Example — Next.js](../example-nextjs/)
+- [XDS Example: Next.js](../example-nextjs/)
diff --git a/apps/sandbox/README.md b/apps/sandbox/README.md
index b8d2857b07..73b72d6bdc 100644
--- a/apps/sandbox/README.md
+++ b/apps/sandbox/README.md
@@ -12,7 +12,7 @@ Before writing any code, install dependencies:
npm install
```
-This automatically generates `AGENTS.md` with the XDS component index via `xds init --features agents`. **Read `AGENTS.md` for all XDS component documentation** — it contains CLI commands to browse components, tokens, themes, and design rules.
+This automatically generates `AGENTS.md` with the XDS component index via `xds init --features agents`. **Read `AGENTS.md` for all XDS component documentation**: it contains CLI commands to browse components, tokens, themes, and design rules.
If `AGENTS.md` is missing, regenerate it:
@@ -83,18 +83,18 @@ pnpm -F @xds/core dev
pnpm -F @xds/sandbox dev
```
-Best of both worlds — edits trigger incremental dist rebuilds via Babel CLI (a few seconds), and CSS layer ordering is correct. Theming works properly.
+Edits trigger incremental dist rebuilds via Babel CLI (a few seconds), and CSS layer ordering is correct. Theming works properly.
## File manifest
| File | Purpose |
| -------------------------- | ------------------------------------------------------------------------ |
-| `package.json` | Dependencies — uses PostCSS path for StyleX |
+| `package.json` | Dependencies; uses PostCSS path for StyleX |
| `babel.config.js` | StyleX babel plugin config (as plugin, not preset) |
-| `postcss.config.js` | StyleX PostCSS plugin — extracts CSS from `@stylex;` directive |
+| `postcss.config.js` | StyleX PostCSS plugin: extracts CSS from `@stylex;` directive |
| `next.config.mjs` | Static export, basePath for GitHub Pages, webpack alias for theme tokens |
| `tsconfig.json` | TypeScript config with workspace path aliases |
-| `src/app/globals.css` | `@stylex;` injection point — PostCSS replaces this with extracted CSS |
+| `src/app/globals.css` | `@stylex;` injection point: PostCSS replaces this with extracted CSS |
| `src/app/providers.tsx` | Client-side theme provider wrapper |
| `src/app/layout.tsx` | Root layout with sidebar navigation |
| `src/app/Sidebar.tsx` | Sidebar navigation component |
diff --git a/internal/eslint-plugin-xds/README.md b/internal/eslint-plugin-xds/README.md
index fbe7951ca2..accb027d84 100644
--- a/internal/eslint-plugin-xds/README.md
+++ b/internal/eslint-plugin-xds/README.md
@@ -13,8 +13,8 @@ This plugin implements a two-tier linting strategy:
### Why Two Tiers?
-- **Agents** should follow strict rules perfectly - they have no excuse for violations
-- **Humans** need flexibility during development - warnings inform without blocking
+- **Agents** should follow strict rules perfectly; they have no excuse for violations
+- **Humans** need flexibility during development; warnings inform without blocking
## Rules
@@ -58,7 +58,7 @@ const styles = stylex.create({
Recommends adding `letterSpacing` when `fontSize` is defined (common design pattern for badges, labels).
-**Strict mode only** - helps catch missing letter-spacing in compact text elements.
+**Strict mode only.** Helps catch missing letter-spacing in compact text elements.
## Usage
@@ -142,9 +142,9 @@ If a property legitimately needs a hardcoded value:
Enforces that presentational components remain server-component compatible by preventing:
-1. **Remembering things** — `useState`, `useReducer`, `useTransition`
-2. **Watching things** — `useEffect`, `useLayoutEffect`, `useRef`, `ResizeObserver`, etc.
-3. **Coordinating children** — `createContext`
+1. **Remembering things**: `useState`, `useReducer`, `useTransition`
+2. **Watching things**: `useEffect`, `useLayoutEffect`, `useRef`, `ResizeObserver`, etc.
+3. **Coordinating children**: `createContext`
Allowed hooks: `useId`, `useMemo`, `useCallback`, `useContext` (read-only).
diff --git a/internal/vibe-tests/README.md b/internal/vibe-tests/README.md
index 15435df8fa..d3e8653eba 100644
--- a/internal/vibe-tests/README.md
+++ b/internal/vibe-tests/README.md
@@ -16,10 +16,10 @@ Prompts live in [`test-sets/default.json`](test-sets/default.json). Each prompt
}
```
-- **`prompt`** — the task given to the agent (identical across all configs)
-- **`expectedComponents`** — used for evaluation ONLY, never shown to agents
-- **`category`** — groups prompts by type (feature-with-constraint, workflow-description, clone-with-modification, state-display, data-display, responsive-challenge, io-integration, page-setup, typography, theme-customization)
-- **`complexity`** — simple, moderate, complex
+- **`prompt`**: the task given to the agent (identical across all configs)
+- **`expectedComponents`**: used for evaluation ONLY, never shown to agents
+- **`category`**: groups prompts by type (feature-with-constraint, workflow-description, clone-with-modification, state-display, data-display, responsive-challenge, io-integration, page-setup, typography, theme-customization)
+- **`complexity`**: simple, moderate, complex
## Sub-Agent Prompts
@@ -63,7 +63,7 @@ Note: no system-specific rules, no expected components, no pre-built commands. T
### 1. Fair Evaluators
- Same evaluation logic across all configurations (tsc, scoring dimensions)
-- Same pass/fail criteria — don't score one config differently than another
+- Same pass/fail criteria; don't score one config differently than another
- Target-aware scoring is OK (different systems need different counting methods) but the judgments must be equivalent
- Evaluation must be blind to which config produced the output
@@ -72,12 +72,12 @@ Note: no system-specific rules, no expected components, no pre-built commands. T
- Same prompts across all configurations (same IDs, same text)
- Same persona across all configurations
- Same output format requirements
-- Equivalent sub-agent instructions — if one config gets "read the README", all get an analogous instruction
-- No system-specific coaching rules (e.g. "use StyleX" or "use Tailwind") — let the docs teach that
+- Equivalent sub-agent instructions: if one config gets "read the README", all get an analogous instruction
+- No system-specific coaching rules (e.g. "use StyleX" or "use Tailwind"); let the docs teach that
### 3. Never Leak the Answer
-- `expectedComponents` is for evaluation ONLY — never include in the sub-agent prompt
+- `expectedComponents` is for evaluation ONLY; never include in the sub-agent prompt
- Don't pre-build retrieval commands from expected components
- Don't hint at which components to use
- Don't include rules that only make sense for one system
@@ -95,7 +95,7 @@ Note: no system-specific rules, no expected components, no pre-built commands. T
- Sub-agents must be spawned fresh with no prior conversation context
- No inherited knowledge about the design system from the parent session
- The sub-agent's only knowledge comes from what it discovers during the task
-- Don't reuse sub-agent sessions across prompts — each prompt gets a fresh agent
+- Don't reuse sub-agent sessions across prompts; each prompt gets a fresh agent
## How to Verify
@@ -120,7 +120,7 @@ For evaluation fairness, check `universal-eval.ts`:
## Known Accepted Asymmetries
-These are intentional and documented — they slightly favor baseline, making XDS wins more credible:
+These are intentional and documented; they slightly favor baseline, making XDS wins more credible:
- **Efficiency:** Tailwind's single-line `className` gets a lower styling-ratio than XDS's multi-line `stylex.create` blocks, despite encoding more decisions
- **Maintainability:** Tailwind scale values (`p-4`, `text-sm`) count as semantic, which is generous compared to how raw `16px` is counted for HTML
diff --git a/internal/vibe-tests/environments/project-xds/README.md b/internal/vibe-tests/environments/project-xds/README.md
index 32b32f33a7..c5247de65d 100644
--- a/internal/vibe-tests/environments/project-xds/README.md
+++ b/internal/vibe-tests/environments/project-xds/README.md
@@ -21,7 +21,7 @@ Components use:
## Styling with StyleX
-Custom styles must use `stylex.create()` — plain objects are not valid:
+Custom styles must use `stylex.create()`. Plain objects are not valid:
```tsx
import stylex from '@stylexjs/stylex';
@@ -40,7 +40,7 @@ const styles = stylex.create({
<div {...stylex.props(styles.container)}>...</div>
```
-**Important:** Never pass plain `{padding: '16px'}` objects to `xstyle` — always use `stylex.create()`.
+**Important:** Never pass plain `{padding: '16px'}` objects to `xstyle`. Always use `stylex.create()`.
## Import Pattern
diff --git a/internal/vibe-tests/ideals/README.md b/internal/vibe-tests/ideals/README.md
index b5908c8d94..8588a9a355 100644
--- a/internal/vibe-tests/ideals/README.md
+++ b/internal/vibe-tests/ideals/README.md
@@ -16,15 +16,15 @@ This supports multi-segment prompt IDs like `feature-card-1`.
Examples:
-- `cwm-1__desktop__light.png` — specific to desktop + light
-- `ty-3__desktop.png` — desktop only, used for both light and dark
-- `dd-3.png` — fallback for all viewport/theme combos
+- `cwm-1__desktop__light.png`: specific to desktop + light
+- `ty-3__desktop.png`: desktop only, used for both light and dark
+- `dd-3.png`: fallback for all viewport/theme combos
## Requirements
- **Format:** PNG
- **Viewport:** 1920×1200 (Figma export resolution)
-- **Source:** Figma mockup or hand-built HTML — NOT generated by any of the 3 targets (XDS, baseline, HTML)
+- **Source:** Figma mockup or hand-built HTML, NOT generated by any of the 3 targets (XDS, baseline, HTML)
- **Review:** At least one designer should review the ideal before committing
## Current Ideals
@@ -32,7 +32,7 @@ Examples:
55 prompt IDs covered (62 images total). See [issue #733](https://github.com/facebookexperimental/xds/issues/733) for context.
Multi-image prompts use `__` suffixes for different states/views:
-- `rc-1.png` + `rc-1__menu.png` — collapsed and expanded menu
-- `rc-3.png` + `rc-3__desktop.png` — mobile and desktop
-- `wd-1.png` + `wd-1__cart.png`, `wd-1__shipping.png`, `wd-1__payment.png`, `wd-1__confirm.png` — checkout flow steps
-- `wd-5.png` + `wd-5__dialog.png` — page and dialog state
+- `rc-1.png` + `rc-1__menu.png`: collapsed and expanded menu
+- `rc-3.png` + `rc-3__desktop.png`: mobile and desktop
+- `wd-1.png` + `wd-1__cart.png`, `wd-1__shipping.png`, `wd-1__payment.png`, `wd-1__confirm.png`: checkout flow steps
+- `wd-5.png` + `wd-5__dialog.png`: page and dialog state
diff --git a/packages/README.md b/packages/README.md
index 74b7f70e38..3bbc24760f 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -7,7 +7,7 @@ Published npm packages for the XDS design system.
| Directory | Package | Purpose |
|-----------|---------|---------|
| `core/` | `@xds/core` | Core UI components, theme system, and utilities |
-| `cli/` | `@xds/cli` | CLI tooling — component docs, templates, scaffolding, codemods |
+| `cli/` | `@xds/cli` | CLI tooling: component docs, templates, scaffolding, codemods |
| `build/` | `@xds/build` | Build plugins for StyleX source builds (Babel, PostCSS, Vite) |
| `vega/` | `@xds/vega` | Vega/Vega-Lite chart wrapper |
| `themes/` | `@xds/theme-*` | Visual themes (default, neutral, daily, brutalist, meta, whatsapp) |
diff --git a/packages/build/README.md b/packages/build/README.md
index aea91774a5..bc1e518b7a 100644
--- a/packages/build/README.md
+++ b/packages/build/README.md
@@ -1,6 +1,6 @@
# @xds/build
-Build plugins for XDS source builds. Provides babel, PostCSS, and Vite integrations that compile XDS library and product code with separate class name prefixes, enabling independent CSS layers:
+Build plugins for XDS source builds. Provides babel, PostCSS, and Vite integrations that compile XDS library and product code with separate class name prefixes, which enables independent CSS layers:
```
reset < xds-base (library, xds prefix) < xds-theme < product (app, x prefix)
@@ -8,7 +8,7 @@ reset < xds-base (library, xds prefix) < xds-theme < product (app, x prefix)
## Why?
-StyleX generates atomic CSS — same declaration = same class name. Without separate prefixes, library and product classes collide and can't be placed in independent CSS layers, which breaks theme overrides.
+StyleX generates atomic CSS: same declaration = same class name. Without separate prefixes, library and product classes collide and can't be placed in independent CSS layers, which breaks theme overrides.
`@xds/build` solves this by:
@@ -20,9 +20,9 @@ StyleX generates atomic CSS — same declaration = same class name. Without sepa
| Export | Purpose | Platform |
| -------------------- | --------------------------------------------- | --------------------------- |
-| `@xds/build/babel` | Babel plugin — splits class prefixes per file | Next.js, any babel pipeline |
-| `@xds/build/postcss` | PostCSS plugin — compiles + splits CSS layers | Next.js |
-| `@xds/build/vite` | Vite plugin — wraps unplugin + splits layers | Vite, Storybook |
+| `@xds/build/babel` | Babel plugin: splits class prefixes per file | Next.js, any babel pipeline |
+| `@xds/build/postcss` | PostCSS plugin: compiles + splits CSS layers | Next.js |
+| `@xds/build/vite` | Vite plugin: wraps unplugin + splits layers | Vite, Storybook |
## Install
@@ -179,7 +179,7 @@ export default defineConfig({
### Babel plugin (`@xds/build/babel`)
-Wraps `@stylexjs/babel-plugin` with two internal instances — one with `classNamePrefix: 'xds'` for library files, one with default `'x'` for product files. Routes each file to the correct instance based on its path.
+Wraps `@stylexjs/babel-plugin` with two internal instances: one with `classNamePrefix: 'xds'` for library files, one with default `'x'` for product files. Routes each file to the correct instance based on its path.
Library patterns (configurable):
@@ -243,5 +243,5 @@ Wraps `@stylexjs/unplugin` and intercepts the dev CSS endpoint (`/virtual:stylex
## Related
-- [example-nextjs-source](../../apps/example-nextjs-source/) — Full Next.js source build example
-- [`@stylexjs/babel-plugin`](https://github.com/facebook/stylex) — The underlying StyleX compiler
+- [example-nextjs-source](../../apps/example-nextjs-source/): full Next.js source build example
+- [`@stylexjs/babel-plugin`](https://github.com/facebook/stylex): the underlying StyleX compiler
diff --git a/packages/cli/docs/tokens.doc.mjs b/packages/cli/docs/tokens.doc.mjs
index 14ebc8c994..f3bb011ac8 100644
--- a/packages/cli/docs/tokens.doc.mjs
+++ b/packages/cli/docs/tokens.doc.mjs
@@ -613,7 +613,7 @@ export const docs = {
"content": [
{
"type": "prose",
- "text": "Elevation shadows (low → med → high) and inset shadows for input state rings."
+ "text": "Elevation shadows (low to med to high) and inset shadows for input state rings."
},
{
"type": "table",
diff --git a/packages/cli/docs/typography.doc.mjs b/packages/cli/docs/typography.doc.mjs
index 586a66eb22..c77998efce 100644
--- a/packages/cli/docs/typography.doc.mjs
+++ b/packages/cli/docs/typography.doc.mjs
@@ -18,11 +18,11 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Typography is built on a geometric type scale: base size × ratio^step, with 14px and 1.2 as defaults. Every text style is a semantic token that composes font size, weight, and line-height — so components express intent (heading, body, label) rather than raw values.',
+ text: 'Typography is built on a geometric type scale: base size × ratio^step, with 14px and 1.2 as defaults. Every text style is a semantic token that composes font size, weight, and line-height, so components express intent (heading, body, label) rather than raw values.',
},
{
type: 'prose',
- text: 'Two layers work together: raw size tokens (--font-size-xs … --font-size-5xl) form the geometric scale, and semantic type scale tokens (--text-heading-1-size, --text-body-leading, etc.) reference them by var(). Themes override the entire scale by adjusting base and ratio in defineTheme — all semantic tokens recompute automatically.',
+ text: 'Two layers work together: raw size tokens (--font-size-xs … --font-size-5xl) form the geometric scale, and semantic type scale tokens (--text-heading-1-size, --text-body-leading, etc.) reference them by var(). Themes override the entire scale by adjusting base and ratio in defineTheme; all semantic tokens recompute automatically.',
},
],
},
@@ -34,7 +34,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Three font roles: body (UI text), heading (titles and headings), and code (monospace). By default, body and heading share the same system font stack; code uses a monospace stack. Custom themes can assign different families per role — heading inherits from body when not explicitly set.',
+ text: 'Three font roles: body (UI text), heading (titles and headings), and code (monospace). By default, body and heading share the same system font stack; code uses a monospace stack. Custom themes can assign different families per role; heading inherits from body when not explicitly set.',
},
{
type: 'token-ref',
@@ -89,7 +89,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'The 4px grid is critical: every line box aligns to 4px increments, which keeps baselines, spacing, and component heights predictable. The expandTypeScale utility computes these automatically when you provide a base and ratio — you should never need to set line-height manually.',
+ text: 'The 4px grid matters: every line box aligns to 4px increments, which keeps baselines, spacing, and component heights predictable. The expandTypeScale utility computes these automatically when you provide a base and ratio, so you should never need to set line-height manually.',
},
],
},
@@ -118,7 +118,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Display variants (display-1, display-2, display-3) continue the geometric progression above heading-1, at steps +6, +5, and +4. They use normal weight (400) instead of semibold, and tighter line-heights (~1.2) — large text reads better with less leading. Use display types for hero banners, marketing headlines, and data callouts — not for document headings.',
+ text: 'Display variants (display-1, display-2, display-3) continue the geometric progression above heading-1, at steps +6, +5, and +4. They use normal weight (400) instead of semibold, and tighter line-heights (~1.2), since large text reads better with less leading. Use display types for hero banners, marketing headlines, and data callouts, not for document headings.',
},
{
type: 'prose',
@@ -203,23 +203,23 @@ const denseTheme = defineTheme({
type: 'list',
style: 'do',
items: [
- 'Use XDSHeading for document headings and XDSText for everything else — they apply the full type scale automatically.',
+ 'Use XDSHeading for document headings and XDSText for everything else; they apply the full type scale automatically.',
'Adjust typography holistically: change base and ratio in defineTheme to shift the entire ramp (e.g. { base: 16, ratio: 1.25 } for editorial, { base: 12, ratio: 1.125 } for dense UI).',
- 'Use display types with as="h1" (or h2/h3) when display text is a page heading — this preserves accessibility while giving you display-level sizing. Or better, use <XDSHeading level={1} type="display-1"> which handles both semantics and styling.',
- 'Let line-height snap to the 4px grid via the type scale — expandTypeScale computes leading automatically from base and ratio.',
+ 'Use display types with as="h1" (or h2/h3) when display text is a page heading; this preserves accessibility while giving you display-level sizing. Or better, use <XDSHeading level={1} type="display-1"> which handles both semantics and styling.',
+ 'Let line-height snap to the 4px grid via the type scale; expandTypeScale computes leading automatically from base and ratio.',
'Use the supporting type for secondary information: timestamps, helper text, metadata, captions.',
- 'Use accessibilityLevel on XDSHeading when the visual hierarchy doesn\u2019t match the document outline (e.g. sidebar or card headings).',
+ 'Use accessibilityLevel on XDSHeading when the visual hierarchy doesn\u0027t match the document outline (e.g. sidebar or card headings).',
],
},
{
type: 'list',
style: 'dont',
items: [
- 'Set font-size or line-height manually — use the semantic type scale tokens so the full ramp stays consistent and 4px-grid-aligned.',
- 'Skip heading levels (e.g. h1 \u2192 h3) — screen readers rely on an unbroken hierarchy. Use accessibilityLevel to decouple visual from semantic level.',
- 'Use display types for body content or in-page sections — they\u2019re designed for hero/marketing/data-callout contexts only.',
- 'Override individual size tokens (--font-size-lg) to "tweak" a heading — adjust base/ratio instead so proportions remain coherent across the entire scale.',
- 'Use raw numeric font-weight values (400, 600) — reference the semantic weight tokens so themes can remap them.',
+ 'Set font-size or line-height manually; use the semantic type scale tokens so the full ramp stays consistent and 4px-grid-aligned.',
+ 'Skip heading levels (e.g. h1 to h3); screen readers rely on an unbroken hierarchy. Use accessibilityLevel to decouple visual from semantic level.',
+ 'Use display types for body content or in-page sections; they\u0027re designed for hero/marketing/data-callout contexts only.',
+ 'Override individual size tokens (--font-size-lg) to "tweak" a heading; adjust base/ratio instead so proportions remain coherent across the entire scale.',
+ 'Use raw numeric font-weight values (400, 600); reference the semantic weight tokens so themes can remap them.',
],
},
],
diff --git a/packages/cli/docs/working-with-ai.doc.mjs b/packages/cli/docs/working-with-ai.doc.mjs
index 9c5eb1dc7d..23d8767f27 100644
--- a/packages/cli/docs/working-with-ai.doc.mjs
+++ b/packages/cli/docs/working-with-ai.doc.mjs
@@ -15,7 +15,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'The design system is built to be AI-friendly \u2014 consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props.',
+ text: 'The design system is built to be AI-friendly: consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props.',
},
{
type: 'prose',
@@ -38,7 +38,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'That\'s it. The agent-docs command generates everything your AI needs \u2014 component index, behavioral rules, CLI reference \u2014 pulled from your installed version. After a version bump, run it again to update in place.',
+ text: 'That\'s it. The agent-docs command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.',
},
{
type: 'prose',
@@ -65,14 +65,14 @@ npx xds agent-docs --agent codex # AGENTS.md (Copilot, Codex, etc.)`,
type: 'list',
style: 'ordered',
items: [
- '`npx xds template --list` \u2014 find a related page pattern to use as reference',
- '`npx xds template <name> --skeleton` \u2014 study the layout structure',
- '`npx xds component <Name>` \u2014 read props and examples for every component used',
+ '`npx xds template --list`: find a related page pattern to use as reference',
+ '`npx xds template <name> --skeleton`: study the layout structure',
+ '`npx xds component <Name>`: read props and examples for every component used',
],
},
{
type: 'prose',
- text: 'It also includes rules that prevent common mistakes (no raw divs, no style={{}}, use tokens not magic values) and a CLI quick reference. After setup, you shouldn\'t need to manually correct your AI on these conventions \u2014 the agent docs handle it at the system level.',
+ text: 'It also includes rules that prevent common mistakes (no raw divs, no style={{}}, use tokens not magic values) and a CLI quick reference. After setup, you shouldn\'t need to manually correct your AI on these conventions; the agent docs handle it at the system level.',
},
],
},
@@ -81,7 +81,7 @@ npx xds agent-docs --agent codex # AGENTS.md (Copilot, Codex, etc.)`,
content: [
{
type: 'prose',
- text: 'Cursor project rules aren\'t always picked up \u2014 it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
+ text: 'Cursor project rules aren\'t always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
},
{
type: 'code',
@@ -97,7 +97,7 @@ npx xds agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
content: [
{
type: 'prose',
- text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs \u2014 models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
+ text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
},
{
type: 'code',
@@ -165,7 +165,7 @@ npx xds docs tokens --dense`,
content: [
{
type: 'prose',
- text: 'XDS ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the XDS design system directly — searching for components, reading full documentation, and pulling code examples on demand.',
+ text: 'XDS ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the XDS design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
},
{
type: 'prose',
@@ -173,7 +173,7 @@ npx xds docs tokens --dense`,
},
{
type: 'prose',
- text: 'Add the server to your MCP config file. This works with any MCP-compatible tool — Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.',
+ text: 'Add the server to your MCP config file. This works with any MCP-compatible tool: Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.',
},
{
type: 'code',
diff --git a/packages/cli/templates/blocks/components/AspectRatio/AspectRatioShowcase.doc.mjs b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioShowcase.doc.mjs
index ee82c274e4..dc4b4235de 100644
--- a/packages/cli/templates/blocks/components/AspectRatio/AspectRatioShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/AspectRatio/AspectRatioShowcase.doc.mjs
@@ -10,6 +10,6 @@ export const doc = {
aspectRatio: 4 / 3,
isShowcase: true,
description:
- 'Three aspect ratio containers at equal height — 1:1, 4:3, and 16:9 — each showing an image with its ratio labeled below.',
+ 'Three aspect ratio containers at equal height (1:1, 4:3, and 16:9), each showing an image with its ratio labeled below.',
componentsUsed: ['AspectRatio', 'Layout', 'Text'],
};
diff --git a/packages/core/src/Blockquote/Blockquote.doc.mjs b/packages/core/src/Blockquote/Blockquote.doc.mjs
index 212ac68563..361027396a 100644
--- a/packages/core/src/Blockquote/Blockquote.doc.mjs
+++ b/packages/core/src/Blockquote/Blockquote.doc.mjs
@@ -25,7 +25,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
],
theming: {
@@ -38,7 +38,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts from external sources.' },
{ guidance: true, description: 'Provide a cite prop when the source of the quote is known.' },
- { guidance: false, description: 'Use for callout boxes or informational notes — use XDSBanner for those.' },
+ { guidance: false, description: 'Use for callout boxes or informational notes; use XDSBanner for those.' },
],
},
};
@@ -63,7 +63,7 @@ export const docsZh = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是 style={{}} 这样的内联样式对象。',
+ '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,不能是 style={{}} 这样的内联样式对象。',
},
],
theming: {
@@ -76,7 +76,7 @@ export const docsZh = {
bestPractices: [
{ guidance: true, description: '用于引用文本、推荐语或来自外部来源的高亮摘录。' },
{ guidance: true, description: '当引用来源已知时,提供 cite 属性。' },
- { guidance: false, description: '用于提示框或信息说明 — 应使用 XDSBanner。' },
+ { guidance: false, description: '用于提示框或信息说明,应使用 XDSBanner。' },
],
},
};
@@ -89,7 +89,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'Use for quoted text, testimonials, or highlighted excerpts.' },
{ guidance: true, description: 'Provide cite when source is known.' },
- { guidance: false, description: 'Use for callouts/notes — use XDSBanner instead.' },
+ { guidance: false, description: 'Use for callouts/notes; use XDSBanner instead.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index 75f5c8b878..390ebe61a0 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -13,12 +13,12 @@ export const docs = {
'Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.',
bestPractices: [
{guidance: true, description: 'Place breadcrumbs above the page heading so the user sees their location before reading the content.'},
- {guidance: true, description: 'Keep labels short and match the page titles they link to — "Settings" not "Application Settings Page".'},
+ {guidance: true, description: 'Keep labels short and match the page titles they link to: "Settings" not "Application Settings Page".'},
{guidance: true, description: 'Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.'},
- {guidance: true, description: 'Make the last item plain text, not a link — it represents the current page. The component does this automatically when you set isCurrent.'},
- {guidance: false, description: 'Use breadcrumbs as the primary navigation — they supplement a sidebar or top nav, not replace it.'},
- {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent — they add clutter without helping the user.'},
- {guidance: false, description: 'Let the trail grow beyond 5 levels — if you need more, consider simplifying the page hierarchy instead.'},
+ {guidance: true, description: 'Make the last item plain text, not a link; it represents the current page. The component does this automatically when you set isCurrent.'},
+ {guidance: false, description: 'Use breadcrumbs as the primary navigation. They supplement a sidebar or top nav, not replace it.'},
+ {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent; they add clutter without helping the user.'},
+ {guidance: false, description: 'Let the trail grow beyond 5 levels. If you need more, consider simplifying the page hierarchy instead.'},
],
anatomy: [
{name: 'Trail', required: true, description: 'The ordered list of links from root to current page.'},
@@ -59,7 +59,7 @@ export const docs = {
name: 'variant',
type: "'default' | 'supporting'",
description:
- 'Visual variant — supporting is smaller with secondary text styling.',
+ 'Visual variant; supporting is smaller with secondary text styling.',
default: "'default'",
},
{
@@ -72,7 +72,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
], },
{
@@ -133,12 +133,12 @@ export const docsZh = {
'Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.',
bestPractices: [
{guidance: true, description: 'Place breadcrumbs above the page heading so the user sees their location before reading the content.'},
- {guidance: true, description: 'Keep labels short and match the page titles they link to — "Settings" not "Application Settings Page".'},
+ {guidance: true, description: 'Keep labels short and match the page titles they link to: "Settings" not "Application Settings Page".'},
{guidance: true, description: 'Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.'},
- {guidance: true, description: 'Make the last item plain text, not a link — it represents the current page. The component does this automatically when you set isCurrent.'},
- {guidance: false, description: 'Use breadcrumbs as the primary navigation — they supplement a sidebar or top nav, not replace it.'},
- {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent — they add clutter without helping the user.'},
- {guidance: false, description: 'Let the trail grow beyond 5 levels — if you need more, consider simplifying the page hierarchy instead.'},
+ {guidance: true, description: 'Make the last item plain text, not a link; it represents the current page. The component does this automatically when you set isCurrent.'},
+ {guidance: false, description: 'Use breadcrumbs as the primary navigation. They supplement a sidebar or top nav, not replace it.'},
+ {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent; they add clutter without helping the user.'},
+ {guidance: false, description: 'Let the trail grow beyond 5 levels. If you need more, consider simplifying the page hierarchy instead.'},
],
},
theming: {
@@ -160,7 +160,7 @@ export const docsZh = {
props: [
{name: 'children', type: 'ReactNode', description: '在面包屑路径内渲染的 XDSBreadcrumbItem 元素。', required: true},
{name: 'separator', type: 'ReactNode', description: '面包屑项之间渲染的分隔符。', default: "'/'"},
- {name: 'variant', type: "'default' | 'supporting'", description: '视觉变体——supporting 更小,使用次要文本样式。', default: "'default'"},
+ {name: 'variant', type: "'default' | 'supporting'", description: '视觉变体:supporting 更小,使用次要文本样式。', default: "'default'"},
{name: 'label', type: 'string', description: 'nav 地标的无障碍标签(aria-label)。', default: "'Breadcrumb'"},
{
name: 'xstyle',
@@ -195,12 +195,12 @@ export const docsDense = {
'Breadcrumbs show a trail of links from root to current page. Use at the top of detail pages, settings, or nested content.',
bestPractices: [
{guidance: true, description: 'Place above the page heading so user sees location before reading content.'},
- {guidance: true, description: 'Keep labels short + matching page titles they link to — "Settings" not "Application Settings Page".'},
+ {guidance: true, description: 'Keep labels short + matching page titles they link to: "Settings" not "Application Settings Page".'},
{guidance: true, description: 'Use supporting variant in dense UIs where the breadcrumb should be subtle.'},
- {guidance: true, description: 'Last item plain text, not a link — represents current page; done automatically when you set isCurrent.'},
- {guidance: false, description: 'Use as primary navigation — breadcrumbs supplement, not replace, a main nav.'},
+ {guidance: true, description: 'Last item plain text, not a link; represents current page; done automatically when you set isCurrent.'},
+ {guidance: false, description: 'Use as primary navigation; breadcrumbs supplement, not replace, a main nav.'},
{guidance: false, description: 'Show on top-level pages with no parent.'},
- {guidance: false, description: 'Let the trail exceed 5 levels — simplify the hierarchy instead.'},
+ {guidance: false, description: 'Let the trail exceed 5 levels; simplify the hierarchy instead.'},
],
},
components: [
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index 19130c7ed6..2259ffda18 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -15,12 +15,12 @@ export const docs = {
'Button triggers an action when clicked. Use it for form submissions, confirmations, navigation, or any interaction that needs a clear call to action.',
bestPractices: [
{guidance: true, description: 'Reserve primary for the single most important action in the view. Use secondary or ghost for everything else based on emphasis.'},
- {guidance: true, description: 'Write labels that describe the action — "Save changes", "Delete account", "Send invite" — not vague labels like "OK" or "Click here".'},
+ {guidance: true, description: 'Write labels that describe the action ("Save changes", "Delete account", "Send invite"), not vague labels like "OK" or "Click here".'},
{guidance: true, description: 'Show a loading state for actions that take time, like saving or submitting, so the user knows it is working.'},
{guidance: true, description: 'Always provide a label for icon-only buttons so screen readers can announce what the button does. Add a tooltip for sighted users.'},
- {guidance: false, description: 'Place more than one primary button in the same view — this dilutes the visual hierarchy.'},
+ {guidance: false, description: 'Place more than one primary button in the same view; this dilutes the visual hierarchy.'},
{guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions like deleting data.'},
- {guidance: false, description: 'Use a button for navigation — if it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
+ {guidance: false, description: 'Use a button for navigation. If it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
],
anatomy: [
{name: 'Icon', required: false, description: 'A leading icon that reinforces the label, like a trash icon on a Delete button.'},
@@ -163,12 +163,12 @@ export const docsZh = {
'Button triggers an action when clicked. Use it for form submissions, confirmations, navigation, or any interaction that needs a clear call to action.',
bestPractices: [
{guidance: true, description: 'Reserve primary for the single most important action in the view. Use secondary or ghost for everything else based on emphasis.'},
- {guidance: true, description: 'Write labels that describe the action — "Save changes", "Delete account", "Send invite" — not vague labels like "OK" or "Click here".'},
+ {guidance: true, description: 'Write labels that describe the action ("Save changes", "Delete account", "Send invite"), not vague labels like "OK" or "Click here".'},
{guidance: true, description: 'Show a loading state for actions that take time, like saving or submitting, so the user knows it is working.'},
{guidance: true, description: 'Always provide a label for icon-only buttons so screen readers can announce what the button does. Add a tooltip for sighted users.'},
- {guidance: false, description: 'Place more than one primary button in the same view — this dilutes the visual hierarchy.'},
+ {guidance: false, description: 'Place more than one primary button in the same view; this dilutes the visual hierarchy.'},
{guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions like deleting data.'},
- {guidance: false, description: 'Use a button for navigation — if it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
+ {guidance: false, description: 'Use a button for navigation. If it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
],
anatomy: [
{name: 'Icon', required: false, description: 'A leading icon that reinforces the label, like a trash icon on a Delete button.'},
@@ -244,12 +244,12 @@ export const docsDense = {
'Button triggers an action when clicked. Use for form submissions, confirmations, navigation, or any interaction needing a clear CTA.',
bestPractices: [
{guidance: true, description: 'Primary for the single most important action. Secondary or ghost for the rest.'},
- {guidance: true, description: 'Labels that describe the action — "Save changes" not "OK" or "Click here".'},
+ {guidance: true, description: 'Labels that describe the action: "Save changes" not "OK" or "Click here".'},
{guidance: true, description: 'Show loading state for async actions so the user knows it is working.'},
{guidance: true, description: 'Icon-only buttons need a label for screen readers and a tooltip for sighted users.'},
- {guidance: false, description: 'Multiple primary buttons in one view — dilutes hierarchy.'},
+ {guidance: false, description: 'Multiple primary buttons in one view; dilutes hierarchy.'},
{guidance: false, description: 'Destructive without confirmation for irreversible actions.'},
- {guidance: false, description: 'Button for navigation — use a link if it only takes the user to another page.'},
+ {guidance: false, description: 'Button for navigation; use a link if it only takes the user to another page.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
index b33a1f35bd..18e7455526 100644
--- a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
+++ b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
@@ -22,7 +22,7 @@ export const docs = {
{
name: 'XDSButtonGroup',
displayName: 'Button Group',
- description: 'Groups multiple buttons together with connected styling — shared borders, proper border-radius handling (only on outer edges), and horizontal or vertical orientation.',
+ description: 'Groups multiple buttons together with connected styling: shared borders, proper border-radius handling (only on outer edges), and horizontal or vertical orientation.',
props: [
{name: 'children', type: 'ReactNode', description: 'XDSButton or XDSIconButton children.', required: true, slotElements: [{__element: 'XDSButton', props: {label: 'Action'}}]},
{name: 'label', type: 'string', description: 'Accessible label for the group (aria-label).', required: true},
@@ -37,13 +37,13 @@ export const docs = {
],
usage: {
description:
- 'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually — like copy/cut/paste, or undo/redo.',
+ 'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually, like copy/cut/paste, or undo/redo.',
bestPractices: [
- {guidance: true, description: 'Group buttons that perform related actions on the same object — like copy, cut, paste on selected text.'},
+ {guidance: true, description: 'Group buttons that perform related actions on the same object, like copy, cut, paste on selected text.'},
{guidance: true, description: 'Use the same variant for all buttons in a group so they look like a single connected unit.'},
{guidance: true, description: 'Keep groups small (2–4 buttons). For more actions, use a Toolbar or DropdownMenu instead.'},
- {guidance: false, description: "Don't mix wildly different actions — a Save button next to a Delete button in the same group is confusing."},
- {guidance: false, description: "Don't use ButtonGroup for navigation — use SegmentedControl or TabList for switching between views."},
+ {guidance: false, description: "Don't mix wildly different actions. A Save button next to a Delete button in the same group is confusing."},
+ {guidance: false, description: "Don't use ButtonGroup for navigation. Use SegmentedControl or TabList for switching between views."},
{guidance: false, description: "Don't nest ButtonGroups. If you need multiple groups, place them side by side with a gap."},
],
anatomy: [
@@ -59,7 +59,7 @@ export const docsZh = {
{
name: 'XDSButtonGroup',
displayName: 'Button Group',
- description: '将多个按钮组合在一起,带有连接样式 — 共享边框、正确的圆角处理(仅外边缘),以及水平或垂直方向。',
+ description: '将多个按钮组合在一起,带有连接样式:共享边框、正确的圆角处理(仅外边缘),以及水平或垂直方向。',
propDescriptions: {
children: 'XDSButton 或 XDSIconButton 子元素。',
label: '按钮组的无障碍标签 (aria-label)。',
@@ -74,13 +74,13 @@ export const docsZh = {
],
usage: {
description:
- 'ButtonGroup 将相关操作连接成一个控件。当多个按钮表示对同一对象的相关操作时使用 — 如复制/剪切/粘贴,或撤销/重做。',
+ 'ButtonGroup 将相关操作连接成一个控件。当多个按钮表示对同一对象的相关操作时使用,如复制/剪切/粘贴,或撤销/重做。',
bestPractices: [
- {guidance: true, description: '将对同一对象执行相关操作的按钮分组 — 如对选中文本的复制、剪切、粘贴。'},
+ {guidance: true, description: '将对同一对象执行相关操作的按钮分组,如对选中文本的复制、剪切、粘贴。'},
{guidance: true, description: '组内所有按钮使用相同的变体,使其看起来像一个连接的整体。'},
{guidance: true, description: '保持组较小(2-4 个按钮)。更多操作请使用工具栏或下拉菜单。'},
- {guidance: false, description: '不要混合差异很大的操作 — 将保存按钮和删除按钮放在同一组中会令人困惑。'},
- {guidance: false, description: '不要使用 ButtonGroup 进行导航 — 使用 SegmentedControl 或 TabList 切换视图。'},
+ {guidance: false, description: '不要混合差异很大的操作,将保存按钮和删除按钮放在同一组中会令人困惑。'},
+ {guidance: false, description: '不要使用 ButtonGroup 进行导航,使用 SegmentedControl 或 TabList 切换视图。'},
{guidance: false, description: '不要嵌套 ButtonGroup。如需多个组,请并排放置并留有间隔。'},
],
anatomy: [
@@ -97,11 +97,11 @@ export const docsDense = {
description:
'ButtonGroup joins related actions into a single connected control. Use for related operations on the same object.',
bestPractices: [
- {guidance: true, description: 'Group related actions on the same object — copy/cut/paste, undo/redo.'},
+ {guidance: true, description: 'Group related actions on the same object: copy/cut/paste, undo/redo.'},
{guidance: true, description: 'Same variant for all buttons to look like one unit.'},
{guidance: true, description: 'Keep groups small (2–4 buttons). Use Toolbar or DropdownMenu for more.'},
{guidance: false, description: "Don't mix unrelated actions in one group."},
- {guidance: false, description: "Don't use for navigation — use SegmentedControl or TabList."},
+ {guidance: false, description: "Don't use for navigation. Use SegmentedControl or TabList."},
{guidance: false, description: "Don't nest ButtonGroups."},
],
},
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 412ec8dfaf..7fc5815c91 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -11,12 +11,12 @@ export const docs = {
description:
'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
bestPractices: [
- {guidance: true, description: 'Set min and max dates to limit selection to a valid window — like only future dates for a booking or the current quarter for a report.'},
+ {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
{guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
{guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
{guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
- {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date — a text input is faster for open-ended entry.'},
- {guidance: false, description: 'Disable large blocks of dates without context — the user should understand why dates are unavailable.'},
+ {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
+ {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
],
anatomy: [
{name: 'Month header', required: true, description: 'The month name and year with navigation arrows to move between months.'},
@@ -124,12 +124,12 @@ export const docsZh = {
description:
'Calendar lets the user pick a date or date range from a month grid. Use it in booking flows, scheduling UIs, date filters, or anywhere the user needs to see surrounding dates for context.',
bestPractices: [
- {guidance: true, description: 'Set min and max dates to limit selection to a valid window — like only future dates for a booking or the current quarter for a report.'},
+ {guidance: true, description: 'Set min and max dates to limit selection to a valid window, like only future dates for a booking or the current quarter for a report.'},
{guidance: true, description: 'Use range mode when the user needs to pick a start and end date, like a trip or a time-off request.'},
{guidance: true, description: 'Use dateConstraints to disable specific dates like weekends or holidays, and explain why they are unavailable.'},
{guidance: true, description: 'Show two months side by side when the user frequently selects dates that span a month boundary.'},
- {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date — a text input is faster for open-ended entry.'},
- {guidance: false, description: 'Disable large blocks of dates without context — the user should understand why dates are unavailable.'},
+ {guidance: false, description: 'Use a calendar for dates far in the past or future like a birth date. A text input is faster for open-ended entry.'},
+ {guidance: false, description: 'Disable large blocks of dates without context. The user should understand why dates are unavailable.'},
],
},
props: [
@@ -177,11 +177,11 @@ export const docsDense = {
description:
'Calendar lets the user pick a date or date range from a month grid. Use in booking, scheduling, date filters.',
bestPractices: [
- {guidance: true, description: 'Set min/max to limit selection to a valid window — only future dates for booking, current quarter for a report.'},
- {guidance: true, description: 'Use range mode when user picks start + end dates — trip, time-off request.'},
+ {guidance: true, description: 'Set min/max to limit selection to a valid window: only future dates for booking, current quarter for a report.'},
+ {guidance: true, description: 'Use range mode when user picks start + end dates: trip, time-off request.'},
{guidance: true, description: 'Use dateConstraints to disable specific dates (weekends/holidays); explain why unavailable.'},
{guidance: true, description: 'Show two months side by side when user frequently selects dates spanning a month boundary.'},
- {guidance: false, description: 'Use for dates far in the past/future — text input is faster.'},
+ {guidance: false, description: 'Use for dates far in the past/future; text input is faster.'},
{guidance: false, description: 'Disable dates without explaining why.'},
],
},
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 7eddb73dab..c7df2e47d9 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -10,18 +10,18 @@ export const docs = {
keywords: ["card","surface","panel","container","elevated","shadow","box","paper","tile","well"],
usage: {
description:
- 'Card is a bordered, elevated container for discrete, self-contained items — things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don\'t need a container at all — spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.',
+ 'Card is a bordered, elevated container for discrete, self-contained items: things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don\'t need a container at all; spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.',
bestPractices: [
- {guidance: true, description: 'Ask "could I reorder or remove this independently?" If yes, it\'s a card. If no, it\'s just a section of the page — use a heading + XDSStack or XDSSection.'},
+ {guidance: true, description: 'Ask "could I reorder or remove this independently?" If yes, it\'s a card. If no, it\'s just a section of the page: use a heading + XDSStack or XDSSection.'},
{guidance: true, description: 'Use cards for discrete items: a single user profile, a single notification, a single metric, a product in a grid. Each card represents one "thing" with clear interaction boundaries.'},
- {guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container — try removing the card and see if the grouping is still clear from whitespace and typography.'},
+ {guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container; try removing the card and see if the grouping is still clear from whitespace and typography.'},
{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},
{guidance: true, description: 'Pair a card with XDSLayout when you need a structured header, scrollable content, and footer with actions.'},
{guidance: false, description: 'Default to cards for visual grouping. A heading + XDSStack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},
- {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups — these are page regions, use XDSSection or heading + stack.'},
+ {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use XDSSection or heading + stack.'},
{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},
- {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use spacing and dividers instead.'},
- {guidance: false, description: 'Use color variants for status — use Banner or Badge for that. Color cards are for categorization.'},
+ {guidance: false, description: 'Nest cards inside other cards; flatten the hierarchy or use spacing and dividers instead.'},
+ {guidance: false, description: 'Use color variants for status; use Banner or Badge for that. Color cards are for categorization.'},
],
anatomy: [
{name: 'Container', required: true, description: 'The outer box with border, background, border-radius, and padding.'},
@@ -102,18 +102,18 @@ export const docsZh = {
displayName: 'Card',
usage: {
description:
- 'Card is a bordered, elevated container for discrete, self-contained items — things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don\'t need a container at all — spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.',
+ 'Card is a bordered, elevated container for discrete, self-contained items: things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don\'t need a container at all; spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.',
bestPractices: [
- {guidance: true, description: 'Ask "could I reorder or remove this independently?" If yes, it\'s a card. If no, it\'s just a section of the page — use a heading + XDSStack or XDSSection.'},
+ {guidance: true, description: 'Ask "could I reorder or remove this independently?" If yes, it\'s a card. If no, it\'s just a section of the page: use a heading + XDSStack or XDSSection.'},
{guidance: true, description: 'Use cards for discrete items: a single user profile, a single notification, a single metric, a product in a grid. Each card represents one "thing" with clear interaction boundaries.'},
- {guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container — try removing the card and see if the grouping is still clear from whitespace and typography.'},
+ {guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container; try removing the card and see if the grouping is still clear from whitespace and typography.'},
{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},
{guidance: true, description: 'Pair a card with XDSLayout when you need a structured header, scrollable content, and footer with actions.'},
{guidance: false, description: 'Default to cards for visual grouping. A heading + XDSStack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},
- {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups — these are page regions, use XDSSection or heading + stack.'},
+ {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups: these are page regions, use XDSSection or heading + stack.'},
{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},
- {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use spacing and dividers instead.'},
- {guidance: false, description: 'Use color variants for status — use Banner or Badge for that. Color cards are for categorization.'},
+ {guidance: false, description: 'Nest cards inside other cards; flatten the hierarchy or use spacing and dividers instead.'},
+ {guidance: false, description: 'Use color variants for status; use Banner or Badge for that. Color cards are for categorization.'},
],
anatomy: [
{name: 'Container', required: true, description: 'The outer box with border, background, border-radius, and padding.'},
@@ -145,21 +145,21 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'bordered container for DISCRETE items — NOT the default layout tool. Most content doesn\'t need a card.',
+ description: 'bordered container for DISCRETE items; NOT the default layout tool. Most content doesn\'t need a card.',
usage: {
description:
- 'Card is for discrete items with clear interaction boundaries (one profile, one notification, one product). Cards are NOT the default. Spacing and alignment create visual grouping without borders. Ask: "could I reorder or remove this independently?" — if no, don\'t use a card.',
+ 'Card is for discrete items with clear interaction boundaries (one profile, one notification, one product). Cards are NOT the default. Spacing and alignment create visual grouping without borders. Ask: "could I reorder or remove this independently?" If no, don\'t use a card.',
bestPractices: [
- {guidance: true, description: 'Ask "could I reorder/remove this independently?" If yes, it\'s a card. If no, it\'s just a page section — use heading + XDSStack or XDSSection.'},
+ {guidance: true, description: 'Ask "could I reorder/remove this independently?" If yes, it\'s a card. If no, it\'s just a page section: use heading + XDSStack or XDSSection.'},
{guidance: true, description: 'Use cards for discrete items: one profile, one notification, one metric, one product in a grid. Each card = one "thing" w/ clear interaction boundaries.'},
- {guidance: true, description: 'Spacing + alignment alone create visual grouping. Not everything needs a container — try removing the card; if grouping still reads from whitespace + typography, skip it.'},
+ {guidance: true, description: 'Spacing + alignment alone create visual grouping. Not everything needs a container; try removing the card; if grouping still reads from whitespace + typography, skip it.'},
{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},
{guidance: true, description: 'Pair a card w/ XDSLayout when you need a structured header, scrollable content, and footer with actions.'},
{guidance: false, description: 'Default to cards for grouping. Heading + XDSStack w/ proper spacing creates hierarchy w/o borders everywhere. Cards are the exception, not the default.'},
- {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups are page regions — use XDSSection or heading + stack.'},
+ {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups are page regions; use XDSSection or heading + stack.'},
{guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},
- {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use spacing + dividers instead.'},
- {guidance: false, description: 'Use color variants for status — use Banner or Badge for that instead. Color cards are for categorization.'},
+ {guidance: false, description: 'Nest cards inside other cards; flatten the hierarchy or use spacing + dividers instead.'},
+ {guidance: false, description: 'Use color variants for status; use Banner or Badge for that instead. Color cards are for categorization.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjs
index 7c549e86cb..adba91cc3f 100644
--- a/packages/core/src/Carousel/Carousel.doc.mjs
+++ b/packages/core/src/Carousel/Carousel.doc.mjs
@@ -14,9 +14,9 @@ export const docs = {
{guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
{guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
{guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
- {guidance: false, description: 'Use a carousel for content every user must see — not everyone scrolls horizontally. Put critical content above the fold.'},
- {guidance: false, description: 'Auto-advance items — let the user scroll at their own pace.'},
- {guidance: false, description: 'Nest carousels — a carousel inside a carousel is confusing and breaks keyboard navigation.'},
+ {guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
+ {guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
+ {guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},
],
anatomy: [
{name: 'Scroll container', required: true, description: 'The horizontal overflow area that holds all items.'},
@@ -62,9 +62,9 @@ export const docsZh = {
{guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
{guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
{guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
- {guidance: false, description: 'Use a carousel for content every user must see — not everyone scrolls horizontally. Put critical content above the fold.'},
- {guidance: false, description: 'Auto-advance items — let the user scroll at their own pace.'},
- {guidance: false, description: 'Nest carousels — a carousel inside a carousel is confusing and breaks keyboard navigation.'},
+ {guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
+ {guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
+ {guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},
],
},
propDescriptions: {
@@ -83,12 +83,12 @@ export const docsDense = {
description:
'Carousel scrolls items horizontally when they overflow. Use for card grids, galleries, product lists.',
bestPractices: [
- {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge — gallery, product list.'},
- {guidance: true, description: 'Always provide an aria-label describing what the carousel contains — "Featured products", "Team members".'},
+ {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge: gallery, product list.'},
+ {guidance: true, description: 'Always provide an aria-label describing what the carousel contains: "Featured products", "Team members".'},
{guidance: true, description: 'Use consistent gap + item width so the carousel looks intentional, not like content overflowing by accident.'},
- {guidance: false, description: 'Use a carousel for content every user must see — not everyone scrolls horizontally. Put critical content above the fold.'},
- {guidance: false, description: 'Auto-advance items — let the user scroll at their own pace.'},
- {guidance: false, description: 'Nest carousels — a carousel inside a carousel is confusing and breaks keyboard navigation.'},
+ {guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
+ {guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
+ {guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjs
index e6d1a7e9b9..aca6897d78 100644
--- a/packages/core/src/Center/Center.doc.mjs
+++ b/packages/core/src/Center/Center.doc.mjs
@@ -41,7 +41,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
],
theming: {
@@ -53,11 +53,11 @@ export const docs = {
description:
'Center aligns content to the middle of its container. Use it for empty states, loading screens, login forms, or any content that should sit in the center of the available space.',
bestPractices: [
- {guidance: true, description: 'Use axis="horizontal" or axis="vertical" when you only need one direction — both axes is the default but not always needed.'},
- {guidance: true, description: 'Set a height when centering vertically — Center needs a defined height to know what space to center within.'},
+ {guidance: true, description: 'Use axis="horizontal" or axis="vertical" when you only need one direction. Both axes is the default but not always needed.'},
+ {guidance: true, description: 'Set a height when centering vertically. Center needs a defined height to know what space to center within.'},
{guidance: true, description: 'Use isInline to center small elements like icons or badges within a line of text without breaking the text flow.'},
- {guidance: false, description: 'Wrap large page sections in Center — use XDSLayout or XDSAppShell for page-level structure.'},
- {guidance: false, description: 'Use Center for horizontal lists of items — use XDSStack with hAlign="center" instead.'},
+ {guidance: false, description: 'Wrap large page sections in Center. Use XDSLayout or XDSAppShell for page-level structure.'},
+ {guidance: false, description: 'Use Center for horizontal lists of items. Use XDSStack with hAlign="center" instead.'},
],
anatomy: [
{name: 'Container', required: true, description: 'A flexbox wrapper that aligns its children to the center along the chosen axis.'},
@@ -74,11 +74,11 @@ export const docsZh = {
description:
'Center aligns content to the middle of its container. Use it for empty states, loading screens, login forms, or any content that should sit in the center of the available space.',
bestPractices: [
- {guidance: true, description: 'Use axis="horizontal" or axis="vertical" when you only need one direction — both axes is the default but not always needed.'},
- {guidance: true, description: 'Set a height when centering vertically — Center needs a defined height to know what space to center within.'},
+ {guidance: true, description: 'Use axis="horizontal" or axis="vertical" when you only need one direction. Both axes is the default but not always needed.'},
+ {guidance: true, description: 'Set a height when centering vertically. Center needs a defined height to know what space to center within.'},
{guidance: true, description: 'Use isInline to center small elements like icons or badges within a line of text without breaking the text flow.'},
- {guidance: false, description: 'Wrap large page sections in Center — use XDSLayout or XDSAppShell for page-level structure.'},
- {guidance: false, description: 'Use Center for horizontal lists of items — use XDSStack with hAlign="center" instead.'},
+ {guidance: false, description: 'Wrap large page sections in Center. Use XDSLayout or XDSAppShell for page-level structure.'},
+ {guidance: false, description: 'Use Center for horizontal lists of items. Use XDSStack with hAlign="center" instead.'},
],
},
props: [
@@ -91,7 +91,7 @@ export const docsZh = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值——不能是 style={{}} 这样的内联样式对象。',
+ '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,不能是 style={{}} 这样的内联样式对象。',
},
],
theming: {
@@ -113,11 +113,11 @@ export const docsDense = {
description:
'Center aligns content to the middle of its container. Use for empty states, loading screens, login forms.',
bestPractices: [
- {guidance: true, description: 'Use axis="horizontal" or axis="vertical" when you only need one direction — both axes is the default but not always needed.'},
- {guidance: true, description: 'Set a height when centering vertically — Center needs a defined height to know what space to center within.'},
+ {guidance: true, description: 'Use axis="horizontal" or axis="vertical" when you only need one direction. Both axes is the default but not always needed.'},
+ {guidance: true, description: 'Set a height when centering vertically. Center needs a defined height to know what space to center within.'},
{guidance: true, description: 'Use isInline to center small elements (icons, badges) within a line of text without breaking text flow.'},
- {guidance: false, description: 'Wrap large page sections in Center — use XDSLayout or XDSAppShell for page-level structure.'},
- {guidance: false, description: 'Use Center for horizontal lists of items — use XDSStack with hAlign="center" instead.'},
+ {guidance: false, description: 'Wrap large page sections in Center. Use XDSLayout or XDSAppShell for page-level structure.'},
+ {guidance: false, description: 'Use Center for horizontal lists of items. Use XDSStack with hAlign="center" instead.'},
],
},
propDescriptions: {
diff --git a/packages/core/src/Chat/ChatDictationButton.doc.mjs b/packages/core/src/Chat/ChatDictationButton.doc.mjs
index 214716c3dc..8c6d536bc3 100644
--- a/packages/core/src/Chat/ChatDictationButton.doc.mjs
+++ b/packages/core/src/Chat/ChatDictationButton.doc.mjs
@@ -18,9 +18,9 @@ export const docs = {
bestPractices: [
{guidance: true, description: 'Place the dictation button in the sendActions slot of XDSChatComposer so it sits next to the send button where users expect voice input controls.'},
{guidance: true, description: 'Pass an inputRef to useXDSChatDictation so interim transcripts appear as ghost text in the composer input while the user speaks.'},
- {guidance: true, description: "Enable hasSounds on useXDSChatDictation to give users audio feedback when dictation starts and stops \u2014 especially helpful when the button's visual change is subtle."},
- {guidance: false, description: "Don't use the dictation button outside a chat composer context \u2014 it's designed for the composer's send-action layout, not as a standalone recording control."},
- {guidance: false, description: "Don't forget to handle the unsupported case \u2014 the button hides itself by default when the browser lacks SpeechRecognition, but you should still design the composer to work without it."},
+ {guidance: true, description: "Enable hasSounds on useXDSChatDictation to give users audio feedback when dictation starts and stops. This is especially helpful when the button's visual change is subtle."},
+ {guidance: false, description: "Don't use the dictation button outside a chat composer context. It's designed for the composer's send-action layout, not as a standalone recording control."},
+ {guidance: false, description: "Don't forget to handle the unsupported case. The button hides itself by default when the browser lacks SpeechRecognition, but you should still design the composer to work without it."},
],
anatomy: [
{name: 'Microphone icon', required: true, description: 'Shown in the idle state. Indicates that tapping will start voice input.'},
@@ -59,7 +59,7 @@ export const docs = {
{
name: 'xstyle',
type: 'StyleXStyles',
- description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
},
],
@@ -73,9 +73,9 @@ export const docsZh = {
bestPractices: [
{guidance: true, description: 'Place the dictation button in the sendActions slot of XDSChatComposer so it sits next to the send button where users expect voice input controls.'},
{guidance: true, description: 'Pass an inputRef to useXDSChatDictation so interim transcripts appear as ghost text in the composer input while the user speaks.'},
- {guidance: true, description: "Enable hasSounds on useXDSChatDictation to give users audio feedback when dictation starts and stops \u2014 especially helpful when the button's visual change is subtle."},
- {guidance: false, description: "Don't use the dictation button outside a chat composer context \u2014 it's designed for the composer's send-action layout, not as a standalone recording control."},
- {guidance: false, description: "Don't forget to handle the unsupported case \u2014 the button hides itself by default when the browser lacks SpeechRecognition, but you should still design the composer to work without it."},
+ {guidance: true, description: "Enable hasSounds on useXDSChatDictation to give users audio feedback when dictation starts and stops. This is especially helpful when the button's visual change is subtle."},
+ {guidance: false, description: "Don't use the dictation button outside a chat composer context. It's designed for the composer's send-action layout, not as a standalone recording control."},
+ {guidance: false, description: "Don't forget to handle the unsupported case. The button hides itself by default when the browser lacks SpeechRecognition, but you should still design the composer to work without it."},
],
},
propDescriptions: {
@@ -97,8 +97,8 @@ export const docsDense = {
{guidance: true, description: 'Place in sendActions slot of XDSChatComposer next to send button.'},
{guidance: true, description: 'Pass inputRef to useXDSChatDictation for interim ghost text in input.'},
{guidance: true, description: 'Enable hasSounds for audio feedback on start/stop.'},
- {guidance: false, description: "Don't use outside chat composer context \u2014 designed for composer send-action layout only."},
- {guidance: false, description: "Don't forget unsupported case \u2014 button auto-hides but composer should work without it."},
+ {guidance: false, description: "Don't use outside chat composer context. Designed for composer send-action layout only."},
+ {guidance: false, description: "Don't forget unsupported case. Button auto-hides but composer should work without it."},
],
},
propDescriptions: {
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 63a5fecb2d..7abb78a893 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -115,11 +115,11 @@ export const docs = {
{ guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },
{ guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },
{ guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },
- { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
],
anatomy: [
- { name: 'Checkbox', required: true, description: 'The check box itself — unchecked, checked, or indeterminate.' },
+ { name: 'Checkbox', required: true, description: 'The check box itself: unchecked, checked, or indeterminate.' },
{ name: 'Label', required: true, description: 'Text describing what the checkbox controls. Always present for accessibility.' },
{ name: 'Description', required: false, description: 'Helper text below the label with additional context.' },
{ name: 'Status message', required: false, description: 'An error, warning, or success message below the checkbox.' },
@@ -137,8 +137,8 @@ export const docsZh = {
{ guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },
{ guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },
{ guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },
- { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
],
},
props: [
@@ -188,10 +188,10 @@ export const docsDense = {
description: 'CheckboxInput toggles a single on/off value. Use for settings, terms acceptance, opt-in choices. Use CheckboxList for groups.',
bestPractices: [
{ guidance: true, description: 'Always provide a visible label so user knows what they\'re toggling. Use isLabelHidden only when surrounding context makes it obvious.' },
- { guidance: true, description: 'Add a description for choices that need extra context — e.g. what "Share usage data" actually shares.' },
+ { guidance: true, description: 'Add a description for choices that need extra context, e.g. what "Share usage data" actually shares.' },
{ guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },
- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },
- { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },
+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },
+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },
],
},
propDescriptions: {
diff --git a/packages/core/src/Citation/Citation.doc.mjs b/packages/core/src/Citation/Citation.doc.mjs
index c212eec0a1..8750591cf8 100644
--- a/packages/core/src/Citation/Citation.doc.mjs
+++ b/packages/core/src/Citation/Citation.doc.mjs
@@ -33,7 +33,7 @@ export const docs = {
name: 'Container',
required: true,
description:
- 'The interactive wrapper — renders as an anchor when a URL is provided, or a span otherwise.',
+ 'The interactive wrapper. Renders as an anchor when a URL is provided, or a span otherwise.',
},
{
name: 'Icon',
@@ -74,7 +74,7 @@ export const docs = {
name: 'variant',
type: "'label' | 'number'",
description:
- 'Display style — a label chip showing the source title or a compact numbered badge.',
+ 'Display style: a label chip showing the source title or a compact numbered badge.',
default: "'label'",
},
],
diff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjs
index 8805bca711..53424c4ced 100644
--- a/packages/core/src/CodeBlock/CodeBlock.doc.mjs
+++ b/packages/core/src/CodeBlock/CodeBlock.doc.mjs
@@ -67,10 +67,10 @@ export const docs = {
description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use XDSCodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use XDSCode for inline references to function names, variables, or CLI flags within body text.',
bestPractices: [
{guidance: true, description: 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.'},
- {guidance: true, description: 'Add a title when the code represents a file — it gives readers context and appears in the header bar alongside the copy button.'},
+ {guidance: true, description: 'Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button.'},
{guidance: true, description: 'Use XDSCode for short inline references like function names or CLI flags, and XDSCodeBlock for standalone multi-line snippets.'},
{guidance: false, description: 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.'},
- {guidance: false, description: 'Nest a code block inside a scrollable container — use the maxHeight prop instead, which handles overflow natively.'},
+ {guidance: false, description: 'Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.'},
],
anatomy: [
{name: 'Header Bar', required: false, description: 'Shows the title, language label, and copy button. Appears when any of these props are set.'},
@@ -87,7 +87,7 @@ export const docsZh = {
usage: {
description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use XDSCodeBlock for fenced multi-line code and XDSCode for inline code within prose.',
bestPractices: [
- { guidance: true, description: 'Set the language prop to enable syntax highlighting — use "plaintext" when the language is unknown or not supported.' },
+ { guidance: true, description: 'Set the language prop to enable syntax highlighting. Use "plaintext" when the language is unknown or not supported.' },
{ guidance: true, description: 'Use XDSCode for short inline code references within body text, and XDSCodeBlock for standalone multi-line snippets.' },
{ guidance: false, description: 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.' },
{ guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },
@@ -111,7 +111,7 @@ export const docsZh = {
maxHeight: '代码块垂直滚动前的最大高度。',
size: '文字大小变体。',
width: "代码块宽度。接受任何CSS宽度值。'fit-content'(默认)适应最长行宽度;'100%' 填满父容器宽度。",
- container: "容器展示样式。'card'(默认)=带边框和圆角及柔和背景;'section'=无边框圆角且背景透明——融入所嵌入的卡片或面板。",
+ container: "容器展示样式。'card'(默认)=带边框和圆角及柔和背景;'section'=无边框圆角且背景透明,融入所嵌入的卡片或面板。",
tokenizer: '用于不支持语言的自定义分词器。',
isCollapsible: '允许将代码折叠为仅标题栏。当代码超过 collapsibleThreshold 行时显示切换按钮。',
collapsibleThreshold: '折叠切换出现前的最小行数。低于此阈值时即使 isCollapsible 为 true 也正常渲染。',
@@ -143,10 +143,10 @@ export const docsDense = {
description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use XDSCodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use XDSCode for inline references to function names, variables, or CLI flags within body text.',
bestPractices: [
{guidance: true, description: 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.'},
- {guidance: true, description: 'Add a title when the code represents a file — it gives readers context and appears in the header bar alongside the copy button.'},
+ {guidance: true, description: 'Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button.'},
{guidance: true, description: 'Use XDSCode for short inline references like function names or CLI flags, and XDSCodeBlock for standalone multi-line snippets.'},
{guidance: false, description: 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.'},
- {guidance: false, description: 'Nest a code block inside a scrollable container — use the maxHeight prop instead, which handles overflow natively.'},
+ {guidance: false, description: 'Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.'},
],
},
components: [
diff --git a/scripts/generate-token-docs.mjs b/scripts/generate-token-docs.mjs
index 86b5334a3e..9278e0e22e 100644
--- a/scripts/generate-token-docs.mjs
+++ b/scripts/generate-token-docs.mjs
@@ -122,7 +122,7 @@ const groups = [
exportName: 'shadowDefaults',
title: 'Shadow Tokens',
description:
- 'Elevation shadows (low → med → high) and inset shadows for input state rings.',
+ 'Elevation shadows (low to med to high) and inset shadows for input state rings.',
headers: ['Token', 'Value'],
formatRow: (name, value) => [name, value],
},