Skip to content

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

TypeScript

Replace markdown READMEs with typed .doc.mjs files (no tsx runtime) (#454)

Joey8527b3368c81
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
index 5ba7fbdc45..49d6737d9b 100644
--- a/.claude/commands/create-component.md
+++ b/.claude/commands/create-component.md
@@ -22,7 +22,7 @@ Use this structure based on Button.tsx:
* @position Core implementation
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/{ComponentName}/README.md
+ * - /packages/core/src/{ComponentName}/{ComponentName}.doc.mjs
* - /packages/core/src/{ComponentName}/{ComponentName}.test.tsx
* - /packages/core/src/{ComponentName}/index.ts
* - /apps/storybook/stories/{ComponentName}.stories.tsx
@@ -111,46 +111,40 @@ export { {ComponentName} } from './{ComponentName}';
export type { {ComponentName}Props, {ComponentName}Variant } from './{ComponentName}';
```
-### 3. README.md
-
-```markdown
-# /packages/core/src/{ComponentName}
-
-Brief description of the component.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Variants**: List variants
-- Other features
-
-## Usage
-
-\`\`\`tsx
-import { {ComponentName} } from '@xds/core/{ComponentName}';
-
-<{ComponentName} variant="default">Content</{ComponentName}>
-\`\`\`
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'{variant1}' \| '{variant2}'` | `'default'` | Visual style variant |
-| `children` | `ReactNode` | — | Component content |
-
-## Files
-
-| File | Role | Purpose |
-|------|------|---------|
-| `index.ts` | Entry | Exports component and types |
-| `{ComponentName}.tsx` | Core | Component implementation |
-| `{ComponentName}.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Variant type derived from `keyof typeof variants`
+### 3. {ComponentName}.doc.mjs
+
+```js
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: '{ComponentName}',
+ description: 'Brief description of the component.',
+ features: ['Variants: list available variants'],
+ props: [
+ {
+ name: 'variant',
+ type: "'{variant1}' | '{variant2}'",
+ description: 'Visual style variant',
+ default: "'default'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Component content',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<{ComponentName} variant="default">Content</{ComponentName}>`,
+ },
+ ],
+ theming: {
+ componentKey: '{componentName}',
+ surfaces: [{name: 'root', description: 'Outer wrapper element'}],
+ },
+};
```
### 4. Update /packages/core/src/index.ts
@@ -172,6 +166,7 @@ export * from './{ComponentName}';
## Token Reference
Available tokens from `tokens.stylex`:
+
- `colorTokens`: accent, surface, textPrimary, hoverOverlay, pressedOverlay, focusOutline, negative, etc.
- `spacingTokens`: space0, space0_5, space1, space2, space3, space4, space5, space6, space7
- `radiusTokens`: rounded, container, element, content
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 62a6b40ed0..56e97c38f3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -58,6 +58,9 @@ jobs:
- run: yarn build
+ - name: Typecheck component docs
+ run: yarn workspace @xds/core typecheck:docs
+
# Build storybook + analyze components (parallel with test)
# Uploads storybook preview and analysis artifacts for downstream jobs
build:
diff --git a/CLAUDE.md b/CLAUDE.md
index cb2bc31b43..f2ba05b9e1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -55,7 +55,7 @@ For architectural context, decisions, and research, see the **[GitHub Wiki](http
- **Research** — AI + Design Systems, AI Model Trajectory, Swizzle Ergonomics
- **Future** — Animation System, RSC Utilities, Distribution Strategy
-For component-specific documentation, see the `README.md` in each component directory under `packages/core/src/`.
+For component-specific documentation, see the `{Name}.doc.mjs` file in each component directory under `packages/core/src/` (e.g. `Button/Button.doc.mjs`). These are plain JS files with JSDoc type annotations exporting a `ComponentDoc` object (typed via `packages/core/src/docs-types.ts`).
## Documentation Standard
diff --git a/apps/sandbox/src/app/pages/polymorphic-link/page.tsx b/apps/sandbox/src/app/pages/polymorphic-link/page.tsx
index f5cb64093f..7f80244d34 100644
--- a/apps/sandbox/src/app/pages/polymorphic-link/page.tsx
+++ b/apps/sandbox/src/app/pages/polymorphic-link/page.tsx
@@ -7,9 +7,8 @@ import {
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
-import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSVStack} from '@xds/core/Layout';
import {XDSText, XDSHeading} from '@xds/core/Text';
-import {XDSButton} from '@xds/core/Button';
import {XDSDivider} from '@xds/core';
import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
import {XDSSideNav, XDSSideNavItem} from '@xds/core/SideNav';
diff --git a/apps/storybook/stories/TopNavMenu.stories.tsx b/apps/storybook/stories/TopNavMenu.stories.tsx
index c9787a4199..8f3adbde6c 100644
--- a/apps/storybook/stories/TopNavMenu.stories.tsx
+++ b/apps/storybook/stories/TopNavMenu.stories.tsx
@@ -17,7 +17,6 @@ import {
CodeBracketIcon,
GlobeAltIcon,
UserCircleIcon,
- MagnifyingGlassIcon,
} from '@heroicons/react/24/outline';
// =============================================================================
@@ -155,7 +154,7 @@ export const MultipleMenus: Story = {
export const MegaMenu: Story = {
name: 'Mega Menu',
render: function MegaMenuStory() {
- const [menuOpen, setMenuOpen] = useState(false);
+ const [, setMenuOpen] = useState(false);
return (
<div style={{position: 'relative'}}>
diff --git a/docs/COMPONENT_README_GUIDE.md b/docs/COMPONENT_README_GUIDE.md
deleted file mode 100644
index 5b16e89eec..0000000000
--- a/docs/COMPONENT_README_GUIDE.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# Component README Structure Guide
-
-## Why This Matters
-
-The XDS CLI's `extractBrief` function parses component READMEs to generate
-LLM-friendly documentation. This documentation powers:
-
-- **`xds component --brief-all`** — compact docs that LLMs use to discover and
- correctly use XDS components
-- **Vibe tests** — automated evaluations of how well LLMs can build UIs with XDS
-- **Developer experience** — `xds component <name>` shows formatted docs in the terminal
-
-When a README doesn't follow the expected structure, the brief extractor can't
-find props or examples. This means LLMs miss critical API details — for example,
-`XDSText.type` (which controls the semantic HTML element) was invisible to LLMs
-because the Text README used `### XDSText / XDSHeading` instead of separate
-`### XDSText` and `### XDSHeading` sections.
-
-## Validation
-
-Run the validation script to check all READMEs:
-
-```bash
-yarn validate-readmes
-```
-
-This runs automatically in CI to catch issues before merge.
-
-## Required Structure
-
-### Single-Component Directories
-
-For directories with one `XDS*.tsx` file (e.g., `Button/`, `Card/`, `Spinner/`):
-
-```markdown
-# ComponentName
-
-Brief description of what the component does.
-
-## Usage
-
-\`\`\`tsx
-import { XDSComponent } from '@xds/core/Component';
-
-<XDSComponent variant="primary" />
-\`\`\`
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------ | ---------------------------- | ------------- | --------------------- |
-| \`variant\` | \`'primary' \| 'secondary'\` | \`'primary'\` | Visual style |
-| \`size\` | \`'sm' \| 'md' \| 'lg'\` | \`'md'\` | Size of the component |
-| \`children\` | \`ReactNode\` | — | Content |
-```
-
-**Requirements:**
-
-- A `## Props` section
-- A markdown table inside `## Props` with at least one `| \`propName\`` row
-
-### Multi-Component Directories
-
-For directories with multiple `XDS*.tsx` files (e.g., `Text/`, `Stack/`, `Dialog/`):
-
-```markdown
-# ComponentGroup
-
-Brief description of the component group.
-
-### XDSComponentA
-
-Description of ComponentA.
-
-\`\`\`tsx
-import { XDSComponentA } from '@xds/core/ComponentGroup';
-
-<XDSComponentA requiredProp="value">Content</XDSComponentA>
-\`\`\`
-
-| Prop | Type | Default | Description |
-| ---------------- | --------------------- | ------- | ---------------------- |
-| \`requiredProp\` | \`'a' \| 'b' \| 'c'\` | — | Description (required) |
-| \`children\` | \`ReactNode\` | — | Content |
-
-### XDSComponentB
-
-Description of ComponentB.
-
-\`\`\`tsx
-<XDSComponentB prop="value" />
-\`\`\`
-
-| Prop | Type | Default | Description |
-| -------- | ---------- | ------- | ----------- |
-| \`prop\` | \`string\` | — | Description |
-```
-
-**Requirements for each component:**
-
-- A `### XDSComponentName` heading (exact match — no slashes, no extra text)
-- A markdown props table within that section
-- At least one `\`\`\`tsx`or`\`\`\`jsx`code block with`<XDS` JSX usage
-
-## Common Mistakes
-
-### ❌ Combined headings
-
-```markdown
-### XDSText / XDSHeading
-```
-
-The extractor looks for exact `### XDSText` and `### XDSHeading` matches.
-Combined headings are invisible to it.
-
-**Fix:** Split into separate sections:
-
-```markdown
-### XDSText
-
-...props table and example...
-
-### XDSHeading
-
-...props table and example...
-```
-
-### ❌ Props table outside the component section
-
-```markdown
-### XDSDialog
-
-Description of Dialog.
-
-## Props
-
-| Prop | Type | Default | Description |
-```
-
-The `## Props` heading breaks out of the `### XDSDialog` section (it's a
-higher-level heading). The extractor can't associate the table with the component.
-
-**Fix:** Put the table directly under the `###` heading without a separate
-`## Props` section:
-
-```markdown
-### XDSDialog
-
-Description of Dialog.
-
-| Prop | Type | Default | Description |
-```
-
-### ❌ Missing code example
-
-```markdown
-### XDSButton
-
-| Prop | Type | Default | Description |
-| ----------- | ---------- | ------- | ------------ |
-| \`variant\` | \`string\` | — | Visual style |
-```
-
-The extractor needs at least one code example to show LLMs how the component
-is used.
-
-**Fix:** Add a code block before or after the props table:
-
-```markdown
-### XDSButton
-
-\`\`\`tsx
-<XDSButton variant="primary" onClick={handleClick}>Save</XDSButton>
-\`\`\`
-
-| Prop | Type | Default | Description |
-```
-
-### ❌ Code example without XDS JSX
-
-```markdown
-\`\`\`tsx
-const items = data.map(item => <li>{item.name}</li>);
-\`\`\`
-```
-
-The extractor looks for `<XDS` in code blocks to find component usage examples.
-
-**Fix:** Include actual component JSX:
-
-```markdown
-\`\`\`tsx
-<XDSList>
-{data.map(item => (
-<XDSListItem key={item.id}>{item.name}</XDSListItem>
-))}
-</XDSList>
-\`\`\`
-```
-
-## CLI Warnings
-
-When running `xds component --brief` or `--brief-all`, the CLI will print
-warnings to stderr if it can't extract complete information:
-
-```
-⚠️ No props found for XDSText. Ensure README has a '### XDSText' section with a props table.
-⚠️ No code example found for XDSText.
-```
-
-These warnings help you identify and fix README structure issues during
-development without polluting the brief output itself.
diff --git a/internal/vibe-tests/app/src/preview.tsx b/internal/vibe-tests/app/src/preview.tsx
index 94c4aa80af..e2c253f217 100644
--- a/internal/vibe-tests/app/src/preview.tsx
+++ b/internal/vibe-tests/app/src/preview.tsx
@@ -1,3 +1,3 @@
-export default function Preview({theme}: {theme: string}) {
+export default function Preview({theme: _theme}: {theme: string}) {
return <div>No component loaded. Use the screenshot script.</div>;
}
diff --git a/internal/vibe-tests/src/build-previews.ts b/internal/vibe-tests/src/build-previews.ts
index b9c6751464..67f42fb5b4 100644
--- a/internal/vibe-tests/src/build-previews.ts
+++ b/internal/vibe-tests/src/build-previews.ts
@@ -18,7 +18,7 @@ import {getResultsDir, ensureDir, readJson, writeJson} from './utils.js';
const __dirname = path.dirname(new URL(import.meta.url).pathname);
const VIBE_DIR = path.resolve(__dirname, '..');
-const APP_DIR = path.join(VIBE_DIR, 'app');
+const _APP_DIR = path.join(VIBE_DIR, 'app');
const REPO_ROOT = path.resolve(VIBE_DIR, '../..');
interface PreviewManifest {
diff --git a/package.json b/package.json
index ca7bd4ddd3..4d63d4d8ae 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,6 @@
"sync:exports": "node scripts/sync-exports.js",
"sync:exports:check": "node scripts/sync-exports.js --check",
"xds": "yarn workspace @xds/cli xds",
- "validate-readmes": "node scripts/validate-readmes.mjs",
"package:source": "node scripts/package-source.js",
"changeset": "changeset",
"version-packages": "changeset version",
diff --git a/packages/cli/src/commands/component.mjs b/packages/cli/src/commands/component.mjs
index a597cf9a43..d12af2cdf4 100644
--- a/packages/cli/src/commands/component.mjs
+++ b/packages/cli/src/commands/component.mjs
@@ -4,6 +4,9 @@
* `xds component --list` prints all components grouped by category.
* `xds component <name>` prints the full component README.
* `xds component <name> --compact` prints a token-optimized version for LLMs.
+ *
+ * Component docs live in typed {Name}.doc.mjs files (ComponentDoc exports).
+ * This file imports them directly — no markdown parsing needed.
*/
import * as fs from 'node:fs';
@@ -120,6 +123,174 @@ export function discoverComponents(coreDir) {
return ordered;
}
+/**
+ * Load the typed docs object from a .doc.mjs file.
+ */
+export async function loadDocs(readmePath) {
+ const mod = await import(pathToFileURL(readmePath).href);
+ return mod.docs;
+}
+
+/**
+ * Find the doc file for a component, checking both top-level
+ * and nested directories. Prefers {Name}.doc.mjs, then README.md
+ * (for backward compatibility).
+ */
+export function findComponentReadme(coreDir, name) {
+ const srcDir = path.join(coreDir, 'src');
+ // Preferred: {Name}.doc.mjs, then README.md
+ const docNames = [`${name}.doc.mjs`, 'README.md'];
+
+ for (const docName of docNames) {
+ // Direct match: src/{name}/{Name}.doc.mjs (or README.md)
+ const direct = path.join(srcDir, name, docName);
+ if (fs.existsSync(direct)) return direct;
+ }
+
+ // Nested match: src/*/{name}/{Name}.doc.mjs (or README.md)
+ const entries = fs.readdirSync(srcDir, {withFileTypes: true});
+ for (const docName of docNames) {
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const nested = path.join(srcDir, entry.name, name, docName);
+ if (fs.existsSync(nested)) return nested;
+ }
+ }
+
+ // Fallback: find the directory containing XDS{name}.tsx,
+ // then return the doc file in that directory or nearest parent
+ const sourcePath = findComponentSource(coreDir, name);
+ if (sourcePath) {
+ let dir = path.dirname(sourcePath);
+ while (dir.startsWith(srcDir)) {
+ for (const docName of docNames) {
+ const docFile = path.join(dir, docName);
+ if (fs.existsSync(docFile)) return docFile;
+ }
+ dir = path.dirname(dir);
+ }
+ }
+
+ return null;
+}
+
+/**
+ * Find the main source file for a component (XDS*.tsx, excluding tests).
+ * For "Button" finds src/Button/XDSButton.tsx
+ * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
+ * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
+ */
+export function findComponentSource(coreDir, name) {
+ const srcDir = path.join(coreDir, 'src');
+ const xdsName = `XDS${name}.tsx`;
+
+ function searchDir(dirPath) {
+ if (!fs.existsSync(dirPath)) return null;
+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+
+ // Check for exact match first
+ const exact = path.join(dirPath, xdsName);
+ if (fs.existsSync(exact)) return exact;
+
+ // Recurse into subdirectories
+ for (const entry of entries) {
+ if (entry.isDirectory()) {
+ const found = searchDir(path.join(dirPath, entry.name));
+ if (found) return found;
+ }
+ }
+ return null;
+ }
+
+ // Search in the component's directory
+ const directDir = path.join(srcDir, name);
+ if (fs.existsSync(directDir)) {
+ const found = searchDir(directDir);
+ if (found) return found;
+ }
+
+ // Search nested (component might be under a parent dir)
+ const entries = fs.readdirSync(srcDir, {withFileTypes: true});
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const nestedDir = path.join(srcDir, entry.name, name);
+ if (fs.existsSync(nestedDir)) {
+ const found = searchDir(nestedDir);
+ if (found) return found;
+ }
+ }
+
+ // Fallback: search entire src tree for the file
+ return searchDir(srcDir);
+}
+
+/**
+ * Compute the Levenshtein (edit) distance between two strings.
+ * Used for fuzzy-matching component names. Dependency-free.
+ */
+export function levenshteinDistance(a, b) {
+ const m = a.length, n = b.length;
+ const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
+ for (let i = 0; i <= m; i++) dp[i][0] = i;
+ for (let j = 0; j <= n; j++) dp[0][j] = j;
+ for (let i = 1; i <= m; i++) {
+ for (let j = 1; j <= n; j++) {
+ dp[i][j] = a[i-1] === b[j-1]
+ ? dp[i-1][j-1]
+ : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
+ }
+ }
+ return dp[m][n];
+}
+
+/**
+ * Find the closest component names to a given (possibly misspelled) name.
+ * Returns matches sorted by distance, filtered to maxDistance.
+ */
+export function findClosestComponents(name, components, maxDistance = 3) {
+ const allNames = Object.values(components).flat();
+ const needle = name.toLowerCase();
+
+ const matches = allNames
+ .map(comp => ({
+ name: comp,
+ distance: levenshteinDistance(needle, comp.toLowerCase()),
+ }))
+ .filter(m => m.distance <= maxDistance)
+ .sort((a, b) => a.distance - b.distance);
+
+ return matches;
+}
+
+/**
+ * Resolve the import path for a component.
+ * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.
+ */
+export function resolveImportPath(coreDir, componentName) {
+ const srcDir = path.join(coreDir, 'src');
+ const sourcePath = findComponentSource(coreDir, componentName);
+ if (!sourcePath) return '@xds/core';
+
+ // Get the top-level directory under src/ from the source path
+ const relToSrc = path.relative(srcDir, sourcePath);
+ const topDir = relToSrc.split(path.sep)[0];
+
+ // Check package.json exports for ./${topDir}
+ const pkgPath = path.join(coreDir, 'package.json');
+ if (fs.existsSync(pkgPath)) {
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+ if (pkg.exports && pkg.exports[`./${topDir}`]) {
+ return `@xds/core/${topDir}`;
+ }
+ }
+
+ return '@xds/core';
+}
+
+// ── Legacy markdown-parsing functions ────────────────────────────────
+// These are kept for backward compatibility with existing tests.
+// The CLI action handler uses the new format functions below instead.
+
/**
* Minimal cleanup for full docs (default mode).
* Strips SYNC comments, rewrites title, collapses blank lines.
@@ -277,129 +448,6 @@ export function extractCompact(content, componentName) {
return cleaned.join('\n') + '\n';
}
-/**
- * Find the README for a component, checking both top-level
- * and nested directories. Falls back to finding the directory
- * containing XDS{name}.tsx and returning its nearest README.
- */
-export function findComponentReadme(coreDir, name) {
- const srcDir = path.join(coreDir, 'src');
-
- // Direct match: src/{name}/README.md
- const direct = path.join(srcDir, name, 'README.md');
- if (fs.existsSync(direct)) return direct;
-
- // Nested match: src/*/{name}/README.md
- const entries = fs.readdirSync(srcDir, {withFileTypes: true});
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
- const nested = path.join(srcDir, entry.name, name, 'README.md');
- if (fs.existsSync(nested)) return nested;
- }
-
- // Fallback: find the directory containing XDS{name}.tsx,
- // then return the README.md in that directory or nearest parent
- const sourcePath = findComponentSource(coreDir, name);
- if (sourcePath) {
- let dir = path.dirname(sourcePath);
- while (dir.startsWith(srcDir)) {
- const readme = path.join(dir, 'README.md');
- if (fs.existsSync(readme)) return readme;
- dir = path.dirname(dir);
- }
- }
-
- return null;
-}
-
-/**
- * Find the main source file for a component (XDS*.tsx, excluding tests).
- * For "Button" finds src/Button/XDSButton.tsx
- * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
- * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
- */
-export function findComponentSource(coreDir, name) {
- const srcDir = path.join(coreDir, 'src');
- const xdsName = `XDS${name}.tsx`;
-
- function searchDir(dirPath) {
- if (!fs.existsSync(dirPath)) return null;
- const entries = fs.readdirSync(dirPath, {withFileTypes: true});
-
- // Check for exact match first
- const exact = path.join(dirPath, xdsName);
- if (fs.existsSync(exact)) return exact;
-
- // Recurse into subdirectories
- for (const entry of entries) {
- if (entry.isDirectory()) {
- const found = searchDir(path.join(dirPath, entry.name));
- if (found) return found;
- }
- }
- return null;
- }
-
- // Search in the component's directory
- const directDir = path.join(srcDir, name);
- if (fs.existsSync(directDir)) {
- const found = searchDir(directDir);
- if (found) return found;
- }
-
- // Search nested (component might be under a parent dir)
- const entries = fs.readdirSync(srcDir, {withFileTypes: true});
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
- const nestedDir = path.join(srcDir, entry.name, name);
- if (fs.existsSync(nestedDir)) {
- const found = searchDir(nestedDir);
- if (found) return found;
- }
- }
-
- // Fallback: search entire src tree for the file
- return searchDir(srcDir);
-}
-
-/**
- * Compute the Levenshtein (edit) distance between two strings.
- * Used for fuzzy-matching component names. Dependency-free.
- */
-export function levenshteinDistance(a, b) {
- const m = a.length, n = b.length;
- const dp = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
- for (let i = 0; i <= m; i++) dp[i][0] = i;
- for (let j = 0; j <= n; j++) dp[0][j] = j;
- for (let i = 1; i <= m; i++) {
- for (let j = 1; j <= n; j++) {
- dp[i][j] = a[i-1] === b[j-1]
- ? dp[i-1][j-1]
- : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
- }
- }
- return dp[m][n];
-}
-
-/**
- * Find the closest component names to a given (possibly misspelled) name.
- * Returns matches sorted by distance, filtered to maxDistance.
- */
-export function findClosestComponents(name, components, maxDistance = 3) {
- const allNames = Object.values(components).flat();
- const needle = name.toLowerCase();
-
- const matches = allNames
- .map(comp => ({
- name: comp,
- distance: levenshteinDistance(needle, comp.toLowerCase()),
- }))
- .filter(m => m.distance <= maxDistance)
- .sort((a, b) => a.distance - b.distance);
-
- return matches;
-}
-
/**
* Extract a brief, LLM-optimized summary from a README.
*
@@ -642,31 +690,6 @@ export function extractBriefAll(coreDir) {
return output.join('\n');
}
-/**
- * Resolve the import path for a component.
- * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.
- */
-export function resolveImportPath(coreDir, componentName) {
- const srcDir = path.join(coreDir, 'src');
- const sourcePath = findComponentSource(coreDir, componentName);
- if (!sourcePath) return '@xds/core';
-
- // Get the top-level directory under src/ from the source path
- const relToSrc = path.relative(srcDir, sourcePath);
- const topDir = relToSrc.split(path.sep)[0];
-
- // Check package.json exports for ./${topDir}
- const pkgPath = path.join(coreDir, 'package.json');
- if (fs.existsSync(pkgPath)) {
- const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
- if (pkg.exports && pkg.exports[`./${topDir}`]) {
- return `@xds/core/${topDir}`;
- }
- }
-
- return '@xds/core';
-}
-
/**
* Ensure compact output includes an import statement.
* If the output already contains `from '@xds/core`, returns as-is.
@@ -753,6 +776,292 @@ export function extractProps(content, componentName) {
return output.join('\n') + '\n';
}
+// ── Format functions ────────────────────────────────────────────────
+// These operate on the typed ComponentDoc object directly.
+// Used by the CLI action handler for .doc.mjs files.
+
+/**
+ * Render a props array as a markdown table.
+ */
+function formatPropsTable(props) {
+ if (!props || props.length === 0) return '';
+ const lines = [];
+ lines.push('| Prop | Type | Default | Description |');
+ lines.push('|------|------|---------|-------------|');
+ for (const p of props) {
+ const def = p.default ? `\`${p.default}\`` : '—';
+ const req = p.required ? ' **(required)**' : '';
+ lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
+ }
+ return lines.join('\n');
+}
+
+/**
+ * Format full component docs (default mode, replaces cleanReadme).
+ */
+export function formatFull(docs) {
+ const sections = [];
+
+ sections.push(`# ${docs.name}\n`);
+ sections.push(docs.description + '\n');
+
+ if (docs.features?.length) {
+ sections.push('## Features\n');
+ sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');
+ }
+
+ // Single component props
+ if ('props' in docs) {
+ sections.push('## Props\n');
+ sections.push(formatPropsTable(docs.props) + '\n');
+ }
+
+ // Multi-component
+ if ('components' in docs) {
+ sections.push('## Components\n');
+ for (const comp of docs.components) {
+ sections.push(`### ${comp.name}\n`);
+ sections.push(comp.description + '\n');
+ sections.push(formatPropsTable(comp.props) + '\n');
+ if (comp.examples?.length) {
+ for (const ex of comp.examples) {
+ if (ex.label) sections.push(`#### ${ex.label}\n`);
+ sections.push('```tsx\n' + ex.code + '\n```\n');
+ }
+ }
+ }
+ }
+
+ if (docs.examples?.length) {
+ sections.push('## Examples\n');
+ for (const ex of docs.examples) {
+ if (ex.label) sections.push(`### ${ex.label}\n`);
+ sections.push('```tsx\n' + ex.code + '\n```\n');
+ }
+ }
+
+ if (docs.theming) {
+ sections.push('## Theming\n');
+ sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);
+ if (docs.theming.surfaces?.length) {
+ const surfaceLines = [];
+ surfaceLines.push('| Surface | Description |');
+ surfaceLines.push('|---------|-------------|');
+ for (const s of docs.theming.surfaces) {
+ surfaceLines.push(`| \`${s.name}\` | ${s.description} |`);
+ }
+ sections.push(surfaceLines.join('\n') + '\n');
+ }
+ }
+
+ if (docs.accessibility?.length) {
+ sections.push('## Accessibility\n');
+ sections.push(docs.accessibility.map(a => `- ${a}`).join('\n') + '\n');
+ }
+
+ if (docs.keyboard) {
+ sections.push('## Keyboard\n');
+ sections.push(docs.keyboard + '\n');
+ }
+
+ if (docs.notes?.length) {
+ sections.push('## Notes\n');
+ sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');
+ }
+
+ return sections.join('\n');
+}
+
+/**
+ * Format compact docs for LLM consumption (replaces extractCompact + ensureImportStatement).
+ * Includes: import, features, props, limited examples, keyboard, notes.
+ */
+export function formatCompact(docs, componentName, importHint) {
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ const sections = [];
+
+ sections.push(`# ${docs.name}\n`);
+ sections.push(docs.description + '\n');
+
+ // Import statement
+ if (importHint) {
+ sections.push('## Import\n');
+ sections.push(`\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`);
+ }
+
+ if (docs.features?.length) {
+ sections.push('## Features\n');
+ sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');
+ }
+
+ // Props
+ if ('props' in docs) {
+ sections.push('## Props\n');
+ sections.push(formatPropsTable(docs.props) + '\n');
+ }
+
+ if ('components' in docs) {
+ for (const comp of docs.components) {
+ sections.push(`### ${comp.name}\n`);
+ sections.push(comp.description + '\n');
+ sections.push(formatPropsTable(comp.props) + '\n');
+ }
+ }
+
+ // Limited examples (max 3)
+ const examples = docs.examples?.slice(0, 3) || [];
+ if (examples.length) {
+ sections.push('## Usage\n');
+ for (const ex of examples) {
+ if (ex.label) sections.push(`### ${ex.label}\n`);
+ sections.push('```tsx\n' + ex.code + '\n```\n');
+ }
+ }
+
+ if (docs.keyboard) {
+ sections.push('## Keyboard\n');
+ sections.push(docs.keyboard + '\n');
+ }
+
+ if (docs.notes?.length) {
+ sections.push('## Notes\n');
+ sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');
+ }
+
+ return sections.join('\n');
+}
+
+/**
+ * Format a brief, LLM-optimized summary (replaces extractBrief).
+ *
+ * Format: component signature + key props + one usage example.
+ * Targets ~200-400 chars per component (vs ~2-3KB for --compact).
+ *
+ * For multi-component docs, extracts the entry matching componentName.
+ */
+export function formatBrief(docs, componentName, importHint) {
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ // Find the right props and examples for this component
+ let props = [];
+ let description = docs.description;
+ let examples = docs.examples || [];
+
+ if ('props' in docs) {
+ props = docs.props;
+ } else if ('components' in docs) {
+ const entry = docs.components.find(c => c.name === displayName);
+ if (entry) {
+ props = entry.props;
+ description = entry.description;
+ examples = entry.examples || docs.examples || [];
+ }
+ }
+
+ // Build signature from union-type props
+ const signatureProps = [];
+ const otherProps = [];
+
+ for (const prop of props) {
+ if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
+ const values = prop.type
+ .replace(/['"]/g, '')
+ .split('|')
+ .map(v => v.trim())
+ .join('|');
+ signatureProps.push(`${prop.name}: ${values}`);
+ } else if (prop.required) {
+ otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
+ } else {
+ otherProps.push(prop.name);
+ }
+ }
+
+ // Build output
+ const output = [];
+
+ // Signature line
+ const sigStr =
+ signatureProps.length > 0
+ ? `${displayName}(${signatureProps.join(', ')})`
+ : displayName;
+ output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);
+
+ // Description (shortened)
+ if (description) {
+ const shortDesc =
+ description.length > 80
+ ? description.slice(0, 77) + '...'
+ : description;
+ output.push(` ${shortDesc}`);
+ }
+
+ // Other props
+ if (otherProps.length > 0) {
+ output.push(` ${otherProps.join(' · ')}`);
+ }
+
+ // First code example
+ if (examples.length > 0) {
+ const code = examples[0].code;
+ const codeLine =
+ code.split('\n').find(l => l.trim().startsWith('<XDS')) ||
+ code.split('\n')[0];
+ output.push(` ${codeLine.trim()}`);
+ }
+
+ return output.join('\n') + '\n';
+}
+
+/**
+ * Format only the props tables (replaces extractProps).
+ */
+export function formatProps(docs, componentName) {
+ if ('props' in docs) {
+ return `## Props\n\n${formatPropsTable(docs.props)}\n`;
+ }
+
+ if ('components' in docs) {
+ const sections = [];
+ for (const comp of docs.components) {
+ sections.push(`### ${comp.name} Props\n`);
+ sections.push(formatPropsTable(comp.props) + '\n');
+ }
+ return sections.join('\n');
+ }
+
+ return `No props documentation found for ${componentName}.\n`;
+}
+
+/**
+ * Format brief summaries for ALL components in one output.
+ */
+export async function formatBriefAll(coreDir) {
+ const components = discoverComponents(coreDir);
+ const output = [];
+
+ for (const [category, comps] of Object.entries(components)) {
+ output.push(`## ${category}\n`);
+ for (const comp of comps) {
+ const readmePath = findComponentReadme(coreDir, comp);
+ if (readmePath) {
+ const docs = await loadDocs(readmePath);
+ const importPath = resolveImportPath(coreDir, comp);
+ output.push(formatBrief(docs, comp, importPath));
+ } else {
+ output.push(`XDS${comp}\n (no docs)\n`);
+ }
+ }
+ }
+
+ return output.join('\n');
+}
+
export function registerComponent(program) {
program
.command('component [name]')
diff --git a/packages/core/package.json b/packages/core/package.json
index 6f3c8445ef..2ac7c630be 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -371,6 +371,7 @@
"test": "vitest run --root ../..",
"test:watch": "vitest --root ../..",
"lint": "eslint src",
+ "typecheck:docs": "tsc --project tsconfig.docs.json",
"build:css": "node ../../scripts/build-css.mjs",
"postbuild": "yarn build:css"
},
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
new file mode 100644
index 0000000000..e7552d6184
--- /dev/null
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -0,0 +1,232 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'AppShell',
+ description:
+ 'Application-level layout shell providing header, side navigation, and main content area — composes XDSLayout internally and replaces the XDSPage + XDSPageLayout pattern.',
+ features: [
+ 'Two navigation slots: topNav (horizontal bar) and sideNav (vertical sidebar)',
+ 'Two height modes: fill (viewport-height, independent scroll containers) and auto (page-scroll with sticky nav)',
+ 'Controlled and uncontrolled sideNav collapse with responsive auto-collapse via sideNavBreakpoint',
+ 'Mobile: collapsed sideNav renders as an overlay with backdrop',
+ 'Composes XDSLayout internally for automatic padding collapse, scroll containment, and slot awareness',
+ 'Semantic HTML: <main> with role="main", SideNav with role="navigation", skip-to-content link',
+ 'Escape key closes mobile sideNav overlay',
+ ],
+ examples: [
+ {
+ label: 'TopNav + SideNav (most common)',
+ code: `<XDSAppShell
+ topNav={
+ <XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="My App" logo={<Logo />} />}
+ startContent={
+ <>
+ <XDSTopNavItem label="Home" href="/" isSelected />
+ <XDSTopNavItem label="Products" href="/products" />
+ </>
+ }
+ />
+ }
+ sideNav={
+ // No header — TopNav has the app identity
+ <XDSSideNav>
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem
+ label="Analytics"
+ icon={ChartBarIcon}
+ href="/analytics"
+ />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem label="General" icon={CogIcon} href="/settings" />
+ </XDSSideNavSection>
+ </XDSSideNav>
+ }>
+ <DashboardContent />
+</XDSAppShell>`,
+ },
+ {
+ label: 'SideNav only (no TopNav)',
+ code: `<XDSAppShell
+ sideNav={
+ <XDSSideNav
+ header={
+ <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
+ }>
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem
+ label="Analytics"
+ icon={ChartBarIcon}
+ href="/analytics"
+ />
+ </XDSSideNavSection>
+ </XDSSideNav>
+ }>
+ <DashboardContent />
+</XDSAppShell>`,
+ },
+ {
+ label: 'TopNav only (no sideNav)',
+ code: `<XDSAppShell
+ topNav={
+ <XDSTopNav
+ label="Navigation"
+ title={<XDSTopNavTitle title="Landing Page" />}
+ />
+ }>
+ <LandingContent />
+</XDSAppShell>`,
+ },
+ {
+ label: 'Auto height for content-heavy pages',
+ code: `<XDSAppShell
+ topNav={<XDSTopNav label="Docs" title={<XDSTopNavTitle title="Docs" />} />}
+ sideNav={<XDSSideNav>...</XDSSideNav>}
+ height="auto"
+>
+ <LongDocumentContent />
+</XDSAppShell>`,
+ },
+ {
+ label: 'Controlled sideNav collapse',
+ code: `<XDSAppShell
+ topNav={<XDSTopNav label="App" title={<XDSTopNavTitle title="App" />} />}
+ sideNav={<XDSSideNav>...</XDSSideNav>}
+ isSideNavCollapsed={collapsed}
+ onSideNavCollapsedChange={setCollapsed}
+>
+ <Content />
+</XDSAppShell>`,
+ },
+ {
+ label: 'Responsive: SideNav + MobileNav',
+ code: `const [mobileOpen, setMobileOpen] = useState(false);
+const isMobile = useMediaQuery('(max-width: 768px)');
+
+<XDSAppShell
+ topNav={
+ <XDSTopNav
+ label="Navigation"
+ title={<XDSTopNavTitle title="My App" />}
+ startContent={
+ isMobile ? (
+ <XDSButton
+ label="Menu"
+ icon={<XDSIcon icon="menu" color="inherit" />}
+ variant="ghost"
+ onClick={() => setMobileOpen(true)}
+ />
+ ) : (
+ <XDSTopNavItem label="Home" href="/" isSelected />
+ )
+ }
+ />
+ }
+ sideNav={<XDSSideNav>{navSections}</XDSSideNav>}
+ mobileNav={
+ <XDSMobileNav
+ isOpen={mobileOpen}
+ onOpenChange={open => setMobileOpen(open)}
+ title="My App">
+ {navSections}
+ </XDSMobileNav>
+ }>
+ <Content />
+</XDSAppShell>`,
+ },
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Main content area, rendered inside a <main> element.',
+ },
+ {
+ name: 'topNav',
+ type: 'ReactNode',
+ description: 'Top navigation slot, typically XDSTopNav.',
+ },
+ {
+ name: 'sideNav',
+ type: 'ReactNode',
+ description: 'Side navigation slot, typically XDSSideNav.',
+ },
+ {
+ name: 'mobileNav',
+ type: 'ReactNode',
+ description:
+ 'Mobile navigation slot, typically an XDSMobileNav component. Rendered when the viewport is below the sideNavBreakpoint.',
+ },
+ {
+ name: 'banner',
+ type: 'ReactNode',
+ description:
+ 'Banner slot for system-wide announcements, placed above the topNav.',
+ },
+ {
+ name: 'height',
+ type: "'fill' | 'auto'",
+ description:
+ "Height behavior: 'fill' makes the shell fill the viewport (100dvh) with independent scroll containers; 'auto' lets the shell grow with content and uses sticky positioning for nav.",
+ default: "'fill'",
+ },
+ {
+ name: 'isSideNavCollapsed',
+ type: 'boolean',
+ description: 'Whether the sideNav is collapsed (controlled mode).',
+ },
+ {
+ name: 'defaultIsSideNavCollapsed',
+ type: 'boolean',
+ description: 'Initial collapsed state for uncontrolled mode.',
+ default: 'false',
+ },
+ {
+ name: 'onSideNavCollapsedChange',
+ type: '(isCollapsed: boolean) => void',
+ description: 'Callback fired when the sideNav collapse state changes.',
+ },
+ {
+ name: 'sideNavBreakpoint',
+ type: "'sm' | 'md' | 'lg' | 'none'",
+ description:
+ 'Viewport-width breakpoint below which the sideNav auto-collapses. Use "none" to disable responsive collapse.',
+ default: "'md'",
+ },
+ {
+ name: 'sideNavWidth',
+ type: 'number',
+ description: 'Width of the sideNav panel in pixels.',
+ default: '260',
+ },
+ ],
+ accessibility: [
+ 'Semantic HTML via XDSLayout slots — each slot maps to a proper landmark element.',
+ '<main> content area has role="main" for landmark navigation.',
+ 'SideNav has role="navigation" with aria-label="Application navigation".',
+ 'Skip-to-content link is visually hidden but shown on focus for keyboard users.',
+ 'Escape key closes the mobile sideNav overlay.',
+ ],
+ notes: [
+ 'When a TopNav is present, omit XDSSideNavHeader from the SideNav — the TopNav already provides app identity. Adding both would double the identity.',
+ 'When there is no TopNav, include XDSSideNavHeader inside the SideNav so the app name and logo are present.',
+ 'XDSAppShell composes XDSLayout internally: topNav + banner map to XDSLayoutHeader, sideNav maps to XDSLayoutPanel, and children map to XDSLayoutContent.',
+ 'SideNav collapse animations currently snap open/closed; ViewTransitions support is planned.',
+ 'In "auto" height mode, TopNav gets position: sticky; top: 0 and SideNav gets position: sticky; top: <header-height>.',
+ 'In "fill" height mode, the shell fills 100dvh, TopNav is pinned at the top, and both the SideNav and content area have independent scroll containers.',
+ ],
+};
diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.md
deleted file mode 100644
index 352f640dd0..0000000000
--- a/packages/core/src/AppShell/README.md
+++ /dev/null
@@ -1,256 +0,0 @@
-# AppShell
-
-Application-level layout shell component.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Overview
-
-XDSAppShell provides the structural frame for an application: header, side navigation, and main content area. It composes XDSLayout internally and replaces the internal XDSPage + XDSPageLayout pattern.
-
-## Import
-
-```tsx
-import {XDSAppShell} from '@xds/core/AppShell';
-```
-
-## Composition Patterns
-
-XDSAppShell has two navigation slots: `topNav` (horizontal bar) and `sideNav` (vertical sidebar). How you combine them determines where app identity lives.
-
-### TopNav + SideNav (most common)
-
-When a TopNav is present, the SideNav should **not** include a header — the TopNav already provides the app name and logo. Adding `XDSSideNavHeader` would double the identity.
-
-```tsx
-<XDSAppShell
- topNav={
- <XDSTopNav
- label="Main navigation"
- title={<XDSTopNavTitle title="My App" logo={<Logo />} />}
- startContent={
- <>
- <XDSTopNavItem label="Home" href="/" isSelected />
- <XDSTopNavItem label="Products" href="/products" />
- </>
- }
- />
- }
- sideNav={
- // No header — TopNav has the app identity
- <XDSSideNav>
- <XDSSideNavSection title="Main" isHeaderHidden>
- <XDSSideNavItem
- label="Dashboard"
- icon={HomeIcon}
- isSelected
- href="/dashboard"
- />
- <XDSSideNavItem
- label="Analytics"
- icon={ChartBarIcon}
- href="/analytics"
- />
- </XDSSideNavSection>
- <XDSSideNavSection title="Settings">
- <XDSSideNavItem label="General" icon={CogIcon} href="/settings" />
- </XDSSideNavSection>
- </XDSSideNav>
- }>
- <DashboardContent />
-</XDSAppShell>
-```
-
-### SideNav Only (no TopNav)
-
-Without a TopNav, the SideNav needs its own header to provide app identity.
-
-```tsx
-<XDSAppShell
- sideNav={
- <XDSSideNav
- header={
- <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
- }>
- <XDSSideNavSection title="Main" isHeaderHidden>
- <XDSSideNavItem
- label="Dashboard"
- icon={HomeIcon}
- isSelected
- href="/dashboard"
- />
- <XDSSideNavItem
- label="Analytics"
- icon={ChartBarIcon}
- href="/analytics"
- />
- </XDSSideNavSection>
- </XDSSideNav>
- }>
- <DashboardContent />
-</XDSAppShell>
-```
-
-### TopNav Only (no sideNav)
-
-For landing pages or simple apps that don't need secondary navigation.
-
-```tsx
-<XDSAppShell
- topNav={
- <XDSTopNav
- label="Navigation"
- title={<XDSTopNavTitle title="Landing Page" />}
- />
- }>
- <LandingContent />
-</XDSAppShell>
-```
-
-### Responsive: SideNav + MobileNav
-
-For apps that need both desktop and mobile layouts, use the `mobileNav` slot.
-On desktop the SideNav renders inline; on mobile AppShell hides the SideNav
-(via `sideNavBreakpoint`) and the consumer shows an XDSMobileNav drawer instead.
-
-Pass a fully composed `<XDSMobileNav>` — AppShell just renders it, same as
-every other slot. All drawer props (`isOpen`, `onOpenChange`, `title`) stay on
-XDSMobileNav where they belong.
-
-```tsx
-const [mobileOpen, setMobileOpen] = useState(false);
-const isMobile = useMediaQuery('(max-width: 768px)');
-
-<XDSAppShell
- topNav={
- <XDSTopNav
- label="Navigation"
- title={<XDSTopNavTitle title="My App" />}
- startContent={
- isMobile ? (
- <XDSButton
- label="Menu"
- icon={<XDSIcon icon="menu" color="inherit" />}
- variant="ghost"
- onClick={() => setMobileOpen(true)}
- />
- ) : (
- <XDSTopNavItem label="Home" href="/" isSelected />
- )
- }
- />
- }
- sideNav={<XDSSideNav>{navSections}</XDSSideNav>}
- mobileNav={
- <XDSMobileNav
- isOpen={mobileOpen}
- onOpenChange={open => setMobileOpen(open)}
- title="My App">
- {navSections}
- </XDSMobileNav>
- }>
- <Content />
-</XDSAppShell>;
-```
-
-### Pattern Summary
-
-| Layout | TopNav | SideNav Header | When to use |
-| ---------------- | ------ | -------------- | ------------------------------- |
-| TopNav + SideNav | ✅ | ❌ Omit | Dashboards, admin panels, tools |
-| SideNav only | ❌ | ✅ Include | Simpler apps, focused tools |
-| TopNav only | ✅ | N/A | Landing pages, single-page apps |
-| Neither | ❌ | N/A | Auth screens, embedded views |
-
-## More Usage
-
-```tsx
-// Auto-height for content-heavy pages
-<XDSAppShell
- topNav={<XDSTopNav label="Docs" title={<XDSTopNavTitle title="Docs" />} />}
- sideNav={<XDSSideNav>...</XDSSideNav>}
- height="auto"
->
- <LongDocumentContent />
-</XDSAppShell>
-
-// Controlled sideNav collapse
-<XDSAppShell
- topNav={<XDSTopNav label="App" title={<XDSTopNavTitle title="App" />} />}
- sideNav={<XDSSideNav>...</XDSSideNav>}
- isSideNavCollapsed={collapsed}
- onSideNavCollapsedChange={setCollapsed}
->
- <Content />
-</XDSAppShell>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------------------- | -------------------------------- | -------- | ------------------------------------------- |
-| `children` | `ReactNode` | — | Main content area (rendered as `<main>`) |
-| `topNav` | `ReactNode` | — | Top navigation slot (typically XDSTopNav) |
-| `sideNav` | `ReactNode` | — | Side navigation slot (typically XDSSideNav) |
-| `banner` | `ReactNode` | — | Banner slot for system-wide announcements |
-| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior |
-| `isSideNavCollapsed` | `boolean` | — | Whether sideNav is collapsed (controlled) |
-| `defaultIsSideNavCollapsed` | `boolean` | `false` | Default collapsed state (uncontrolled) |
-| `mobileNav` | `ReactNode` | — | Mobile navigation (typically XDSMobileNav) |
-| `onSideNavCollapsedChange` | `(isCollapsed: boolean) => void` | — | Collapse change callback |
-| `sideNavBreakpoint` | `'sm' \| 'md' \| 'lg' \| 'none'` | `'md'` | Breakpoint for auto-collapse |
-| `sideNavWidth` | `number` | `260` | SideNav width in pixels |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
-| `data-testid` | `string` | — | Test ID |
-
-## Height Modes
-
-### Fill (default)
-
-- Shell fills viewport (`100dvh`)
-- TopNav is pinned at top
-- SideNav has its own scroll container
-- Content area scrolls independently
-- Best for: dashboards, admin panels, tools
-
-### Auto
-
-- Shell grows with content, page scrolls
-- TopNav gets `position: sticky; top: 0`
-- SideNav gets `position: sticky; top: <header-height>`
-- Best for: docs sites, content-heavy pages
-
-## SideNav Behavior
-
-- **Controlled**: Use `isSideNavCollapsed` + `onSideNavCollapsedChange`
-- **Uncontrolled**: Use `defaultIsSideNavCollapsed`
-- **Responsive**: `sideNavBreakpoint` auto-collapses below the specified width
-- **Mobile**: Collapsed sideNav renders as an overlay with backdrop
-- **Animations**: Snap open/closed for now; ViewTransitions support planned
-
-## Internal Composition
-
-XDSAppShell composes `XDSLayout` internally with:
-
-- `header` → `XDSLayoutHeader` containing topNav + banner
-- `start` → `XDSLayoutPanel` containing sideNav
-- `content` → `XDSLayoutContent` containing children as `<main>`
-
-This gives automatic padding collapse, scroll containment, and slot awareness.
-
-## Accessibility
-
-- Semantic HTML via XDSLayout slots
-- `<main>` has `role="main"` for landmark navigation
-- SideNav has `role="navigation"` with `aria-label="Application navigation"`
-- Skip-to-content link (visually hidden, shown on focus)
-- Escape closes mobile sideNav overlay
-
-## Files
-
-| File | Role | Purpose |
-| ---------------------- | --------- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSAppShell.tsx` | Component | Main shell implementation |
-| `XDSAppShell.test.tsx` | Tests | Unit tests |
-| `README.md` | Docs | This documentation |
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 897c6c3696..31dd2692a0 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -7,7 +7,7 @@
* Use for any app that needs a top nav, side navigation, and scrollable content.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/AppShell/README.md
+ * - /packages/core/src/AppShell/AppShell.doc.mjs
* - /packages/core/src/AppShell/index.ts
* - /packages/core/src/AppShell/XDSAppShell.test.tsx
* - /apps/storybook/stories/AppShell.stories.tsx
diff --git a/packages/core/src/AppShell/index.ts b/packages/core/src/AppShell/index.ts
index ce183c4859..9ac9b90405 100644
--- a/packages/core/src/AppShell/index.ts
+++ b/packages/core/src/AppShell/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSAppShell and related types
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/AppShell/README.md
+ * SYNC: When modified, update this header and /packages/core/src/AppShell/AppShell.doc.mjs
*/
export {XDSAppShell} from './XDSAppShell';
diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
new file mode 100644
index 0000000000..d84f2ac34a
--- /dev/null
+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
@@ -0,0 +1,54 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'AspectRatio',
+ description: 'Maintains a specific aspect ratio for its children.',
+ features: [
+ 'Accepts any numeric ratio expressed as width/height (e.g. 16/9, 4/3, 1)',
+ 'Children are positioned absolutely to fill the container',
+ 'Supports theming via the aspectRatio component key',
+ ],
+ examples: [
+ {
+ label: 'Widescreen image (16:9)',
+ code: `<XDSAspectRatio ratio={16 / 9}>
+ <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />
+</XDSAspectRatio>`,
+ },
+ {
+ label: 'Square',
+ code: `<XDSAspectRatio ratio={1}>
+ <Avatar />
+</XDSAspectRatio>`,
+ },
+ {
+ label: '4:3 video',
+ code: `<XDSAspectRatio ratio={4 / 3}>
+ <video src="video.mp4" />
+</XDSAspectRatio>`,
+ },
+ ],
+ props: [
+ {
+ name: 'ratio',
+ type: 'number',
+ description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content positioned absolutely to fill the container.',
+ required: true,
+ },
+ ],
+ theming: {
+ componentKey: 'aspectRatio',
+ surfaces: [
+ {
+ name: 'root',
+ description: 'Root container styles.',
+ },
+ ],
+ },
+};
diff --git a/packages/core/src/AspectRatio/README.md b/packages/core/src/AspectRatio/README.md
deleted file mode 100644
index c9ecd7c7ae..0000000000
--- a/packages/core/src/AspectRatio/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# XDSAspectRatio
-
-Maintains a specific aspect ratio for its children.
-
-## Import
-
-```tsx
-import {XDSAspectRatio} from '@xds/core/AspectRatio';
-```
-
-## Usage
-
-```tsx
-<XDSAspectRatio ratio={16 / 9}>
- <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />
-</XDSAspectRatio>
-
-// Square
-<XDSAspectRatio ratio={1}>
- <Avatar />
-</XDSAspectRatio>
-
-// 4:3 video
-<XDSAspectRatio ratio={4 / 3}>
- <video src="video.mp4" />
-</XDSAspectRatio>
-```
-
-## Theming
-
-Themes can override `AspectRatio` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- aspectRatio: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | --------------------- |
-| `root` | Root container styles |
-
-## Props
-
-| Prop | Type | Default | Description |
-| ---------- | -------------- | ------- | ------------------------------------------------- |
-| `ratio` | `number` | — | Aspect ratio as width/height (e.g., 16/9, 1) |
-| `children` | `ReactNode` | — | Content positioned absolutely to fill container |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides for the container |
diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
index d06afdbf47..af6892ed41 100644
--- a/packages/core/src/AspectRatio/XDSAspectRatio.tsx
+++ b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
@@ -5,7 +5,7 @@
* @position AspectRatio component; maintains a specific aspect ratio for its children
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/AspectRatio/README.md
+ * - /packages/core/src/AspectRatio/AspectRatio.doc.mjs
* - /packages/core/src/AspectRatio/XDSAspectRatio.test.tsx
* - /apps/storybook/stories/AspectRatio.stories.tsx
*/
diff --git a/packages/core/src/AspectRatio/index.ts b/packages/core/src/AspectRatio/index.ts
index a93048e2c3..507797266b 100644
--- a/packages/core/src/AspectRatio/index.ts
+++ b/packages/core/src/AspectRatio/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSAspectRatio component and props type
* @position Package entry point for AspectRatio
*
- * SYNC: When modified, update /packages/core/src/AspectRatio/README.md
+ * SYNC: When modified, update /packages/core/src/AspectRatio/AspectRatio.doc.mjs
*/
export {XDSAspectRatio} from './XDSAspectRatio';
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
new file mode 100644
index 0000000000..813a6c28d6
--- /dev/null
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -0,0 +1,153 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Avatar',
+ description:
+ 'Avatar component for displaying user profile pictures with fallback support.',
+ features: [
+ 'Image loading: Primary and fallback image sources',
+ 'Initials fallback: Auto-generates initials from user name',
+ 'Default icon: Generic person icon when no image or name provided',
+ 'Sizes: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values',
+ 'Status slot: Corner position for status indicators or badges',
+ 'Size-aware status dot: Built-in XDSAvatarStatusDot that scales proportionally with avatar size',
+ 'Accessible: Proper role and aria-label support',
+ ],
+ examples: [
+ {
+ label: 'With image',
+ code: '<XDSAvatar src="/user.jpg" name="John Doe" />',
+ },
+ {
+ label: 'Initials fallback',
+ code: '<XDSAvatar name="Jane Smith" size="large" />',
+ },
+ {
+ label: 'With size-aware status indicator',
+ code: `<XDSAvatar
+ src="/user.jpg"
+ name="John Doe"
+ size="medium"
+ status={<XDSAvatarStatusDot variant="positive" label="Online" />}
+/>`,
+ },
+ {
+ label: 'Status dot scales automatically across sizes',
+ code: `<XDSAvatar name="AB" size="tiny" status={<XDSAvatarStatusDot />} />
+<XDSAvatar name="CD" size="large" status={<XDSAvatarStatusDot />} />`,
+ },
+ {
+ label: 'Different variants for different contexts',
+ code: `<XDSAvatar name="EF" status={<XDSAvatarStatusDot variant="negative" label="Busy" />} />
+<XDSAvatar name="GH" status={<XDSAvatarStatusDot variant="neutral" label="Away" />} />`,
+ },
+ ],
+ theming: {
+ componentKey: 'avatar',
+ surfaces: [
+ {name: 'root', description: 'Root wrapper styles'},
+ {name: 'fallback', description: 'Fallback/initials container styles'},
+ ],
+ },
+ notes: [
+ 'Always circular shape (border-radius: 50%)',
+ 'Uses color.deemphasized and color.textSecondary for fallback background',
+ 'Initials extracted from first and last word of name',
+ 'XDSAvatarSizeContext provides the resolved numeric size to sub-components',
+ 'Status dot uses CIRCLE_EDGE_OFFSET_RATIO for positioning at the 45° point on the circle edge',
+ 'Fallback cascade: (1) src loads → show image; (2) src fails → try fallbackSrc; (3) fallbackSrc fails/missing → show initials from name; (4) no name → show generic person icon',
+ 'Status dot size tiers: avatar ≤ 36px → 8px dot with 1px border; avatar 40–72px → 16px dot with 2px border; avatar ≥ 96px → 24px dot with 4px border',
+ ],
+ components: [
+ {
+ name: 'XDSAvatar',
+ description:
+ 'Displays a user avatar with image, initials fallback, and optional status indicator.',
+ props: [
+ {
+ name: 'src',
+ type: 'string',
+ description: 'Primary image source URL.',
+ },
+ {
+ name: 'fallbackSrc',
+ type: 'string',
+ description: 'Fallback image when primary fails.',
+ },
+ {
+ name: 'name',
+ type: 'string',
+ description: 'User name for initials and alt text.',
+ },
+ {
+ name: 'alt',
+ type: 'string',
+ description: 'Alt text (falls back to name).',
+ },
+ {
+ name: 'size',
+ type: 'XDSAvatarSize',
+ description: 'Avatar size (named or numeric pixel value).',
+ default: "'small'",
+ },
+ {
+ name: 'status',
+ type: 'ReactNode',
+ description: 'Corner content for status indicators.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSAvatar src="/user.jpg" name="John Doe" size="medium" />',
+ },
+ {
+ label: 'With status dot',
+ code: `<XDSAvatar
+ src="/user.jpg"
+ name="John Doe"
+ size="medium"
+ status={<XDSAvatarStatusDot variant="positive" label="Online" />}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSAvatarStatusDot',
+ description:
+ 'Size-aware status indicator dot that reads avatar size from context and scales proportionally.',
+ props: [
+ {
+ name: 'variant',
+ type: "'positive' | 'neutral' | 'negative'",
+ description: 'Semantic color variant of the dot.',
+ default: "'positive'",
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for screen readers.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon centered inside the dot (hidden at tiny sizes).',
+ },
+ ],
+ examples: [
+ {
+ label: 'Online',
+ code: '<XDSAvatarStatusDot variant="positive" label="Online" />',
+ },
+ {
+ label: 'Busy',
+ code: '<XDSAvatarStatusDot variant="negative" label="Busy" />',
+ },
+ {
+ label: 'Away',
+ code: '<XDSAvatarStatusDot variant="neutral" label="Away" />',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Avatar/README.md b/packages/core/src/Avatar/README.md
deleted file mode 100644
index 4beb7aff82..0000000000
--- a/packages/core/src/Avatar/README.md
+++ /dev/null
@@ -1,129 +0,0 @@
-# Avatar
-
-Avatar component for displaying user profile pictures with fallback support.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Image loading**: Primary and fallback image sources
-- **Initials fallback**: Auto-generates initials from user name
-- **Default icon**: Generic person icon when no image or name provided
-- **Sizes**: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values
-- **Status slot**: Corner position for status indicators or badges
-- **Size-aware status dot**: Built-in `XDSAvatarStatusDot` that scales proportionally with avatar size
-- **Accessible**: Proper role and aria-label support
-
-## Usage
-
-```tsx
-import { XDSAvatar, XDSAvatarStatusDot } from '@xds/core/Avatar';
-
-// With image
-<XDSAvatar src="/user.jpg" name="John Doe" />
-
-// Initials fallback
-<XDSAvatar name="Jane Smith" size="large" />
-
-// With size-aware status indicator
-<XDSAvatar
- src="/user.jpg"
- name="John Doe"
- size="medium"
- status={<XDSAvatarStatusDot variant="positive" label="Online" />}
-/>
-
-// Status dot scales automatically across sizes
-<XDSAvatar name="AB" size="tiny" status={<XDSAvatarStatusDot />} />
-<XDSAvatar name="CD" size="large" status={<XDSAvatarStatusDot />} />
-
-// Different variants for different contexts
-<XDSAvatar name="EF" status={<XDSAvatarStatusDot variant="negative" label="Busy" />} />
-<XDSAvatar name="GH" status={<XDSAvatarStatusDot variant="neutral" label="Away" />} />
-```
-
-## Props
-
-### XDSAvatar
-
-```tsx
-<XDSAvatar src="/user.jpg" name="John Doe" size="medium" />
-```
-
-| Prop | Type | Default | Description |
-| ------------- | --------------- | --------- | ------------------------------------ |
-| `src` | `string` | — | Primary image source URL |
-| `fallbackSrc` | `string` | — | Fallback image when primary fails |
-| `name` | `string` | — | User name for initials and alt text |
-| `alt` | `string` | — | Alt text (falls back to `name`) |
-| `size` | `XDSAvatarSize` | `'small'` | Avatar size (named or numeric) |
-| `status` | `ReactNode` | — | Corner content for status indicators |
-| `data-testid` | `string` | — | Test ID for testing |
-
-### XDSAvatarStatusDot
-
-```tsx
-<XDSAvatarStatusDot variant="positive" label="Online" />
-```
-
-| Prop | Type | Default | Description |
-| --------- | --------------------------------------- | ------------ | --------------------------------------------------- |
-| `variant` | `'positive' \| 'neutral' \| 'negative'` | `'positive'` | Semantic color variant of the dot |
-| `label` | `string` | — | Accessible label for screen readers |
-| `icon` | `ReactNode` | — | Icon centered inside the dot (hidden at tiny sizes) |
-
-The status dot reads the avatar size from context and uses discrete size tiers:
-
-| Avatar size | Dot size | Border |
-| ----------- | -------- | ------ |
-| ≤ 36px | 8px | 1px |
-| 40–72px | 16px | 2px |
-| ≥ 96px | 24px | 4px |
-
-## Fallback Cascade
-
-1. `src` loads → show image
-2. `src` fails → try `fallbackSrc`
-3. `fallbackSrc` fails/missing → show initials from `name`
-4. No `name` → show generic person icon
-
-## Theming
-
-Themes can override `Avatar` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- avatar: {
- root: myStyles,
- fallback: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ---------- | ---------------------------------- |
-| `root` | Root wrapper styles |
-| `fallback` | Fallback/initials container styles |
-
-## Files
-
-| File | Role | Purpose |
-| ------------------------- | -------- | ------------------------------------------ |
-| `index.ts` | Entry | Exports components and types |
-| `XDSAvatar.tsx` | Core | Avatar component implementation |
-| `XDSAvatarStatusDot.tsx` | Sub-comp | Size-aware status indicator dot |
-| `XDSAvatarSizeContext.ts` | Context | Internal context for passing size to slots |
-
-## Implementation Notes
-
-- Always circular shape (border-radius: 50%)
-- Uses `color.deemphasized` and `color.textSecondary` for fallback background
-- Initials extracted from first and last word of name
-- `XDSAvatarSizeContext` provides the resolved numeric size to sub-components
-- Status dot uses `CIRCLE_EDGE_OFFSET_RATIO` for positioning at the 45° point on the circle edge
diff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsx
index 09dd046df6..f6d92e6424 100644
--- a/packages/core/src/Avatar/XDSAvatar.tsx
+++ b/packages/core/src/Avatar/XDSAvatar.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Avatar/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Avatar/Avatar.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Avatar/XDSAvatar.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Avatar/index.ts (exports if types change)
* - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
diff --git a/packages/core/src/Avatar/XDSAvatarSizeContext.ts b/packages/core/src/Avatar/XDSAvatarSizeContext.ts
index 3a400de398..08535cd2d7 100644
--- a/packages/core/src/Avatar/XDSAvatarSizeContext.ts
+++ b/packages/core/src/Avatar/XDSAvatarSizeContext.ts
@@ -5,7 +5,7 @@
* @position Internal context; provided by XDSAvatar, consumed by sub-components
*
* SYNC: When modified, update:
- * - /packages/core/src/Avatar/README.md
+ * - /packages/core/src/Avatar/Avatar.doc.mjs
*/
'use client';
diff --git a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
index ff58fa0443..1b62c54283 100644
--- a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
+++ b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
@@ -5,7 +5,7 @@
* @position Sub-component of XDSAvatar; renders a size-aware status indicator
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Avatar/README.md (features, files table)
+ * - /packages/core/src/Avatar/Avatar.doc.mjs (features, files table)
* - /packages/core/src/Avatar/index.ts (exports)
* - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
*/
diff --git a/packages/core/src/Avatar/index.ts b/packages/core/src/Avatar/index.ts
index 769a552653..76cc5dc3cc 100644
--- a/packages/core/src/Avatar/index.ts
+++ b/packages/core/src/Avatar/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSAvatar, XDSAvatarProps, XDSAvatarSize, XDSAvatarStatusDot, XDSAvatarStatusDotProps, XDSAvatarStatusDotVariant
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Avatar/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Avatar/Avatar.doc.mjs
*/
export {XDSAvatar} from './XDSAvatar';
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjs
new file mode 100644
index 0000000000..e8c355936f
--- /dev/null
+++ b/packages/core/src/Badge/Badge.doc.mjs
@@ -0,0 +1,59 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Badge',
+ description:
+ 'A badge component for displaying status indicators, counts, or labels.',
+ props: [
+ {
+ name: 'variant',
+ type: "'neutral' | 'info' | 'success' | 'warning' | 'error'",
+ description: 'Visual style variant.',
+ default: "'neutral'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Badge content. Omit for dot indicator.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Optional leading icon.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Text badge',
+ code: '<XDSBadge>Default</XDSBadge>',
+ },
+ {
+ label: 'Status variants',
+ code: `<XDSBadge variant="success">Active</XDSBadge>
+<XDSBadge variant="error">Failed</XDSBadge>
+<XDSBadge variant="warning">Pending</XDSBadge>`,
+ },
+ {
+ label: 'Count badge',
+ code: '<XDSBadge variant="info">42</XDSBadge>',
+ },
+ {
+ label: 'Dot indicator (no children)',
+ code: '<XDSBadge variant="success" />',
+ },
+ ],
+ theming: {
+ componentKey: 'badge',
+ surfaces: [
+ {
+ name: 'root',
+ description: 'Root badge styles.',
+ },
+ {
+ name: 'variants',
+ description:
+ 'Per-variant overrides (Partial<Record<XDSBadgeVariant, StyleXStyles>>).',
+ },
+ ],
+ },
+};
diff --git a/packages/core/src/Badge/README.md b/packages/core/src/Badge/README.md
deleted file mode 100644
index eedb4d9f4a..0000000000
--- a/packages/core/src/Badge/README.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# Badge
-
-A badge component for displaying status indicators, counts, or labels.
-
-## Exports
-
-| Export | Type | Description |
-| ----------------- | --------- | -------------------- |
-| `XDSBadge` | Component | Main badge component |
-| `XDSBadgeProps` | Type | Props interface |
-| `XDSBadgeVariant` | Type | Variant union type |
-
-## Props
-
-| Prop | Type | Default | Description |
-| ---------- | ---------------------------------------------------------- | ----------- | ------------------------------------- |
-| `variant` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | `'neutral'` | Visual style variant |
-| `children` | `ReactNode` | - | Badge content. Omit for dot indicator |
-| `icon` | `ReactNode` | - | Optional leading icon |
-
-## Usage
-
-```tsx
-import {XDSBadge} from '@xds/core/Badge';
-
-// Text badge
-<XDSBadge>Default</XDSBadge>
-
-// Status variants
-<XDSBadge variant="success">Active</XDSBadge>
-<XDSBadge variant="error">Failed</XDSBadge>
-<XDSBadge variant="warning">Pending</XDSBadge>
-
-// Count badge
-<XDSBadge variant="info">42</XDSBadge>
-
-// Dot indicator (no children)
-<XDSBadge variant="success" />
-```
-
-## Theming
-
-Themes can override `Badge` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- badge: {
- root: myStyles,
- variants: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ---------- | ---------------------------------------------------------------------- |
-| `root` | Root badge styles |
-| `variants` | Per-variant overrides (Partial<Record<XDSBadgeVariant, StyleXStyles>>) |
-
-## Files
-
-| File | Purpose |
-| ------------------- | ------------------------ |
-| `XDSBadge.tsx` | Component implementation |
-| `XDSBadge.test.tsx` | Unit tests |
-| `index.ts` | Barrel exports |
diff --git a/packages/core/src/Badge/XDSBadge.tsx b/packages/core/src/Badge/XDSBadge.tsx
index 4240360aa3..203ddb9b87 100644
--- a/packages/core/src/Badge/XDSBadge.tsx
+++ b/packages/core/src/Badge/XDSBadge.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Badge/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Badge/Badge.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Badge/XDSBadge.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Badge/index.ts (exports if types change)
* - /apps/storybook/stories/Badge.stories.tsx (storybook stories)
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
new file mode 100644
index 0000000000..f6f2a5c218
--- /dev/null
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -0,0 +1,115 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Banner',
+ description:
+ 'Persistent status notification for info, warning, error, or success messages.',
+
+ features: [
+ 'Two-part layout: colored status header with icon, title, description, action buttons, and optional dismiss; optional card-background content area below',
+ 'When no children are provided, only the colored header renders',
+ 'Self-managed dismiss state — banner hides itself on dismiss without requiring external state wiring',
+ 'onDismiss callback fires alongside the internal state change for logging or backend sync',
+ 'Default status icons from @heroicons/react/24/solid: InformationCircleIcon (info), ExclamationTriangleIcon (warning), XCircleIcon (error), CheckCircleIcon (success)',
+ 'Status colors: info uses --color-accent-deemphasized, warning uses --color-warning-deemphasized, error uses --color-negative-deemphasized, success uses --color-positive-deemphasized',
+ 'Card variant (default): has border-radius with optional card content area below the colored header',
+ 'Section variant: no border-radius, full-width for page-level banners',
+ ],
+
+ examples: [
+ {
+ label: 'Simple — just the colored header',
+ code: '<XDSBanner status="info" title="New update available" />',
+ },
+ {
+ label: 'With description and self-dismissing behavior',
+ code: `<XDSBanner
+ status="error"
+ title="Something went wrong"
+ description="Please try again later."
+ isDismissable
+ onDismiss={() => logDismiss()}
+/>`,
+ },
+ {
+ label: 'With content area (card background below header)',
+ code: `<XDSBanner
+ status="error"
+ title="Multiple errors found"
+ description="The following issues need to be resolved:"
+>
+ <ul>
+ <li>Email address is invalid</li>
+ <li>Password must be at least 8 characters</li>
+ </ul>
+</XDSBanner>`,
+ },
+ ],
+
+ props: [
+ {
+ name: 'status',
+ type: "'info' | 'warning' | 'error' | 'success'",
+ description: 'Status type controlling icon and color.',
+ required: true,
+ },
+ {
+ name: 'title',
+ type: 'ReactNode',
+ description: 'Title text or ReactNode displayed in the header.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: 'Description text rendered below the title in the header.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Override the default status icon.',
+ },
+ {
+ name: 'isDismissable',
+ type: 'boolean',
+ description: 'Whether the banner can be dismissed by the user.',
+ default: 'false',
+ },
+ {
+ name: 'onDismiss',
+ type: '() => void',
+ description:
+ 'Called when the dismiss button is clicked; banner hides itself regardless of whether this is provided.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description:
+ 'Action content rendered in the header area, end-aligned. Typically a button or link.',
+ },
+ {
+ name: 'variant',
+ type: "'card' | 'section'",
+ description:
+ 'Visual variant: card has border-radius; section is full-width with no border-radius for page-level use.',
+ default: "'card'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Content rendered in the card-background area below the colored header.',
+ },
+ ],
+
+ accessibility: [
+ 'Uses role="alert" for error and warning statuses',
+ 'Uses role="status" for info and success statuses',
+ 'Dismiss button has aria-label="Dismiss"',
+ 'Status icon is aria-hidden="true" — status is conveyed by the ARIA role instead',
+ ],
+
+ notes: [
+ 'Collapsible support is planned: the content area will support collapsing via useXDSCollapsible (issue #187)',
+ ],
+};
diff --git a/packages/core/src/Banner/README.md b/packages/core/src/Banner/README.md
deleted file mode 100644
index aeffec2cb5..0000000000
--- a/packages/core/src/Banner/README.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# XDSBanner
-
-Persistent status notification for info, warning, error, or success messages.
-
-## Visual Structure
-
-The banner has a two-part layout:
-
-1. **Header area** — colored status background with icon, title, description, action buttons, and dismiss
-2. **Content area** (optional) — card background below the header for additional rich content
-
-When no `children` are provided, only the colored header renders.
-
-## Usage
-
-```tsx
-import {XDSBanner} from '@xds/core/Banner';
-
-// Simple — just the colored header
-<XDSBanner status="info" title="New update available" />
-
-// With description and self-dismissing behavior
-<XDSBanner
- status="error"
- title="Something went wrong"
- description="Please try again later."
- isDismissable
- onDismiss={() => logDismiss()}
-/>
-
-// With content area (card background below header)
-<XDSBanner
- status="error"
- title="Multiple errors found"
- description="The following issues need to be resolved:"
->
- <ul>
- <li>Email address is invalid</li>
- <li>Password must be at least 8 characters</li>
- </ul>
-</XDSBanner>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------- | --------------------------------------------- | -------- | ----------------------------------------------------- |
-| `status` | `'info' \| 'warning' \| 'error' \| 'success'` | — | Status type controlling icon and color (required) |
-| `title` | `ReactNode` | — | Title text or ReactNode (required) |
-| `description` | `ReactNode` | — | Description text below the title |
-| `icon` | `ReactNode` | — | Override the default status icon |
-| `isDismissable` | `boolean` | `false` | Whether the banner can be dismissed |
-| `onDismiss` | `() => void` | — | Called on dismiss (banner hides itself regardless) |
-| `endContent` | `ReactNode` | — | Action button in the header area (end-aligned) |
-| `variant` | `'card' \| 'section'` | `'card'` | Visual variant |
-| `children` | `ReactNode` | — | Content rendered in card-background area below header |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
-| `data-testid` | `string` | — | Test ID |
-
-## Dismiss Behavior
-
-When `isDismissable` is true, the banner manages its own dismissed state internally.
-Clicking the dismiss button hides the banner immediately, even if `onDismiss` is not provided.
-This ensures product teams get working dismiss behavior out of the box without needing
-to wire up state management. The `onDismiss` callback is optional and fires alongside
-the internal state change for logging or backend sync.
-
-## Status Colors
-
-| Status | Background Token | Role |
-| --------- | ------------------------------- | -------- |
-| `info` | `--color-accent-deemphasized` | `status` |
-| `warning` | `--color-warning-deemphasized` | `alert` |
-| `error` | `--color-negative-deemphasized` | `alert` |
-| `success` | `--color-positive-deemphasized` | `status` |
-
-## Variants
-
-- **Card** (default): Has border-radius, colored header with optional card content area below
-- **Section**: No border-radius, full-width for page-level banners
-
-## Default Icons
-
-Each status has a default icon from `@heroicons/react/24/solid`:
-
-- `info` → `InformationCircleIcon`
-- `warning` → `ExclamationTriangleIcon`
-- `error` → `XCircleIcon`
-- `success` → `CheckCircleIcon`
-
-## Accessibility
-
-- Uses `role="alert"` for error/warning statuses
-- Uses `role="status"` for info/success statuses
-- Dismiss button has `aria-label="Dismiss"`
-- Status icon is `aria-hidden="true"` (status conveyed by role)
-
-## Future
-
-- **Collapsible**: Banner will support collapsing the content area via `useXDSCollapsible` (#187)
-
-## File Manifest
-
-| File | Purpose |
-| -------------------- | ------------------------ |
-| `XDSBanner.tsx` | Component implementation |
-| `XDSBanner.test.tsx` | Unit tests |
-| `index.ts` | Public exports |
-| `README.md` | Documentation |
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index ffcc79ad4d..49df65bba7 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -11,7 +11,7 @@
* - When children are provided, a collapse/expand toggle button appears in the end area
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Banner/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Banner/Banner.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Banner/XDSBanner.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Banner/index.ts (exports if types change)
* - /apps/storybook/stories/Banner.stories.tsx (storybook stories)
diff --git a/packages/core/src/Banner/index.ts b/packages/core/src/Banner/index.ts
index d459e8d07e..31589d2615 100644
--- a/packages/core/src/Banner/index.ts
+++ b/packages/core/src/Banner/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSBanner, XDSBannerProps, XDSBannerStatus, XDSBannerVariant
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Banner/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Banner/Banner.doc.mjs
*/
export {XDSBanner} from './XDSBanner';
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
new file mode 100644
index 0000000000..bddebdbb94
--- /dev/null
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -0,0 +1,158 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Breadcrumbs',
+ description: 'A navigation breadcrumb trail with semantic HTML.',
+ features: [
+ 'Renders a <nav> landmark with an ordered list of breadcrumb items',
+ 'Configurable separator between items (defaults to /)',
+ 'Two visual variants: default and supporting (smaller, secondary text)',
+ 'Current page item is marked with aria-current="page"',
+ 'Separators are hidden from assistive technology via aria-hidden',
+ 'Supports icons before item labels via startIcon',
+ 'Auto-detects the last child as the current page when no isCurrent is set',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSBreadcrumbs>
+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
+</XDSBreadcrumbs>`,
+ },
+ {
+ label: 'Supporting variant',
+ code: `<XDSBreadcrumbs variant="supporting">
+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem isCurrent>Page</XDSBreadcrumbItem>
+</XDSBreadcrumbs>`,
+ },
+ {
+ label: 'With icons',
+ code: `<XDSBreadcrumbs>
+ <XDSBreadcrumbItem href="/" startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>
+ Home
+ </XDSBreadcrumbItem>
+ <XDSBreadcrumbItem isCurrent>Settings</XDSBreadcrumbItem>
+</XDSBreadcrumbs>`,
+ },
+ {
+ label: 'Item with icon and click handler',
+ code: `<XDSBreadcrumbItem href="/settings" startIcon={<XDSIcon icon={CogIcon} size="sm" />}>
+ Settings
+</XDSBreadcrumbItem>`,
+ },
+ ],
+ accessibility: [
+ 'Container renders as a <nav aria-label> landmark; the label defaults to "Breadcrumb" and is customizable via the label prop',
+ 'Items are placed inside an <ol> with individual <li> wrappers for correct list semantics',
+ 'The current page item receives aria-current="page"',
+ 'Separators are rendered with aria-hidden="true" so screen readers skip them',
+ 'Auto-detects the last child as the current item when no isCurrent prop is explicitly set',
+ ],
+ components: [
+ {
+ name: 'XDSBreadcrumbs',
+ description:
+ 'Navigation container that renders a <nav> with an ordered list of breadcrumb items.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'XDSBreadcrumbItem elements to render inside the breadcrumb trail.',
+ required: true,
+ },
+ {
+ name: 'separator',
+ type: 'ReactNode',
+ description: 'Separator rendered between breadcrumb items.',
+ default: "'/'",
+ },
+ {
+ name: 'variant',
+ type: "'default' | 'supporting'",
+ description:
+ 'Visual variant — supporting is smaller with secondary text styling.',
+ default: "'default'",
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the nav landmark (aria-label).',
+ default: "'Breadcrumb'",
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSBreadcrumbs>
+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
+</XDSBreadcrumbs>`,
+ },
+ {
+ label: 'Supporting variant',
+ code: `<XDSBreadcrumbs variant="supporting">
+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem isCurrent>Page</XDSBreadcrumbItem>
+</XDSBreadcrumbs>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSBreadcrumbItem',
+ description:
+ 'Individual breadcrumb item that renders as a link when href is provided, or as plain text for the current page.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Label content for the breadcrumb item.',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description:
+ 'URL the breadcrumb links to; omit for non-navigable items.',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: 'Click handler for the breadcrumb item.',
+ },
+ {
+ name: 'isCurrent',
+ type: 'boolean',
+ description:
+ 'Marks this item as the current page, applying aria-current="page".',
+ default: 'false',
+ },
+ {
+ name: 'startIcon',
+ type: 'ReactNode',
+ description: 'Icon rendered before the item label.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Link item',
+ code: `<XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>`,
+ },
+ {
+ label: 'Current page item',
+ code: `<XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>`,
+ },
+ {
+ label: 'With icon',
+ code: `<XDSBreadcrumbItem href="/settings" startIcon={<XDSIcon icon={CogIcon} size="sm" />}>
+ Settings
+</XDSBreadcrumbItem>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Breadcrumbs/README.md b/packages/core/src/Breadcrumbs/README.md
deleted file mode 100644
index 9784719ec0..0000000000
--- a/packages/core/src/Breadcrumbs/README.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# Breadcrumbs
-
-A navigation breadcrumb trail with semantic HTML.
-
-## Exports
-
-| Export | Type | Description |
-| ------------------------ | --------- | -------------------------- |
-| `XDSBreadcrumbs` | Component | Container with nav + ol |
-| `XDSBreadcrumbsProps` | Type | Container props interface |
-| `XDSBreadcrumbsVariant` | Type | Variant union type |
-| `XDSBreadcrumbItem` | Component | Individual breadcrumb item |
-| `XDSBreadcrumbItemProps` | Type | Item props interface |
-
-### XDSBreadcrumbs
-
-Navigation container that renders a `<nav>` with an ordered list of breadcrumb items.
-
-```tsx
-<XDSBreadcrumbs>
- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
- <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
- <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
-</XDSBreadcrumbs>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | --------------------------- | -------------- | --------------------------------- |
-| `children` | `ReactNode` | — | XDSBreadcrumbItem elements |
-| `separator` | `ReactNode` | `'/'` | Separator between items |
-| `variant` | `'default' \| 'supporting'` | `'default'` | Visual variant |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
-| `label` | `string` | `'Breadcrumb'` | Accessible label for nav landmark |
-| `data-testid` | `string` | — | Test ID |
-
-### XDSBreadcrumbItem
-
-Individual breadcrumb item that renders as a link or plain text.
-
-```tsx
-<XDSBreadcrumbItem href="/settings" startIcon={<XDSIcon icon={CogIcon} size="sm" />}>
- Settings
-</XDSBreadcrumbItem>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | ------------------------- | ------- | ------------------------------------ |
-| `children` | `ReactNode` | — | Item label content |
-| `href` | `string` | — | URL for the breadcrumb link |
-| `onClick` | `(e: MouseEvent) => void` | — | Click handler |
-| `isCurrent` | `boolean` | `false` | Marks as current page (aria-current) |
-| `startIcon` | `ReactNode` | — | Icon before the label |
-| `data-testid` | `string` | — | Test ID |
-
-## Usage
-
-```tsx
-import {XDSBreadcrumbs, XDSBreadcrumbItem} from '@xds/core/Breadcrumbs';
-
-// Basic breadcrumbs
-<XDSBreadcrumbs>
- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
- <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>
- <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>
-</XDSBreadcrumbs>
-
-// Supporting variant (smaller, secondary text)
-<XDSBreadcrumbs variant="supporting">
- <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
- <XDSBreadcrumbItem isCurrent>Page</XDSBreadcrumbItem>
-</XDSBreadcrumbs>
-
-// With icons
-<XDSBreadcrumbs>
- <XDSBreadcrumbItem href="/" startIcon={<XDSIcon icon={HomeIcon} size="sm" />}>
- Home
- </XDSBreadcrumbItem>
- <XDSBreadcrumbItem isCurrent>Settings</XDSBreadcrumbItem>
-</XDSBreadcrumbs>
-```
-
-## Accessibility
-
-- Container is `<nav aria-label>` landmark
-- Items in `<ol>` with `<li>` elements
-- Current item has `aria-current="page"`
-- Separators are `aria-hidden="true"`
-- Auto-detects last child as current when no `isCurrent` is set
-
-## Files
-
-| File | Purpose |
-| ------------------------- | ------------------------- |
-| `XDSBreadcrumbs.tsx` | Container component |
-| `XDSBreadcrumbItem.tsx` | Individual item component |
-| `XDSBreadcrumbs.test.tsx` | Unit tests |
-| `index.ts` | Barrel exports |
diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx
index 374c485c60..82f426257f 100644
--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx
+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx
@@ -5,7 +5,7 @@
* @position Individual breadcrumb item; used inside XDSBreadcrumbs
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Breadcrumbs/README.md
+ * - /packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
* - /packages/core/src/Breadcrumbs/XDSBreadcrumbs.test.tsx
* - /packages/core/src/Breadcrumbs/index.ts
* - /apps/storybook/stories/Breadcrumbs.stories.tsx
diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
index d6cd87f8ca..647aeccb05 100644
--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
@@ -5,7 +5,7 @@
* @position Core container component; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Breadcrumbs/README.md
+ * - /packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
* - /packages/core/src/Breadcrumbs/XDSBreadcrumbs.test.tsx
* - /packages/core/src/Breadcrumbs/index.ts
* - /apps/storybook/stories/Breadcrumbs.stories.tsx
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
new file mode 100644
index 0000000000..912eb08ef8
--- /dev/null
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -0,0 +1,141 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Button',
+ description:
+ 'XDSButton component with multiple variants, sizes, and isLoading state support.',
+
+ features: [
+ "Variants: 'primary', 'secondary', 'ghost', 'destructive'",
+ 'Sizes: sm (28px), md (32px), lg (36px)',
+ 'Loading state: Shows spinner, disables interaction',
+ 'Focus visible: Accessible focus outline with variant-specific colors',
+ 'Hover/active states: Uses overlay colors via backgroundImage for consistent layering',
+ ],
+
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label; used as aria-label for icon-only buttons.',
+ required: true,
+ },
+ {
+ name: 'variant',
+ type: "'primary' | 'secondary' | 'ghost' | 'destructive'",
+ description: 'Visual style variant.',
+ default: "'secondary'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant.',
+ default: "'md'",
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'Shows a loading spinner and disables interaction.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the button.',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ 'Icon element. When provided without children the button renders as a square icon-only button.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Button content. When provided alongside icon, the text is rendered next to the icon.',
+ },
+ {
+ name: 'endSlot',
+ type: 'ReactElement<XDSIconProps> | ReactElement<XDSBadgeProps>',
+ description:
+ 'Trailing icon or badge rendered after the label. Only accepts <XDSIcon> or <XDSBadge>. Ignored for icon-only buttons. Color is inherited from the button variant.',
+ },
+ {
+ name: 'tooltip',
+ type: 'string',
+ description: 'Tooltip text shown on hover.',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description:
+ 'Standard click handler (passed through from ButtonHTMLAttributes).',
+ },
+ {
+ name: 'onClickAction',
+ type: '(e: MouseEvent) => void | Promise<void>',
+ description:
+ 'Async click handler. Shows loading state while the returned promise is pending.',
+ },
+ ],
+
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSButton label="Click me" variant="primary" />',
+ },
+ {
+ label: 'With size',
+ code: '<XDSButton label="Large button" variant="primary" size="lg" />',
+ },
+ {
+ label: 'Loading state',
+ code: '<XDSButton label="Saving..." variant="primary" isLoading />',
+ },
+ {
+ label: 'Destructive action',
+ code: '<XDSButton label="Delete" variant="destructive" />',
+ },
+ {
+ label: 'Icon-only button',
+ code: `// Pass \`icon\` without \`children\` — \`label\` becomes the aria-label
+<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" />`,
+ },
+ {
+ label: 'Icon-only with emoji content',
+ code: '<XDSButton label="Select rocket emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />',
+ },
+ {
+ label: 'Icon + visible label',
+ code: '<XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>',
+ },
+ {
+ label: 'endSlot — badge after label',
+ code: '<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />',
+ },
+ {
+ label: 'endSlot — icon, label, and badge',
+ code: '<XDSButton label="Edit" icon={<PencilIcon />} endSlot={<XDSBadge>New</XDSBadge>}>Edit</XDSButton>',
+ },
+ {
+ label: 'endSlot — settings with badge',
+ code: `<XDSButton label="Settings" icon={<GearIcon />} endSlot={<XDSBadge>New</XDSBadge>}>
+ Settings
+</XDSButton>`,
+ },
+ ],
+
+ notes: [
+ 'XDSButtonVariant type is derived from the variants StyleX object using keyof typeof variants.',
+ 'Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.',
+ 'Destructive variant uses colorTokens.negative for its focus outline color.',
+ 'endSlot is wrapped in a <span> with color: inherit so icons/badges match the button text color across all variants.',
+ 'When icon is provided without children, the button becomes icon-only: it renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon — SVG components, emoji, or text.',
+ 'endSlot is ignored for icon-only buttons (when icon is provided without children) to preserve the square aspect ratio.',
+ 'Prefer XDSButton over <div onClick> or <span onClick> for accessibility — it provides keyboard navigation, focus management, and screen reader support.',
+ 'Icon-only buttons are suitable for toolbars, action grids, and compact controls.',
+ ],
+};
diff --git a/packages/core/src/Button/README.md b/packages/core/src/Button/README.md
deleted file mode 100644
index 26e4b5cfa0..0000000000
--- a/packages/core/src/Button/README.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# Button
-
-XDSButton component with multiple variants, sizes, and isLoading state support.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Variants**: `primary`, `secondary`, `ghost`, `destructive`
-- **Sizes**: `sm` (28px), `md` (32px), `lg` (36px)
-- **Loading state**: Shows spinner, disables interaction
-- **Focus visible**: Accessible focus outline with variant-specific colors
-- **Hover/active states**: Uses overlay colors via `backgroundImage` for consistent layering
-
-## Usage
-
-```tsx
-import { XDSButton } from '@xds/core/Button';
-
-// Basic usage
-<XDSButton label="Click me" variant="primary" />
-
-// With size
-<XDSButton label="Large button" variant="primary" size="lg" />
-
-// With isLoading state
-<XDSButton label="Saving..." variant="primary" isLoading />
-
-// Destructive action
-<XDSButton label="Delete" variant="destructive" />
-
-// Icon-only button (renders as a square)
-// Pass `icon` without `children` — `label` becomes the aria-label
-<XDSButton label="Settings" icon={<GearIcon />} variant="ghost" />
-
-// Icon-only with emoji or text content
-<XDSButton label="Select rocket emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />
-
-// Icon + visible label (pass children to show text alongside icon)
-<XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>
-
-// With endSlot — badge or trailing icon after the label
-<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />
-<XDSButton label="Edit" icon={<PencilIcon />} endSlot={<XDSBadge>New</XDSBadge>}>Edit</XDSButton>
-```
-
-### Icon-Only Buttons
-
-When `icon` is provided without `children`, the button becomes **icon-only**:
-
-- Renders as a perfect square (`aspectRatio: 1/1`)
-- `label` is used as `aria-label` for accessibility (not rendered visually)
-- Works with any `ReactNode` as the icon — SVG components, emoji, or text
-
-Use icon-only buttons for toolbars, action grids, compact controls, and anywhere
-you need a small clickable element. Always prefer `XDSButton` over `<div onClick>`
-or `<span onClick>` for accessibility (keyboard navigation, focus management, screen readers).
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------ | ----------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `label` | `string` | — | Accessible label (required) |
-| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | `'secondary'` | Visual style variant |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |
-| `isLoading` | `boolean` | `false` | Shows isLoading spinner |
-| `isDisabled` | `boolean` | `false` | Disables the button |
-| `icon` | `ReactNode` | — | Icon element |
-| `children` | `ReactNode` | — | Button content |
-| `endSlot` | `ReactElement<XDSIconProps> \| ReactElement<XDSBadgeProps>` | — | Trailing icon or badge after the label. Only accepts `<XDSIcon>` or `<XDSBadge>`. Ignored for icon-only. Color is inherited from the button variant. |
-| `tooltip` | `string` | — | Tooltip text shown on hover |
-| `onClick` | `(e: MouseEvent) => void` | — | Standard click handler (passed through from `ButtonHTMLAttributes`) |
-| `onClickAction` | `(e: MouseEvent) => void \| Promise<void>` | — | Async click handler. Shows loading state while the returned promise is pending. |
-
-## Files
-
-| File | Role | Purpose |
-| -------------------- | ----- | ------------------------------------- |
-| `index.ts` | Entry | Exports XDSButton component and types |
-| `XDSButton.tsx` | Core | XDSButton component implementation |
-| `XDSButton.test.tsx` | Test | Unit tests for XDSButton component |
-
-### endSlot
-
-The `endSlot` prop renders an `<XDSIcon>` or `<XDSBadge>` after the label text:
-
-```tsx
-// Counter badge
-<XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />
-
-// Icon + label + endSlot
-<XDSButton label="Settings" icon={<GearIcon />} endSlot={<XDSBadge>New</XDSBadge>}>
- Settings
-</XDSButton>
-```
-
-`endSlot` is ignored for icon-only buttons (when `icon` is provided without `children`) to preserve the square aspect ratio. The endSlot is wrapped in a container that inherits the button's text color (`color: inherit`), so `<XDSIcon>` elements will automatically match the button variant's color (e.g., white text on `primary`/`destructive` variants) without needing an explicit `color` prop.
-
-## Implementation Notes
-
-- `XDSButtonVariant` type is derived from the `variants` StyleX object using `keyof typeof variants`
-- Hover/active states use `backgroundImage` with `linear-gradient` to layer overlay colors on top of the base background
-- Destructive variant uses `colorTokens.negative` for its focus outline color
-- `endSlot` is wrapped in a `<span>` with `color: inherit` so icons/badges match the button's text color across all variants
diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsx
index 47092a38d9..c9f1753f38 100644
--- a/packages/core/src/Button/XDSButton.tsx
+++ b/packages/core/src/Button/XDSButton.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSButton.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Button/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Button/Button.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Button/XDSButton.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Button/index.ts (exports if types change)
* - /apps/storybook/stories/Button.stories.tsx (storybook stories)
diff --git a/packages/core/src/Button/index.ts b/packages/core/src/Button/index.ts
index ce5abca43c..b719630a87 100644
--- a/packages/core/src/Button/index.ts
+++ b/packages/core/src/Button/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSButton, XDSButtonProps, XDSButtonVariant
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Button/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Button/Button.doc.mjs
*/
export {XDSButton} from './XDSButton';
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
new file mode 100644
index 0000000000..eed8f94535
--- /dev/null
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -0,0 +1,133 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Calendar',
+ description:
+ 'XDSCalendar component for date selection with single and range modes.',
+ features: [
+ "Selection Modes: 'single' (default) and 'range'",
+ 'Multi-Month Display: Show 1 or 2 months side by side',
+ 'Date Constraints: min, max, and custom dateConstraints functions',
+ 'Locale Options: weekStartsOn for configurable first day of week',
+ 'Week Numbers: Optional ISO week number column',
+ 'Controlled/Uncontrolled: Supports both patterns via value/defaultValue',
+ ],
+ examples: [
+ {
+ label: 'Single date selection',
+ code: `<XDSCalendar
+ value="2026-01-28"
+ onChange={(value, valueAsDate) => console.log(value)}
+/>`,
+ },
+ {
+ label: 'Range selection',
+ code: `<XDSCalendar
+ mode="range"
+ value={{ start: "2026-01-28", end: "2026-02-05" }}
+ onChange={(range) => console.log(range.start, range.end)}
+/>`,
+ },
+ {
+ label: 'Two months with constraints',
+ code: `<XDSCalendar
+ numberOfMonths={2}
+ min="2026-01-01"
+ max="2026-12-31"
+ weekStartsOn={1}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'mode',
+ type: "'single' | 'range'",
+ description: 'Selection mode.',
+ default: "'single'",
+ },
+ {
+ name: 'value',
+ type: 'ISODateString | DateRange',
+ description: 'Controlled selected value.',
+ },
+ {
+ name: 'defaultValue',
+ type: 'ISODateString | DateRange',
+ description: 'Uncontrolled default value.',
+ },
+ {
+ name: 'onChange',
+ type: 'Function',
+ description: 'Selection callback.',
+ },
+ {
+ name: 'numberOfMonths',
+ type: '1 | 2',
+ description: 'Number of months to display.',
+ default: '1',
+ },
+ {
+ name: 'min',
+ type: 'ISODateString',
+ description: 'Minimum selectable date.',
+ },
+ {
+ name: 'max',
+ type: 'ISODateString',
+ description: 'Maximum selectable date.',
+ },
+ {
+ name: 'dateConstraints',
+ type: 'Array<(date: Date) => boolean>',
+ description: 'Custom constraint functions.',
+ },
+ {
+ name: 'focusDate',
+ type: 'ISODateString',
+ description: 'Controlled visible month.',
+ },
+ {
+ name: 'onFocusDateChange',
+ type: '(focusDate: ISODateString) => void',
+ description: 'Navigation callback.',
+ },
+ {
+ name: 'hasOutsideDays',
+ type: 'boolean',
+ description: 'Show days from adjacent months.',
+ default: 'true',
+ },
+ {
+ name: 'hasWeekNumbers',
+ type: 'boolean',
+ description: 'Show ISO week numbers.',
+ default: 'false',
+ },
+ {
+ name: 'hasVariableRowCount',
+ type: 'boolean',
+ description: 'Variable vs fixed 6-row grid.',
+ default: 'false',
+ },
+ {
+ name: 'weekStartsOn',
+ type: '0 | 1 | 2 | 3 | 4 | 5 | 6',
+ description: 'First day of week (0=Sunday).',
+ default: '0',
+ },
+ ],
+ theming: {
+ componentKey: 'calendar',
+ surfaces: [
+ {
+ name: 'root',
+ description: 'Root container styles',
+ },
+ ],
+ },
+ notes: [
+ 'ISODateString type: `${number}${number}${number}${number}-${number}${number}-${number}${number}`',
+ 'DayOfWeek type: 0 | 1 | 2 | 3 | 4 | 5 | 6',
+ 'DateRange interface: { start: ISODateString; end: ISODateString }',
+ ],
+};
diff --git a/packages/core/src/Calendar/README.md b/packages/core/src/Calendar/README.md
deleted file mode 100644
index b1ad07069d..0000000000
--- a/packages/core/src/Calendar/README.md
+++ /dev/null
@@ -1,103 +0,0 @@
-# Calendar
-
-XDSCalendar component for date selection with single and range modes.
-
-## Features
-
-- **Selection Modes**: `single` (default) and `range`
-- **Multi-Month Display**: Show 1 or 2 months side by side
-- **Date Constraints**: `min`, `max`, and custom `dateConstraints` functions
-- **Locale Options**: `weekStartsOn` for configurable first day of week
-- **Week Numbers**: Optional ISO week number column
-- **Controlled/Uncontrolled**: Supports both patterns via `value`/`defaultValue`
-
-## Usage
-
-```tsx
-import { XDSCalendar } from '@xds/core/Calendar';
-
-// Single date selection
-<XDSCalendar
- value="2026-01-28"
- onChange={(value, valueAsDate) => console.log(value)}
-/>
-
-// Range selection
-<XDSCalendar
- mode="range"
- value={{ start: "2026-01-28", end: "2026-02-05" }}
- onChange={(range) => console.log(range.start, range.end)}
-/>
-
-// Two months with constraints
-<XDSCalendar
- numberOfMonths={2}
- min="2026-01-01"
- max="2026-12-31"
- weekStartsOn={1}
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------------- | ------------------------------------ | ---------- | ------------------------------ |
-| `mode` | `'single' \| 'range'` | `'single'` | Selection mode |
-| `value` | `ISODateString \| DateRange` | — | Controlled selected value |
-| `defaultValue` | `ISODateString \| DateRange` | — | Uncontrolled default value |
-| `onChange` | `Function` | — | Selection callback |
-| `numberOfMonths` | `1 \| 2` | `1` | Number of months to display |
-| `min` | `ISODateString` | — | Minimum selectable date |
-| `max` | `ISODateString` | — | Maximum selectable date |
-| `dateConstraints` | `Array<(date: Date) => boolean>` | — | Custom constraint functions |
-| `focusDate` | `ISODateString` | — | Controlled visible month |
-| `onFocusDateChange` | `(focusDate: ISODateString) => void` | — | Navigation callback |
-| `hasOutsideDays` | `boolean` | `true` | Show days from adjacent months |
-| `hasWeekNumbers` | `boolean` | `false` | Show ISO week numbers |
-| `hasVariableRowCount` | `boolean` | `false` | Variable vs fixed 6-row grid |
-| `weekStartsOn` | `0-6` | `0` | First day of week (0=Sunday) |
-
-## Types
-
-```typescript
-type ISODateString =
- `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
-
-type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
-
-interface DateRange {
- start: ISODateString;
- end: ISODateString;
-}
-```
-
-## Theming
-
-Themes can override `Calendar` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- calendar: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | --------------------- |
-| `root` | Root container styles |
-
-## Files
-
-| File | Role | Purpose |
-| -------------------- | ------ | ------------------------ |
-| XDSCalendar.tsx | Core | Component implementation |
-| XDSCalendar.test.tsx | Test | Unit tests |
-| index.ts | Export | Public API exports |
-| README.md | Docs | This documentation |
diff --git a/packages/core/src/Calendar/XDSCalendar.tsx b/packages/core/src/Calendar/XDSCalendar.tsx
index 1c5fce5ee8..60c663139b 100644
--- a/packages/core/src/Calendar/XDSCalendar.tsx
+++ b/packages/core/src/Calendar/XDSCalendar.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSCalendar.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Calendar/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Calendar/Calendar.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Calendar/XDSCalendar.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Calendar/index.ts (exports if types change)
* - /apps/storybook/stories/Calendar.stories.tsx (storybook stories)
diff --git a/packages/core/src/Calendar/index.ts b/packages/core/src/Calendar/index.ts
index 86dc69a2da..e3f7f8020f 100644
--- a/packages/core/src/Calendar/index.ts
+++ b/packages/core/src/Calendar/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSCalendar and related types
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Calendar/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Calendar/Calendar.doc.mjs
*/
export {XDSCalendar} from './XDSCalendar';
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
new file mode 100644
index 0000000000..f47f8a4636
--- /dev/null
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -0,0 +1,96 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Card',
+ description: 'Card container component with elevation and themed styling.',
+ features: [
+ 'Top-level container for elevated content',
+ 'Provides card-specific appearance: background, shadow, and border-radius',
+ 'Sets CSS variables for child layout components',
+ 'Supports optional full-bleed mode to remove internal padding for edge-to-edge content',
+ 'Composable with XDSLayout, XDSCollapsible, and XDSCollapsibleGroup',
+ ],
+ props: [
+ {
+ name: 'width',
+ type: 'SizeValue',
+ description: 'Width of the card (number = pixels, string = used as-is).',
+ },
+ {
+ name: 'height',
+ type: 'SizeValue',
+ description: 'Height of the card (number = pixels, string = used as-is).',
+ },
+ {
+ name: 'maxWidth',
+ type: 'SizeValue',
+ description: 'Maximum width of the card.',
+ },
+ {
+ name: 'minHeight',
+ type: 'SizeValue',
+ description: 'Minimum height of the card.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content to render inside the card.',
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description: 'Removes internal padding for edge-to-edge content.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic card with layout',
+ code: `<XDSCard width={400} height={300}>
+ <XDSLayout
+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Content</XDSLayoutContent>}
+ footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}
+ />
+</XDSCard>`,
+ },
+ {
+ label: 'Simple content',
+ code: `<XDSCard>
+ <p>Card content with default padding</p>
+</XDSCard>`,
+ },
+ {
+ label: 'Collapsible card',
+ code: `<XDSCard>
+ <XDSCollapsible trigger="Details">
+ <p>This content can be collapsed</p>
+ </XDSCollapsible>
+</XDSCard>`,
+ },
+ {
+ label: 'Accordion of cards',
+ code: `<XDSCollapsibleGroup type="single" defaultValue="general">
+ <XDSVStack gap="space2">
+ <XDSCard>
+ <XDSCollapsible trigger="General" value="general">
+ <GeneralSettings />
+ </XDSCollapsible>
+ </XDSCard>
+ <XDSCard>
+ <XDSCollapsible trigger="Advanced" value="advanced">
+ <AdvancedSettings />
+ </XDSCollapsible>
+ </XDSCard>
+ </XDSVStack>
+</XDSCollapsibleGroup>`,
+ },
+ ],
+ theming: {
+ componentKey: 'card',
+ surfaces: [
+ {name: 'container', description: 'Outer card wrapper element'},
+ {name: 'content', description: 'Inner content area with padding'},
+ ],
+ },
+};
diff --git a/packages/core/src/Card/README.md b/packages/core/src/Card/README.md
deleted file mode 100644
index 1dae5871e1..0000000000
--- a/packages/core/src/Card/README.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Card
-
-Card container component with elevation and themed styling.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Overview
-
-XDSCard is a top-level container for elevated content. It provides card-specific appearance (background, shadow, border-radius) and sets CSS variables for child layout components.
-
-## Import
-
-```tsx
-import {XDSCard} from '@xds/core/Card';
-```
-
-## Usage
-
-```tsx
-// Basic card with layout
-<XDSCard width={400} height={300}>
- <XDSLayout
- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
- content={<XDSLayoutContent>Content</XDSLayoutContent>}
- footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}
- />
-</XDSCard>
-
-// Simple content
-<XDSCard>
- <p>Card content with default padding</p>
-</XDSCard>
-
-// Collapsible card — compose XDSCollapsible inside
-<XDSCard>
- <XDSCollapsible trigger="Details">
- <p>This content can be collapsed</p>
- </XDSCollapsible>
-</XDSCard>
-
-// Accordion of cards
-<XDSCollapsibleGroup type="single" defaultValue="general">
- <XDSVStack gap="space2">
- <XDSCard>
- <XDSCollapsible trigger="General" value="general">
- <GeneralSettings />
- </XDSCollapsible>
- </XDSCard>
- <XDSCard>
- <XDSCollapsible trigger="Advanced" value="advanced">
- <AdvancedSettings />
- </XDSCollapsible>
- </XDSCard>
- </XDSVStack>
-</XDSCollapsibleGroup>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------- | ----------- | ------- | ------------------------------------------------- |
-| `width` | `SizeValue` | — | Width (number = pixels, string = as-is) |
-| `height` | `SizeValue` | — | Height (number = pixels, string = as-is) |
-| `maxWidth` | `SizeValue` | — | Maximum width |
-| `minHeight` | `SizeValue` | — | Minimum height |
-| `children` | `ReactNode` | — | Content to render inside the card |
-| `isFullBleed` | `boolean` | `false` | Removes internal padding for edge-to-edge content |
-
-## Theming
-
-```tsx
-declare module '@xds/core' {
- interface ComponentStyles {
- card?: {
- container?: StyleXStyles;
- content?: StyleXStyles;
- };
- }
-}
-```
-
-## Files
-
-| File | Role | Purpose |
-| ------------- | --------- | ----------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSCard.tsx` | Component | Card container implementation |
-| `README.md` | Docs | This documentation |
diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsx
index ee8d506239..44bdd649ae 100644
--- a/packages/core/src/Card/XDSCard.tsx
+++ b/packages/core/src/Card/XDSCard.tsx
@@ -5,7 +5,7 @@
* @position Core card container component
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Card/README.md (props table, features)
+ * - /packages/core/src/Card/Card.doc.mjs (props table, features)
* - /packages/core/src/Card/index.ts (exports if types change)
* - /apps/storybook/stories/Card.stories.tsx (storybook stories)
*/
diff --git a/packages/core/src/Card/index.ts b/packages/core/src/Card/index.ts
index af25b12d5e..ae2ecec091 100644
--- a/packages/core/src/Card/index.ts
+++ b/packages/core/src/Card/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSCard component and types
* @position Entry point for @xds/core/Card module
*
- * SYNC: When modified, update /packages/core/src/Card/README.md
+ * SYNC: When modified, update /packages/core/src/Card/Card.doc.mjs
*/
export {XDSCard} from './XDSCard';
diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjs
new file mode 100644
index 0000000000..9dfd0581cc
--- /dev/null
+++ b/packages/core/src/Center/Center.doc.mjs
@@ -0,0 +1,69 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Center',
+ description: 'Centers children horizontally and/or vertically using flexbox.',
+ features: [
+ 'Supports centering on both axes, horizontal only, or vertical only',
+ 'Inline-flex mode for centering inline content such as text and icons',
+ 'Accepts explicit width and height to size the container',
+ ],
+ examples: [
+ {
+ label: 'Center both axes (default)',
+ code: `<XDSCenter width={300} height={200}>
+ <Content />
+</XDSCenter>`,
+ },
+ {
+ label: 'Center horizontally only',
+ code: `<XDSCenter axis="horizontal">
+ <Logo />
+</XDSCenter>`,
+ },
+ {
+ label: 'Inline centering for icons',
+ code: `<XDSCenter isInline>
+ <XDSIcon icon={StarIcon} />
+</XDSCenter>`,
+ },
+ ],
+ props: [
+ {
+ name: 'axis',
+ type: "'both' | 'horizontal' | 'vertical'",
+ description: 'Which direction(s) to center.',
+ default: "'both'",
+ },
+ {
+ name: 'width',
+ type: 'number | string',
+ description: 'Container width (px or CSS value).',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Container height (px or CSS value).',
+ },
+ {
+ name: 'isInline',
+ type: 'boolean',
+ description: 'Use inline-flex (useful for text/icons).',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content to center.',
+ },
+ ],
+ theming: {
+ componentKey: 'center',
+ surfaces: [
+ {
+ name: 'root',
+ description: 'Root container styles',
+ },
+ ],
+ },
+};
diff --git a/packages/core/src/Center/README.md b/packages/core/src/Center/README.md
deleted file mode 100644
index 3bf10a969f..0000000000
--- a/packages/core/src/Center/README.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# XDSCenter
-
-Centers children horizontally and/or vertically using flexbox.
-
-## Import
-
-```tsx
-import {XDSCenter} from '@xds/core/Center';
-```
-
-## Usage
-
-```tsx
-// Center both axes (default)
-<XDSCenter width={300} height={200}>
- <Content />
-</XDSCenter>
-
-// Center horizontally only
-<XDSCenter axis="horizontal">
- <Logo />
-</XDSCenter>
-
-// Inline centering for icons
-<XDSCenter isInline>
- <XDSIcon icon={StarIcon} />
-</XDSCenter>
-```
-
-## Theming
-
-Themes can override `Center` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- center: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | --------------------- |
-| `root` | Root container styles |
-
-## Props
-
-| Prop | Type | Default | Description |
-| ---------- | -------------------------------------------- | -------- | -------------------------------------------------- |
-| `axis` | `'both' \| 'horizontal' \| 'vertical'` | `'both'` | Which direction(s) to center |
-| `width` | `number \| string` | — | Container width (px or CSS value) |
-| `height` | `number \| string` | — | Container height (px or CSS value) |
-| `isInline` | `boolean` | `false` | Use inline-flex (useful for text/icons) |
-| `children` | `ReactNode` | — | Content to center |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
diff --git a/packages/core/src/Center/XDSCenter.tsx b/packages/core/src/Center/XDSCenter.tsx
index db55d72a4e..77c00ff4bb 100644
--- a/packages/core/src/Center/XDSCenter.tsx
+++ b/packages/core/src/Center/XDSCenter.tsx
@@ -5,7 +5,7 @@
* @position Center component for centering children horizontally/vertically
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Center/README.md
+ * - /packages/core/src/Center/Center.doc.mjs
* - /packages/core/src/Center/XDSCenter.test.tsx
* - /apps/storybook/stories/Center.stories.tsx
*/
diff --git a/packages/core/src/Center/index.ts b/packages/core/src/Center/index.ts
index 64481b735a..0a9f6b9a85 100644
--- a/packages/core/src/Center/index.ts
+++ b/packages/core/src/Center/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSCenter and types for @xds/core/Center
* @position Entry point for Center component
*
- * SYNC: When modified, update /packages/core/src/Center/README.md
+ * SYNC: When modified, update /packages/core/src/Center/Center.doc.mjs
*/
export {XDSCenter} from './XDSCenter';
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
new file mode 100644
index 0000000000..737c8c85cc
--- /dev/null
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -0,0 +1,110 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CheckboxInput',
+ description: 'A checkbox input component for toggling boolean values.',
+ features: [
+ 'Accessible — always includes a label (can be visually hidden)',
+ 'Indeterminate state — supports indeterminate state for "select all" patterns',
+ 'Descriptions — optional description text below the label',
+ 'Custom styling — uses StyleX with XDS design tokens',
+ 'Disabled state — full support for disabled state styling',
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the checkbox (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Whether to visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'value',
+ type: "boolean | 'indeterminate'",
+ description:
+ 'Whether the checkbox is checked, unchecked, or indeterminate.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(checked: boolean, e: ChangeEvent) => void',
+ description: 'Callback fired when the checkbox state changes.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the checkbox is disabled.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSCheckboxInput
+ label="Accept terms and conditions"
+ value={accepted}
+ onChange={setAccepted}
+/>`,
+ },
+ {
+ label: 'With description',
+ code: `<XDSCheckboxInput
+ label="Subscribe to newsletter"
+ description="Receive weekly updates about new features"
+ value={subscribed}
+ onChange={setSubscribed}
+/>`,
+ },
+ {
+ label: 'Indeterminate state',
+ code: `<XDSCheckboxInput
+ label="Select all items"
+ value="indeterminate"
+ onChange={setSelectAll}
+/>`,
+ },
+ {
+ label: 'Hidden label',
+ code: `<XDSCheckboxInput
+ label="Select row"
+ isLabelHidden
+ value={selected}
+ onChange={setSelected}
+/>`,
+ },
+ {
+ label: 'Disabled',
+ code: `<XDSCheckboxInput
+ label="Premium feature"
+ description="Upgrade to enable this option"
+ value={false}
+ onChange={() => {}}
+ isDisabled
+/>`,
+ },
+ ],
+ theming: {
+ componentKey: 'checkboxInput',
+ surfaces: [
+ {name: 'root', description: 'Root container styles'},
+ {name: 'checkbox', description: 'Visual checkbox element styles'},
+ ],
+ },
+ notes: [
+ 'Uses a hidden native <input type="checkbox"> for accessibility with a custom visual checkbox overlay.',
+ 'The visual checkbox responds to hover, focus, and checked states via sibling selectors in CSS.',
+ 'Label is clickable and properly associated with the input via htmlFor/id.',
+ 'Focus outline uses the standard XDS focus outline token.',
+ ],
+};
diff --git a/packages/core/src/CheckboxInput/README.md b/packages/core/src/CheckboxInput/README.md
deleted file mode 100644
index b590ed4f53..0000000000
--- a/packages/core/src/CheckboxInput/README.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# CheckboxInput
-
-A checkbox input component for toggling boolean values.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Accessible**: Always includes a label (can be visually hidden)
-- **Indeterminate state**: Supports indeterminate state for "select all" patterns
-- **Descriptions**: Optional description text below the label
-- **Custom styling**: Uses StyleX with XDS design tokens
-- **Disabled state**: Full support for disabled state styling
-
-## Usage
-
-```tsx
-import { XDSCheckboxInput } from '@xds/core/CheckboxInput';
-
-// Basic usage
-<XDSCheckboxInput
- label="Accept terms and conditions"
- value={accepted}
- onChange={setAccepted}
-/>
-
-// With description
-<XDSCheckboxInput
- label="Subscribe to newsletter"
- description="Receive weekly updates about new features"
- value={subscribed}
- onChange={setSubscribed}
-/>
-
-// Indeterminate state (e.g., for "select all" when some items are selected)
-<XDSCheckboxInput
- label="Select all items"
- value="indeterminate"
- onChange={setSelectAll}
-/>
-
-// Hidden label (still accessible)
-<XDSCheckboxInput
- label="Select row"
- isLabelHidden
- value={selected}
- onChange={setSelected}
-/>
-
-// Disabled
-<XDSCheckboxInput
- label="Premium feature"
- description="Upgrade to enable this option"
- value={false}
- onChange={() => {}}
- isDisabled
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------- | -------------------------------------------- | ------- | --------------------------------------------------------------- |
-| `label` | `string` | — | Label text for the checkbox (always rendered for accessibility) |
-| `isLabelHidden` | `boolean` | `false` | Whether to visually hide the label |
-| `description` | `string` | — | Description text displayed below the label |
-| `value` | `boolean \| 'indeterminate'` | — | Whether the checkbox is checked, unchecked, or indeterminate |
-| `onChange` | `(checked: boolean, e: ChangeEvent) => void` | — | Callback fired when the checkbox state changes |
-| `isDisabled` | `boolean` | `false` | Whether the checkbox is disabled |
-
-## Theming
-
-Themes can override `CheckboxInput` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- checkboxInput: {
- root: myStyles,
- checkbox: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ---------- | ------------------------------ |
-| `root` | Root container styles |
-| `checkbox` | Visual checkbox element styles |
-
-## Files
-
-| File | Role | Purpose |
-| --------------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSCheckboxInput.tsx` | Core | Component implementation |
-| `XDSCheckboxInput.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Uses a hidden native `<input type="checkbox">` for accessibility with a custom visual checkbox overlay
-- The visual checkbox responds to hover, focus, and checked states via sibling selectors in CSS
-- Label is clickable and properly associated with the input via `htmlFor`/`id`
-- Focus outline uses the standard XDS focus outline token
diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
index 12e0712d28..f1cdc40bb7 100644
--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSCheckboxInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/CheckboxInput/README.md (props table, features, implementation notes)
+ * - /packages/core/src/CheckboxInput/CheckboxInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/CheckboxInput/XDSCheckboxInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/CheckboxInput/index.ts (exports if types change)
* - /apps/storybook/stories/CheckboxInput.stories.tsx (storybook stories)
diff --git a/packages/core/src/CheckboxInput/index.ts b/packages/core/src/CheckboxInput/index.ts
index e38b33de48..88840283f2 100644
--- a/packages/core/src/CheckboxInput/index.ts
+++ b/packages/core/src/CheckboxInput/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSCheckboxInput, XDSCheckboxInputProps, XDSCheckboxInputSize
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/CheckboxInput/README.md
+ * SYNC: When modified, update this header and /packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
*/
export {XDSCheckboxInput} from './XDSCheckboxInput';
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
new file mode 100644
index 0000000000..1f4d016be5
--- /dev/null
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -0,0 +1,216 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Collapsible',
+ description: 'Collapsible content primitive and group coordination.',
+ features: [
+ 'XDSCollapsible makes any content collapsible — a trigger toggles visibility of the content area',
+ 'Handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator',
+ 'Supports uncontrolled (defaultIsOpen), controlled (isOpen / onOpenChange), and group-coordinated modes',
+ 'XDSCollapsibleGroup coordinates multiple XDSCollapsible instances so only one (single mode) or multiple (multiple mode) can be open at a time',
+ 'XDSCollapsibleGroup renders no wrapper DOM element',
+ 'When inside a group, XDSCollapsible defers open/close state to the group context via the value prop',
+ ],
+ keyboard:
+ 'Enter or Space activates the trigger button to toggle open/close state.',
+ accessibility: [
+ 'Trigger renders as a <button> with aria-expanded reflecting the current open state',
+ 'A chevron indicator provides a visual affordance for the expanded/collapsed state',
+ ],
+ notes: [
+ 'XDSCollapsible manages its own open/close state by default (uncontrolled)',
+ 'When nested inside an XDSCollapsibleGroup with a matching value prop, it defers to the group context',
+ 'XDSCollapsibleGroup provides context with isOpen(value) and toggle(value) methods',
+ 'The group renders no wrapper DOM — layout is the responsibility of the consumer (e.g. XDSVStack)',
+ ],
+ examples: [
+ {
+ label: 'Standalone collapsible',
+ code: `// Inside a card
+<XDSCard>
+ <XDSCollapsible trigger="Details">
+ <p>This content can be collapsed</p>
+ </XDSCollapsible>
+</XDSCard>
+
+// Starts collapsed
+<XDSCard>
+ <XDSCollapsible trigger="Advanced" defaultIsOpen={false}>
+ <p>Hidden by default</p>
+ </XDSCollapsible>
+</XDSCard>
+
+// Controlled
+<XDSCard>
+ <XDSCollapsible trigger="Settings" isOpen={open} onOpenChange={setOpen}>
+ <p>Controlled externally</p>
+ </XDSCollapsible>
+</XDSCard>
+
+// Without a card — works anywhere
+<XDSCollapsible trigger="Show more">
+ <p>Expandable content</p>
+</XDSCollapsible>`,
+ },
+ {
+ label: 'Coordinated group — single mode (accordion)',
+ code: `// Single mode — only one open at a time (FAQ, settings panels)
+<XDSCollapsibleGroup type="single" defaultValue="general">
+ <XDSVStack gap="space2">
+ <XDSCard>
+ <XDSCollapsible trigger="General Settings" value="general">
+ <GeneralContent />
+ </XDSCollapsible>
+ </XDSCard>
+ <XDSCard>
+ <XDSCollapsible trigger="Advanced Settings" value="advanced">
+ <AdvancedContent />
+ </XDSCollapsible>
+ </XDSCard>
+ </XDSVStack>
+</XDSCollapsibleGroup>`,
+ },
+ {
+ label: 'Coordinated group — multiple mode',
+ code: `// Multiple mode — any number open
+<XDSCollapsibleGroup type="multiple" defaultValue={["s1", "s2"]}>
+ <XDSVStack gap="space2">
+ <XDSCard>
+ <XDSCollapsible trigger="Section 1" value="s1">...</XDSCollapsible>
+ </XDSCard>
+ <XDSCard>
+ <XDSCollapsible trigger="Section 2" value="s2">...</XDSCollapsible>
+ </XDSCard>
+ </XDSVStack>
+</XDSCollapsibleGroup>`,
+ },
+ {
+ label: 'With Layout (structured header)',
+ code: `<XDSCard>
+ <XDSCollapsible trigger="Report Details" value="report">
+ <XDSLayout
+ content={<XDSLayoutContent>Report body</XDSLayoutContent>}
+ footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}
+ />
+ </XDSCollapsible>
+</XDSCard>`,
+ },
+ ],
+ components: [
+ {
+ name: 'XDSCollapsible',
+ description:
+ 'A primitive that makes any content collapsible — a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',
+ props: [
+ {
+ name: 'trigger',
+ type: 'ReactNode',
+ description: 'Content shown in the trigger area (always visible).',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content that collapses and expands.',
+ },
+ {
+ name: 'defaultIsOpen',
+ type: 'boolean',
+ description: 'Default open state (uncontrolled).',
+ default: 'true',
+ },
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Controlled open state.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback invoked when the open state changes.',
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description:
+ 'Identifier used for group coordination. Required when placed inside an XDSCollapsibleGroup.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSCollapsible trigger="Details">
+ <p>This content can be collapsed</p>
+</XDSCollapsible>`,
+ },
+ {
+ label: 'Starts collapsed',
+ code: `<XDSCollapsible trigger="Advanced" defaultIsOpen={false}>
+ <p>Hidden by default</p>
+</XDSCollapsible>`,
+ },
+ {
+ label: 'Controlled',
+ code: `<XDSCollapsible trigger="Settings" isOpen={open} onOpenChange={setOpen}>
+ <p>Controlled externally</p>
+</XDSCollapsible>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSCollapsibleGroup',
+ description:
+ 'Coordinates multiple XDSCollapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element.',
+ props: [
+ {
+ name: 'type',
+ type: "'single' | 'multiple'",
+ description: 'Whether one or many items can be open simultaneously.',
+ default: "'single'",
+ },
+ {
+ name: 'defaultValue',
+ type: 'string | string[]',
+ description:
+ 'Default open item(s) for uncontrolled usage. Use a string for single mode and an array for multiple mode.',
+ },
+ {
+ name: 'value',
+ type: 'string | string[]',
+ description: 'Controlled open item(s).',
+ },
+ {
+ name: 'onChange',
+ type: '(value: string | string[]) => void',
+ description: 'Callback invoked when the set of open items changes.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSCollapsible instances to coordinate.',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'Single mode (accordion)',
+ code: `<XDSCollapsibleGroup type="single" defaultValue="general">
+ <XDSCollapsible trigger="General" value="general">
+ <p>General settings</p>
+ </XDSCollapsible>
+ <XDSCollapsible trigger="Advanced" value="advanced">
+ <p>Advanced settings</p>
+ </XDSCollapsible>
+</XDSCollapsibleGroup>`,
+ },
+ {
+ label: 'Multiple mode',
+ code: `<XDSCollapsibleGroup type="multiple" defaultValue={["s1", "s2"]}>
+ <XDSCollapsible trigger="Section 1" value="s1">...</XDSCollapsible>
+ <XDSCollapsible trigger="Section 2" value="s2">...</XDSCollapsible>
+</XDSCollapsibleGroup>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Collapsible/README.md b/packages/core/src/Collapsible/README.md
deleted file mode 100644
index 61133ba78d..0000000000
--- a/packages/core/src/Collapsible/README.md
+++ /dev/null
@@ -1,152 +0,0 @@
-# Collapsible
-
-Collapsible content primitive and group coordination.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Overview
-
-XDSCollapsible is a primitive that makes any content collapsible — a trigger toggles visibility of the content area. It handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator.
-
-XDSCollapsibleGroup coordinates multiple XDSCollapsible instances so only one (or multiple) can be open at a time. It renders no wrapper DOM.
-
-## Import
-
-```tsx
-import {XDSCollapsible, XDSCollapsibleGroup} from '@xds/core/Collapsible';
-```
-
-## Usage
-
-### Standalone collapsible
-
-```tsx
-// Inside a card
-<XDSCard>
- <XDSCollapsible trigger="Details">
- <p>This content can be collapsed</p>
- </XDSCollapsible>
-</XDSCard>
-
-// Starts collapsed
-<XDSCard>
- <XDSCollapsible trigger="Advanced" defaultIsOpen={false}>
- <p>Hidden by default</p>
- </XDSCollapsible>
-</XDSCard>
-
-// Controlled
-<XDSCard>
- <XDSCollapsible trigger="Settings" isOpen={open} onOpenChange={setOpen}>
- <p>Controlled externally</p>
- </XDSCollapsible>
-</XDSCard>
-
-// Without a card — works anywhere
-<XDSCollapsible trigger="Show more">
- <p>Expandable content</p>
-</XDSCollapsible>
-```
-
-### Coordinated group (accordion pattern)
-
-```tsx
-// Single mode — only one open at a time (FAQ, settings panels)
-<XDSCollapsibleGroup type="single" defaultValue="general">
- <XDSVStack gap="space2">
- <XDSCard>
- <XDSCollapsible trigger="General Settings" value="general">
- <GeneralContent />
- </XDSCollapsible>
- </XDSCard>
- <XDSCard>
- <XDSCollapsible trigger="Advanced Settings" value="advanced">
- <AdvancedContent />
- </XDSCollapsible>
- </XDSCard>
- </XDSVStack>
-</XDSCollapsibleGroup>
-
-// Multiple mode — any number open
-<XDSCollapsibleGroup type="multiple" defaultValue={["s1", "s2"]}>
- <XDSVStack gap="space2">
- <XDSCard>
- <XDSCollapsible trigger="Section 1" value="s1">...</XDSCollapsible>
- </XDSCard>
- <XDSCard>
- <XDSCollapsible trigger="Section 2" value="s2">...</XDSCollapsible>
- </XDSCard>
- </XDSVStack>
-</XDSCollapsibleGroup>
-```
-
-### With Layout (structured header)
-
-```tsx
-<XDSCard>
- <XDSCollapsible trigger="Report Details" value="report">
- <XDSLayout
- content={<XDSLayoutContent>Report body</XDSLayoutContent>}
- footer={<XDSLayoutFooter hasDivider>Actions</XDSLayoutFooter>}
- />
- </XDSCollapsible>
-</XDSCard>
-```
-
-## Props
-
-### XDSCollapsible
-
-```tsx
-<XDSCollapsible trigger="Details">
- <p>This content can be collapsed</p>
-</XDSCollapsible>
-```
-
-| Prop | Type | Default | Description |
-| --------------- | --------------------------- | ------- | -------------------------------------------------- |
-| `trigger` | `ReactNode` | — | Content shown in the trigger area (always visible) |
-| `children` | `ReactNode` | — | Content that collapses/expands |
-| `defaultIsOpen` | `boolean` | `true` | Default open state (uncontrolled) |
-| `isOpen` | `boolean` | — | Controlled open state |
-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when open state changes |
-| `value` | `string` | — | Identifier for group coordination |
-
-### XDSCollapsibleGroup
-
-```tsx
-<XDSCollapsibleGroup type="single" defaultValue="general">
- <XDSCollapsible trigger="General" value="general">
- <p>General settings</p>
- </XDSCollapsible>
- <XDSCollapsible trigger="Advanced" value="advanced">
- <p>Advanced settings</p>
- </XDSCollapsible>
-</XDSCollapsibleGroup>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ------------------------------------- | ---------- | -------------------------------------- |
-| `type` | `"single" \| "multiple"` | `"single"` | Whether one or many items can be open |
-| `defaultValue` | `string \| string[]` | — | Default open item(s) — uncontrolled |
-| `value` | `string \| string[]` | — | Controlled open item(s) |
-| `onChange` | `(value: string \| string[]) => void` | — | Callback when open items change |
-| `children` | `ReactNode` | — | XDSCollapsible instances to coordinate |
-
-## How It Works
-
-1. XDSCollapsible manages its own open/close state by default
-2. When inside an XDSCollapsibleGroup with a `value` prop, it defers to the group
-3. XDSCollapsibleGroup provides context with `isOpen(value)` and `toggle(value)` methods
-4. The trigger renders as a button with `aria-expanded` and a chevron indicator
-
-## Files
-
-| File | Role | Purpose |
-| -------------------------------- | --------- | ------------------------------- |
-| `index.ts` | Entry | Exports components, hook, types |
-| `XDSCollapsibleGroup.tsx` | Component | Collapsible group provider |
-| `XDSCollapsibleGroupContext.tsx` | Context | React context definition |
-| `useXDSCollapsible.ts` | Hook | Collapsible state management |
-| `XDSCollapsibleGroup.test.tsx` | Tests | Unit tests |
-| `README.md` | Docs | This documentation |
diff --git a/packages/core/src/Collapsible/XDSCollapsible.tsx b/packages/core/src/Collapsible/XDSCollapsible.tsx
index 04ee7a6ea6..3ba15d07cb 100644
--- a/packages/core/src/Collapsible/XDSCollapsible.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsible.tsx
@@ -12,7 +12,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Collapsible/index.ts (exports)
- * - /packages/core/src/Collapsible/README.md
+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs
* - /apps/storybook/stories/Collapsible.stories.tsx
*/
diff --git a/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx b/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx
index 8765412320..8185c6c673 100644
--- a/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx
@@ -13,7 +13,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx (context type)
- * - /packages/core/src/Collapsible/README.md
+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs
* - /packages/core/src/Collapsible/index.ts (exports)
* - /apps/storybook/stories/Collapsible.stories.tsx
*/
diff --git a/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx b/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx
index de70c4668a..30ba9f106a 100644
--- a/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsibleGroupContext.tsx
@@ -6,7 +6,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Collapsible/XDSCollapsibleGroup.tsx (provider)
- * - /packages/core/src/Collapsible/README.md
+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs
*/
'use client';
diff --git a/packages/core/src/Collapsible/index.ts b/packages/core/src/Collapsible/index.ts
index e3dad11eaf..e20a08bd69 100644
--- a/packages/core/src/Collapsible/index.ts
+++ b/packages/core/src/Collapsible/index.ts
@@ -4,7 +4,7 @@
* @output Exports components, hook, and types
* @position Entry point for @xds/core/Collapsible module
*
- * SYNC: When modified, update /packages/core/src/Collapsible/README.md
+ * SYNC: When modified, update /packages/core/src/Collapsible/Collapsible.doc.mjs
*/
export {XDSCollapsible} from './XDSCollapsible';
diff --git a/packages/core/src/Collapsible/useXDSCollapsible.ts b/packages/core/src/Collapsible/useXDSCollapsible.ts
index c063870b98..2277d222c9 100644
--- a/packages/core/src/Collapsible/useXDSCollapsible.ts
+++ b/packages/core/src/Collapsible/useXDSCollapsible.ts
@@ -12,7 +12,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Collapsible/index.ts (exports)
- * - /packages/core/src/Collapsible/README.md
+ * - /packages/core/src/Collapsible/Collapsible.doc.mjs
*
* NOTE: Public hooks use the `useXDS` prefix per XDS naming conventions.
*/
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
new file mode 100644
index 0000000000..b68778c018
--- /dev/null
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -0,0 +1,168 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'DateInput',
+ description:
+ 'XDSDateInput component combining a text input with a calendar popover for date selection.',
+ features: [
+ 'Text Input — manual date entry with flexible parsing (supports various formats)',
+ 'Calendar Popover — click icon or use keyboard to open calendar picker',
+ 'Date Constraints — min, max, and custom dateConstraints functions',
+ 'Status Indicators — error, warning, and success states with messages',
+ 'Accessibility — full keyboard navigation, focus trapping, screen reader support',
+ 'Field Integration — built on XDSField for consistent label, description, and validation states',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSDateInput
+ label="Event date"
+ value={date}
+ onChange={setDate}
+/>`,
+ },
+ {
+ label: 'With constraints',
+ code: `<XDSDateInput
+ label="Departure date"
+ value={date}
+ onChange={setDate}
+ min="2026-01-01"
+ max="2026-12-31"
+ placeholder="Pick a date"
+/>`,
+ },
+ {
+ label: 'Two-month calendar',
+ code: `<XDSDateInput
+ label="Check-in date"
+ value={date}
+ onChange={setDate}
+ numberOfMonths={2}
+/>`,
+ },
+ {
+ label: 'With description and required',
+ code: `<XDSDateInput
+ label="Due date"
+ description="When should this task be completed?"
+ isRequired
+ value={date}
+ onChange={setDate}
+/>`,
+ },
+ {
+ label: 'With error status',
+ code: `<XDSDateInput
+ label="Event date"
+ value={date}
+ onChange={setDate}
+ status={{
+ type: 'error',
+ message: 'This date is not available',
+ }}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed below the label.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Show an "(optional)" indicator next to the label.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Mark the field as required.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disable the input and calendar.',
+ default: 'false',
+ },
+ {
+ name: 'value',
+ type: 'ISODateString',
+ description: 'Selected date in YYYY-MM-DD format.',
+ },
+ {
+ name: 'onChange',
+ type: '(value: ISODateString | undefined) => void',
+ description: 'Callback invoked when the selected date changes.',
+ },
+ {
+ name: 'min',
+ type: 'ISODateString',
+ description: 'Minimum selectable date (YYYY-MM-DD).',
+ },
+ {
+ name: 'max',
+ type: 'ISODateString',
+ description: 'Maximum selectable date (YYYY-MM-DD).',
+ },
+ {
+ name: 'dateConstraints',
+ type: 'Array<(date: Date) => boolean>',
+ description:
+ 'Array of custom constraint functions that disable specific dates.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown in the text input.',
+ default: "'Select a date'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size of the input control.',
+ default: "'md'",
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description:
+ 'Status indicator object for error, warning, or success states with a message.',
+ },
+ {
+ name: 'numberOfMonths',
+ type: '1 | 2',
+ description:
+ 'Number of months displayed simultaneously in the calendar popover.',
+ default: '1',
+ },
+ ],
+ keyboard:
+ 'Tab moves between input and calendar icon button; Enter/Space on icon opens the calendar and moves focus into it; Escape closes the calendar popover; Arrow keys navigate between days; Page Up/Down navigate between months.',
+ notes: [
+ 'The text input accepts multiple date formats: ISO (2026-01-28), US (01/28/2026, 1/28/2026), and written (Jan 28, 2026 / January 28 2026).',
+ 'Invalid input reverts to the previous valid value on blur.',
+ ],
+ theming: {
+ componentKey: 'dateInput',
+ surfaces: [
+ {name: 'wrapper', description: 'Input wrapper element styles'},
+ {name: 'input', description: 'Text input element styles'},
+ ],
+ },
+};
diff --git a/packages/core/src/DateInput/README.md b/packages/core/src/DateInput/README.md
deleted file mode 100644
index 9d78d2198c..0000000000
--- a/packages/core/src/DateInput/README.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# DateInput
-
-XDSDateInput component combining a text input with a calendar popover for date selection.
-
-## Features
-
-- **Text Input**: Manual date entry with flexible parsing (supports various formats)
-- **Calendar Popover**: Click icon or use keyboard to open calendar picker
-- **Date Constraints**: `min`, `max`, and custom `dateConstraints` functions
-- **Status Indicators**: Error, warning, and success states with messages
-- **Accessibility**: Full keyboard navigation, focus trapping, screen reader support
-- **Field Integration**: Built on XDSField for consistent label, description, and validation states
-
-## Usage
-
-```tsx
-import { XDSDateInput } from '@xds/core/DateInput';
-
-// Basic usage
-<XDSDateInput
- label="Event date"
- value={date}
- onChange={setDate}
-/>
-
-// With constraints
-<XDSDateInput
- label="Departure date"
- value={date}
- onChange={setDate}
- min="2026-01-01"
- max="2026-12-31"
- placeholder="Pick a date"
-/>
-
-// Two-month calendar
-<XDSDateInput
- label="Check-in date"
- value={date}
- onChange={setDate}
- numberOfMonths={2}
-/>
-
-// With description and required
-<XDSDateInput
- label="Due date"
- description="When should this task be completed?"
- isRequired
- value={date}
- onChange={setDate}
-/>
-
-// With error status
-<XDSDateInput
- label="Event date"
- value={date}
- onChange={setDate}
- status={{
- type: 'error',
- message: 'This date is not available',
- }}
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| ----------------- | --------------------------------------------- | ----------------- | ---------------------------------------- |
-| `label` | `string` | — | Label text (required) |
-| `isLabelHidden` | `boolean` | `false` | Visually hide label |
-| `description` | `string` | — | Helper text below label |
-| `isOptional` | `boolean` | `false` | Show "(optional)" indicator |
-| `isRequired` | `boolean` | `false` | Mark field as required |
-| `isDisabled` | `boolean` | `false` | Disable input and calendar |
-| `value` | `ISODateString` | — | Selected date (YYYY-MM-DD) |
-| `onChange` | `(value: ISODateString \| undefined) => void` | — | Selection callback |
-| `min` | `ISODateString` | — | Minimum selectable date |
-| `max` | `ISODateString` | — | Maximum selectable date |
-| `dateConstraints` | `Array<(date: Date) => boolean>` | — | Custom constraint functions |
-| `placeholder` | `string` | `"Select a date"` | Input placeholder text |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
-| `status` | `XDSInputStatus` | — | Status indicator (error/warning/success) |
-| `numberOfMonths` | `1 \| 2` | `1` | Months shown in calendar popover |
-
-## Keyboard Navigation
-
-- **Tab**: Move between input and calendar icon button
-- **Enter/Space** on icon: Open calendar and move focus into it
-- **Escape**: Close calendar popover
-- **Arrow keys** in calendar: Navigate between days
-- **Page Up/Down** in calendar: Navigate between months
-
-## Date Input Parsing
-
-The text input accepts various date formats:
-
-- ISO format: `2026-01-28`
-- US format: `01/28/2026`, `1/28/2026`
-- Written: `Jan 28, 2026`, `January 28 2026`
-
-Invalid input reverts to the previous valid value on blur.
-
-## Theming
-
-Themes can override `DateInput` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- dateInput: {
- wrapper: myStyles,
- input: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| --------- | ------------------------- |
-| `wrapper` | Input wrapper styles |
-| `input` | Text input element styles |
-
-## Files
-
-| File | Role | Purpose |
-| --------------------- | ------ | ------------------------ |
-| XDSDateInput.tsx | Core | Component implementation |
-| XDSDateInput.test.tsx | Test | Unit tests |
-| index.ts | Export | Public API exports |
-| README.md | Docs | This documentation |
diff --git a/packages/core/src/DateInput/XDSDateInput.tsx b/packages/core/src/DateInput/XDSDateInput.tsx
index ee037c9d6f..ddee3d25db 100644
--- a/packages/core/src/DateInput/XDSDateInput.tsx
+++ b/packages/core/src/DateInput/XDSDateInput.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSDateInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/DateInput/README.md (props table, features, implementation notes)
+ * - /packages/core/src/DateInput/DateInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/DateInput/XDSDateInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/DateInput/index.ts (exports if types change)
* - /apps/storybook/stories/DateInput.stories.tsx (storybook stories)
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
new file mode 100644
index 0000000000..5b2eba48cb
--- /dev/null
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -0,0 +1,258 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Dialog',
+ description:
+ 'Modal dialog using the native <dialog> element with automatic focus trapping, backdrop, and purpose-based dismissal control.',
+ features: [
+ "Native <dialog>: Uses the browser's built-in modal behavior via showModal()",
+ 'Automatic focus trap: Focus is trapped within the dialog when open (browser-native)',
+ 'Backdrop: Native ::backdrop pseudo-element with blur effect',
+ 'Variants: standard (configurable dimensions) and fullscreen (full viewport)',
+ 'Purpose-based dismissal: required, form, and info control Escape key and backdrop-click behavior',
+ 'Custom positioning: Static position support via the position prop',
+ 'Accessible: Proper ARIA attributes and keyboard navigation',
+ ],
+ examples: [
+ {
+ label: 'Basic dialog with Layout',
+ code: `import {XDSDialog} from '@xds/core/Dialog';
+import {
+ XDSLayout,
+ XDSLayoutHeader,
+ XDSLayoutContent,
+ XDSLayoutFooter,
+} from '@xds/core/Layout';
+import {XDSButton} from '@xds/core/Button';
+import {useState} from 'react';
+
+function Example() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <>
+ <XDSButton label="Open Dialog" onClick={() => setIsOpen(true)} />
+
+ <XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
+ <XDSLayout
+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSButton
+ label="Cancel"
+ variant="secondary"
+ onClick={() => setIsOpen(false)}
+ />
+ <XDSButton
+ label="Confirm"
+ variant="primary"
+ onClick={() => setIsOpen(false)}
+ />
+ </XDSLayoutFooter>
+ }
+ />
+ </XDSDialog>
+ </>
+ );
+}`,
+ },
+ {
+ label: 'Static position',
+ code: `<XDSDialog
+ isOpen={isOpen}
+ onOpenChange={open => setIsOpen(open)}
+ position={{top: 100, right: 20}}>
+ {/* content */}
+</XDSDialog>`,
+ },
+ {
+ label: 'Fullscreen variant',
+ code: `<XDSDialog
+ isOpen={isOpen}
+ onOpenChange={open => setIsOpen(open)}
+ variant="fullscreen">
+ <XDSLayout
+ header={<XDSLayoutHeader hasDivider>Full-screen title</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSButton label="Close" onClick={() => setIsOpen(false)} />
+ </XDSLayoutFooter>
+ }
+ />
+</XDSDialog>`,
+ },
+ {
+ label: 'Required purpose (non-dismissible)',
+ code: `<XDSDialog
+ isOpen={isOpen}
+ onOpenChange={open => setIsOpen(open)}
+ purpose="required">
+ {/* user must take an explicit action to close */}
+</XDSDialog>`,
+ },
+ {
+ label: 'XDSDialogHeader with close button',
+ code: `<XDSDialogHeader
+ title="Confirm Action"
+ subtitle="This cannot be undone"
+ onOpenChange={open => setIsOpen(open)}
+/>`,
+ },
+ ],
+ theming: {
+ componentKey: 'dialog',
+ surfaces: [
+ {name: 'root', description: 'Dialog element styles'},
+ {name: 'backdrop', description: 'Backdrop overlay styles'},
+ ],
+ },
+ keyboard:
+ 'Escape closes the dialog (unless purpose="required"); focus is trapped inside the dialog while open.',
+ accessibility: [
+ 'Uses the native <dialog> element with showModal() for correct ARIA modal semantics.',
+ 'Focus is automatically trapped by the browser when using showModal().',
+ 'XDSDialogHeader title receives focus when the dialog opens.',
+ ],
+ notes: [
+ 'Height is unset (grows with content) and constrained by the maxHeight prop.',
+ 'When variant="fullscreen", the width, maxHeight, and position props are ignored.',
+ 'For form purpose, backdrop click is only allowed before the user has interacted with the dialog.',
+ 'Purpose=required disables both Escape key and backdrop click; purpose=form disables backdrop click after interaction; purpose=info (default) allows both.',
+ 'XDSDialog is designed to be used with XDSLayout as its child.',
+ ],
+ components: [
+ {
+ name: 'XDSDialog',
+ description: 'Modal dialog using the native <dialog> element.',
+ props: [
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Whether the dialog is open (required).',
+ required: true,
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => unknown',
+ description: 'Callback when dialog visibility changes (required).',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Dialog content.',
+ required: true,
+ },
+ {
+ name: 'width',
+ type: 'number | string',
+ description: 'Width of the dialog in pixels or any CSS value.',
+ default: '400',
+ },
+ {
+ name: 'maxHeight',
+ type: 'number | string',
+ description: 'Maximum height of the dialog.',
+ default: "'75vh'",
+ },
+ {
+ name: 'position',
+ type: 'XDSDialogPosition',
+ description:
+ 'Static position for the dialog; centered by default when omitted.',
+ },
+ {
+ name: 'variant',
+ type: "'standard' | 'fullscreen'",
+ description:
+ 'Dialog variant — fullscreen expands to fill the entire viewport.',
+ default: "'standard'",
+ },
+ {
+ name: 'purpose',
+ type: "'required' | 'form' | 'info'",
+ description:
+ 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
+ default: "'info'",
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
+ <XDSLayout
+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSButton label="Confirm" variant="primary" onClick={() => setIsOpen(false)} />
+ </XDSLayoutFooter>
+ }
+ />
+</XDSDialog>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSDialogHeader',
+ description:
+ 'Header for dialogs with a title, optional subtitle, close button, and start/end content slots.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Dialog title (receives focus on open).',
+ },
+ {
+ name: 'subtitle',
+ type: 'string',
+ description: 'Subtitle below the title.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => unknown',
+ description:
+ 'Close button callback (no button if omitted).',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description:
+ 'Content before the title (e.g., a back button).',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description:
+ 'Content after the title, before close button.',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Adds border at the bottom edge.',
+ default: 'true',
+ },
+ ],
+ examples: [
+ {
+ label: 'With title, subtitle, and close button',
+ code: `<XDSDialogHeader
+ title="Confirm Action"
+ subtitle="This cannot be undone"
+ onOpenChange={open => setIsOpen(open)}
+/>`,
+ },
+ {
+ label: 'With start content (back button)',
+ code: `<XDSDialogHeader
+ title="Step 2 of 3"
+ startContent={<XDSButton label="Back" variant="secondary" onClick={goBack} />}
+ onOpenChange={open => setIsOpen(open)}
+/>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Dialog/README.md b/packages/core/src/Dialog/README.md
deleted file mode 100644
index 339c4b2e44..0000000000
--- a/packages/core/src/Dialog/README.md
+++ /dev/null
@@ -1,183 +0,0 @@
-# Dialog
-
-XDSDialog component using the native `<dialog>` element for modal dialogs.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Native `<dialog>`**: Uses browser's built-in modal behavior
-- **Automatic focus trap**: Focus is trapped within the dialog when open
-- **Backdrop**: Native `::backdrop` pseudo-element with blur effect
-- **Variants**: `standard` (configurable dimensions), `fullscreen` (full viewport)
-- **Purpose-based dismissal**: `required`, `form`, `info` control exit behavior
-- **Custom positioning**: Static position support via `position` prop
-- **Accessible**: Proper ARIA attributes and keyboard navigation
-
-## Usage
-
-XDSDialog is designed to be used with XDSLayout as its child:
-
-```tsx
-import {XDSDialog} from '@xds/core/Dialog';
-import {
- XDSLayout,
- XDSLayoutHeader,
- XDSLayoutContent,
- XDSLayoutFooter,
-} from '@xds/core/Layout';
-import {XDSButton} from '@xds/core/Button';
-import {useState} from 'react';
-
-function Example() {
- const [isOpen, setIsOpen] = useState(false);
-
- return (
- <>
- <XDSButton label="Open Dialog" onClick={() => setIsOpen(true)} />
-
- <XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
- <XDSLayout
- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
- content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}
- footer={
- <XDSLayoutFooter hasDivider>
- <XDSButton
- label="Cancel"
- variant="secondary"
- onClick={() => setIsOpen(false)}
- />
- <XDSButton
- label="Confirm"
- variant="primary"
- onClick={() => setIsOpen(false)}
- />
- </XDSLayoutFooter>
- }
- />
- </XDSDialog>
- </>
- );
-}
-```
-
-## Components
-
-### XDSDialog
-
-Modal dialog using the native `<dialog>` element.
-
-```tsx
-<XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
- <XDSLayout
- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
- content={<XDSLayoutContent>Content goes here</XDSLayoutContent>}
- footer={
- <XDSLayoutFooter hasDivider>
- <XDSButton
- label="Confirm"
- variant="primary"
- onClick={() => setIsOpen(false)}
- />
- </XDSLayoutFooter>
- }
- />
-</XDSDialog>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | -------------------------------- | ------------ | -------------------------------------------------- |
-| `isOpen` | `boolean` | — | Whether the dialog is open (required) |
-| `onOpenChange` | `(isOpen: boolean) => unknown` | — | Callback when dialog visibility changes (required) |
-| `width` | `number \| string` | `400` | Width of the dialog (px or CSS value) |
-| `maxHeight` | `number \| string` | `'75vh'` | Maximum height of the dialog |
-| `position` | `XDSDialogPosition` | — | Static position (centered by default) |
-| `variant` | `'standard' \| 'fullscreen'` | `'standard'` | Dialog variant |
-| `purpose` | `'required' \| 'form' \| 'info'` | `'info'` | Dismissal behavior |
-| `children` | `ReactNode` | — | Dialog content (required) |
-
-### XDSDialogHeader
-
-Header for dialogs with title, optional subtitle, close button, and start/end content slots.
-
-```tsx
-<XDSDialogHeader
- title="Confirm Action"
- subtitle="This cannot be undone"
- onOpenChange={open => setIsOpen(open)}
-/>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | --------------- | ------- | -------------------------------------------- |
-| `title` | `string` | — | Dialog title (receives focus on open) |
-| `subtitle` | `string` | — | Subtitle below the title |
-| `onOpenChange` | `() => unknown` | — | Close button callback (no button if omitted) |
-| `startContent` | `ReactNode` | — | Content before the title (e.g., back button) |
-| `endContent` | `ReactNode` | — | Content after the title, before close button |
-| `hasDivider` | `boolean` | `true` | Adds border at the bottom edge |
-
-## Purpose Prop
-
-The `purpose` prop controls how users can dismiss the dialog:
-
-| Purpose | Escape Key | Backdrop Click | Use Case |
-| ---------- | ----------- | -------------- | ------------------------------------------ |
-| `required` | ❌ Disabled | ❌ Disabled | Mandatory flows (security, permissions) |
-| `form` | ✅ Allowed | ❌ Disabled\* | Forms where accidental dismiss = data loss |
-| `info` | ✅ Allowed | ✅ Allowed | Informational content, low-cost dismissal |
-
-\*For `form` purpose, backdrop click is only allowed before user interaction.
-
-## Position Prop
-
-Configure a static position instead of centering:
-
-```tsx
-<XDSDialog
- isOpen={isOpen}
- onOpenChange={open => setIsOpen(open)}
- position={{top: 100, right: 20}}>
- {/* content */}
-</XDSDialog>
-```
-
-## Theming
-
-Themes can override `Dialog` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- dialog: {
- root: myStyles,
- backdrop: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ---------- | ----------------------- |
-| `root` | Dialog element styles |
-| `backdrop` | Backdrop overlay styles |
-
-## Files
-
-| File | Role | Purpose |
-| -------------------- | ----- | ------------------------------------- |
-| `index.ts` | Entry | Exports XDSDialog component and types |
-| `XDSDialog.tsx` | Core | XDSDialog component implementation |
-| `XDSDialog.test.tsx` | Test | Unit tests for XDSDialog component |
-
-## Implementation Notes
-
-- Uses native `<dialog>` element with `showModal()` for proper modal behavior
-- Height is `unset` (grows with content) and constrained by `maxHeight`
-- Focus is automatically trapped by the browser when using `showModal()`
-- Escape key and backdrop clicks are controlled by the `purpose` prop
-- When `variant="fullscreen"`, the `width`, `maxHeight`, and `position` props are ignored
diff --git a/packages/core/src/Dialog/XDSDialog.tsx b/packages/core/src/Dialog/XDSDialog.tsx
index ade557591c..bbde713a3b 100644
--- a/packages/core/src/Dialog/XDSDialog.tsx
+++ b/packages/core/src/Dialog/XDSDialog.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSDialog.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Dialog/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Dialog/XDSDialog.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Dialog/index.ts (exports if types change)
* - /apps/storybook/stories/Dialog.stories.tsx (storybook stories)
diff --git a/packages/core/src/Dialog/XDSDialogHeader.tsx b/packages/core/src/Dialog/XDSDialogHeader.tsx
index 40446bde14..03721cfe12 100644
--- a/packages/core/src/Dialog/XDSDialogHeader.tsx
+++ b/packages/core/src/Dialog/XDSDialogHeader.tsx
@@ -5,7 +5,7 @@
* @position Dialog header component; used with XDSDialog and XDSLayout
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Dialog/README.md
+ * - /packages/core/src/Dialog/Dialog.doc.mjs
* - /packages/core/src/Dialog/XDSDialogHeader.test.tsx
* - /packages/core/src/Dialog/index.ts
* - /apps/storybook/stories/Dialog.stories.tsx
diff --git a/packages/core/src/Dialog/index.ts b/packages/core/src/Dialog/index.ts
index 35ac941624..f1f64729e0 100644
--- a/packages/core/src/Dialog/index.ts
+++ b/packages/core/src/Dialog/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSDialog, XDSDialogHeader, and related types
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Dialog/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Dialog/Dialog.doc.mjs
*/
export {XDSDialog} from './XDSDialog';
diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjs
new file mode 100644
index 0000000000..1943cc0a31
--- /dev/null
+++ b/packages/core/src/Divider/Divider.doc.mjs
@@ -0,0 +1,69 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Divider',
+ description: 'Visual separator with optional label, using XDS design tokens.',
+ features: [
+ 'Supports horizontal and vertical orientations',
+ 'Optional label centered on the divider line',
+ 'Subtle and strong visual weight variants',
+ 'Full-bleed mode extends the divider to container edges via negative margins',
+ 'Themeable via ComponentStyles — exposes root, line, and label surfaces',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSDivider />',
+ },
+ {
+ label: 'With label',
+ code: '<XDSDivider label="or" />',
+ },
+ {
+ label: 'Vertical',
+ code: '<XDSDivider orientation="vertical" />',
+ },
+ {
+ label: 'Strong variant',
+ code: '<XDSDivider variant="strong" />',
+ },
+ {
+ label: 'Full bleed',
+ code: '<XDSDivider isFullBleed />',
+ },
+ ],
+ props: [
+ {
+ name: 'orientation',
+ type: "'horizontal' | 'vertical'",
+ description: 'Orientation of the divider.',
+ default: "'horizontal'",
+ },
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: 'Optional label centered on the divider.',
+ },
+ {
+ name: 'variant',
+ type: "'subtle' | 'strong'",
+ description: 'Visual weight of the divider line.',
+ default: "'subtle'",
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description:
+ 'Extend the divider to container edges with negative margins.',
+ default: 'false',
+ },
+ ],
+ theming: {
+ componentKey: 'divider',
+ surfaces: [
+ {name: 'root', description: 'Root container element'},
+ {name: 'line', description: 'Divider line element'},
+ {name: 'label', description: 'Label text element'},
+ ],
+ },
+};
diff --git a/packages/core/src/Divider/README.md b/packages/core/src/Divider/README.md
deleted file mode 100644
index 27e7e90143..0000000000
--- a/packages/core/src/Divider/README.md
+++ /dev/null
@@ -1,64 +0,0 @@
-# XDSDivider
-
-Visual separator with optional label, using XDS design tokens.
-
-## Import
-
-```tsx
-import {XDSDivider} from '@xds/core/Divider';
-```
-
-## Usage
-
-```tsx
-// Simple horizontal divider
-<XDSDivider />
-
-// With label
-<XDSDivider label="or" />
-
-// Vertical divider
-<XDSDivider orientation="vertical" />
-
-// Strong variant (more visible)
-<XDSDivider variant="strong" />
-
-// Full bleed (extends to container edges)
-<XDSDivider isFullBleed />
-```
-
-## Theming
-
-Themes can override `Divider` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- divider: {
- root: myStyles,
- line: myStyles,
- label: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | --------------------- |
-| `root` | Root container styles |
-| `line` | Divider line styles |
-| `label` | Label text styles |
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------- | ------------------------------ | -------------- | ----------------------------------------------- |
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the divider |
-| `label` | `ReactNode` | — | Optional label centered on the divider |
-| `variant` | `'subtle' \| 'strong'` | `'subtle'` | Visual weight of the divider line |
-| `isFullBleed` | `boolean` | `false` | Extend to container edges with negative margins |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
diff --git a/packages/core/src/Divider/XDSDivider.tsx b/packages/core/src/Divider/XDSDivider.tsx
index 8a3bd76ab6..012505a284 100644
--- a/packages/core/src/Divider/XDSDivider.tsx
+++ b/packages/core/src/Divider/XDSDivider.tsx
@@ -5,7 +5,7 @@
* @position Divider component; provides visual separation with optional label
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Divider/README.md
+ * - /packages/core/src/Divider/Divider.doc.mjs
* - /packages/core/src/Divider/XDSDivider.test.tsx
* - /apps/storybook/stories/Divider.stories.tsx
*/
diff --git a/packages/core/src/Divider/index.ts b/packages/core/src/Divider/index.ts
index d445499f55..887f4c2ede 100644
--- a/packages/core/src/Divider/index.ts
+++ b/packages/core/src/Divider/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSDivider component and props type
* @position Package entry point for Divider
*
- * SYNC: When modified, update /packages/core/src/Divider/README.md
+ * SYNC: When modified, update /packages/core/src/Divider/Divider.doc.mjs
*/
export {XDSDivider} from './XDSDivider';
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
new file mode 100644
index 0000000000..eb42a65603
--- /dev/null
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -0,0 +1,326 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'DropdownMenu',
+ description:
+ 'A dropdown menu component for displaying actionable items in a popup menu.',
+ features: [
+ 'Button customization: Customize the trigger button via the `button` prop (supports all XDSButton props)',
+ 'Data-driven items: Pass items via the `items` prop with support for sections and dividers',
+ 'Controlled/Uncontrolled: Supports both controlled (`isMenuOpen`/`onOpenChange`) and uncontrolled modes',
+ 'Custom menu width: Override default width (matches button) via `menuWidth` prop',
+ 'Sections: Group related items with optional headers using `XDSDropdownMenuSection`',
+ 'Keyboard navigation: Full keyboard support (Arrow keys, Home, End, Enter, Space, Escape)',
+ 'Accessibility: Proper ARIA roles (menu, menuitem) and attributes',
+ 'Custom rendering: Optional `children` render function with `XDSDropdownMenuItem` helper',
+ ],
+ examples: [
+ {
+ label: 'Basic usage',
+ code: `<XDSDropdownMenu
+ button={{ label: 'Actions' }}
+ items={[
+ { label: 'Edit', onClick: () => handleEdit() },
+ { label: 'Delete', onClick: () => handleDelete() },
+ ]}
+/>`,
+ },
+ {
+ label: 'With icons',
+ code: `<XDSDropdownMenu
+ button={{ label: 'Actions' }}
+ items={[
+ { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit() },
+ { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete() },
+ ]}
+/>`,
+ },
+ {
+ label: 'With sections',
+ code: `<XDSDropdownMenu
+ button={{ label: 'File', variant: 'ghost' }}
+ items={[
+ {
+ type: 'section',
+ title: 'Create',
+ items: [
+ { label: 'New File', onClick: () => handleNew() },
+ { label: 'New Folder', onClick: () => handleNewFolder() },
+ ],
+ },
+ {
+ type: 'section',
+ title: 'Manage',
+ items: [
+ { label: 'Rename', onClick: () => handleRename() },
+ { label: 'Delete', isDisabled: true },
+ ],
+ },
+ ]}
+/>`,
+ },
+ {
+ label: 'With dividers',
+ code: `<XDSDropdownMenu
+ button={{ label: 'Actions' }}
+ items={[
+ { label: 'Edit', onClick: () => handleEdit() },
+ { type: 'divider' },
+ { label: 'Delete', onClick: () => handleDelete() },
+ ]}
+/>`,
+ },
+ {
+ label: 'Controlled mode',
+ code: `const [isOpen, setIsOpen] = useState(false);
+<XDSDropdownMenu
+ button={{ label: 'Options' }}
+ items={[...]}
+ isMenuOpen={isOpen}
+ onOpenChange={setIsOpen}
+/>`,
+ },
+ {
+ label: 'Custom item rendering with XDSDropdownMenuItem',
+ code: `<XDSDropdownMenu
+ button={{ label: 'Users' }}
+ items={users}
+>
+ {item => (
+ <XDSDropdownMenuItem
+ icon={item.icon}
+ label={item.label}
+ description={item.email}
+ />
+ )}
+</XDSDropdownMenu>`,
+ },
+ ],
+ theming: {
+ componentKey: 'dropdownMenu',
+ surfaces: [
+ {name: 'root', description: 'Dropdown container styles'},
+ {name: 'item', description: 'Menu item styles'},
+ ],
+ },
+ keyboard:
+ 'Arrow keys navigate items, Home/End jump to first/last, Enter/Space select, Escape closes the menu',
+ accessibility: [
+ 'Uses proper ARIA roles: `menu` on the popup container, `menuitem` on each item',
+ 'Focus returns to the trigger button when the menu closes',
+ 'Keyboard navigation automatically skips disabled items',
+ ],
+ notes: [
+ 'Uses `useXDSLayer` with `mode: "context"` for CSS anchor positioning',
+ 'Uses `XDSButton` internally with `ChevronDownIcon` that inherits button text color',
+ 'Items are tracked via the `items` prop to enable keyboard navigation',
+ 'Light dismiss is enabled by default (clicking outside closes menu)',
+ ],
+ components: [
+ {
+ name: 'XDSDropdownMenu',
+ description:
+ 'Main dropdown menu component with a trigger button and popup item list.',
+ props: [
+ {
+ name: 'button',
+ type: 'XDSDropdownMenuButtonProps',
+ description:
+ 'Props for the trigger button (XDSButton props except onClick).',
+ default: "{ label: 'Menu' }",
+ },
+ {
+ name: 'items',
+ type: 'XDSDropdownMenuOption[]',
+ description:
+ 'Menu items, dividers, or sections to display in the popup.',
+ required: true,
+ },
+ {
+ name: 'isMenuOpen',
+ type: 'boolean',
+ description: 'Controlled open state for the menu.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback fired when the open state changes.',
+ },
+ {
+ name: 'menuWidth',
+ type: 'number | string',
+ description:
+ 'Custom menu width; defaults to matching the trigger button width.',
+ },
+ {
+ name: 'onClick',
+ type: '() => void',
+ description: 'Callback fired when the trigger button is clicked.',
+ },
+ {
+ name: 'children',
+ type: '(item: XDSDropdownMenuItemData) => ReactNode',
+ description: 'Custom render function for each item in the list.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSDropdownMenu
+ button={{ label: 'Actions' }}
+ items={[
+ { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit() },
+ { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete() },
+ ]}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSDropdownMenuItem',
+ description:
+ 'Helper component for custom item rendering with consistent styling.',
+ props: [
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon to display before the label.',
+ },
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: 'Primary label text.',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: 'Secondary description text displayed below the label.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Additional content rendered after the label and description.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for the root container.',
+ },
+ ],
+ examples: [
+ {
+ label: 'With icon and description',
+ code: `<XDSDropdownMenuItem
+ icon={UserIcon}
+ label="Alice Johnson"
+ description="[email protected]"
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSDropdownMenuItemData',
+ description:
+ 'Data shape for a single actionable menu item passed via the `items` prop.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Display label for the item.',
+ required: true,
+ },
+ {
+ name: 'onClick',
+ type: '() => void',
+ description: 'Callback fired when the item is selected.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description:
+ 'Whether the item is disabled; disabled items are skipped during keyboard navigation.',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon to display before the item label.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic item',
+ code: `{ label: 'Edit', onClick: () => handleEdit() }`,
+ },
+ {
+ label: 'Disabled item with icon',
+ code: `{ label: 'Delete', icon: TrashIcon, isDisabled: true }`,
+ },
+ ],
+ },
+ {
+ name: 'XDSDropdownMenuDivider',
+ description:
+ 'A visual divider that can be placed between items in the `items` array.',
+ props: [
+ {
+ name: 'type',
+ type: "'divider'",
+ description:
+ 'Discriminant value that identifies this entry as a divider.',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'Divider between items',
+ code: `items={[
+ { label: 'Edit', onClick: () => handleEdit() },
+ { type: 'divider' },
+ { label: 'Delete', onClick: () => handleDelete() },
+]}`,
+ },
+ ],
+ },
+ {
+ name: 'XDSDropdownMenuSection',
+ description:
+ 'A labeled group of items that can be placed in the `items` array.',
+ props: [
+ {
+ name: 'type',
+ type: "'section'",
+ description:
+ 'Discriminant value that identifies this entry as a section.',
+ required: true,
+ },
+ {
+ name: 'title',
+ type: 'string',
+ description:
+ 'Optional header text displayed above the section items.',
+ },
+ {
+ name: 'items',
+ type: 'XDSDropdownMenuItemData[]',
+ description: 'The actionable items that belong to this section.',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'Section with title',
+ code: `{
+ type: 'section',
+ title: 'Create',
+ items: [
+ { label: 'New File', onClick: () => handleNew() },
+ { label: 'New Folder', onClick: () => handleNewFolder() },
+ ],
+}`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/DropdownMenu/README.md b/packages/core/src/DropdownMenu/README.md
deleted file mode 100644
index 1588f9172e..0000000000
--- a/packages/core/src/DropdownMenu/README.md
+++ /dev/null
@@ -1,206 +0,0 @@
-# DropdownMenu
-
-A dropdown menu component for displaying actionable items in a popup menu.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Button customization**: Customize the trigger button via the `button` prop (supports all XDSButton props)
-- **Data-driven items**: Pass items via the `items` prop with support for sections and dividers
-- **Controlled/Uncontrolled**: Supports both controlled (`isMenuOpen`/`onOpenChange`) and uncontrolled modes
-- **Custom menu width**: Override default width (matches button) via `menuWidth` prop
-- **Sections**: Group related items with optional headers using `XDSDropdownMenuSection`
-- **Keyboard navigation**: Full keyboard support (Arrow keys, Home, End, Enter, Space, Escape)
-- **Accessibility**: Proper ARIA roles (menu, menuitem) and attributes
-- **Custom rendering**: Optional `children` render function with `XDSDropdownMenuItem` helper
-
-## Usage
-
-```tsx
-import {XDSDropdownMenu, XDSDropdownMenuItem} from '@xds/core/DropdownMenu';
-
-// Basic usage
-<XDSDropdownMenu
- button={{ label: 'Actions' }}
- items={[
- { label: 'Edit', onClick: () => handleEdit() },
- { label: 'Delete', onClick: () => handleDelete() },
- ]}
-/>
-
-// With icons
-<XDSDropdownMenu
- button={{ label: 'Actions' }}
- items={[
- { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit() },
- { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete() },
- ]}
-/>
-
-// With sections
-<XDSDropdownMenu
- button={{ label: 'File', variant: 'ghost' }}
- items={[
- {
- type: 'section',
- title: 'Create',
- items: [
- { label: 'New File', onClick: () => handleNew() },
- { label: 'New Folder', onClick: () => handleNewFolder() },
- ],
- },
- {
- type: 'section',
- title: 'Manage',
- items: [
- { label: 'Rename', onClick: () => handleRename() },
- { label: 'Delete', disabled: true },
- ],
- },
- ]}
-/>
-
-// With dividers
-<XDSDropdownMenu
- button={{ label: 'Actions' }}
- items={[
- { label: 'Edit', onClick: () => handleEdit() },
- { type: 'divider' },
- { label: 'Delete', onClick: () => handleDelete() },
- ]}
-/>
-
-// Controlled mode
-const [isOpen, setIsOpen] = useState(false);
-<XDSDropdownMenu
- button={{ label: 'Options' }}
- items={[...]}
- isMenuOpen={isOpen}
- onOpenChange={setIsOpen}
-/>
-
-// Custom item rendering with XDSDropdownMenuItem
-<XDSDropdownMenu
- button={{ label: 'Users' }}
- items={users}
->
- {item => (
- <XDSDropdownMenuItem
- icon={item.icon}
- label={item.label}
- description={item.email}
- />
- )}
-</XDSDropdownMenu>
-```
-
-## Props
-
-### XDSDropdownMenu
-
-```tsx
-<XDSDropdownMenu
- button={{label: 'Actions'}}
- items={[
- {label: 'Edit', icon: PencilIcon, onClick: () => handleEdit()},
- {label: 'Delete', icon: TrashIcon, onClick: () => handleDelete()},
- ]}
-/>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ---------------------------------------------- | ------------------- | ------------------------------------------------------------- |
-| `button` | `XDSDropdownMenuButtonProps` | `{ label: 'Menu' }` | Props for the trigger button (XDSButton props except onClick) |
-| `items` | `XDSDropdownMenuOption[]` | — | Menu items (items, dividers, or sections) |
-| `isMenuOpen` | `boolean` | — | Controlled open state |
-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when menu visibility changes |
-| `menuWidth` | `number \| string` | — | Custom menu width (default: matches button) |
-| `onClick` | `() => void` | — | Callback when button is clicked |
-| `children` | `(item: XDSDropdownMenuItemData) => ReactNode` | — | Custom render function for items |
-
-### XDSDropdownMenuItem
-
-Helper component for custom item rendering with consistent styling.
-
-```tsx
-<XDSDropdownMenuItem
- icon={UserIcon}
- label="Alice Johnson"
- description="[email protected]"
-/>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | -------------- | ------- | ---------------------------------------------- |
-| `icon` | `XDSIconType` | — | Icon to display before the label |
-| `label` | `ReactNode` | — | Primary label text |
-| `description` | `ReactNode` | — | Secondary description text below the label |
-| `children` | `ReactNode` | — | Additional content after the label/description |
-| `xstyle` | `StyleXStyles` | — | StyleX styles for the root container |
-
-### XDSDropdownMenuItemData
-
-| Prop | Type | Default | Description |
-| ---------- | ------------- | ------- | -------------------------------- |
-| `label` | `string` | — | Display label for the item |
-| `onClick` | `() => void` | — | Callback when item is selected |
-| `disabled` | `boolean` | `false` | Whether the item is disabled |
-| `icon` | `XDSIconType` | — | Icon to display before the label |
-
-### XDSDropdownMenuDivider
-
-| Prop | Type | Value | Description |
-| ------ | ----------- | ----------- | ----------------- |
-| `type` | `'divider'` | `'divider'` | Indicates divider |
-
-### XDSDropdownMenuSection
-
-| Prop | Type | Default | Description |
-| ------- | --------------------------- | ------- | ----------------------- |
-| `type` | `'section'` | — | Indicates section |
-| `title` | `string` | — | Optional section header |
-| `items` | `XDSDropdownMenuItemData[]` | — | Items in the section |
-
-## Theming
-
-Themes can override `DropdownMenu` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- dropdownMenu: {
- root: myStyles,
- item: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | ------------------------- |
-| `root` | Dropdown container styles |
-| `item` | Menu item styles |
-
-## Files
-
-| File | Role | Purpose |
-| -------------------------- | --------- | -------------------------------- |
-| `index.ts` | Entry | Exports components and types |
-| `XDSDropdownMenu.tsx` | Core | Main component implementation |
-| `XDSDropdownMenuItem.tsx` | Component | Helper for custom item rendering |
-| `XDSDropdownMenu.test.tsx` | Testing | Unit tests |
-
-## Implementation Notes
-
-- Uses `useXDSLayer` with `mode: 'context'` for CSS anchor positioning
-- Uses `XDSButton` internally with `ChevronDownIcon` that inherits button text color
-- Items are tracked via the `items` prop to enable keyboard navigation
-- Keyboard navigation skips disabled items
-- Light dismiss is enabled by default (clicking outside closes menu)
-- Focus returns to button when menu closes
-- `XDSDropdownMenuItem` provides consistent styling for custom item layouts
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
index 619d7bc1ac..5b5e390806 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/DropdownMenu/README.md
+ * - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
* - /packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
* - /packages/core/src/DropdownMenu/index.ts
* - /apps/storybook/stories/DropdownMenu.stories.tsx
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
index b29f72c4cb..c4e4127634 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
@@ -4,7 +4,7 @@
* @position Sub-component; used by XDSDropdownMenu and consumers for custom items
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/DropdownMenu/README.md
+ * - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
* - /packages/core/src/DropdownMenu/XDSDropdownMenu.test.tsx
* - /packages/core/src/DropdownMenu/index.ts
* - /apps/storybook/stories/DropdownMenu.stories.tsx
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
new file mode 100644
index 0000000000..548c96c8b1
--- /dev/null
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -0,0 +1,85 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'EmptyState',
+ description:
+ 'An empty state placeholder for content areas with no data. Displays an icon or illustration, title, optional description, and action buttons.',
+ features: [
+ 'Uses role="status" so screen readers announce the empty state automatically',
+ 'Icon slot renders as decorative (aria-hidden="true") — no extra labeling needed',
+ 'Title renders as an <h3> heading element for correct document outline',
+ 'Actions are laid out horizontally by default and stack vertically in compact mode',
+ 'Compact variant reduces spacing for constrained content areas',
+ 'Accepts StyleX override styles via xstyle for custom container adjustments',
+ 'Forwarded ref lands on the root <div> container',
+ ],
+ examples: [
+ {
+ label: 'Minimal',
+ code: '<XDSEmptyState title="No results found" />',
+ },
+ {
+ label: 'With description',
+ code: `<XDSEmptyState
+ title="No results found"
+ description="Try adjusting your search or filters."
+/>`,
+ },
+ {
+ label: 'Full example with icon and action',
+ code: `<XDSEmptyState
+ icon={<XDSIcon icon={InboxIcon} size="lg" />}
+ title="No messages"
+ description="You're all caught up!"
+ actions={<XDSButton label="Compose" variant="primary" />}
+/>`,
+ },
+ {
+ label: 'Compact variant',
+ code: `<XDSEmptyState
+ title="No items"
+ description="Nothing to show here."
+ isCompact
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description:
+ 'Primary message rendered as an <h3> heading inside the empty state.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description:
+ 'Optional secondary text providing additional context below the title.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ 'Optional icon or illustration displayed above the title; rendered as decorative (aria-hidden="true").',
+ },
+ {
+ name: 'actions',
+ type: 'ReactNode',
+ description:
+ 'Optional action buttons displayed below the description, laid out horizontally by default and stacked vertically when isCompact is true.',
+ },
+ {
+ name: 'isCompact',
+ type: 'boolean',
+ description:
+ 'Enables the compact variant with reduced spacing for constrained content areas.',
+ default: 'false',
+ },
+ ],
+ accessibility: [
+ 'Container uses role="status" to announce the empty state content to screen readers.',
+ 'Icon wrapper has aria-hidden="true" so decorative icons are ignored by assistive technology.',
+ 'Title renders as an <h3> element, keeping it in the document heading outline.',
+ ],
+};
diff --git a/packages/core/src/EmptyState/README.md b/packages/core/src/EmptyState/README.md
deleted file mode 100644
index a5f962e5f0..0000000000
--- a/packages/core/src/EmptyState/README.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# EmptyState
-
-An empty state placeholder for content areas with no data. Displays an icon or illustration, title, optional description, and action buttons.
-
-## Exports
-
-| Export | Type | Description |
-| -------------------- | --------- | -------------------------- |
-| `XDSEmptyState` | Component | Main empty state component |
-| `XDSEmptyStateProps` | Type | Props interface |
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------- | -------------- | ------- | ------------------------------------------------------------- |
-| `title` | `string` | — | Primary message (required) |
-| `description` | `string` | — | Optional secondary text |
-| `icon` | `ReactNode` | — | Optional icon/illustration (rendered decorative, aria-hidden) |
-| `actions` | `ReactNode` | — | Optional action buttons (horizontal, stacked when compact) |
-| `isCompact` | `boolean` | `false` | Compact variant with reduced spacing |
-| `xstyle` | `StyleXStyles` | — | StyleX override styles for the container |
-| `data-testid` | `string` | — | Test ID for the container element |
-
-## Usage
-
-```tsx
-import {XDSEmptyState} from '@xds/core/EmptyState';
-
-// Minimal
-<XDSEmptyState title="No results found" />
-
-// With description
-<XDSEmptyState
- title="No results found"
- description="Try adjusting your search or filters."
-/>
-
-// Full example
-<XDSEmptyState
- icon={<XDSIcon icon={InboxIcon} size="lg" />}
- title="No messages"
- description="You're all caught up!"
- actions={<XDSButton label="Compose" variant="primary" />}
-/>
-
-// Compact variant
-<XDSEmptyState
- title="No items"
- description="Nothing to show here."
- isCompact
-/>
-```
-
-## Accessibility
-
-- Container uses `role="status"` to announce content to screen readers
-- Icon wrapper has `aria-hidden="true"` (decorative)
-- Title renders as an `<h3>` heading element
-
-## Files
-
-| File | Purpose |
-| ------------------------ | ------------------------ |
-| `XDSEmptyState.tsx` | Component implementation |
-| `XDSEmptyState.test.tsx` | Unit tests |
-| `index.ts` | Barrel exports |
diff --git a/packages/core/src/EmptyState/XDSEmptyState.tsx b/packages/core/src/EmptyState/XDSEmptyState.tsx
index 6d6802780f..1ccfa58241 100644
--- a/packages/core/src/EmptyState/XDSEmptyState.tsx
+++ b/packages/core/src/EmptyState/XDSEmptyState.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/EmptyState/README.md (props table, features, implementation notes)
+ * - /packages/core/src/EmptyState/EmptyState.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/EmptyState/XDSEmptyState.test.tsx (tests for new/changed behavior)
* - /packages/core/src/EmptyState/index.ts (exports if types change)
* - /apps/storybook/stories/EmptyState.stories.tsx (storybook stories)
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
new file mode 100644
index 0000000000..4d7d7f86c5
--- /dev/null
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -0,0 +1,262 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Field',
+ description:
+ 'A form field wrapper component that provides label, description, and optional/required indicators.',
+ features: [
+ 'Label Support — required label for accessibility (can be visually hidden)',
+ 'Description — optional description text displayed between the label and input',
+ 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',
+ 'Label Tooltip — optional info icon with tooltip at end of label',
+ 'Accessible — label properly associated with input via htmlFor/id',
+ 'Styled with StyleX — uses XDS design tokens for consistent styling',
+ ],
+ examples: [
+ {
+ label: 'Basic usage',
+ code: `const id = useId();
+<XDSField label="Email" inputID={id}>
+ <input id={id} />
+</XDSField>`,
+ },
+ {
+ label: 'With description',
+ code: `const inputId = useId();
+const descId = useId();
+<XDSField
+ label="Email"
+ description="We'll never share your email"
+ inputID={inputId}
+ descriptionID={descId}>
+ <input id={inputId} aria-describedby={descId} />
+</XDSField>`,
+ },
+ {
+ label: 'Hidden label (screen readers only)',
+ code: `const searchId = useId();
+<XDSField label="Search" isLabelHidden inputID={searchId}>
+ <input id={searchId} placeholder="Search..." />
+</XDSField>`,
+ },
+ {
+ label: 'Optional field',
+ code: `const nicknameId = useId();
+<XDSField label="Nickname" isOptional inputID={nicknameId}>
+ <input id={nicknameId} placeholder="Enter your nickname" />
+</XDSField>`,
+ },
+ {
+ label: 'Required field',
+ code: `const usernameId = useId();
+<XDSField label="Username" isRequired inputID={usernameId}>
+ <input id={usernameId} placeholder="Enter your username" />
+</XDSField>`,
+ },
+ {
+ label: 'Description with optional indicator (shows bullet separator)',
+ code: `const bioId = useId();
+const bioDescId = useId();
+<XDSField
+ label="Bio"
+ description="Tell us about yourself"
+ isOptional
+ inputID={bioId}
+ descriptionID={bioDescId}>
+ <input id={bioId} aria-describedby={bioDescId} />
+</XDSField>`,
+ },
+ ],
+ theming: {
+ componentKey: 'field',
+ surfaces: [
+ {name: 'root', description: 'Root container styles'},
+ {name: 'description', description: 'Description text styles'},
+ ],
+ },
+ notes: [
+ 'Parent components are responsible for generating IDs (using the useId hook).',
+ 'Label is always rendered for accessibility; use isLabelHidden to hide visually.',
+ 'Hidden label uses a CSS technique that remains accessible to screen readers.',
+ 'Description is rendered when provided; if descriptionID is also provided, the description element gets that ID for aria-describedby association.',
+ 'isOptional and isRequired are mutually exclusive; setting both will show "Optional".',
+ 'Optional/Required text appears on the same line as the label.',
+ ],
+ components: [
+ {
+ name: 'XDSField',
+ description:
+ 'Form field wrapper that provides label, description, and optional/required indicators.',
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSField label="Email" inputID={id}>
+ <input id={id} />
+</XDSField>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the field (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'inputID',
+ type: 'string',
+ description:
+ 'ID for the input element (used for the label htmlFor attribute).',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'The input or control to render.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Visually hide the label (still accessible to screen readers).',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description:
+ 'Description text displayed between the label and input.',
+ },
+ {
+ name: 'descriptionID',
+ type: 'string',
+ description:
+ 'ID for the description element (use for aria-describedby on the input).',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Whether the field is optional (mutually exclusive with isRequired).',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description:
+ 'Whether the field is required (mutually exclusive with isOptional).',
+ default: 'false',
+ },
+ {
+ name: 'labelIcon',
+ type: 'XDSIconType',
+ description: 'Icon to display before the label text.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description:
+ 'Tooltip text to display in an info icon at the end of the label.',
+ },
+ ],
+ },
+ {
+ name: 'XDSFieldLabel',
+ description:
+ 'Standalone label component with optional/required indicators and tooltip support.',
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSFieldLabel label="Username" inputID={id} isRequired />',
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text.',
+ required: true,
+ },
+ {
+ name: 'inputID',
+ type: 'string',
+ description: 'ID of the input this label is for.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the associated input is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Show "Optional" indicator.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Show "Required" indicator.',
+ default: 'false',
+ },
+ {
+ name: 'labelIcon',
+ type: 'XDSIconType',
+ description: 'Icon before the label text.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text for info icon at end of label.',
+ },
+ ],
+ },
+ {
+ name: 'XDSFieldStatus',
+ description:
+ 'Status message component for form field validation feedback.',
+ examples: [
+ {
+ label: 'Error',
+ code: '<XDSFieldStatus type="error" message="This field is required" />',
+ },
+ ],
+ props: [
+ {
+ name: 'type',
+ type: "'error' | 'warning' | 'success'",
+ description: 'Status type.',
+ required: true,
+ },
+ {
+ name: 'message',
+ type: 'string',
+ description: 'Status message text.',
+ required: true,
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: 'ID for aria-describedby association.',
+ },
+ {
+ name: 'variant',
+ type: "'attached' | 'detached'",
+ description:
+ 'Visual variant — attached overlaps the input, detached floats below.',
+ default: "'attached'",
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Field/README.md b/packages/core/src/Field/README.md
deleted file mode 100644
index a5d6629fb6..0000000000
--- a/packages/core/src/Field/README.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# Field
-
-A form field wrapper component that provides label and description.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Label Support**: Required label for accessibility (can be visually hidden)
-- **Description**: Optional description text displayed between the label and input
-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator
-- **Label Tooltip**: Optional info icon with tooltip at end of label
-- **Accessible**: Label properly associated with input via htmlFor/id
-- **Styled with StyleX**: Uses XDS design tokens for consistent styling
-
-## Components
-
-### XDSField
-
-Form field wrapper that provides label, description, and optional/required indicators.
-
-```tsx
-<XDSField label="Email" inputID={id}>
- <input id={id} />
-</XDSField>
-```
-
-| Prop | Type | Default | Description |
-| ---------------- | ------------- | ------- | --------------------------------------------- |
-| `label` | `string` | — | Label text (required for accessibility) |
-| `isLabelHidden` | `boolean` | `false` | Visually hide the label |
-| `description` | `string` | — | Description text between label and input |
-| `inputID` | `string` | — | ID for the input (used for label's htmlFor) |
-| `descriptionID` | `string` | — | ID for the description (for aria-describedby) |
-| `isOptional` | `boolean` | `false` | Show "Optional" indicator |
-| `isRequired` | `boolean` | `false` | Show "Required" indicator |
-| `labelStartIcon` | `XDSIconType` | — | Icon before the label text |
-| `labelTooltip` | `string` | — | Tooltip text for info icon at end of label |
-| `children` | `ReactNode` | — | The input or control to render |
-
-### XDSFieldLabel
-
-Standalone label component with optional/required indicators and tooltip support.
-
-```tsx
-<XDSFieldLabel label="Username" inputID={id} isRequired />
-```
-
-| Prop | Type | Default | Description |
-| --------------- | ------------- | ------- | ------------------------------------------ |
-| `label` | `string` | — | Label text (required) |
-| `inputID` | `string` | — | ID of the input this label is for |
-| `isLabelHidden` | `boolean` | `false` | Visually hide the label |
-| `isDisabled` | `boolean` | `false` | Whether the associated input is disabled |
-| `isOptional` | `boolean` | `false` | Show "Optional" indicator |
-| `isRequired` | `boolean` | `false` | Show "Required" indicator |
-| `startIcon` | `XDSIconType` | — | Icon before the label text |
-| `tooltip` | `string` | — | Tooltip text for info icon at end of label |
-
-### XDSFieldStatus
-
-Status message component for form field validation feedback.
-
-```tsx
-<XDSFieldStatus type="error" message="This field is required" />
-```
-
-| Prop | Type | Default | Description |
-| --------- | ----------------------------------- | ------------ | ----------------------------------------------- |
-| `type` | `'error' \| 'warning' \| 'success'` | — | Status type |
-| `message` | `string` | — | Status message text |
-| `id` | `string` | — | ID for aria-describedby association |
-| `variant` | `'attached' \| 'detached'` | `'attached'` | Visual variant (overlaps vs floats below input) |
-
-## Usage
-
-```tsx
-import {XDSField} from '@xds/core/Field';
-import {useId} from 'react';
-
-// Basic usage with explicit IDs
-const id = useId();
-<XDSField label="Email" inputID={id}>
- <input id={id} />
-</XDSField>;
-
-// With description
-const inputId = useId();
-const descId = useId();
-<XDSField
- label="Email"
- description="We'll never share your email"
- inputID={inputId}
- descriptionID={descId}>
- <input id={inputId} aria-describedby={descId} />
-</XDSField>;
-
-// Hidden label (for screen readers only)
-const searchId = useId();
-<XDSField label="Search" isLabelHidden inputID={searchId}>
- <input id={searchId} placeholder="Search..." />
-</XDSField>;
-
-// Optional field
-const nicknameId = useId();
-<XDSField label="Nickname" isOptional inputID={nicknameId}>
- <input id={nicknameId} placeholder="Enter your nickname" />
-</XDSField>;
-
-// Required field
-const usernameId = useId();
-<XDSField label="Username" isRequired inputID={usernameId}>
- <input id={usernameId} placeholder="Enter your username" />
-</XDSField>;
-
-// Description with optional indicator (shows bullet separator)
-const bioId = useId();
-const bioDescId = useId();
-<XDSField
- label="Bio"
- description="Tell us about yourself"
- isOptional
- inputID={bioId}
- descriptionID={bioDescId}>
- <input id={bioId} aria-describedby={bioDescId} />
-</XDSField>;
-```
-
-## Props
-
-| Prop | Type | Required | Description |
-| ---------------- | ------------- | -------- | ---------------------------------------------------------------------- |
-| `label` | `string` | Yes | Label text for the field (always rendered for accessibility) |
-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |
-| `description` | `string` | No | Description text displayed between the label and input |
-| `inputID` | `string` | Yes | ID for the input element (used for label's htmlFor attribute) |
-| `descriptionID` | `string` | No | ID for the description element (use for aria-describedby on the input) |
-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |
-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |
-| `labelStartIcon` | `XDSIconType` | No | Icon to display before the label text |
-| `labelTooltip` | `string` | No | Tooltip text to display in an info icon at the end of the label |
-| `children` | `ReactNode` | Yes | The input or control to render |
-
-## Theming
-
-Themes can override `Field` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- field: {
- root: myStyles,
- description: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------------- | ----------------------- |
-| `root` | Root container styles |
-| `description` | Description text styles |
-
-## Files
-
-| File | Role | Purpose |
-| ------------------------ | ------ | ------------------------------------------------- |
-| `index.ts` | Entry | Exports component, types, and shared input styles |
-| `XDSField.tsx` | Core | Component implementation |
-| `XDSFieldLabel.tsx` | Core | Standalone label component |
-| `XDSFieldStatus.tsx` | Core | Status message component |
-| `XDSField.test.tsx` | Test | Unit tests |
-| `XDSFieldLabel.test.tsx` | Test | Unit tests for label component |
-| `types.ts` | Types | Shared input types (status, size) |
-| `inputStyles.stylex.ts` | Styles | Shared input wrapper appearance styles |
-
-## Implementation Notes
-
-- Parent components are responsible for generating IDs (using `useId` hook)
-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually
-- Hidden label uses CSS technique that remains accessible to screen readers
-- Description is rendered when provided; if `descriptionID` is also provided, the description element gets that ID for `aria-describedby` association
-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"
-- Optional/Required text appears on the same line as the label
diff --git a/packages/core/src/Field/XDSField.tsx b/packages/core/src/Field/XDSField.tsx
index dd8231f6c1..a559119e3d 100644
--- a/packages/core/src/Field/XDSField.tsx
+++ b/packages/core/src/Field/XDSField.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSField.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Field/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Field/XDSField.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Field/index.ts (exports if types change)
* - /apps/storybook/stories/Field.stories.tsx (storybook stories)
diff --git a/packages/core/src/Field/XDSFieldLabel.tsx b/packages/core/src/Field/XDSFieldLabel.tsx
index 73e6a37e8a..2798155e35 100644
--- a/packages/core/src/Field/XDSFieldLabel.tsx
+++ b/packages/core/src/Field/XDSFieldLabel.tsx
@@ -5,7 +5,7 @@
* @position Core label implementation; used by XDSField, XDSCheckboxInput
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Field/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Field/index.ts (exports if types change)
*/
diff --git a/packages/core/src/Field/XDSFieldStatus.tsx b/packages/core/src/Field/XDSFieldStatus.tsx
index fe25f0e2a1..b0d23af9b7 100644
--- a/packages/core/src/Field/XDSFieldStatus.tsx
+++ b/packages/core/src/Field/XDSFieldStatus.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, XDSField.tsx, XDSSwitch.tsx, XDSCheckboxInput.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Field/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Field/index.ts (exports if types change)
*/
diff --git a/packages/core/src/Field/index.ts b/packages/core/src/Field/index.ts
index 973e8c7bfc..f29c197731 100644
--- a/packages/core/src/Field/index.ts
+++ b/packages/core/src/Field/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSField, XDSFieldProps, XDSFieldStatus, XDSFieldStatusType, XDSFieldLabel, XDSFieldLabelProps, XDSFieldStatus component
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Field/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Field/Field.doc.mjs
*/
export {XDSField} from './XDSField';
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
new file mode 100644
index 0000000000..77525c2777
--- /dev/null
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -0,0 +1,80 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'FormLayout',
+ description:
+ 'A spatial layout container for arranging form fields with consistent spacing and direction.',
+ props: [
+ {
+ name: 'direction',
+ type: "'vertical' | 'horizontal' | 'horizontal-labels'",
+ description:
+ 'Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px).',
+ default: "'vertical'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Form fields to arrange. Accepts XDS inputs (XDSTextInput, XDSSelector, etc.) and XDSField-wrapped custom controls.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Vertical layout (default)',
+ code: `<XDSFormLayout>
+ <XDSTextInput label="Name" value={name} onChange={setName} />
+ <XDSTextInput label="Email" value={email} onChange={setEmail} />
+</XDSFormLayout>`,
+ },
+ {
+ label: 'Horizontal layout for related fields',
+ code: `<XDSFormLayout direction="horizontal">
+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />
+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />
+</XDSFormLayout>`,
+ },
+ {
+ label: 'Horizontal labels for settings panels',
+ code: `<XDSFormLayout direction="horizontal-labels">
+ <XDSTextInput label="Display Name" value={name} onChange={setName} />
+ <XDSSelector label="Timezone" value={tz} onChange={setTz} options={tzs} />
+</XDSFormLayout>`,
+ },
+ {
+ label: 'Nested layouts',
+ code: `<XDSFormLayout direction="vertical">
+ <XDSFormLayout direction="horizontal">
+ <XDSTextInput label="First Name" value={first} onChange={setFirst} />
+ <XDSTextInput label="Last Name" value={last} onChange={setLast} />
+ </XDSFormLayout>
+ <XDSTextInput label="Email" value={email} onChange={setEmail} />
+</XDSFormLayout>`,
+ },
+ {
+ label: 'Dialog composition via HTML form attribute',
+ code: `<XDSDialog>
+ <form id="edit-form" onSubmit={handleSubmit}>
+ <XDSFormLayout>
+ <XDSTextInput label="Name" value={name} onChange={setName} />
+ </XDSFormLayout>
+ </form>
+ <XDSDialogFooter>
+ <XDSButton label="Save" type="submit" form="edit-form" />
+ </XDSDialogFooter>
+</XDSDialog>`,
+ },
+ ],
+ features: [
+ "Three layout modes: 'vertical' (default), 'horizontal', and 'horizontal-labels'",
+ 'Direction context via XDSFormLayoutContext — children can read the current layout direction',
+ 'Responsive: horizontal-labels collapses to vertical on narrow viewports (<=480px)',
+ 'Nestable: inner FormLayout overrides context for its children',
+ 'Purely spatial: does not manage form state or render <form> — form submission is separate',
+ ],
+ notes: [
+ 'Renders a <div>, not a <form>. Use a separate <form> element and connect submit buttons via the HTML form attribute.',
+ 'XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout to read layout direction in custom components.',
+ 'Also accepts standard HTML div attributes (id, role, aria-*, etc.) via rest props.',
+ ],
+};
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
new file mode 100644
index 0000000000..da70b3c6f1
--- /dev/null
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -0,0 +1,162 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Grid',
+ description: 'CSS Grid-based layout with responsive auto-fit support.',
+ features: [
+ 'Fixed-column grids via the `columns` prop',
+ 'Responsive auto-fit columns via `minChildWidth` — items wrap based on available space',
+ 'Combine `minChildWidth` and `columns` to cap the maximum number of columns',
+ 'Gap tokens via `SpacingScale` values for `gap`, `rowGap`, and `columnGap`',
+ 'Vertical and horizontal item alignment via `align` and `justify`',
+ 'XDSGridSpan lets individual items span multiple columns or rows',
+ 'Theming support — override root styles via the `grid` component key',
+ ],
+ examples: [
+ {
+ label: 'Fixed 3-column grid',
+ code: `<XDSGrid columns={3} gap="space4">
+ <Item />
+ <Item />
+ <Item />
+</XDSGrid>`,
+ },
+ {
+ label: 'Responsive auto-fit',
+ code: `<XDSGrid minChildWidth={200} gap="space4">
+ <Card />
+ <Card />
+ <Card />
+</XDSGrid>`,
+ },
+ {
+ label: 'Auto-fit with max columns cap',
+ code: `<XDSGrid minChildWidth={200} columns={4} gap="space4">
+ <Card />
+</XDSGrid>`,
+ },
+ {
+ label: 'Grid item spanning multiple columns',
+ code: `<XDSGrid columns={3} gap="space4">
+ <XDSGridSpan columns={2}>Wide item</XDSGridSpan>
+ <div>Normal item</div>
+</XDSGrid>`,
+ },
+ {
+ label: 'Dense grid (e.g. color swatches, icon grids, compact controls)',
+ code: `<XDSGrid columns={6} gap="space2">
+ {items.map(item => (
+ <XDSButton key={item.id} label={item.label} icon={item.icon} variant="ghost" size="sm" />
+ ))}
+</XDSGrid>`,
+ },
+ ],
+ theming: {
+ componentKey: 'grid',
+ surfaces: [{name: 'root', description: 'Root grid container styles'}],
+ },
+ notes: [
+ 'Use XDSGrid for any grid layout instead of manual CSS grid (`display: "grid"`, `gridTemplateColumns`). It handles gap tokens and works with any column count.',
+ ],
+ components: [
+ {
+ name: 'XDSGrid',
+ description: 'Grid container with fixed or responsive auto-fit columns.',
+ props: [
+ {
+ name: 'columns',
+ type: 'number',
+ description: 'Maximum number of columns.',
+ },
+ {
+ name: 'minChildWidth',
+ type: 'number',
+ description:
+ 'Minimum item width in px; enables responsive auto-fit column behaviour.',
+ },
+ {
+ name: 'width',
+ type: 'number | string',
+ description: 'Container width.',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Container height.',
+ },
+ {
+ name: 'gap',
+ type: 'SpacingScale',
+ description: 'Spacing between all items.',
+ },
+ {
+ name: 'rowGap',
+ type: 'SpacingScale',
+ description: 'Row spacing; overrides `gap` for the row axis.',
+ },
+ {
+ name: 'columnGap',
+ type: 'SpacingScale',
+ description: 'Column spacing; overrides `gap` for the column axis.',
+ },
+ {
+ name: 'align',
+ type: 'GridAlignment',
+ description: 'Vertical alignment of items.',
+ default: "'stretch'",
+ },
+ {
+ name: 'justify',
+ type: 'GridAlignment',
+ description: 'Horizontal alignment of items.',
+ default: "'stretch'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Grid content.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSGrid columns={3} gap="space4">
+ <Item />
+ <Item />
+ <Item />
+</XDSGrid>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSGridSpan',
+ description: 'Grid item that spans multiple columns or rows.',
+ props: [
+ {
+ name: 'columns',
+ type: "number | 'full'",
+ description: "Columns to span; use `'full'` to span the entire row.",
+ },
+ {
+ name: 'rows',
+ type: 'number',
+ description: 'Rows to span.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Spanning two columns',
+ code: `<XDSGrid columns={3} gap="space4">
+ <XDSGridSpan columns={2}>Wide item</XDSGridSpan>
+ <div>Normal item</div>
+</XDSGrid>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Grid/README.md b/packages/core/src/Grid/README.md
deleted file mode 100644
index 6e4d72f862..0000000000
--- a/packages/core/src/Grid/README.md
+++ /dev/null
@@ -1,114 +0,0 @@
-# XDSGrid
-
-CSS Grid-based layout with responsive auto-fit support.
-
-## Import
-
-```tsx
-import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';
-```
-
-### XDSGrid
-
-Grid container with fixed or responsive auto-fit columns.
-
-```tsx
-<XDSGrid columns={3} gap="space4">
- <Item />
- <Item />
- <Item />
-</XDSGrid>
-```
-
-| Prop | Type | Default | Description |
-| --------------- | ---------------- | ----------- | ---------------------------------------------- |
-| `columns` | `number` | — | Maximum number of columns |
-| `minChildWidth` | `number` | — | Min item width in px (enables auto-fit) |
-| `width` | `number \| string` | — | Container width |
-| `height` | `number \| string` | — | Container height |
-| `gap` | `SpacingScale` | — | Spacing between all items |
-| `rowGap` | `SpacingScale` | — | Row spacing (overrides gap) |
-| `columnGap` | `SpacingScale` | — | Column spacing (overrides gap) |
-| `align` | `GridAlignment` | `'stretch'` | Vertical alignment of items |
-| `justify` | `GridAlignment` | `'stretch'` | Horizontal alignment of items |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
-| `children` | `ReactNode` | — | Grid content |
-
-### XDSGridSpan
-
-Grid item that spans multiple columns or rows.
-
-```tsx
-<XDSGrid columns={3} gap="space4">
- <XDSGridSpan columns={2}>Wide item</XDSGridSpan>
- <div>Normal item</div>
-</XDSGrid>
-```
-
-| Prop | Type | Default | Description |
-| ---------- | -------------------- | ------- | ---------------------------------------- |
-| `columns` | `number \| 'full'` | — | Columns to span ('full' = entire row) |
-| `rows` | `number` | — | Rows to span |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
-| `children` | `ReactNode` | — | Content |
-
-## Usage
-
-```tsx
-// Fixed 3-column grid
-<XDSGrid columns={3} gap="space4">
- <Item />
- <Item />
- <Item />
-</XDSGrid>
-
-// Responsive auto-fit (items wrap based on min width)
-<XDSGrid minChildWidth={200} gap="space4">
- <Card />
- <Card />
- <Card />
-</XDSGrid>
-
-// Auto-fit with max columns cap
-<XDSGrid minChildWidth={200} columns={4} gap="space4">
- <Card />
-</XDSGrid>
-
-// Grid item spanning multiple columns
-<XDSGrid columns={3} gap="space4">
- <XDSGridSpan span={2}>Wide item</XDSGridSpan>
- <div>Normal item</div>
-</XDSGrid>
-
-// Dense grid (e.g. color swatches, icon grids, compact controls)
-<XDSGrid columns={6} gap="space2">
- {items.map(item => (
- <XDSButton key={item.id} label={item.label} icon={item.icon} variant="ghost" size="sm" />
- ))}
-</XDSGrid>
-```
-
-Use `XDSGrid` for any grid layout instead of manual CSS grid (`display: 'grid'`,
-`gridTemplateColumns`). It handles gap tokens and works with any column count.
-
-## Theming
-
-Themes can override `Grid` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- grid: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | -------------------------- |
-| `root` | Root grid container styles |
diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsx
index b8a1505703..cc68abe845 100644
--- a/packages/core/src/Grid/XDSGrid.tsx
+++ b/packages/core/src/Grid/XDSGrid.tsx
@@ -5,7 +5,7 @@
* @position Grid component; provides CSS Grid-based layout
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Grid/README.md
+ * - /packages/core/src/Grid/Grid.doc.mjs
* - /packages/core/src/Grid/XDSGrid.test.tsx
* - /apps/storybook/stories/Grid.stories.tsx
*/
diff --git a/packages/core/src/Grid/XDSGridSpan.tsx b/packages/core/src/Grid/XDSGridSpan.tsx
index 48bd5eeb57..7d7d331730 100644
--- a/packages/core/src/Grid/XDSGridSpan.tsx
+++ b/packages/core/src/Grid/XDSGridSpan.tsx
@@ -5,7 +5,7 @@
* @position Grid span component; controls grid item span
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Grid/README.md
+ * - /packages/core/src/Grid/Grid.doc.mjs
* - /packages/core/src/Grid/XDSGrid.test.tsx
* - /apps/storybook/stories/Grid.stories.tsx
*/
diff --git a/packages/core/src/Grid/index.ts b/packages/core/src/Grid/index.ts
index 839cce3dde..072f1cda27 100644
--- a/packages/core/src/Grid/index.ts
+++ b/packages/core/src/Grid/index.ts
@@ -4,7 +4,7 @@
* @output Exports Grid components and types
* @position Package entry point for Grid
*
- * SYNC: When modified, update /packages/core/src/Grid/README.md
+ * SYNC: When modified, update /packages/core/src/Grid/Grid.doc.mjs
*/
export {XDSGrid} from './XDSGrid';
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
new file mode 100644
index 0000000000..ca138029f5
--- /dev/null
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -0,0 +1,97 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Icon',
+ description:
+ 'Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.',
+ features: [
+ "Semantic Icon Names: Use names like 'close' or 'chevronDown' — resolved from the theme's icon registry",
+ 'Direct Icon Components: Pass any SVG icon component (heroicons, lucide, etc.) directly',
+ "Theme-Adaptable: Semantic icons automatically match the active theme's icon set",
+ 'Built-in Fallbacks: 12 lightweight inline SVGs (~1.4KB) ensure icons render without a theme',
+ 'Theme Colors: Color variants mapped to XDS icon color tokens',
+ 'Consistent Sizing: Four size options aligned with common UI patterns',
+ 'Accessible: Icons are hidden from screen readers by default (aria-hidden)',
+ ],
+ props: [
+ {
+ name: 'icon',
+ type: 'XDSIconName | ComponentType<SVGProps>',
+ description: 'Semantic name or SVG icon component.',
+ required: true,
+ },
+ {
+ name: 'color',
+ type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'positive' | 'negative' | 'warning' | 'inherit'",
+ description: 'Color variant mapped to XDS icon color tokens.',
+ default: "'primary'",
+ },
+ {
+ name: 'size',
+ type: "'xsm' | 'sm' | 'md' | 'lg'",
+ description: 'Icon size.',
+ default: "'md'",
+ },
+ ],
+ examples: [
+ {
+ label: 'Semantic icon names (theme-adaptable)',
+ code: `import { XDSIcon } from '@xds/core/Icon';
+
+// Semantic name — adapts to theme
+<XDSIcon icon="close" />
+<XDSIcon icon="chevronDown" size="sm" color="inherit" />
+<XDSIcon icon="checkCircle" color="positive" />
+
+// Great for building theme-adaptable UI
+<XDSIcon icon="info" size="sm" color="secondary" />`,
+ },
+ {
+ label: 'Direct icon components',
+ code: `import { XDSIcon } from '@xds/core/Icon';
+import { HomeIcon } from '@heroicons/react/24/outline';
+import { HeartIcon } from '@heroicons/react/24/solid';
+
+// Direct component
+<XDSIcon icon={HomeIcon} />
+<XDSIcon icon={HomeIcon} color="accent" size="lg" />
+<XDSIcon icon={HeartIcon} color="negative" />
+
+// Accessible icon with label
+<XDSIcon icon={HomeIcon} aria-hidden={false} aria-label="Home" role="img" />`,
+ },
+ {
+ label: 'Icon sources',
+ code: `// Heroicons
+import {HomeIcon} from '@heroicons/react/24/outline';
+
+// Lucide
+import {Home} from 'lucide-react';
+
+// Any component matching ComponentType<SVGProps<SVGSVGElement>>`,
+ },
+ ],
+ theming: {
+ componentKey: 'icon',
+ surfaces: [
+ {
+ name: 'root',
+ description: 'Root SVG element styles',
+ },
+ ],
+ },
+ accessibility: [
+ 'Icons are hidden from screen readers by default via aria-hidden="true" since icons are typically decorative.',
+ 'For meaningful icons, set aria-hidden={false}, role="img", and aria-label to provide accessible context.',
+ ],
+ notes: [
+ 'When icon is a semantic name string, resolution order is: (1) theme registry — if an XDSTheme is active and provides an icon for that name, it is used; (2) built-in fallback — otherwise, a lightweight inline SVG is rendered. Components always render visually complete, even without a theme. Themes can override any or all icons; the registry accepts partial overrides.',
+ 'When icon is a component, additional SVG props (like aria-label, role) are passed through to the underlying SVG element.',
+ 'flexShrink: 0 prevents icons from shrinking in flex containers.',
+ 'String mode wraps the resolved icon in a <span> with fontSize-based sizing so 1em-based registry icons scale correctly.',
+ 'Component mode passes stylex.props directly to the SVG element for zero-overhead styling.',
+ 'Semantic icon names and their usages — close (CloseButton, TimeInput): ✕ close/dismiss; chevronDown (DropdownMenu, Selector, TabMenu): ▾ expand/dropdown; chevronLeft (Calendar): ‹ previous; chevronRight (Calendar): › next; check (Selector, TabMenu): ✓ selected item; checkCircle (Input status): ✓○ success; xCircle (Input status): ✕○ error; warning (Input status): △! warning; info (FieldLabel): ⓘ information tooltip; calendar (DateInput): 📅 date picker; clock (TimeInput): 🕐 time picker; externalLink (Link): ↗ opens in new window.',
+ 'Color token mappings — primary: --color-icon-primary (default); secondary: --color-icon-secondary (de-emphasized); tertiary: --color-icon-tertiary (subtle/background); disabled: --color-icon-disabled (disabled state); accent: --color-accent (interactive/actionable); positive: --color-positive (success/confirmation); negative: --color-negative (error/destructive); warning: --color-warning (caution/attention); inherit: currentColor (inherits from parent text color).',
+ 'Size dimensions — xsm: 12x12px (dense UI, badges, indicators); sm: 16x16px (inline with text, compact UI); md: 20x20px (default, buttons, inputs); lg: 24x24px (emphasis, standalone icons).',
+ ],
+};
diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsx
index f48866d284..f19f14891e 100644
--- a/packages/core/src/Icon/IconRegistry.tsx
+++ b/packages/core/src/Icon/IconRegistry.tsx
@@ -5,7 +5,7 @@
* @position Core icon infrastructure; consumed by components that need internal icons
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Icon/README.md (features, usage)
+ * - /packages/core/src/Icon/Icon.doc.mjs (features, usage)
* - /packages/core/src/Icon/index.ts (exports)
* - /packages/core/src/Icon/defaultIcons.tsx (fallback icon set)
*/
diff --git a/packages/core/src/Icon/README.md b/packages/core/src/Icon/README.md
deleted file mode 100644
index f7ad785c62..0000000000
--- a/packages/core/src/Icon/README.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# Icon
-
-Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Semantic Icon Names**: Use names like `'close'` or `'chevronDown'` — resolved from the theme's icon registry
-- **Direct Icon Components**: Pass any SVG icon component (heroicons, lucide, etc.) directly
-- **Theme-Adaptable**: Semantic icons automatically match the active theme's icon set
-- **Built-in Fallbacks**: 12 lightweight inline SVGs (~1.4KB) ensure icons render without a theme
-- **Theme Colors**: Color variants mapped to XDS icon color tokens
-- **Consistent Sizing**: Four size options aligned with common UI patterns
-- **Accessible**: Icons are hidden from screen readers by default (aria-hidden)
-
-## Usage
-
-### Semantic icon names (theme-adaptable)
-
-Use semantic names for icons that should adapt to the active theme. These resolve from the theme's icon registry, falling back to built-in SVGs when no theme is present.
-
-```tsx
-import { XDSIcon } from '@xds/core/Icon';
-
-// Semantic name — adapts to theme
-<XDSIcon icon="close" />
-<XDSIcon icon="chevronDown" size="sm" color="inherit" />
-<XDSIcon icon="checkCircle" color="positive" />
-
-// Great for building theme-adaptable UI
-<XDSIcon icon="info" size="sm" color="secondary" />
-```
-
-### Direct icon components
-
-Pass SVG icon components directly when you need a specific icon that isn't in the semantic set, or when you want full control.
-
-```tsx
-import { XDSIcon } from '@xds/core/Icon';
-import { HomeIcon } from '@heroicons/react/24/outline';
-import { HeartIcon } from '@heroicons/react/24/solid';
-
-// Direct component
-<XDSIcon icon={HomeIcon} />
-<XDSIcon icon={HomeIcon} color="accent" size="lg" />
-<XDSIcon icon={HeartIcon} color="negative" />
-
-// Accessible icon with label
-<XDSIcon icon={HomeIcon} aria-hidden={false} aria-label="Home" role="img" />
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------- | ------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------- |
-| `icon` | `XDSIconName \| ComponentType<SVGProps>` | (required) | Semantic name or SVG icon component |
-| `color` | `'primary' \| 'secondary' \| 'tertiary' \| 'disabled' \| 'accent' \| 'positive' \| 'negative' \| 'warning' \| 'inherit'` | `'primary'` | Color variant |
-| `size` | `'xsm' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Icon size |
-
-When `icon` is a component, additional SVG props (like `aria-label`, `role`) are passed through to the underlying SVG element.
-
-## Semantic Icon Names
-
-These names are used internally by XDS components and can be used in your own UI to build theme-adaptable interfaces. They resolve from the theme's icon registry, or fall back to built-in lightweight SVGs.
-
-| Name | Used by | Description |
-| -------------- | ------------------------------- | --------------------- |
-| `close` | CloseButton, TimeInput | ✕ close / dismiss |
-| `chevronDown` | DropdownMenu, Selector, TabMenu | ▾ expand / dropdown |
-| `chevronLeft` | Calendar | ‹ previous |
-| `chevronRight` | Calendar | › next |
-| `check` | Selector, TabMenu | ✓ selected item |
-| `checkCircle` | Input status | ✓○ success |
-| `xCircle` | Input status | ✕○ error |
-| `warning` | Input status | △! warning |
-| `info` | FieldLabel | ⓘ information tooltip |
-| `calendar` | DateInput | 📅 date picker |
-| `clock` | TimeInput | 🕐 time picker |
-| `externalLink` | Link | ↗ opens in new window |
-
-## Color Variants
-
-| Value | Token | Use Case |
-| ----------- | ------------------------ | ------------------------------- |
-| `primary` | `--color-icon-primary` | Default icon color |
-| `secondary` | `--color-icon-secondary` | De-emphasized icons |
-| `tertiary` | `--color-icon-tertiary` | Subtle, background icons |
-| `disabled` | `--color-icon-disabled` | Disabled state |
-| `accent` | `--color-accent` | Interactive, actionable icons |
-| `positive` | `--color-positive` | Success, confirmation |
-| `negative` | `--color-negative` | Error, destructive actions |
-| `warning` | `--color-warning` | Caution, attention |
-| `inherit` | `currentColor` | Inherits from parent text color |
-
-## Size Variants
-
-| Value | Dimensions | Use Case |
-| ----- | ---------- | ---------------------------- |
-| `xsm` | 12x12px | Dense UI, badges, indicators |
-| `sm` | 16x16px | Inline with text, compact UI |
-| `md` | 20x20px | Default, buttons, inputs |
-| `lg` | 24x24px | Emphasis, standalone icons |
-
-## How Icon Resolution Works
-
-When `icon` is a semantic name string:
-
-1. **Theme registry** — If an `XDSTheme` is active and provides an icon for that name, it's used
-2. **Built-in fallback** — Otherwise, a lightweight inline SVG is rendered
-
-This means components always render visually complete, even without a theme. Themes can override any or all icons — the registry accepts partial overrides.
-
-## Icon Sources
-
-Any SVG icon component works with the direct component mode:
-
-```tsx
-// Heroicons
-import {HomeIcon} from '@heroicons/react/24/outline';
-
-// Lucide
-import {Home} from 'lucide-react';
-
-// Any component matching ComponentType<SVGProps<SVGSVGElement>>
-```
-
-## Theming
-
-Themes can override `Icon` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- icon: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | ----------------------- |
-| `root` | Root SVG element styles |
-
-## Files
-
-| File | Role | Purpose |
-| ------------------ | -------- | ---------------------------------------- |
-| `index.ts` | Entry | Exports component, types, and registry |
-| `XDSIcon.tsx` | Core | Component implementation (both modes) |
-| `IconRegistry.tsx` | Registry | Context, hook, and semantic name types |
-| `defaultIcons.tsx` | Fallback | 12 lightweight inline SVG fallback icons |
-| `XDSIcon.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Uses `aria-hidden="true"` by default since icons are typically decorative
-- For meaningful icons, set `aria-hidden={false}`, `role="img"`, and `aria-label`
-- `flexShrink: 0` prevents icons from shrinking in flex containers
-- String mode wraps the resolved icon in a `<span>` with `fontSize`-based sizing so `1em`-based registry icons scale correctly
-- Component mode passes `stylex.props` directly to the SVG element for zero-overhead styling
diff --git a/packages/core/src/Icon/XDSIcon.tsx b/packages/core/src/Icon/XDSIcon.tsx
index 007932a997..433c152ff7 100644
--- a/packages/core/src/Icon/XDSIcon.tsx
+++ b/packages/core/src/Icon/XDSIcon.tsx
@@ -11,7 +11,7 @@
* theme's icon registry (or built-in fallback SVGs) and wrapped in a styled span.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Icon/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Icon/Icon.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Icon/XDSIcon.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Icon/index.ts (exports if types change)
* - /apps/storybook/stories/Icon.stories.tsx (storybook stories)
diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsx
index b17add46b2..07aa267bd9 100644
--- a/packages/core/src/Icon/defaultIcons.tsx
+++ b/packages/core/src/Icon/defaultIcons.tsx
@@ -18,7 +18,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Icon/IconRegistry.tsx (XDSIconName type if names change)
- * - /packages/core/src/Icon/README.md (fallback icon documentation)
+ * - /packages/core/src/Icon/Icon.doc.mjs (fallback icon documentation)
*/
import type {XDSIconRegistry} from './IconRegistry';
diff --git a/packages/core/src/Icon/index.ts b/packages/core/src/Icon/index.ts
index 828d275321..642f72ade0 100644
--- a/packages/core/src/Icon/index.ts
+++ b/packages/core/src/Icon/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSIcon, its prop types, icon registry context, and semantic name types
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Icon/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Icon/Icon.doc.mjs
*/
export {XDSIcon} from './XDSIcon';
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
new file mode 100644
index 0000000000..41eb544a28
--- /dev/null
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -0,0 +1,464 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Layer',
+ description:
+ 'Hooks and components for overlay content using CSS Anchor Positioning and the Popover API — no React portals needed.',
+ features: [
+ 'CSS Anchor Positioning for automatic placement relative to trigger elements',
+ 'Popover API for top-layer rendering — no React portals needed',
+ 'Type-safe mode system: context mode (anchor positioning) and fixed mode (manual coordinates)',
+ 'TypeScript enforces correct render props per mode at compile time',
+ 'Hover/focus triggered layers with configurable show and hide delays',
+ 'Controlled and uncontrolled popover modes',
+ 'Light dismiss support (click outside or Escape to close)',
+ 'Focus trap inside open popovers',
+ 'ARIA button + dialog pattern applied automatically to trigger elements',
+ 'Graceful degradation in Firefox: Popover API works, anchor positioning degrades acceptably',
+ 'Full support in Chrome and Safari',
+ ],
+ notes: [
+ 'CSS Anchor Positioning is fully supported in Chrome and Safari. Firefox supports the Popover API but not anchor positioning — this is an acceptable degradation.',
+ 'useXDSLayer context mode: pass a ref to the trigger element, then call render(children, { placement?, alignment? }). Fixed mode: call show() to display, then render(children, { x, y }) with required coordinates.',
+ 'When using hooks directly, compose aria-describedby with your own IDs using a mergeIds utility: ids.filter(Boolean).join(" ") || undefined.',
+ 'XDSPopover locates the trigger button inside children by searching for <button> or [role="button"] — the child tree must contain one. It applies click/keydown handlers and aria-haspopup, aria-expanded, aria-controls automatically.',
+ 'XDSPopover uses an inline-flex anchor wrapper so that pressed-state transforms on the trigger (e.g. :active scale) do not shift the anchor position and cause popover jitter.',
+ 'In sibling mode (anchorRef prop), XDSPopover and XDSTooltip attach to an external ref rather than wrapping children — useful when the trigger and overlay are not parent/child.',
+ 'XDSHoverCard (hook) returns a describedBy id — pass it as aria-describedby on the trigger for screen reader support.',
+ 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',
+ ],
+ accessibility: [
+ 'XDSPopover implements the button + dialog ARIA pattern: aria-haspopup, aria-expanded, and aria-controls are set on the trigger button automatically.',
+ 'XDSTooltip links the tooltip content to the trigger via aria-describedby.',
+ 'useXDSHoverCard returns a describedBy id that should be spread onto the trigger element so screen readers announce the hover card content.',
+ 'When composing multiple aria-describedby sources, merge them with a utility: ids.filter(Boolean).join(" ") || undefined.',
+ 'XDSPopover traps focus inside the popover dialog while it is open.',
+ 'XDSPopover supports keyboard activation for role="button" elements (Enter and Space) in addition to native <button> click synthesis.',
+ ],
+ keyboard:
+ 'Escape closes any open layer. Enter/Space open a popover when the trigger has focus. Focus is trapped inside an open XDSPopover.',
+ examples: [
+ {
+ label: 'useXDSLayer — context mode',
+ code: `const layer = useXDSLayer({mode: 'context'});
+
+<button ref={layer.ref}>Trigger</button>
+{layer.render(<Content />, {placement: 'above', alignment: 'center'})}`,
+ },
+ {
+ label: 'useXDSLayer — fixed mode',
+ code: `const layer = useXDSLayer({mode: 'fixed'});
+
+layer.show();
+{layer.render(<Content />, {x: mouseX, y: mouseY})}`,
+ },
+ {
+ label: 'useXDSHoverCard',
+ code: `const hoverCard = useXDSHoverCard({placement: 'above'});
+
+<XDSButton ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>
+ Hover me
+</XDSButton>
+{hoverCard.renderHoverCard(<ProfileCard user={user} />)}`,
+ },
+ {
+ label: 'XDSTooltip',
+ code: `<XDSTooltip content="Save your changes" placement="above">
+ <XDSButton label="Save" variant="primary" />
+</XDSTooltip>`,
+ },
+ {
+ label: 'XDSHoverCard',
+ code: `<XDSHoverCard content={<ProfileCard user={user} />} placement="above">
+ <XDSButton>Hover me</XDSButton>
+</XDSHoverCard>`,
+ },
+ {
+ label: 'XDSPopover — basic',
+ code: `<XDSPopover label="Settings" content={<SettingsPanel />} placement="below">
+ <XDSButton label="Settings" />
+</XDSPopover>`,
+ },
+ {
+ label: 'XDSPopover — controlled',
+ code: `<XDSPopover
+ isShown={isOpen}
+ onToggle={setIsOpen}
+ label="Filter"
+ content={<FilterForm />}
+>
+ <XDSButton label="Filter" />
+</XDSPopover>`,
+ },
+ {
+ label: 'XDSPopover — sibling mode with anchorRef',
+ code: `<XDSPopover
+ anchorRef={myButtonRef}
+ label="Actions"
+ content={<ActionMenu />}
+ placement="below"
+/>`,
+ },
+ {
+ label: 'Composing aria-describedby with useXDSHoverCard',
+ code: `const hoverCard = useXDSHoverCard();
+
+function mergeIds(...ids: (string | undefined)[]) {
+ return ids.filter(Boolean).join(' ') || undefined;
+}
+
+<XDSInput
+ ref={hoverCard.ref}
+ aria-describedby={mergeIds(fieldErrorId, hoverCard.describedBy)}
+/>`,
+ },
+ ],
+ components: [
+ {
+ name: 'useXDSLayer',
+ description:
+ 'Core layer hook with type-safe modes for different positioning strategies (context mode for anchor positioning, fixed mode for manual coordinates).',
+ props: [
+ {
+ name: 'mode',
+ type: "'context' | 'fixed'",
+ description:
+ 'Positioning strategy: context uses CSS anchor positioning relative to a trigger ref; fixed uses explicit x/y coordinates.',
+ required: true,
+ },
+ {
+ name: 'onShow',
+ type: '() => void',
+ description: 'Callback fired when the layer becomes visible.',
+ },
+ {
+ name: 'onHide',
+ type: '() => void',
+ description: 'Callback fired when the layer is hidden.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Context mode',
+ code: `const layer = useXDSLayer({mode: 'context'});
+
+<button ref={layer.ref}>Trigger</button>
+{layer.render(<Content />, {placement: 'above', alignment: 'center'})}`,
+ },
+ {
+ label: 'Fixed mode',
+ code: `const layer = useXDSLayer({mode: 'fixed'});
+
+layer.show();
+{layer.render(<Content />, {x: mouseX, y: mouseY})}`,
+ },
+ ],
+ },
+ {
+ name: 'useXDSHoverCard',
+ description:
+ 'Hook for hover/focus triggered layers with configurable show and hide timing.',
+ props: [
+ {
+ name: 'placement',
+ type: 'LayerPlacement',
+ description: 'Position relative to the anchor element.',
+ default: "'above'",
+ },
+ {
+ name: 'alignment',
+ type: 'LayerAlignment',
+ description: 'Alignment along the placement axis.',
+ default: "'center'",
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: 'Show delay in milliseconds.',
+ default: '300',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description: 'Hide delay in milliseconds.',
+ default: '200',
+ },
+ {
+ name: 'focusTrigger',
+ type: "'auto' | 'always' | 'never'",
+ description: 'Controls when focus events trigger the layer.',
+ default: "'auto'",
+ },
+ {
+ name: 'isEnabled',
+ type: 'boolean',
+ description: 'Enables or disables all hover and focus triggers.',
+ default: 'true',
+ },
+ {
+ name: 'onShow',
+ type: '() => void',
+ description: 'Callback fired when the hover card becomes visible.',
+ },
+ {
+ name: 'onHide',
+ type: '() => void',
+ description: 'Callback fired when the hover card is hidden.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic usage',
+ code: `const hoverCard = useXDSHoverCard({placement: 'above'});
+
+<XDSButton ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>
+ Hover me
+</XDSButton>
+{hoverCard.renderHoverCard(<ProfileCard user={user} />)}`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTooltip',
+ description:
+ 'Component wrapper for tooltip display triggered on hover or focus.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Trigger element(s) that activate the tooltip.',
+ },
+ {
+ name: 'anchorRef',
+ type: 'RefObject<HTMLElement>',
+ description:
+ 'External anchor ref for sibling mode — attaches the tooltip to this element instead of wrapping children.',
+ },
+ {
+ name: 'content',
+ type: 'ReactNode',
+ description: 'Tooltip content, typically short text.',
+ },
+ {
+ name: 'placement',
+ type: 'LayerPlacement',
+ description: 'Position relative to the anchor element.',
+ default: "'above'",
+ },
+ {
+ name: 'alignment',
+ type: 'LayerAlignment',
+ description: 'Alignment along the placement axis.',
+ default: "'center'",
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: 'Show delay in milliseconds.',
+ default: '200',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description: 'Hide delay in milliseconds.',
+ default: '0',
+ },
+ {
+ name: 'focusTrigger',
+ type: "'auto' | 'always' | 'never'",
+ description: 'Controls when focus events trigger the tooltip.',
+ default: "'auto'",
+ },
+ {
+ name: 'isEnabled',
+ type: 'boolean',
+ description: 'Enables or disables the tooltip triggers.',
+ default: 'true',
+ },
+ {
+ name: 'hasHoverIndication',
+ type: "'auto' | boolean",
+ description:
+ 'Shows a dashed underline on the trigger element to indicate a tooltip is available.',
+ default: "'auto'",
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic tooltip',
+ code: `<XDSTooltip content="Save your changes" placement="above">
+ <XDSButton label="Save" variant="primary" />
+</XDSTooltip>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSHoverCard',
+ description:
+ 'Component wrapper for hover card display — a richer, larger overlay triggered on hover or focus.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Trigger element that must accept a ref.',
+ },
+ {
+ name: 'content',
+ type: 'ReactNode',
+ description: 'Hover card content.',
+ required: true,
+ },
+ {
+ name: 'placement',
+ type: 'LayerPlacement',
+ description: 'Position relative to the anchor element.',
+ default: "'above'",
+ },
+ {
+ name: 'alignment',
+ type: 'LayerAlignment',
+ description: 'Alignment along the placement axis.',
+ default: "'center'",
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: 'Show delay in milliseconds.',
+ default: '300',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description: 'Hide delay in milliseconds.',
+ default: '200',
+ },
+ {
+ name: 'focusTrigger',
+ type: "'auto' | 'always' | 'never'",
+ description: 'Controls when focus events trigger the hover card.',
+ default: "'auto'",
+ },
+ {
+ name: 'isEnabled',
+ type: 'boolean',
+ description: 'Enables or disables the hover and focus triggers.',
+ default: 'true',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic hover card',
+ code: `<XDSHoverCard content={<ProfileCard user={user} />} placement="above">
+ <XDSButton>Hover me</XDSButton>
+</XDSHoverCard>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSPopover',
+ description:
+ 'A click-triggered popover for displaying interactive content anchored to a trigger element, implementing the button + dialog ARIA pattern.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Trigger element. Must contain a <button> or [role="button"] element — the popover finds it and applies click/keydown handlers and ARIA attributes.',
+ },
+ {
+ name: 'anchorRef',
+ type: 'React.RefObject<HTMLElement>',
+ description:
+ 'External ref to use as the popover anchor in sibling mode. The referenced element must be a <button> or [role="button"].',
+ },
+ {
+ name: 'content',
+ type: 'ReactNode',
+ description: 'Content to display inside the popover.',
+ required: true,
+ },
+ {
+ name: 'placement',
+ type: 'LayerPlacement',
+ description:
+ 'Position placement relative to the trigger using CSS anchor positioning.',
+ default: "'below'",
+ },
+ {
+ name: 'alignment',
+ type: 'LayerAlignment',
+ description: 'Alignment along the placement axis.',
+ default: "'start'",
+ },
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description:
+ 'Whether the popover is shown in controlled mode. Omit for uncontrolled behavior.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback fired when the popover visibility changes.',
+ },
+ {
+ name: 'isEnabled',
+ type: 'boolean',
+ description: 'When false, trigger interactions are ignored.',
+ default: 'true',
+ },
+ {
+ name: 'width',
+ type: 'number | string',
+ description:
+ 'Width of the popover container. Numbers are treated as px; strings are used as-is. Defaults to matching the trigger width.',
+ default: "'auto'",
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label for the popover dialog, used as aria-label on the dialog element. Recommended for accessibility.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic popover',
+ code: `<XDSPopover label="Settings" content={<SettingsPanel />} placement="below">
+ <XDSButton label="Settings" />
+</XDSPopover>`,
+ },
+ {
+ label: 'Controlled popover',
+ code: `<XDSPopover
+ isShown={isOpen}
+ onToggle={setIsOpen}
+ label="Filter"
+ content={<FilterForm />}
+>
+ <XDSButton label="Filter" />
+</XDSPopover>`,
+ },
+ {
+ label: 'Sibling mode with anchorRef',
+ code: `<XDSPopover
+ anchorRef={myButtonRef}
+ label="Actions"
+ content={<ActionMenu />}
+ placement="below"
+/>`,
+ },
+ ],
+ },
+ ],
+ theming: {
+ componentKey: 'popover',
+ surfaces: [
+ {
+ name: 'container',
+ description:
+ 'Inner content container of the popover (background, border-radius, shadow, padding).',
+ },
+ ],
+ },
+};
diff --git a/packages/core/src/Layer/README.md b/packages/core/src/Layer/README.md
deleted file mode 100644
index 01356c9864..0000000000
--- a/packages/core/src/Layer/README.md
+++ /dev/null
@@ -1,181 +0,0 @@
-# Layer
-
-Layer components for overlay content using modern browser APIs.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Overview
-
-The Layer system provides hooks and components for overlay content using:
-
-- **CSS Anchor Positioning** for automatic positioning relative to trigger elements
-- **Popover API** for top-layer rendering (no React portals needed)
-
-## Browser Support
-
-- **Chrome**: Full support
-- **Safari**: Full support
-- **Firefox**: Popover API works, anchor positioning not yet (acceptable degradation)
-
-## Import
-
-```tsx
-import {useXDSLayer, useXDSHoverCard, XDSHoverCard} from '@xds/core/Layer';
-```
-
-## Hooks
-
-### useXDSLayer
-
-Core layer hook with type-safe modes for different positioning strategies.
-
-```tsx
-// Context mode (anchor positioning)
-const layer = useXDSLayer({mode: 'context'});
-
-<button ref={layer.ref}>Trigger</button>;
-{
- layer.render(<Content />, {placement: 'above', alignment: 'center'});
-}
-
-// Fixed mode (manual coordinates)
-const layer = useXDSLayer({mode: 'fixed'});
-
-layer.show();
-{
- layer.render(<Content />, {x: mouseX, y: mouseY});
-}
-```
-
-TypeScript enforces correct render props per mode:
-
-- **Context mode**: `render(children, { placement?, alignment? })`
-- **Fixed mode**: `render(children, { x, y })` (required)
-
-| Option | Type | Description |
-| -------- | ---------------------- | -------------------- |
-| `mode` | `'context' \| 'fixed'` | Positioning strategy |
-| `onShow` | `() => void` | Callback when shown |
-| `onHide` | `() => void` | Callback when hidden |
-
-### useXDSHoverCard
-
-Hook for hover/focus triggered layers with timing control.
-
-```tsx
-const hoverCard = useXDSHoverCard({placement: 'above'});
-
-<XDSButton ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>
- Hover me
-</XDSButton>;
-
-{
- hoverCard.renderHoverCard(<ProfileCard user={user} />);
-}
-```
-
-| Option | Type | Default | Description |
-| -------------- | ------------------------------- | --------- | --------------------------- |
-| `placement` | `LayerPlacement` | `'above'` | Position relative to anchor |
-| `alignment` | `LayerAlignment` | `'start'` | Alignment on placement axis |
-| `delay` | `number` | `300` | Show delay in ms |
-| `hideDelay` | `number` | `200` | Hide delay in ms |
-| `focusTrigger` | `'auto' \| 'always' \| 'never'` | `'auto'` | Focus listener behavior |
-| `isEnabled` | `boolean` | `true` | Enable/disable triggers |
-| `onShow` | `() => void` | — | Callback when shown |
-| `onHide` | `() => void` | — | Callback when hidden |
-
-## Components
-
-### XDSTooltip
-
-Component wrapper for tooltip display on hover/focus.
-
-```tsx
-<XDSTooltip content="Save your changes" placement="above">
- <XDSButton label="Save" variant="primary" />
-</XDSTooltip>
-```
-
-| Prop | Type | Default | Description |
-| -------------------- | ------------------------------- | ---------- | -------------------------------------- |
-| `children` | `ReactNode` | — | Trigger element(s) |
-| `anchorRef` | `RefObject<HTMLElement>` | — | External anchor ref (sibling mode) |
-| `content` | `ReactNode` | — | Tooltip content (typically short text) |
-| `placement` | `LayerPlacement` | `'above'` | Position relative to anchor |
-| `alignment` | `LayerAlignment` | `'center'` | Alignment on placement axis |
-| `delay` | `number` | `200` | Show delay in ms |
-| `hideDelay` | `number` | `0` | Hide delay in ms |
-| `focusTrigger` | `'auto' \| 'always' \| 'never'` | `'auto'` | When to trigger on focus |
-| `isEnabled` | `boolean` | `true` | Enable/disable triggers |
-| `hasHoverIndication` | `'auto' \| boolean` | `'auto'` | Show dashed underline on trigger |
-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when visibility changes |
-
-### XDSHoverCard
-
-Component wrapper for simpler hover card usage.
-
-```tsx
-<XDSHoverCard content={<ProfileCard user={user} />} placement="above">
- <XDSButton>Hover me</XDSButton>
-</XDSHoverCard>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ------------------------------- | --------- | --------------------------------- |
-| `children` | `ReactElement` | Required | Trigger element (must accept ref) |
-| `content` | `ReactNode` | Required | Hover card content |
-| `placement` | `LayerPlacement` | `'above'` | Position relative to anchor |
-| `alignment` | `LayerAlignment` | `'start'` | Alignment on placement axis |
-| `delay` | `number` | `300` | Show delay in ms |
-| `hideDelay` | `number` | `200` | Hide delay in ms |
-| `focusTrigger` | `'auto' \| 'always' \| 'never'` | `'auto'` | Focus listener behavior |
-| `isEnabled` | `boolean` | `true` | Enable/disable triggers |
-| `onOpenChange` | `(isOpen: boolean) => void` | — | Callback when visibility changes |
-
-## Position Values
-
-### LayerPlacement
-
-| Value | Description |
-| ------- | ------------------------ |
-| `above` | Above the anchor |
-| `below` | Below the anchor |
-| `start` | Start side (left in LTR) |
-| `end` | End side (right in LTR) |
-
-### LayerAlignment
-
-| Value | Description |
-| -------- | ------------------- |
-| `start` | Align to start edge |
-| `center` | Center aligned |
-| `end` | Align to end edge |
-
-## ARIA Guidelines
-
-When using hooks directly, compose `aria-describedby` with your own IDs:
-
-```tsx
-const hoverCard = useXDSHoverCard();
-
-<XDSInput
- ref={hoverCard.ref}
- aria-describedby={mergeIds(fieldErrorId, hoverCard.describedBy)}
-/>;
-
-// Utility function
-function mergeIds(...ids: (string | undefined)[]) {
- return ids.filter(Boolean).join(' ') || undefined;
-}
-```
-
-## Files
-
-| File | Role | Purpose |
-| ----------------------- | --------- | ------------------------------------------ |
-| `index.ts` | Entry | Exports all layer utilities and components |
-| `useXDSLayer.ts` | Hook | Core popover and positioning logic |
-| `useXDSHoverCard.ts` | Hook | Hover/focus triggers for layers |
-| `XDSHoverCard.tsx` | Component | Wrapper component for hover cards |
-| `XDSHoverCard.test.tsx` | Test | HoverCard unit tests |
diff --git a/packages/core/src/Layer/XDSHoverCard.tsx b/packages/core/src/Layer/XDSHoverCard.tsx
index f5177c9353..be54162803 100644
--- a/packages/core/src/Layer/XDSHoverCard.tsx
+++ b/packages/core/src/Layer/XDSHoverCard.tsx
@@ -5,7 +5,7 @@
* @position Layer component; uses display:contents wrapper to avoid cloneElement
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/Layer.doc.mjs
* - /packages/core/src/Layer/XDSHoverCard.test.tsx
* - /packages/core/src/Layer/index.ts
* - /apps/storybook/stories/HoverCard.stories.tsx
diff --git a/packages/core/src/Layer/XDSPopover.tsx b/packages/core/src/Layer/XDSPopover.tsx
index 89bf8e241c..3f880e9eee 100644
--- a/packages/core/src/Layer/XDSPopover.tsx
+++ b/packages/core/src/Layer/XDSPopover.tsx
@@ -7,7 +7,7 @@
* For hover-triggered overlays, use XDSHoverCard instead.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/Layer.doc.mjs
* - /packages/core/src/Layer/XDSPopover.test.tsx
* - /packages/core/src/Layer/index.ts
* - /apps/storybook/stories/Popover.stories.tsx
diff --git a/packages/core/src/Layer/XDSTooltip.tsx b/packages/core/src/Layer/XDSTooltip.tsx
index 97f380d79c..3bfc7062bd 100644
--- a/packages/core/src/Layer/XDSTooltip.tsx
+++ b/packages/core/src/Layer/XDSTooltip.tsx
@@ -5,7 +5,7 @@
* @position Layer component; uses display:contents wrapper to avoid cloneElement
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/Layer.doc.mjs
* - /packages/core/src/Layer/XDSTooltip.test.tsx
* - /packages/core/src/Layer/index.ts
* - /apps/storybook/stories/Tooltip.stories.tsx
diff --git a/packages/core/src/Layer/useXDSHoverCard.tsx b/packages/core/src/Layer/useXDSHoverCard.tsx
index 7188b7fc9e..bc3c00c34e 100644
--- a/packages/core/src/Layer/useXDSHoverCard.tsx
+++ b/packages/core/src/Layer/useXDSHoverCard.tsx
@@ -5,7 +5,7 @@
* @position Layer hook; builds on useXDSLayer for hover card behavior
*
* SYNC: When modified, update:
- * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/Layer.doc.mjs
* - /packages/core/src/Layer/index.ts
*/
diff --git a/packages/core/src/Layer/useXDSLayer.tsx b/packages/core/src/Layer/useXDSLayer.tsx
index b32696b31e..b7817fc909 100644
--- a/packages/core/src/Layer/useXDSLayer.tsx
+++ b/packages/core/src/Layer/useXDSLayer.tsx
@@ -5,7 +5,7 @@
* @position Core layer utility; used by useXDSHoverCard, useXDSTooltip, etc.
*
* SYNC: When modified, update:
- * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/Layer.doc.mjs
* - /packages/core/src/Layer/index.ts
*/
diff --git a/packages/core/src/Layer/useXDSPopover.tsx b/packages/core/src/Layer/useXDSPopover.tsx
index c42aa43523..39f233173f 100644
--- a/packages/core/src/Layer/useXDSPopover.tsx
+++ b/packages/core/src/Layer/useXDSPopover.tsx
@@ -8,7 +8,7 @@
* Use this for interactive popover content that should trap focus.
*
* SYNC: When modified, update:
- * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/Layer.doc.mjs
* - /packages/core/src/Layer/index.ts
*/
diff --git a/packages/core/src/Layer/useXDSTooltip.tsx b/packages/core/src/Layer/useXDSTooltip.tsx
index 8e179045e6..dd3bf76688 100644
--- a/packages/core/src/Layer/useXDSTooltip.tsx
+++ b/packages/core/src/Layer/useXDSTooltip.tsx
@@ -5,7 +5,7 @@
* @position Layer hook; builds on useXDSLayer for tooltip behavior
*
* SYNC: When modified, update:
- * - /packages/core/src/Layer/README.md
+ * - /packages/core/src/Layer/Layer.doc.mjs
* - /packages/core/src/Layer/index.ts
*/
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
new file mode 100644
index 0000000000..2d9f8e674a
--- /dev/null
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -0,0 +1,414 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Layout',
+ description:
+ 'Composable utilities and components for building structured layouts with a container/content separation pattern.',
+ features: [
+ 'Primitive + higher-order architecture — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order',
+ 'Directional padding via CSS variables — inner/outer, horizontal/vertical padding control',
+ 'Context-aware defaults — components detect their slot and self-adjust',
+ 'Automatic RTL support — uses CSS logical properties',
+ 'XDSLayout provides a page shell with header, sidebar(s), content, and footer slots',
+ 'XDSHStack and XDSVStack for simple stacking layouts',
+ 'XDSStackItem for fill/alignment control within stacks',
+ ],
+ examples: [
+ {
+ label: 'Basic page layout',
+ code: `<XDSLayout
+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}
+ footer={<XDSLayoutFooter hasDivider>Footer</XDSLayoutFooter>}
+/>`,
+ },
+ {
+ label: 'App shell with sidebar',
+ code: `<XDSLayout
+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
+ start={
+ <XDSLayoutPanel hasDivider width={240} role="navigation">
+ <Navigation />
+ </XDSLayoutPanel>
+ }
+ content={
+ <XDSLayoutContent role="main">
+ <MainContent />
+ </XDSLayoutContent>
+ }
+/>`,
+ },
+ {
+ label: 'Card layout',
+ code: `<XDSCard>
+ <XDSLayout
+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSHStack gap="space2" hAlign="end">
+ <XDSButton variant="secondary">Cancel</XDSButton>
+ <XDSButton variant="primary">Save</XDSButton>
+ </XDSHStack>
+ </XDSLayoutFooter>
+ }
+ />
+</XDSCard>`,
+ },
+ ],
+ notes: [
+ 'Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation, scrollable content area, or action footer. Do not use for simple stacking (use XDSVStack/XDSHStack instead).',
+ 'XDSLayoutContainer sets CSS variables that child components read: --layout-padding-outer-x (outer horizontal padding), --layout-padding-outer-y (outer vertical padding), --layout-padding-inner-x (inner horizontal padding used by Header, Footer, Content, Panel), --layout-padding-inner-y (inner vertical padding used by Header, Footer, Content, Panel).',
+ 'Architecture layers from top to bottom: Higher-Order Components (XDSCard, XDSSection), Layout Structure (XDSLayout + XDSLayoutHeader/Footer/Content/Panel), Primitive (XDSLayoutContainer sets CSS variables), Layout Utilities (XDSHStack, XDSVStack, stack(), stackItem()).',
+ 'All layout utilities and components are exported from @xds/core/Layout.',
+ ],
+ components: [
+ {
+ name: 'XDSLayout',
+ description:
+ 'Page shell with header, sidebar(s), content, and footer slots for building full app layouts.',
+ props: [
+ {
+ name: 'content',
+ type: 'ReactNode',
+ description: 'Main content area (center).',
+ },
+ {
+ name: 'header',
+ type: 'ReactNode',
+ description: 'Header slot.',
+ },
+ {
+ name: 'footer',
+ type: 'ReactNode',
+ description: 'Footer slot.',
+ },
+ {
+ name: 'start',
+ type: 'ReactNode',
+ description: 'Start panel (left in LTR).',
+ },
+ {
+ name: 'end',
+ type: 'ReactNode',
+ description: 'End panel (right in LTR).',
+ },
+ {
+ name: 'height',
+ type: "'fill' | 'auto'",
+ description:
+ 'Height behavior — fill the container or grow with content.',
+ default: "'fill'",
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description: 'Remove padding at outer edges.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSLayout
+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}
+ footer={<XDSLayoutFooter hasDivider>Footer</XDSLayoutFooter>}
+/>`,
+ },
+ {
+ label: 'With start panel',
+ code: `<XDSLayout
+ header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
+ start={
+ <XDSLayoutPanel hasDivider width={240} role="navigation">
+ <Navigation />
+ </XDSLayoutPanel>
+ }
+ content={
+ <XDSLayoutContent role="main">
+ <MainContent />
+ </XDSLayoutContent>
+ }
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSLayoutHeader',
+ description: 'Top bar for page titles, app bars, and toolbars.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Header content.',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Border at bottom edge.',
+ default: 'false',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Header height.',
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description: 'Remove internal padding.',
+ default: 'false',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSLayoutHeader hasDivider role="banner">
+ Page Title
+</XDSLayoutHeader>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSLayoutContent',
+ description: 'Scrollable main content area.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content.',
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description: 'Remove internal padding.',
+ default: 'false',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description: 'Enable scrollable overflow.',
+ default: 'true',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSLayoutContent role="main">
+ <MainContent />
+</XDSLayoutContent>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSLayoutFooter',
+ description: 'Bottom bar for action bars, pagination, and status bars.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Footer content.',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Border at top edge.',
+ default: 'false',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Footer height.',
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description: 'Remove internal padding.',
+ default: 'false',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSLayoutFooter hasDivider>
+ <XDSButton label="Save" variant="primary" />
+</XDSLayoutFooter>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSLayoutPanel',
+ description: 'Sidebar for navigation, settings, or inspector panels.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Panel content.',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Border on the appropriate edge.',
+ default: 'false',
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description: 'Remove internal padding.',
+ default: 'false',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description: 'Enable scrollable overflow.',
+ default: 'true',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Navigation sidebar',
+ code: `<XDSLayoutPanel hasDivider width={240} role="navigation">
+ <Navigation />
+</XDSLayoutPanel>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSLayoutContainer',
+ description:
+ 'Primitive component that sets CSS variables for padding, used as the base for XDSCard and XDSSection.',
+ props: [],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSLayoutContainer>Content</XDSLayoutContainer>',
+ },
+ ],
+ },
+ {
+ name: 'XDSCard',
+ description:
+ 'Card with elevation and themed styling, built on XDSLayoutContainer.',
+ props: [],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSCard>Card content</XDSCard>',
+ },
+ {
+ label: 'With layout structure',
+ code: `<XDSCard>
+ <XDSLayout
+ header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
+ content={<XDSLayoutContent>Body content</XDSLayoutContent>}
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSHStack gap="space2" hAlign="end">
+ <XDSButton variant="secondary">Cancel</XDSButton>
+ <XDSButton variant="primary">Save</XDSButton>
+ </XDSHStack>
+ </XDSLayoutFooter>
+ }
+ />
+</XDSCard>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSSection',
+ description:
+ 'Section with background variants (section, transparent, wash), built on XDSLayoutContainer.',
+ props: [],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSSection>Section content</XDSSection>',
+ },
+ ],
+ },
+ {
+ name: 'XDSHStack',
+ description: 'Horizontal stack that arranges children left-to-right.',
+ props: [],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSHStack gap="space2" hAlign="end">
+ <XDSButton variant="secondary">Cancel</XDSButton>
+ <XDSButton variant="primary">Save</XDSButton>
+</XDSHStack>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSVStack',
+ description: 'Vertical stack that arranges children top-to-bottom.',
+ props: [],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSVStack gap="space4">
+ <XDSCard>First</XDSCard>
+ <XDSCard>Second</XDSCard>
+</XDSVStack>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSStackItem',
+ description:
+ 'Stack item with fill and alignment control for use inside XDSHStack or XDSVStack.',
+ props: [],
+ examples: [
+ {
+ label: 'Fill remaining space',
+ code: `<XDSHStack>
+ <XDSStackItem grow>Main content</XDSStackItem>
+ <XDSButton variant="primary">Action</XDSButton>
+</XDSHStack>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Layout/README.md b/packages/core/src/Layout/README.md
deleted file mode 100644
index b8cd028150..0000000000
--- a/packages/core/src/Layout/README.md
+++ /dev/null
@@ -1,278 +0,0 @@
-# Layout
-
-XDS Layout System - composable utilities and components for building structured layouts.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Overview
-
-The layout system provides a container/content separation pattern with:
-
-- **Primitive + higher-order architecture** — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order
-- **Directional padding via CSS variables** — Inner/outer, horizontal/vertical padding control
-- **Context-aware defaults** — Components detect their slot and self-adjust
-- **Automatic RTL support** — Uses CSS logical properties
-
-## Import
-
-All layout utilities and components are exported from `@xds/core/Layout`:
-
-```tsx
-import {
- // Container components
- XDSLayoutContainer,
- XDSCard,
- XDSSection,
- // Layout structure
- XDSLayout,
- XDSLayoutHeader,
- XDSLayoutFooter,
- XDSLayoutContent,
- XDSLayoutPanel,
- // Stack utilities
- XDSHStack,
- XDSVStack,
- XDSStackItem,
- stack,
- stackItem,
-} from '@xds/core/Layout';
-```
-
-## Structure
-
-```
-Layout/
-├── index.ts # Entry point, re-exports everything
-├── README.md # This documentation
-├── Container/ # Container primitive and higher-order components
-│ ├── index.ts
-│ ├── README.md
-│ ├── XDSLayoutContainer.tsx # Primitive
-│ ├── XDSCard.tsx # Card with elevation
-│ └── XDSSection.tsx # Section with background variants
-├── XDSLayout/ # Layout structure components
-│ ├── index.ts
-│ ├── README.md
-│ ├── XDSLayout.tsx
-│ ├── XDSLayoutHeader.tsx
-│ ├── XDSLayoutFooter.tsx
-│ ├── XDSLayoutContent.tsx
-│ ├── XDSLayoutPanel.tsx
-│ └── XDSLayoutAreaContext.ts
-└── Stack/ # Stack utilities and components
- ├── index.ts
- ├── README.md
- ├── stack.stylex.ts
- ├── stackItem.stylex.ts
- ├── XDSHStack.tsx
- ├── XDSVStack.tsx
- └── XDSStackItem.tsx
-```
-
-## Quick Start
-
-### XDSLayout
-
-Page shell with header, sidebar(s), content, and footer slots.
-
-```tsx
-<XDSLayout
- header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
- content={<XDSLayoutContent>Body content</XDSLayoutContent>}
- footer={<XDSLayoutFooter hasDivider>Footer</XDSLayoutFooter>}
-/>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | --------------- | -------- | ----------------------------------------------- |
-| `content` | `ReactNode` | — | Main content area (center) |
-| `header` | `ReactNode` | — | Header slot |
-| `footer` | `ReactNode` | — | Footer slot |
-| `start` | `ReactNode` | — | Start panel (left in LTR) |
-| `end` | `ReactNode` | — | End panel (right in LTR) |
-| `height` | `'fill' \| 'auto'` | `'fill'` | Height behavior (fill container vs grow) |
-| `isFullBleed` | `boolean` | `false` | Remove padding at outer edges |
-
-### XDSLayoutHeader
-
-Top bar for page titles, app bars, and toolbars.
-
-```tsx
-<XDSLayoutHeader hasDivider role="banner">
- Page Title
-</XDSLayoutHeader>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | ------------------ | ------- | ------------------------------------- |
-| `children` | `ReactNode` | — | Header content |
-| `hasDivider` | `boolean` | `false` | Border at bottom edge |
-| `height` | `number \| string` | — | Header height |
-| `isFullBleed` | `boolean` | `false` | Remove internal padding |
-| `label` | `string` | — | Accessible label for landmark |
-| `role` | `AriaRole` | — | ARIA landmark role |
-
-### XDSLayoutContent
-
-Scrollable main content area.
-
-```tsx
-<XDSLayoutContent role="main">
- <MainContent />
-</XDSLayoutContent>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ---------- | ------- | ------------------------------------- |
-| `children` | `ReactNode`| — | Content |
-| `isFullBleed` | `boolean` | `false` | Remove internal padding |
-| `isScrollable` | `boolean` | `true` | Enable scrollable overflow |
-| `label` | `string` | — | Accessible label for landmark |
-| `role` | `AriaRole` | — | ARIA landmark role |
-
-### XDSLayoutFooter
-
-Bottom bar for action bars, pagination, and status bars.
-
-```tsx
-<XDSLayoutFooter hasDivider>
- <XDSButton label="Save" variant="primary" />
-</XDSLayoutFooter>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | ------------------ | ------- | ------------------------------------- |
-| `children` | `ReactNode` | — | Footer content |
-| `hasDivider` | `boolean` | `false` | Border at top edge |
-| `height` | `number \| string` | — | Footer height |
-| `isFullBleed` | `boolean` | `false` | Remove internal padding |
-| `label` | `string` | — | Accessible label for landmark |
-| `role` | `AriaRole` | — | ARIA landmark role |
-
-### XDSLayoutPanel
-
-Sidebar for navigation, settings, or inspector panels.
-
-```tsx
-<XDSLayoutPanel hasDivider width={240} role="navigation">
- <Navigation />
-</XDSLayoutPanel>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ------------------ | ------- | ------------------------------------- |
-| `children` | `ReactNode` | — | Panel content |
-| `hasDivider` | `boolean` | `false` | Border on appropriate edge |
-| `isFullBleed` | `boolean` | `false` | Remove internal padding |
-| `isScrollable` | `boolean` | `true` | Enable scrollable overflow |
-| `label` | `string` | — | Accessible label for landmark |
-| `role` | `AriaRole` | — | ARIA landmark role |
-
-## Usage Examples
-
-### Card Layout
-
-```tsx
-<XDSCard>
- <XDSLayout
- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
- content={<XDSLayoutContent>Body content</XDSLayoutContent>}
- footer={
- <XDSLayoutFooter hasDivider>
- <XDSHStack gap="space2" hAlign="end">
- <XDSButton variant="secondary">Cancel</XDSButton>
- <XDSButton variant="primary">Save</XDSButton>
- </XDSHStack>
- </XDSLayoutFooter>
- }
- />
-</XDSCard>
-```
-
-### App shell with sidebar
-
-```tsx
-<XDSLayout
- header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
- start={
- <XDSLayoutPanel hasDivider width={240} role="navigation">
- <Navigation />
- </XDSLayoutPanel>
- }
- content={
- <XDSLayoutContent role="main">
- <MainContent />
- </XDSLayoutContent>
- }
-/>
-```
-
-## Components
-
-### Container Components
-
-| Component | Description |
-| -------------------- | ------------------------------------------------------------- |
-| `XDSLayoutContainer` | Primitive that sets CSS variables for padding |
-| `XDSCard` | Card with elevation and themed styling |
-| `XDSSection` | Section with background variants (section, transparent, wash) |
-
-See [Container/README.md](./Container/README.md) for full documentation.
-
-### Layout Structure
-
-Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation,
-scrollable content area, or action footer. Don't use for simple stacking (use XDSVStack/XDSHStack).
-
-| Component | Description |
-| ------------------ | ----------------------------------------------------------------------- |
-| `XDSLayout` | Page shell with header, sidebar(s), content, and footer slots |
-| `XDSLayoutHeader` | Top bar — page titles, app bars, toolbars |
-| `XDSLayoutFooter` | Bottom bar — action bars, pagination, status bars |
-| `XDSLayoutContent` | Scrollable main content area |
-| `XDSLayoutPanel` | Sidebar — navigation panels, settings sidebars, detail/inspector panels |
-
-See [XDSLayout/README.md](./XDSLayout/README.md) for full documentation.
-
-### Stack Components
-
-| Component | Description |
-| -------------- | -------------------------------------- |
-| `XDSHStack` | Horizontal stack (left-to-right) |
-| `XDSVStack` | Vertical stack (top-to-bottom) |
-| `XDSStackItem` | Stack item with fill/alignment control |
-
-See [Stack/README.md](./Stack/README.md) for full documentation.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ Higher-Order Components │
-│ XDSCard, XDSSection (future: XDSModal, XDSPopover) │
-├─────────────────────────────────────────────────────────┤
-│ Layout Structure │
-│ XDSLayout + XDSLayoutHeader/Footer/Content/Panel │
-├─────────────────────────────────────────────────────────┤
-│ Primitive │
-│ XDSLayoutContainer (sets CSS variables) │
-├─────────────────────────────────────────────────────────┤
-│ Layout Utilities │
-│ XDSHStack, XDSVStack, stack(), stackItem() │
-└─────────────────────────────────────────────────────────┘
-```
-
-## CSS Variables
-
-XDSLayoutContainer sets these CSS variables that child components read:
-
-| Variable | Used By | Purpose |
-| -------------------------- | ------------------------------ | ------------------------ |
-| `--layout-padding-outer-x` | XDSLayout | Outer horizontal padding |
-| `--layout-padding-outer-y` | XDSLayout | Outer vertical padding |
-| `--layout-padding-inner-x` | Header, Footer, Content, Panel | Inner horizontal padding |
-| `--layout-padding-inner-y` | Header, Footer, Content, Panel | Inner vertical padding |
-
-## Related
-
-- See the [System Architecture](https://github.com/facebookexperimental/xds/wiki/System-Architecture) wiki page for the broader layout philosophy
diff --git a/packages/core/src/Layout/XDSLayout.tsx b/packages/core/src/Layout/XDSLayout.tsx
index 1a076318e4..366fffaec7 100644
--- a/packages/core/src/Layout/XDSLayout.tsx
+++ b/packages/core/src/Layout/XDSLayout.tsx
@@ -8,7 +8,7 @@
* Manages padding collapse, scroll containment, and responsive slot sizing automatically.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/XDSLayout/README.md
+ * - /packages/core/src/Layout/Layout.doc.mjs
* - /packages/core/src/Layout/XDSLayout/index.ts
* - /apps/storybook/stories/Layout.stories.tsx
*/
diff --git a/packages/core/src/Layout/XDSLayoutAreaContext.ts b/packages/core/src/Layout/XDSLayoutAreaContext.ts
index 70a76d2aa6..321c157d32 100644
--- a/packages/core/src/Layout/XDSLayoutAreaContext.ts
+++ b/packages/core/src/Layout/XDSLayoutAreaContext.ts
@@ -5,7 +5,7 @@
* @position Context for layout slot detection
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/XDSLayout/README.md
+ * - /packages/core/src/Layout/Layout.doc.mjs
*/
'use client';
diff --git a/packages/core/src/Layout/XDSLayoutContent.tsx b/packages/core/src/Layout/XDSLayoutContent.tsx
index 4f15ad84d0..ff3b2cc400 100644
--- a/packages/core/src/Layout/XDSLayoutContent.tsx
+++ b/packages/core/src/Layout/XDSLayoutContent.tsx
@@ -6,7 +6,7 @@
* with automatic scroll containment and context-aware padding.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/XDSLayout/README.md
+ * - /packages/core/src/Layout/Layout.doc.mjs
* - /apps/storybook/stories/Layout.stories.tsx
*/
diff --git a/packages/core/src/Layout/XDSLayoutFooter.tsx b/packages/core/src/Layout/XDSLayoutFooter.tsx
index fe1b61bec5..7991464537 100644
--- a/packages/core/src/Layout/XDSLayoutFooter.tsx
+++ b/packages/core/src/Layout/XDSLayoutFooter.tsx
@@ -6,7 +6,7 @@
* pagination, status bars, or any fixed-height content at the bottom of a layout.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/XDSLayout/README.md
+ * - /packages/core/src/Layout/Layout.doc.mjs
* - /apps/storybook/stories/Layout.stories.tsx
*/
diff --git a/packages/core/src/Layout/XDSLayoutHeader.tsx b/packages/core/src/Layout/XDSLayoutHeader.tsx
index 3138395944..1c82b317a7 100644
--- a/packages/core/src/Layout/XDSLayoutHeader.tsx
+++ b/packages/core/src/Layout/XDSLayoutHeader.tsx
@@ -6,7 +6,7 @@
* toolbar areas, or any fixed-height content at the top of a layout.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/XDSLayout/README.md
+ * - /packages/core/src/Layout/Layout.doc.mjs
* - /apps/storybook/stories/Layout.stories.tsx
*/
diff --git a/packages/core/src/Layout/XDSLayoutPanel.tsx b/packages/core/src/Layout/XDSLayoutPanel.tsx
index 5fad27f3c1..7906021573 100644
--- a/packages/core/src/Layout/XDSLayoutPanel.tsx
+++ b/packages/core/src/Layout/XDSLayoutPanel.tsx
@@ -6,7 +6,7 @@
* settings sidebars, detail panels, or any fixed-width side content.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/XDSLayout/README.md
+ * - /packages/core/src/Layout/Layout.doc.mjs
* - /apps/storybook/stories/Layout.stories.tsx
*/
diff --git a/packages/core/src/Layout/XDSLayoutSlotsContext.ts b/packages/core/src/Layout/XDSLayoutSlotsContext.ts
index 5decd7ef31..6551eddfef 100644
--- a/packages/core/src/Layout/XDSLayoutSlotsContext.ts
+++ b/packages/core/src/Layout/XDSLayoutSlotsContext.ts
@@ -5,7 +5,7 @@
* @position Context for layout slot information
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/XDSLayout/README.md
+ * - /packages/core/src/Layout/Layout.doc.mjs
* - /packages/core/src/Layout/XDSLayout/index.ts
*/
diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.ts
index 6669d8c846..bafb8545f9 100644
--- a/packages/core/src/Layout/container.stylex.ts
+++ b/packages/core/src/Layout/container.stylex.ts
@@ -4,7 +4,7 @@
* @output StyleX utility for layout container styling
* @position Layout utility; used by XDSCard, XDSSection components
*
- * SYNC: When modified, update /packages/core/src/Layout/README.md
+ * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs
*/
import * as stylex from '@stylexjs/stylex';
diff --git a/packages/core/src/Layout/edgeCompensation.stylex.ts b/packages/core/src/Layout/edgeCompensation.stylex.ts
index 03e39eddd4..f1115647df 100644
--- a/packages/core/src/Layout/edgeCompensation.stylex.ts
+++ b/packages/core/src/Layout/edgeCompensation.stylex.ts
@@ -41,7 +41,7 @@
* by Divider and Section for edge-to-edge bleeds in both directions — we don't
* want to overload it with a value that only represents one axis.
*
- * SYNC: When modified, update /packages/core/src/Layout/README.md
+ * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs
*/
import * as stylex from '@stylexjs/stylex';
diff --git a/packages/core/src/Layout/index.ts b/packages/core/src/Layout/index.ts
index 1b08d6e65b..b837246fbd 100644
--- a/packages/core/src/Layout/index.ts
+++ b/packages/core/src/Layout/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDS layout system
* @position Entry point for @xds/core/Layout
*
- * SYNC: When modified, update /packages/core/src/Layout/README.md
+ * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs
*/
// Container utility
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
new file mode 100644
index 0000000000..4b4822894e
--- /dev/null
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -0,0 +1,214 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Link',
+ description:
+ 'XDSLink component for styled anchor links with multiple variants and features, plus polymorphic link infrastructure for rendering custom link components (Next.js Link, React Router Link, etc.).',
+ features: [
+ "Color control: Uses XDSText color prop ('active' default, 'secondary', 'inherit', etc.)",
+ 'External links: Opens in new tab with external link icon',
+ 'Tooltip support: Display tooltip text on hover',
+ 'Underline control: Always show underline or only on hover',
+ 'Inline support: Inherits parent font styles when used within text',
+ 'Standalone mode: Applies base font sizing for independent links',
+ 'Disabled state: Visual and interaction disabled',
+ 'Focus visible: Accessible focus outline',
+ 'Polymorphic link: Render as a custom component via `as` prop or XDSLinkProvider',
+ ],
+ examples: [
+ {
+ label: 'Basic link',
+ code: '<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>',
+ },
+ {
+ label: 'External link (opens in new tab with icon)',
+ code: '<XDSLink label="GitHub" href="https://github.com" isExternalLink>GitHub</XDSLink>',
+ },
+ {
+ label: 'Link with tooltip',
+ code: `<XDSLink label="Settings" href="/settings" tooltip="Configure your preferences">
+ Settings
+</XDSLink>`,
+ },
+ {
+ label: 'Always underlined link',
+ code: '<XDSLink label="Privacy Policy" href="/privacy" hasUnderline>Privacy Policy</XDSLink>',
+ },
+ {
+ label: 'Inline within text (inherits parent font styles)',
+ code: '<XDSText>Read the <XDSLink label="docs" href="/docs">documentation</XDSLink> for more info.</XDSText>',
+ },
+ {
+ label: 'Standalone link',
+ code: '<XDSLink label="Settings" href="/settings" isStandalone>Settings</XDSLink>',
+ },
+ {
+ label: 'Disabled link',
+ code: '<XDSLink label="Disabled" href="/disabled" isDisabled>Disabled Link</XDSLink>',
+ },
+ {
+ label: 'Provider (global default) — Next.js',
+ code: `import Link from 'next/link';
+import {XDSLinkProvider} from '@xds/core/Link';
+
+<XDSLinkProvider component={Link}>
+ <App />
+</XDSLinkProvider>`,
+ },
+ {
+ label: 'Per-component override (as prop)',
+ code: `import {Link as RouterLink} from 'react-router-dom';
+
+<XDSLink label="Docs" href="/docs" as={RouterLink}>
+ Docs
+</XDSLink>`,
+ },
+ {
+ label: 'Hook: useXDSLinkComponent',
+ code: `import {useXDSLinkComponent} from '@xds/core/Link';
+
+function MyComponent({as}: {as?: XDSLinkComponentType}) {
+ const LinkComponent = useXDSLinkComponent(as);
+ return <LinkComponent href="/foo">Click me</LinkComponent>;
+}`,
+ },
+ ],
+ theming: {
+ componentKey: 'link',
+ surfaces: [{name: 'root', description: 'Root anchor element styles'}],
+ },
+ notes: [
+ 'By default, links inherit font family, size, line-height, and weight from parent elements',
+ 'Use isStandalone prop when the link is not inline within other text content',
+ 'isExternalLink automatically sets target="_blank" and rel="noopener noreferrer" for security',
+ 'Disabled state uses aria-disabled and pointer-events: none for accessibility',
+ 'Tooltip wraps the link in XDSTooltip component when provided',
+ 'XDSLinkComponentType is React.ElementType, allowing both string tags ("a") and custom components',
+ 'XDSLinkContext is separated from XDSLinkProvider (mirrors ThemeContext/XDSTheme pattern) so consumers can import the context without the full provider',
+ 'XDSLinkProvider memoizes its context value to prevent unnecessary re-renders',
+ 'Polymorphic link resolution order: (1) per-component as prop (highest priority), (2) XDSLinkProvider context, (3) native <a> element (default)',
+ 'All XDS components that render links (XDSLink, XDSTopNavItem, XDSSideNavItem, XDSBreadcrumbItem, XDSTab) support rendering as a custom link component',
+ ],
+ components: [
+ {
+ name: 'XDSLink',
+ description:
+ 'Styled anchor link with variants, external link support, and polymorphic rendering.',
+ props: [
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom component to render instead of <a>',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Link destination URL',
+ },
+ {
+ name: 'hasUnderline',
+ type: 'boolean',
+ description: 'Always show underline',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the link',
+ default: 'false',
+ },
+ {
+ name: 'isExternalLink',
+ type: 'boolean',
+ description: 'Opens in new tab with external icon',
+ default: 'false',
+ },
+ {
+ name: 'target',
+ type: 'string',
+ description: 'Where to open linked document',
+ },
+ {
+ name: 'onClick',
+ type: 'MouseEventHandler',
+ description: 'Click event handler',
+ },
+ {
+ name: 'tooltip',
+ type: 'string',
+ description: 'Tooltip text displayed on hover',
+ },
+ {
+ name: 'isStandalone',
+ type: 'boolean',
+ description: 'Applies base font sizing',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Link content',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>',
+ },
+ {
+ label: 'External link',
+ code: '<XDSLink label="GitHub" href="https://github.com" isExternalLink>GitHub</XDSLink>',
+ },
+ {
+ label: 'With tooltip',
+ code: `<XDSLink label="Settings" href="/settings" tooltip="Configure your preferences">
+ Settings
+</XDSLink>`,
+ },
+ {
+ label: 'With custom component (as prop)',
+ code: `<XDSLink label="Docs" href="/docs" as={RouterLink}>
+ Docs
+</XDSLink>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSLinkProvider',
+ description:
+ 'Provider that sets the default link component for all XDS link components in the subtree.',
+ props: [
+ {
+ name: 'component',
+ type: 'XDSLinkComponentType',
+ description: 'Component to use for all link elements',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Subtree',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'With Next.js Link',
+ code: `import Link from 'next/link';
+import {XDSLinkProvider} from '@xds/core/Link';
+
+<XDSLinkProvider component={Link}>
+ <App />
+</XDSLinkProvider>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Link/README.md b/packages/core/src/Link/README.md
deleted file mode 100644
index 60b32eef7b..0000000000
--- a/packages/core/src/Link/README.md
+++ /dev/null
@@ -1,201 +0,0 @@
-# Link
-
-XDSLink component for styled anchor links with multiple variants and features, plus polymorphic link infrastructure for rendering custom link components (Next.js Link, React Router Link, etc.).
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Variants**: `default`, `subtle`, `inherit`
-- **External links**: Opens in new tab with external link icon
-- **Tooltip support**: Display tooltip text on hover
-- **Underline control**: Always show underline or only on hover
-- **Inline support**: Inherits parent font styles when used within text
-- **Standalone mode**: Applies base font sizing for independent links
-- **Disabled state**: Visual and interaction disabled
-- **Focus visible**: Accessible focus outline
-- **Polymorphic link**: Render as a custom component via `as` prop or `XDSLinkProvider`
-
-## Components
-
-### XDSLink
-
-Styled anchor link with variants, external link support, and polymorphic rendering.
-
-```tsx
-<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>
-```
-
-| Prop | Type | Default | Description |
-| ---------------- | ------------------------------------ | ----------- | ------------------------------------------- |
-| `as` | `XDSLinkComponentType` | — | Custom component to render instead of `<a>` |
-| `label` | `string` | — | Accessible label (required) |
-| `href` | `string` | — | Link destination URL |
-| `variant` | `'default' \| 'subtle' \| 'inherit'` | `'default'` | Visual style variant |
-| `hasUnderline` | `boolean` | `false` | Always show underline |
-| `isDisabled` | `boolean` | `false` | Disables the link |
-| `isExternalLink` | `boolean` | `false` | Opens in new tab with external icon |
-| `target` | `string` | — | Where to open linked document |
-| `onClick` | `MouseEventHandler` | — | Click event handler |
-| `tooltip` | `string` | — | Tooltip text displayed on hover |
-| `isStandalone` | `boolean` | `false` | Applies base font sizing |
-| `children` | `ReactNode` | — | Link content (required) |
-
-### XDSLinkProvider
-
-Provider that sets the default link component for all XDS link components in the subtree.
-
-```tsx
-<XDSLinkProvider component={Link}>
- <App />
-</XDSLinkProvider>
-```
-
-| Prop | Type | Default | Description |
-| ----------- | ---------------------- | ------- | ------------------------------------------------ |
-| `component` | `XDSLinkComponentType` | — | Component to use for all link elements (required)|
-| `children` | `ReactNode` | — | Subtree |
-
-## Usage
-
-```tsx
-import { XDSLink } from '@xds/core/Link';
-
-// Basic link
-<XDSLink label="Documentation" href="/docs">Documentation</XDSLink>
-
-// External link (opens in new tab with icon)
-<XDSLink label="GitHub" href="https://github.com" isExternalLink>GitHub</XDSLink>
-
-// Link with tooltip
-<XDSLink label="Settings" href="/settings" tooltip="Configure your preferences">
- Settings
-</XDSLink>
-
-// Always underlined link
-<XDSLink label="Privacy Policy" href="/privacy" hasUnderline>Privacy Policy</XDSLink>
-
-// Inline within text (inherits parent font styles)
-<XDSText>Read the <XDSLink label="docs" href="/docs">documentation</XDSLink> for more info.</XDSText>
-
-// Standalone link
-<XDSLink label="Settings" href="/settings" isStandalone>Settings</XDSLink>
-
-// Subtle variant
-<XDSLink label="Privacy" href="/privacy" variant="subtle">Privacy Policy</XDSLink>
-
-// Disabled link
-<XDSLink label="Disabled" href="/disabled" isDisabled>Disabled Link</XDSLink>
-```
-
-## Polymorphic Link
-
-All XDS components that render links (`XDSLink`, `XDSTopNavItem`, `XDSSideNavItem`, `XDSBreadcrumbItem`, `XDSTab`) support rendering as a custom link component instead of the native `<a>` element. This enables framework-specific routing (Next.js, React Router, etc.).
-
-### Provider (global default)
-
-Wrap your app in `XDSLinkProvider` to set the default link component for all XDS components in the subtree:
-
-```tsx
-import Link from 'next/link';
-import {XDSLinkProvider} from '@xds/core/Link';
-
-<XDSLinkProvider component={Link}>
- <App />
-</XDSLinkProvider>;
-```
-
-### Per-component override (`as` prop)
-
-Override the provider for a single component using the `as` prop:
-
-```tsx
-import {Link as RouterLink} from 'react-router-dom';
-
-<XDSLink label="Docs" href="/docs" as={RouterLink}>
- Docs
-</XDSLink>;
-```
-
-### Resolution order
-
-1. Per-component `as` prop (highest priority)
-2. `XDSLinkProvider` context
-3. Native `<a>` element (default)
-
-### Hook: `useXDSLinkComponent`
-
-For custom components that need to resolve the link component:
-
-```tsx
-import {useXDSLinkComponent} from '@xds/core/Link';
-
-function MyComponent({as}: {as?: XDSLinkComponentType}) {
- const LinkComponent = useXDSLinkComponent(as);
- return <LinkComponent href="/foo">Click me</LinkComponent>;
-}
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| ---------------- | ------------------------------------ | ----------- | ------------------------------------------- |
-| `as` | `XDSLinkComponentType` | — | Custom component to render instead of `<a>` |
-| `label` | `string` | — | Accessible label (required) |
-| `href` | `string` | — | Link destination URL |
-| `variant` | `'default' \| 'subtle' \| 'inherit'` | `'default'` | Visual style variant |
-| `hasUnderline` | `boolean` | `false` | Always show underline |
-| `isDisabled` | `boolean` | `false` | Disables the link |
-| `isExternalLink` | `boolean` | `false` | Opens in new tab with external icon |
-| `target` | `string` | — | Where to open linked document |
-| `onClick` | `MouseEventHandler` | — | Click event handler |
-| `tooltip` | `string` | — | Tooltip text displayed on hover |
-| `isStandalone` | `boolean` | `false` | Applies base font sizing |
-| `children` | `ReactNode` | — | Link content (required) |
-
-## Theming
-
-Themes can override `Link` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- link: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | -------------------------- |
-| `root` | Root anchor element styles |
-
-## Files
-
-| File | Role | Purpose |
-| ------------------------------ | -------- | ------------------------------------------------ |
-| `index.ts` | Entry | Exports all public Link components, hooks, types |
-| `XDSLink.tsx` | Core | XDSLink component implementation |
-| `XDSLink.test.tsx` | Test | Unit tests for XDSLink component |
-| `XDSLinkProvider.tsx` | Provider | Sets default link component for subtree |
-| `XDSLinkContext.ts` | Context | React context definition for link provider |
-| `useXDSLinkComponent.ts` | Hook | Resolves link component (as > provider > `<a>`) |
-| `useXDSLinkComponent.test.tsx` | Test | Unit tests for hook and provider |
-| `types.ts` | Types | Shared XDSLinkComponentType definition |
-
-## Implementation Notes
-
-- `XDSLinkVariant` type is derived from the `variants` StyleX object using `keyof typeof variants`
-- By default, links inherit font family, size, line-height, and weight from parent elements
-- Use `isStandalone` prop when the link is not inline within other text content
-- `isExternalLink` automatically sets `target="_blank"` and `rel="noopener noreferrer"` for security
-- Disabled state uses `aria-disabled` and `pointer-events: none` for accessibility
-- Tooltip wraps the link in `XDSTooltip` component when provided
-- `XDSLinkComponentType` is `React.ElementType`, allowing both string tags (`'a'`) and custom components
-- `XDSLinkContext` is separated from `XDSLinkProvider` (mirrors `ThemeContext`/`XDSTheme` pattern) so consumers can import the context without the full provider
-- `XDSLinkProvider` memoizes its context value to prevent unnecessary re-renders
diff --git a/packages/core/src/Link/XDSLink.tsx b/packages/core/src/Link/XDSLink.tsx
index 9604513704..5f8ff12ee0 100644
--- a/packages/core/src/Link/XDSLink.tsx
+++ b/packages/core/src/Link/XDSLink.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSLink.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Link/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Link/Link.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Link/XDSLink.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Link/index.ts (exports if types change)
* - /apps/storybook/stories/Link.stories.tsx (storybook stories)
diff --git a/packages/core/src/Link/XDSLinkContext.ts b/packages/core/src/Link/XDSLinkContext.ts
index 7bc120deb1..5187527ed7 100644
--- a/packages/core/src/Link/XDSLinkContext.ts
+++ b/packages/core/src/Link/XDSLinkContext.ts
@@ -12,7 +12,7 @@
* - /packages/core/src/Link/XDSLinkProvider.tsx
* - /packages/core/src/Link/useXDSLinkComponent.ts
* - /packages/core/src/Link/index.ts
- * - /packages/core/src/Link/README.md
+ * - /packages/core/src/Link/Link.doc.mjs
*/
'use client';
diff --git a/packages/core/src/Link/XDSLinkProvider.tsx b/packages/core/src/Link/XDSLinkProvider.tsx
index a27957f04d..79f00d7384 100644
--- a/packages/core/src/Link/XDSLinkProvider.tsx
+++ b/packages/core/src/Link/XDSLinkProvider.tsx
@@ -18,7 +18,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Link/index.ts
- * - /packages/core/src/Link/README.md
+ * - /packages/core/src/Link/Link.doc.mjs
*/
'use client';
diff --git a/packages/core/src/Link/index.ts b/packages/core/src/Link/index.ts
index c8e94e9789..9544c7dc3f 100644
--- a/packages/core/src/Link/index.ts
+++ b/packages/core/src/Link/index.ts
@@ -4,7 +4,7 @@
* @output Exports all public Link components, hooks, and types
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Link/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Link/Link.doc.mjs
*/
export {XDSLink} from './XDSLink';
diff --git a/packages/core/src/Link/types.ts b/packages/core/src/Link/types.ts
index f3e26440cf..4c0362e4f4 100644
--- a/packages/core/src/Link/types.ts
+++ b/packages/core/src/Link/types.ts
@@ -6,7 +6,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Link/index.ts
- * - /packages/core/src/Link/README.md
+ * - /packages/core/src/Link/Link.doc.mjs
*/
import type {ElementType} from 'react';
diff --git a/packages/core/src/Link/useXDSLinkComponent.ts b/packages/core/src/Link/useXDSLinkComponent.ts
index 5f5f497f0e..db27235b0a 100644
--- a/packages/core/src/Link/useXDSLinkComponent.ts
+++ b/packages/core/src/Link/useXDSLinkComponent.ts
@@ -8,7 +8,7 @@
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Link/index.ts
- * - /packages/core/src/Link/README.md
+ * - /packages/core/src/Link/Link.doc.mjs
*/
'use client';
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
new file mode 100644
index 0000000000..6e3a746db9
--- /dev/null
+++ b/packages/core/src/List/List.doc.mjs
@@ -0,0 +1,183 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'List',
+ description:
+ 'Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: XDSList wraps XDSListItem sub-components.',
+ features: [
+ 'Composition model — XDSList wraps XDSListItem sub-components',
+ 'Density variants: compact, balanced, spacious',
+ 'Optional dividers between items',
+ 'Optional header associated via aria-labelledby',
+ 'List marker styles: none, disc, decimal (renders <ol>), circle',
+ 'Interactive items via invisible button or anchor pattern',
+ 'Start and end content slots (icon, avatar, badge, chevron)',
+ ],
+ examples: [
+ {
+ label: 'Basic list',
+ code: `<XDSList>
+ <XDSListItem label="Notifications" description="Manage your alerts" />
+ <XDSListItem label="Privacy" description="Control your data" />
+</XDSList>`,
+ },
+ {
+ label: 'With dividers and header',
+ code: `<XDSList hasDividers header={<strong>Team Members</strong>}>
+ <XDSListItem
+ label="Alice Johnson"
+ description="Engineering"
+ startContent={<XDSIcon icon={UserIcon} />}
+ />
+ <XDSListItem
+ label="Bob Smith"
+ description="Design"
+ startContent={<XDSIcon icon={UserIcon} />}
+ />
+</XDSList>`,
+ },
+ {
+ label: 'Interactive items',
+ code: `<XDSList>
+ <XDSListItem label="Settings" onClick={() => navigate('/settings')} />
+ <XDSListItem label="Docs" href="/docs" target="_blank" />
+</XDSList>`,
+ },
+ {
+ label: 'Ordered list',
+ code: `<XDSList listStyle="decimal">
+ <XDSListItem label="First step" />
+ <XDSListItem label="Second step" />
+</XDSList>`,
+ },
+ ],
+ accessibility: [
+ 'Semantic <ul> / <ol> with <li> elements',
+ 'role="list" added when listStyle=\'none\' (Safari fix for list semantics removed by CSS list-style:none)',
+ 'aria-labelledby links the header element to the list',
+ 'aria-selected on selected items',
+ 'aria-disabled on disabled items',
+ 'Dividers are aria-hidden="true"',
+ 'Interactive items are keyboard-focusable via Tab',
+ ],
+ notes: [
+ 'Invisible button pattern: when onClick is provided, an invisible <button> wraps the label + description for accessibility. The <li> is the visual container with hover/press styles. startContent and endContent are siblings to the button (not inside it). Container click fires onClick unless the click originated from an interactive child. :focus-within on the container shows the focus outline.',
+ 'When href is provided instead of onClick, the same invisible pattern uses an <a> element.',
+ ],
+ components: [
+ {
+ name: 'XDSList',
+ description: 'List container with density, dividers, and header support.',
+ examples: [
+ {
+ label: 'With dividers and header',
+ code: `<XDSList hasDividers header={<strong>Team Members</strong>}>
+ <XDSListItem label="Alice" description="Engineering" />
+ <XDSListItem label="Bob" description="Design" />
+</XDSList>`,
+ },
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'List items (XDSListItem components).',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Spacing density for items.',
+ default: "'balanced'",
+ },
+ {
+ name: 'hasDividers',
+ type: 'boolean',
+ description: 'Show dividers between items.',
+ default: 'false',
+ },
+ {
+ name: 'header',
+ type: 'ReactNode',
+ description:
+ 'Header content, associated with the list via aria-labelledby.',
+ },
+ {
+ name: 'listStyle',
+ type: "'none' | 'disc' | 'decimal' | 'circle'",
+ description:
+ "List marker style. 'decimal' renders an <ol> element instead of <ul>.",
+ default: "'none'",
+ },
+ ],
+ },
+ {
+ name: 'XDSListItem',
+ description:
+ 'List item with label, description, start/end content slots, and interactive patterns.',
+ examples: [
+ {
+ label: 'With icon and click handler',
+ code: `<XDSListItem
+ label="Settings"
+ description="Manage your preferences"
+ startContent={<XDSIcon icon={CogIcon} />}
+ onClick={() => navigate('/settings')}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Primary text.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Secondary text displayed below the label.',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description:
+ 'Content rendered before the label area (e.g. icon, avatar).',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description:
+ 'Content rendered after the label area (e.g. badge, chevron).',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: 'Click handler; enables the invisible button pattern.',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Link URL; enables the invisible anchor pattern.',
+ },
+ {
+ name: 'target',
+ type: 'string',
+ description:
+ 'Link target attribute, only applicable when href is provided.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disabled state; sets aria-disabled on the item.',
+ default: 'false',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: 'Selected state; sets aria-selected on the item.',
+ default: 'false',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/List/README.md b/packages/core/src/List/README.md
deleted file mode 100644
index 87705af11d..0000000000
--- a/packages/core/src/List/README.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# XDSList
-
-Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: `XDSList` wraps `XDSListItem` sub-components.
-
-## Files
-
-<!-- SYNC: Update when files are added/removed -->
-
-| File | Purpose |
-| -------------------- | ------------------------------------ |
-| `XDSList.tsx` | List container component |
-| `XDSListItem.tsx` | List item component |
-| `XDSListContext.tsx` | Internal context for density sharing |
-| `XDSList.test.tsx` | Unit tests |
-| `index.ts` | Public exports |
-| `README.md` | This documentation |
-
-## Usage
-
-```tsx
-import {XDSList, XDSListItem} from '@xds/core';
-
-// Basic list
-<XDSList>
- <XDSListItem label="Notifications" description="Manage your alerts" />
- <XDSListItem label="Privacy" description="Control your data" />
-</XDSList>
-
-// With dividers and header
-<XDSList hasDividers header={<strong>Team Members</strong>}>
- <XDSListItem
- label="Alice Johnson"
- description="Engineering"
- startContent={<XDSIcon icon={UserIcon} />}
- />
- <XDSListItem
- label="Bob Smith"
- description="Design"
- startContent={<XDSIcon icon={UserIcon} />}
- />
-</XDSList>
-
-// Interactive items
-<XDSList>
- <XDSListItem label="Settings" onClick={() => navigate('/settings')} />
- <XDSListItem label="Docs" href="/docs" target="_blank" />
-</XDSList>
-
-// Ordered list
-<XDSList listStyle="decimal">
- <XDSListItem label="First step" />
- <XDSListItem label="Second step" />
-</XDSList>
-```
-
-### XDSList
-
-List container with density, dividers, and header support.
-
-```tsx
-<XDSList hasDividers header={<strong>Team Members</strong>}>
- <XDSListItem label="Alice" description="Engineering" />
- <XDSListItem label="Bob" description="Design" />
-</XDSList>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | ------------------------------------------- | ------------ | ------------------------------------------------ |
-| `children` | `ReactNode` | — | List items (XDSListItem components) |
-| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Spacing density for items |
-| `hasDividers` | `boolean` | `false` | Show dividers between items |
-| `header` | `ReactNode` | — | Header content, associated via `aria-labelledby` |
-| `listStyle` | `'none' \| 'disc' \| 'decimal' \| 'circle'` | `'none'` | List marker style. `'decimal'` renders `<ol>` |
-| `xstyle` | `StyleXStyles` | — | Style overrides |
-| `data-testid` | `string` | — | Test ID |
-
-### XDSListItem
-
-List item with label, description, start/end content slots, and interactive patterns.
-
-```tsx
-<XDSListItem
- label="Settings"
- description="Manage your preferences"
- startContent={<XDSIcon icon={CogIcon} />}
- onClick={() => navigate('/settings')}
-/>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ------- | ------------------------------------------------ |
-| `label` | `string` | — | Primary text (required) |
-| `description` | `string` | — | Secondary text below label |
-| `startContent` | `ReactNode` | — | Content before label area (icon, avatar) |
-| `endContent` | `ReactNode` | — | Content after label area (badge, chevron) |
-| `onClick` | `(e: MouseEvent) => void` | — | Click handler (enables invisible button pattern) |
-| `href` | `string` | — | Link URL (enables invisible anchor pattern) |
-| `target` | `string` | — | Link target (only with `href`) |
-| `isDisabled` | `boolean` | `false` | Disabled state |
-| `isSelected` | `boolean` | `false` | Selected state (`aria-selected`) |
-| `xstyle` | `StyleXStyles` | — | Style overrides |
-| `data-testid` | `string` | — | Test ID |
-
-## Interactive Pattern
-
-When `onClick` is provided, XDSListItem uses the **invisible button pattern**:
-
-```
-┌─ li (container, :focus-within outline, click area) ──────────┐
-│ [startContent] [button.invisible(label + desc)] [endContent] │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-- The `<li>` is the visual container with hover/press styles
-- An invisible `<button>` wraps the label + description for accessibility
-- `startContent` and `endContent` are siblings to the button (not inside it)
-- Container click fires `onClick` unless the click originated from an interactive child
-- `:focus-within` on the container shows the focus outline
-
-When `href` is provided, the same pattern uses an invisible `<a>` instead.
-
-## Accessibility
-
-- Semantic `<ul>` / `<ol>` with `<li>` elements
-- `role="list"` added when `listStyle='none'` (Safari fix)
-- `aria-labelledby` links header to list
-- `aria-selected` on selected items
-- `aria-disabled` on disabled items
-- Dividers are `aria-hidden="true"`
-- Interactive items are keyboard-focusable via Tab
diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsx
index 46c37aec8f..318eb878ae 100644
--- a/packages/core/src/List/XDSList.tsx
+++ b/packages/core/src/List/XDSList.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSList.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/List/README.md
+ * - /packages/core/src/List/List.doc.mjs
* - /packages/core/src/List/XDSList.test.tsx
* - /packages/core/src/List/index.ts
* - /apps/storybook/stories/List.stories.tsx
diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsx
index e5d5f86ca4..4896bfc2c0 100644
--- a/packages/core/src/List/XDSListItem.tsx
+++ b/packages/core/src/List/XDSListItem.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by XDSList, index.ts, tested by XDSList.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/List/README.md
+ * - /packages/core/src/List/List.doc.mjs
* - /packages/core/src/List/XDSList.test.tsx
* - /packages/core/src/List/index.ts
* - /apps/storybook/stories/List.stories.tsx
diff --git a/packages/core/src/List/index.ts b/packages/core/src/List/index.ts
index 1ebd48cd4d..f3d283371b 100644
--- a/packages/core/src/List/index.ts
+++ b/packages/core/src/List/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSList, XDSListItem components and their props/types
* @position Package entry point for List
*
- * SYNC: When modified, update /packages/core/src/List/README.md
+ * SYNC: When modified, update /packages/core/src/List/List.doc.mjs
*/
export {XDSList} from './XDSList';
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
new file mode 100644
index 0000000000..bbb8828834
--- /dev/null
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -0,0 +1,150 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'MobileNav',
+ description:
+ 'Slide-out drawer overlay for mobile navigation. The mobile counterpart to XDSSideNav — accepts the same children (XDSSideNavSection, XDSSideNavItem, or any ReactNode).',
+ props: [
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Whether the drawer is open.',
+ required: true,
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description:
+ 'Called when the drawer visibility changes (backdrop click, Escape key, or close button).',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Drawer content — typically XDSSideNavSection/XDSSideNavItem, or any ReactNode.',
+ required: true,
+ },
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Optional title shown at the top of the drawer.',
+ },
+ {
+ name: 'width',
+ type: 'number',
+ description:
+ 'Drawer width in pixels. Capped at 85vw to prevent overflow on small screens.',
+ default: '280',
+ },
+ {
+ name: 'side',
+ type: "'start' | 'end'",
+ description:
+ 'Which side the drawer slides from. Start is left in LTR, right in RTL.',
+ default: "'start'",
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic hamburger menu',
+ code: `const [isOpen, setIsOpen] = useState(false);
+
+<XDSButton
+ label="Menu"
+ icon={<MenuIcon />}
+ variant="ghost"
+ onClick={() => setIsOpen(true)}
+/>
+
+<XDSMobileNav
+ isOpen={isOpen}
+ onOpenChange={() => setIsOpen(false)}
+ title="Navigation"
+>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" href="/dashboard" isSelected />
+ <XDSSideNavItem label="Analytics" href="/analytics" />
+ <XDSSideNavItem label="Settings" href="/settings" />
+ </XDSSideNavSection>
+</XDSMobileNav>`,
+ },
+ {
+ label: 'Responsive sidebar/drawer pattern',
+ code: `const isMobile = useMediaQuery('(max-width: 768px)');
+const [drawerOpen, setDrawerOpen] = useState(false);
+
+const navSections = (
+ <>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" href="/" isSelected />
+ <XDSSideNavItem label="Projects" href="/projects" />
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem label="General" href="/settings" />
+ <XDSSideNavItem label="Security" href="/security" />
+ </XDSSideNavSection>
+ </>
+);
+
+{isMobile ? (
+ <>
+ <XDSButton
+ label="Menu"
+ icon={<MenuIcon />}
+ variant="ghost"
+ onClick={() => setDrawerOpen(true)}
+ />
+ <XDSMobileNav
+ isOpen={drawerOpen}
+ onOpenChange={() => setDrawerOpen(false)}
+ title="My App"
+ >
+ {navSections}
+ </XDSMobileNav>
+ </>
+) : (
+ <XDSSideNav>{navSections}</XDSSideNav>
+)}`,
+ },
+ {
+ label: 'Shared children with XDSSideNav',
+ code: `const sections = (
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Home" href="/" />
+ <XDSSideNavItem label="Settings" href="/settings" />
+ </XDSSideNavSection>
+);
+
+// Desktop: sidebar
+<XDSSideNav>{sections}</XDSSideNav>
+
+// Mobile: drawer
+<XDSMobileNav isOpen={open} onOpenChange={close}>{sections}</XDSMobileNav>`,
+ },
+ ],
+ features: [
+ 'Native <dialog> element with showModal() for top-layer rendering — no z-index stacking issues',
+ 'Animated slide-in from start or end edge with backdrop fade',
+ 'Shares children with XDSSideNav — extract nav sections into a variable and render in both',
+ 'RTL-aware: automatically mirrors slide direction for right-to-left layouts',
+ 'Respects prefers-reduced-motion: reduces animation duration',
+ ],
+ accessibility: [
+ 'Uses native <dialog> with showModal() for correct ARIA modal semantics.',
+ "aria-label set to title or 'Navigation' as fallback.",
+ 'Focus trapping provided by showModal() (browser-native).',
+ 'Escape key closes via native cancel event.',
+ 'Backdrop click closes the drawer.',
+ 'Body scroll locked while modal is open.',
+ ],
+ keyboard:
+ 'Escape closes the drawer; Tab/Shift+Tab cycles focus within the drawer (browser-native focus trapping)',
+ theming: {
+ componentKey: 'mobileNav',
+ surfaces: [
+ {name: 'root', description: 'Root dialog element styles'},
+ {name: 'drawer', description: 'Drawer panel styles'},
+ ],
+ },
+};
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
new file mode 100644
index 0000000000..8c861ceec7
--- /dev/null
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -0,0 +1,148 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'MoreMenu',
+ description:
+ 'Overflow menu with a three-dot icon trigger. A convenience wrapper that composes an icon-only XDSButton with a dropdown menu, eliminating the boilerplate of wiring up state management, positioning, and accessibility attributes.',
+ props: [
+ {
+ name: 'items',
+ type: 'XDSDropdownMenuOption[]',
+ description:
+ 'Menu items — data array of actions, dividers, and sections. Same type as XDSDropdownMenu items prop.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label for the trigger button (aria-label) and tooltip text.',
+ default: "'More options'",
+ },
+ {
+ name: 'variant',
+ type: 'XDSButtonVariant',
+ description: 'Visual style variant of the trigger button.',
+ default: "'ghost'",
+ },
+ {
+ name: 'size',
+ type: 'XDSButtonSize',
+ description: 'Size of the trigger button.',
+ default: "'md'",
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ 'Override the default three-dot icon. Accepts any ReactNode.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the menu trigger is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: '(item: XDSDropdownMenuItemData) => ReactNode',
+ description:
+ 'Custom render function for items. Only called for selectable items (not dividers/sections).',
+ },
+ ],
+ examples: [
+ {
+ label: 'Minimal actions',
+ code: `<XDSMoreMenu
+ items={[
+ { label: 'Edit', onClick: handleEdit },
+ { label: 'Delete', onClick: handleDelete },
+ ]}
+/>`,
+ },
+ {
+ label: 'Table row actions with icons',
+ code: `<XDSMoreMenu
+ label="Row actions"
+ size="sm"
+ items={[
+ { label: 'Edit', icon: PencilIcon, onClick: () => handleEdit(row) },
+ { type: 'divider' },
+ { label: 'Delete', icon: TrashIcon, onClick: () => handleDelete(row) },
+ ]}
+/>`,
+ },
+ {
+ label: 'With sections',
+ code: `<XDSMoreMenu
+ label="Document actions"
+ items={[
+ {
+ type: 'section',
+ title: 'Actions',
+ items: [
+ { label: 'Edit', onClick: handleEdit },
+ { label: 'Duplicate', onClick: handleDuplicate },
+ ],
+ },
+ {
+ type: 'section',
+ title: 'Danger zone',
+ items: [
+ { label: 'Delete', onClick: handleDelete },
+ ],
+ },
+ ]}
+/>`,
+ },
+ {
+ label: 'Card header with overflow menu',
+ code: `<XDSHStack align="center" justify="between">
+ <XDSHeading level={3}>Card Title</XDSHeading>
+ <XDSMoreMenu
+ items={[
+ { label: 'Edit', onClick: handleEdit },
+ { label: 'Duplicate', onClick: handleDuplicate },
+ { type: 'divider' },
+ { label: 'Delete', onClick: handleDelete },
+ ]}
+ />
+</XDSHStack>`,
+ },
+ {
+ label: 'Custom item rendering',
+ code: `<XDSMoreMenu
+ label="User actions"
+ items={actions}
+>
+ {item => (
+ <XDSDropdownMenuItem
+ icon={item.icon}
+ label={item.label}
+ description={item.description}
+ />
+ )}
+</XDSMoreMenu>`,
+ },
+ ],
+ features: [
+ "Zero-config defaults: three-dot icon, 'More options' label, ghost variant — just pass items",
+ 'Data-driven items: same items prop as XDSDropdownMenu (items, dividers, sections)',
+ 'Icon-only trigger: always renders as a square icon button with aria-label',
+ 'Tooltip: shows label on hover, hidden when menu is open',
+ 'Custom rendering: optional children render function for custom item content',
+ ],
+ accessibility: [
+ 'Proper ARIA roles: menu and menuitem on dropdown elements.',
+ 'Trigger button has aria-haspopup="menu" and aria-expanded.',
+ 'aria-activedescendant tracks the highlighted menu item.',
+ 'Disabled items have aria-disabled set.',
+ 'Sections use role="group" with aria-label.',
+ ],
+ keyboard:
+ 'Arrow keys navigate items; Home/End jump to first/last; Enter/Space select highlighted item; Escape closes menu',
+ notes: [
+ 'For full control over trigger rendering or menu content, compose XDSButton + useXDSLayer + XDSDropdownMenuItem directly.',
+ 'Use XDSMoreMenu for icon-only overflow actions in tight spaces (table rows, card headers). Use XDSDropdownMenu for labeled trigger buttons with chevrons.',
+ ],
+};
diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjs
new file mode 100644
index 0000000000..fe7e2ecac3
--- /dev/null
+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs
@@ -0,0 +1,50 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'NavIcon',
+ description:
+ 'Circular icon container with accent background for navigation headers.',
+ features: [
+ 'Shared — used in both XDSTopNavTitle and XDSPageNavHeader',
+ 'Accent background — uses --color-accent with --color-icon-on-media contrast',
+ 'Fixed size — renders at the medium (--size-md) design token size',
+ ],
+ props: [
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ 'The icon element to render inside the circular background. Should be an XDSIcon or similar icon component.',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'In top navigation',
+ code: `import {CubeIcon} from '@heroicons/react/24/solid';
+
+<XDSTopNavTitle
+ title="My App"
+ logo={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}
+/>`,
+ },
+ {
+ label: 'In side navigation',
+ code: `import {CubeIcon} from '@heroicons/react/24/solid';
+
+<XDSPageNavHeader
+ icon={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}
+ title="My App"
+/>`,
+ },
+ {
+ label: 'With HomeIcon',
+ code: `import {HomeIcon} from '@heroicons/react/24/solid';
+
+<XDSTopNavTitle
+ title="Dashboard"
+ logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
+/>`,
+ },
+ ],
+};
diff --git a/packages/core/src/NavIcon/README.md b/packages/core/src/NavIcon/README.md
deleted file mode 100644
index c88980c5f8..0000000000
--- a/packages/core/src/NavIcon/README.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# /packages/core/src/NavIcon
-
-Circular icon container for navigation headers.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Shared** — used in both XDSTopNavTitle and XDSPageNavHeader
-- **Accent background** — uses `--color-accent` with `--color-icon-on-media` contrast
-- **Fixed size** — renders at the medium (`--size-md`) design token size
-
-## Usage
-
-```tsx
-import {XDSNavIcon} from '@xds/core/NavIcon';
-import {CubeIcon} from '@heroicons/react/24/solid';
-
-// In top navigation
-<XDSTopNavTitle
- title="My App"
- logo={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}
-/>
-
-// In side navigation
-<XDSPageNavHeader
- icon={<XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}
- title="My App"
-/>
-```
-
-## Components
-
-- **XDSNavIcon** — Circular icon container with accent background
-
-## Props
-
-### XDSNavIcon
-
-| Prop | Type | Default | Description |
-| ------ | ----------- | ------- | ----------------------- |
-| `icon` | `ReactNode` | — | Icon element (required) |
-
-## Files
-
-| File | Role | Purpose |
-| --------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSNavIcon.tsx` | Core | Circular icon container |
-| `XDSNavIcon.test.tsx` | Test | Unit tests |
diff --git a/packages/core/src/NavIcon/XDSNavIcon.tsx b/packages/core/src/NavIcon/XDSNavIcon.tsx
index 65975d71f9..7412d8c4a6 100644
--- a/packages/core/src/NavIcon/XDSNavIcon.tsx
+++ b/packages/core/src/NavIcon/XDSNavIcon.tsx
@@ -5,7 +5,7 @@
* @position Shared circular icon container for navigation headers (TopNav, PageNav)
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/NavIcon/README.md
+ * - /packages/core/src/NavIcon/NavIcon.doc.mjs
* - /packages/core/src/NavIcon/XDSNavIcon.test.tsx
* - /packages/core/src/NavIcon/index.ts
* - /apps/storybook/stories/TopNav.stories.tsx
diff --git a/packages/core/src/NavIcon/index.ts b/packages/core/src/NavIcon/index.ts
index 9f69801cee..7af743a15d 100644
--- a/packages/core/src/NavIcon/index.ts
+++ b/packages/core/src/NavIcon/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSNavIcon component and types
* @position Entry point for NavIcon module
*
- * SYNC: When modified, update /packages/core/src/NavIcon/README.md
+ * SYNC: When modified, update /packages/core/src/NavIcon/NavIcon.doc.mjs
*/
export {XDSNavIcon} from './XDSNavIcon';
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
new file mode 100644
index 0000000000..2c97ca7714
--- /dev/null
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -0,0 +1,240 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'NumberInput',
+ description:
+ 'A number input component for collecting numeric user input with validation.',
+ features: [
+ 'Label Support — required label for accessibility (can be visually hidden)',
+ 'Description — optional description text displayed between the label and input',
+ 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',
+ 'Label Tooltip — optional info icon with tooltip at end of label',
+ 'Label Icon — optional icon before the label text',
+ 'Accessible — label properly associated with input via htmlFor/id',
+ 'Styled with StyleX — uses XDS design tokens for consistent styling',
+ 'Size Variants — three sizes (sm, md, lg) for different contexts',
+ 'Status Handling — error, warning, and success states with messages',
+ 'Number Constraints — support for min, max, and step attributes',
+ 'Validated onChange — only calls onChange when the entered value passes validation',
+ 'Units Display — optional units suffix (e.g., "%" or "GB")',
+ 'Integer Mode — option to restrict to integers only',
+ 'Native Controls — uses type="number" for browser step controls',
+ 'Event Callbacks — onFocus, onBlur, and onEnter handlers',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSNumberInput label="Quantity" value={quantity} onChange={setQuantity} />',
+ },
+ {
+ label: 'With placeholder',
+ code: '<XDSNumberInput label="Age" value={age} onChange={setAge} placeholder="Enter your age" />',
+ },
+ {
+ label: 'With min/max constraints',
+ code: '<XDSNumberInput label="Rating" value={rating} onChange={setRating} min={1} max={5} />',
+ },
+ {
+ label: 'With step for decimals',
+ code: '<XDSNumberInput label="Price" value={price} onChange={setPrice} min={0} step={0.01} />',
+ },
+ {
+ label: 'With units display',
+ code: '<XDSNumberInput label="Discount" value={discount} onChange={setDiscount} units="%" />',
+ },
+ {
+ label: 'Integer only',
+ code: '<XDSNumberInput label="Count" value={count} onChange={setCount} isIntegerOnly />',
+ },
+ {
+ label: 'With description',
+ code: '<XDSNumberInput label="Quantity" description="Enter the number of items" value={qty} onChange={setQty} />',
+ },
+ {
+ label: 'Optional field',
+ code: '<XDSNumberInput label="Phone Extension" isOptional value={ext} onChange={setExt} />',
+ },
+ {
+ label: 'Required field',
+ code: '<XDSNumberInput label="Amount" isRequired value={amount} onChange={setAmount} />',
+ },
+ {
+ label: 'With validation status',
+ code: `<XDSNumberInput
+ label="Age"
+ value={age}
+ onChange={setAge}
+ status={{ type: 'error', message: 'Age must be between 18 and 120' }}
+/>`,
+ },
+ {
+ label: 'With event handlers',
+ code: `<XDSNumberInput
+ label="Search"
+ value={search}
+ onChange={setSearch}
+ onEnter={() => handleSearch()}
+ onFocus={() => console.log('focused')}
+ onBlur={() => console.log('blurred')}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the input (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'number | null | undefined',
+ description: 'Current value of the input.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: number) => void',
+ description:
+ 'Callback fired when input value changes (only on valid input).',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant.',
+ default: "'md'",
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Visually hide the label (still accessible to screen readers).',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed between the label and input.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Whether the field is optional (mutually exclusive with isRequired).',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description:
+ 'Whether the field is required (mutually exclusive with isOptional).',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the input is disabled.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description:
+ 'Tooltip text to display in an info icon at the end of the label.',
+ },
+ {
+ name: 'startIcon',
+ type: 'XDSIconType',
+ description: 'Icon to display at the start of the input.',
+ },
+ {
+ name: 'labelIcon',
+ type: 'XDSIconType',
+ description: 'Icon to display before the label text.',
+ },
+ {
+ name: 'status',
+ type: "{type: 'error' | 'warning' | 'success', message?: string}",
+ description: 'Validation status with optional message.',
+ },
+ {
+ name: 'min',
+ type: 'number | null',
+ description: 'Minimum value allowed.',
+ },
+ {
+ name: 'max',
+ type: 'number | null',
+ description: 'Maximum value allowed.',
+ },
+ {
+ name: 'step',
+ type: 'number | null',
+ description: 'Step increment for the input.',
+ default: '1',
+ },
+ {
+ name: 'units',
+ type: 'string | null',
+ description:
+ 'Units text to display at the end of the input (e.g., "%" or "GB").',
+ },
+ {
+ name: 'isIntegerOnly',
+ type: 'boolean',
+ description: 'Only allow integer values (no floating point).',
+ },
+ {
+ name: 'htmlName',
+ type: 'string',
+ description: 'HTML name attribute for form submissions.',
+ },
+ {
+ name: 'autoComplete',
+ type: 'string',
+ description: 'HTML autocomplete attribute.',
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Whether to focus the input on mount.',
+ },
+ {
+ name: 'onFocus',
+ type: '(e: FocusEvent<HTMLInputElement>) => void',
+ description: 'Callback fired when the input receives focus.',
+ },
+ {
+ name: 'onBlur',
+ type: '(e: FocusEvent<HTMLInputElement>) => void',
+ description: 'Callback fired when the input loses focus.',
+ },
+ {
+ name: 'onEnter',
+ type: '() => void',
+ description: 'Callback fired when the user presses the Enter key.',
+ },
+ ],
+ theming: {
+ componentKey: 'numberInput',
+ surfaces: [
+ {name: 'wrapper', description: 'Input wrapper styles'},
+ {name: 'input', description: 'Number input element styles'},
+ ],
+ },
+ accessibility: [
+ 'Label is always rendered and associated with the input via htmlFor/id using the useId hook.',
+ 'Use isLabelHidden to hide the label visually while keeping it accessible to screen readers via a CSS technique.',
+ 'Wraps XDSField for consistent label, description, and optional/required indicator handling.',
+ ],
+ notes: [
+ 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" is shown.',
+ 'Uses type="number" to enable native browser step controls (up/down arrows).',
+ 'Validated onChange: only calls onChange when the entered value is a valid number that passes min/max/integer constraints.',
+ 'Uses internal pending state to allow free-form typing while validating on commit.',
+ 'Units are displayed as a lighter grey suffix after the input value.',
+ ],
+};
diff --git a/packages/core/src/NumberInput/README.md b/packages/core/src/NumberInput/README.md
deleted file mode 100644
index 1c63d11f7c..0000000000
--- a/packages/core/src/NumberInput/README.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# NumberInput
-
-A number input component for collecting numeric user input with validation.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Label Support**: Required label for accessibility (can be visually hidden)
-- **Description**: Optional description text displayed between the label and input
-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator
-- **Label Tooltip**: Optional info icon with tooltip at end of label
-- **Label Icon**: Optional icon before the label text
-- **Accessible**: Label properly associated with input via htmlFor/id
-- **Styled with StyleX**: Uses XDS design tokens for consistent styling
-- **Size Variants**: Three sizes (sm, md, lg) for different contexts
-- **Status Handling**: Error, warning, and success states with messages
-- **Number Constraints**: Support for min, max, and step attributes
-- **Validated onChange**: Only calls onChange when the entered value passes validation
-- **Units Display**: Optional units suffix (e.g., "%" or "GB")
-- **Integer Mode**: Option to restrict to integers only
-- **Native Controls**: Uses `type="number"` for browser step controls
-- **Event Callbacks**: onFocus, onBlur, and onEnter handlers
-
-## Usage
-
-```tsx
-import { XDSNumberInput } from '@xds/core/NumberInput';
-
-// Basic input with label
-<XDSNumberInput label="Quantity" value={quantity} onChange={setQuantity} />
-
-// With placeholder
-<XDSNumberInput label="Age" value={age} onChange={setAge} placeholder="Enter your age" />
-
-// With min/max constraints
-<XDSNumberInput label="Rating" value={rating} onChange={setRating} min={1} max={5} />
-
-// With step for decimals
-<XDSNumberInput label="Price" value={price} onChange={setPrice} min={0} step={0.01} />
-
-// With units display
-<XDSNumberInput label="Discount" value={discount} onChange={setDiscount} units="%" />
-
-// Integer only
-<XDSNumberInput label="Count" value={count} onChange={setCount} isIntegerOnly />
-
-// With description
-<XDSNumberInput label="Quantity" description="Enter the number of items" value={qty} onChange={setQty} />
-
-// Optional field
-<XDSNumberInput label="Phone Extension" isOptional value={ext} onChange={setExt} />
-
-// Required field
-<XDSNumberInput label="Amount" isRequired value={amount} onChange={setAmount} />
-
-// With validation status (error, warning, or success)
-<XDSNumberInput
- label="Age"
- value={age}
- onChange={setAge}
- status={{ type: 'error', message: 'Age must be between 18 and 120' }}
-/>
-
-// With event handlers
-<XDSNumberInput
- label="Search"
- value={search}
- onChange={setSearch}
- onEnter={() => handleSearch()}
- onFocus={() => console.log('focused')}
- onBlur={() => console.log('blurred')}
-/>
-```
-
-## Props
-
-| Prop | Type | Required | Description |
-| --------------- | --------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
-| `label` | `string` | Yes | Label text for the input (always rendered for accessibility) |
-| `value` | `number \| null \| undefined` | Yes | Current value of the input |
-| `onChange` | `(value: number) => void` | Yes | Callback fired when input value changes (only on valid input) |
-| `size` | `'sm' \| 'md' \| 'lg'` | No | Size variant (default: `'md'`) |
-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |
-| `description` | `string` | No | Description text displayed between the label and input |
-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |
-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |
-| `isDisabled` | `boolean` | No | Whether the input is disabled |
-| `placeholder` | `string` | No | Placeholder text |
-| `tooltip` | `string` | No | Tooltip text to display in an info icon at the end of the label |
-| `startIcon` | `XDSIconType` | No | Icon to display at the start of the input |
-| `labelIcon` | `XDSIconType` | No | Icon to display before the label text |
-| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | No | Validation status with optional message |
-| `min` | `number \| null` | No | Minimum value allowed |
-| `max` | `number \| null` | No | Maximum value allowed |
-| `step` | `number \| null` | No | Step increment for the input (default: 1) |
-| `units` | `string \| null` | No | Units text to display at the end of the input (e.g., "%" or "GB") |
-| `isIntegerOnly` | `boolean` | No | Only allow integer values (no floating point) |
-| `htmlName` | `string` | No | HTML name attribute for form submissions |
-| `autoComplete` | `string` | No | HTML autocomplete attribute |
-| `hasAutoFocus` | `boolean` | No | Whether to focus the input on mount |
-| `onFocus` | `(e: FocusEvent<HTMLInputElement>) => void` | No | Callback fired when the input receives focus |
-| `onBlur` | `(e: FocusEvent<HTMLInputElement>) => void` | No | Callback fired when the input loses focus |
-| `onEnter` | `() => void` | No | Callback fired when the user presses the Enter key |
-
-## Theming
-
-Themes can override `NumberInput` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- numberInput: {
- wrapper: myStyles,
- input: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| --------- | --------------------------- |
-| `wrapper` | Input wrapper styles |
-| `input` | Number input element styles |
-
-## Files
-
-| File | Role | Purpose |
-| ------------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSNumberInput.tsx` | Core | Component implementation |
-| `XDSNumberInput.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Uses `useId` hook for accessible label-input association
-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually
-- Hidden label uses CSS technique that remains accessible to screen readers
-- Wraps `XDSField` component for label, description, and optional/required handling
-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"
-- Uses `type="number"` to enable native browser step controls (up/down arrows)
-- **Validated onChange**: Only calls `onChange` when the entered value is a valid number that passes min/max/integer constraints
-- Uses internal pending state to allow free-form typing while validating
-- Units are displayed as a lighter grey suffix after the input value
diff --git a/packages/core/src/NumberInput/XDSNumberInput.tsx b/packages/core/src/NumberInput/XDSNumberInput.tsx
index 5191b205aa..e69628307f 100644
--- a/packages/core/src/NumberInput/XDSNumberInput.tsx
+++ b/packages/core/src/NumberInput/XDSNumberInput.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSNumberInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/NumberInput/README.md (props table, features, implementation notes)
+ * - /packages/core/src/NumberInput/NumberInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/NumberInput/XDSNumberInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/NumberInput/index.ts (exports if types change)
* - /apps/storybook/stories/NumberInput.stories.tsx (storybook stories)
diff --git a/packages/core/src/NumberInput/index.ts b/packages/core/src/NumberInput/index.ts
index b83c464db7..ad6557def8 100644
--- a/packages/core/src/NumberInput/index.ts
+++ b/packages/core/src/NumberInput/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSNumberInput, XDSNumberInputProps, XDSNumberInputSize, XDSNumberInputStatus, XDSNumberInputStatusType
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/NumberInput/README.md
+ * SYNC: When modified, update this header and /packages/core/src/NumberInput/NumberInput.doc.mjs
*/
export {XDSNumberInput} from './XDSNumberInput';
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
new file mode 100644
index 0000000000..2dfa8cd82e
--- /dev/null
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -0,0 +1,162 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Pagination',
+ description:
+ 'Standalone pagination controls for navigating through pages of content. Supports multiple display variants and works with known totals or cursor-based pagination.',
+ props: [
+ {
+ name: 'page',
+ type: 'number',
+ description: 'Current page number (1-based). Page 1 is the first page.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(page: number) => void',
+ description: 'Called when the page changes.',
+ required: true,
+ },
+ {
+ name: 'onChangeAction',
+ type: '(page: number) => void | Promise<void>',
+ description:
+ 'Async action on page change. Fires after onChange and uses React transitions for built-in loading state.',
+ },
+ {
+ name: 'totalItems',
+ type: 'number',
+ description:
+ 'Total number of items. Used to calculate page count. Takes precedence over totalPages if both provided.',
+ },
+ {
+ name: 'totalPages',
+ type: 'number',
+ description:
+ 'Total number of pages. Use when you know page count but not item count.',
+ },
+ {
+ name: 'hasMore',
+ type: 'boolean',
+ description:
+ 'Whether more pages exist after the current one. Use for cursor-based pagination where total is unknown.',
+ },
+ {
+ name: 'pageSize',
+ type: 'number',
+ description: 'Number of items per page.',
+ default: '10',
+ },
+ {
+ name: 'pageSizeOptions',
+ type: 'number[]',
+ description:
+ 'Available page size options. Shows a page size selector dropdown when provided.',
+ },
+ {
+ name: 'onPageSizeChange',
+ type: '(pageSize: number) => void',
+ description:
+ 'Called when the page size changes. Automatically resets to page 1.',
+ },
+ {
+ name: 'variant',
+ type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+ description:
+ "Visual variant controlling what appears between prev/next buttons. 'pages' shows page number buttons with ellipsis, 'count' shows 'X-Y of Z' text, 'compact' shows 'Page X of Y', 'dots' shows dot indicators, 'none' shows just prev/next buttons.",
+ default: "'pages'",
+ },
+ {
+ name: 'siblingCount',
+ type: 'number',
+ description:
+ "Number of page buttons to show on each side of the current page. Only applies when variant='pages'.",
+ default: '1',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Size of the pagination controls.',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the component is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the navigation landmark.',
+ default: "'Pagination'",
+ },
+ ],
+ examples: [
+ {
+ label: 'Page number buttons (default)',
+ code: `<XDSPagination
+ page={page}
+ onChange={setPage}
+ totalItems={200}
+ pageSize={20}
+/>`,
+ },
+ {
+ label: 'Count display with page size selector',
+ code: `<XDSPagination
+ page={page}
+ onChange={setPage}
+ totalItems={200}
+ variant="count"
+ pageSizeOptions={[10, 20, 50]}
+ onPageSizeChange={setPageSize}
+/>`,
+ },
+ {
+ label: 'Cursor-based (no total known)',
+ code: `<XDSPagination
+ page={page}
+ onChange={setPage}
+ hasMore={data.hasNextPage}
+/>`,
+ },
+ {
+ label: 'Carousel dots',
+ code: `<XDSPagination
+ page={slideIndex}
+ onChange={setSlideIndex}
+ totalPages={slides.length}
+ variant="dots"
+/>`,
+ },
+ ],
+ features: [
+ "Five display variants: 'pages', 'count', 'compact', 'dots', 'none'",
+ 'Offset and cursor-based pagination: provide totalItems/totalPages for known totals, or hasMore for cursor-based',
+ 'Page size selector: shows a dropdown when pageSizeOptions is provided',
+ 'Ellipsis truncation for page numbers via generatePageRange utility',
+ 'React transitions: onChangeAction uses useTransition for built-in loading state',
+ "Sizes: 'sm' and 'md'",
+ ],
+ accessibility: [
+ 'Root is <nav> with configurable aria-label.',
+ 'Current page button has aria-current="page".',
+ 'Prev/next buttons have descriptive aria-label.',
+ 'Ellipsis elements are aria-hidden.',
+ 'All interactive elements are keyboard accessible.',
+ ],
+ theming: {
+ componentKey: 'pagination',
+ surfaces: [
+ {name: 'root', description: 'Root nav container styles'},
+ ],
+ },
+ notes: [
+ "Page number buttons use XDSButton (variant='ghost' for inactive, variant='primary' for active) for theming and swizzle compatibility.",
+ "Prev/next buttons use XDSButton with variant='ghost' and icon-only mode.",
+ 'Dot indicators remain custom elements (intentionally different visual treatment from buttons).',
+ 'Returns null when totalItems <= 0 or totalPages <= 0.',
+ 'Also exports generatePageRange utility for computing visible page numbers with ellipsis.',
+ ],
+};
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
new file mode 100644
index 0000000000..6e76b0f680
--- /dev/null
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -0,0 +1,112 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ProgressBar',
+ description:
+ 'A progress bar for displaying determinate or indeterminate progress.',
+ features: [
+ 'Determinate mode uses role="meter" with aria-valuenow, aria-valuemin, and aria-valuemax',
+ 'Indeterminate mode uses role="progressbar" without value attributes',
+ 'Label is always connected via aria-labelledby',
+ 'aria-valuetext provides human-readable value description (determinate only)',
+ 'Indeterminate animation respects prefers-reduced-motion',
+ 'Supports four semantic color variants: accent, positive, warning, negative',
+ 'Three track height sizes: sm=4px, md=8px, lg=12px',
+ 'Supports custom value label formatter via formatValueLabel',
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label (required).',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'number',
+ description: 'Current value (ignored when indeterminate).',
+ default: '0',
+ },
+ {
+ name: 'max',
+ type: 'number',
+ description: 'Maximum value.',
+ default: '100',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hide the label (remains accessible).',
+ default: 'false',
+ },
+ {
+ name: 'hasValueLabel',
+ type: 'boolean',
+ description: 'Show formatted value text (ignored when indeterminate).',
+ default: 'false',
+ },
+ {
+ name: 'formatValueLabel',
+ type: '(value: number, max: number) => string',
+ description:
+ 'Custom value label formatter; defaults to a percentage string.',
+ },
+ {
+ name: 'variant',
+ type: "'accent' | 'positive' | 'warning' | 'negative'",
+ description: 'Semantic color variant.',
+ default: "'accent'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Track height: sm=4px, md=8px, lg=12px.',
+ default: "'md'",
+ },
+ {
+ name: 'isIndeterminate',
+ type: 'boolean',
+ description: 'Animated loading indicator for unknown progress.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'Determinate progress bar',
+ code: `<XDSProgressBar value={75} label="Upload progress" />`,
+ },
+ {
+ label: 'With visible value label',
+ code: `<XDSProgressBar value={75} label="Storage used" hasValueLabel />`,
+ },
+ {
+ label: 'Custom value label formatter',
+ code: `<XDSProgressBar
+ value={3.2}
+ max={5}
+ label="Disk usage"
+ hasValueLabel
+ formatValueLabel={(value, max) => \`\${value} GB / \${max} GB\`}
+/>`,
+ },
+ {
+ label: 'Indeterminate loading',
+ code: `<XDSProgressBar isIndeterminate label="Loading..." />`,
+ },
+ {
+ label: 'Variant and size',
+ code: `<XDSProgressBar value={92} label="Disk" variant="negative" size="sm" />`,
+ },
+ {
+ label: 'Hidden label (accessible but not visible)',
+ code: `<XDSProgressBar value={50} label="Loading" isLabelHidden />`,
+ },
+ ],
+ accessibility: [
+ 'Determinate: uses role="meter" with aria-valuenow, aria-valuemin, aria-valuemax',
+ 'Indeterminate: uses role="progressbar" without value attributes',
+ 'Label is always connected via aria-labelledby',
+ 'aria-valuetext provides human-readable value description (determinate only)',
+ 'Indeterminate animation respects prefers-reduced-motion',
+ ],
+};
diff --git a/packages/core/src/ProgressBar/README.md b/packages/core/src/ProgressBar/README.md
deleted file mode 100644
index a2e7c24c6f..0000000000
--- a/packages/core/src/ProgressBar/README.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# ProgressBar
-
-A progress bar for displaying determinate or indeterminate progress.
-
-## Exports
-
-| Export | Type | Description |
-| ----------------------- | --------- | --------------------------- |
-| `XDSProgressBar` | Component | Main progress bar component |
-| `XDSProgressBarProps` | Type | Props interface |
-| `XDSProgressBarVariant` | Type | Variant union type |
-| `XDSProgressBarSize` | Type | Size union type |
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------------ | --------------------------------------------------- | ---------- | ------------------------------------------------------ |
-| `value` | `number` | `0` | Current value (ignored when indeterminate) |
-| `max` | `number` | `100` | Maximum value |
-| `label` | `string` | — | Accessible label (required) |
-| `isLabelHidden` | `boolean` | `false` | Visually hide the label (remains accessible) |
-| `hasValueLabel` | `boolean` | `false` | Show formatted value text (ignored when indeterminate) |
-| `formatValueLabel` | `(value: number, max: number) => string` | percentage | Custom value label formatter |
-| `variant` | `'accent' \| 'positive' \| 'warning' \| 'negative'` | `'accent'` | Semantic color variant |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Track height: sm=4px, md=8px, lg=12px |
-| `isIndeterminate` | `boolean` | `false` | Animated loading indicator for unknown progress |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides for outer container |
-| `data-testid` | `string` | — | Test ID |
-
-## Usage
-
-```tsx
-import {XDSProgressBar} from '@xds/core/ProgressBar';
-
-// Determinate progress bar
-<XDSProgressBar value={75} label="Upload progress" />
-
-// With visible value label
-<XDSProgressBar value={75} label="Storage used" hasValueLabel />
-
-// Custom format
-<XDSProgressBar
- value={3.2}
- max={5}
- label="Disk usage"
- hasValueLabel
- formatValueLabel={(value, max) => `${value} GB / ${max} GB`}
-/>
-
-// Indeterminate loading
-<XDSProgressBar isIndeterminate label="Loading..." />
-
-// Variant and size
-<XDSProgressBar value={92} label="Disk" variant="negative" size="sm" />
-
-// Hidden label (accessible but not visible)
-<XDSProgressBar value={50} label="Loading" isLabelHidden />
-```
-
-## Accessibility
-
-- Determinate: uses `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
-- Indeterminate: uses `role="progressbar"` without value attributes
-- Label is always connected via `aria-labelledby`
-- `aria-valuetext` provides human-readable value description (determinate only)
-- Indeterminate animation respects `prefers-reduced-motion`
-
-## Files
-
-| File | Purpose |
-| ------------------------- | ------------------------ |
-| `XDSProgressBar.tsx` | Component implementation |
-| `XDSProgressBar.test.tsx` | Unit tests |
-| `index.ts` | Barrel exports |
diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsx
index 046f02eb5b..8c1309b58e 100644
--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx
+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/ProgressBar/README.md (props table, features, implementation notes)
+ * - /packages/core/src/ProgressBar/ProgressBar.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/ProgressBar/XDSProgressBar.test.tsx (tests for new/changed behavior)
* - /packages/core/src/ProgressBar/index.ts (exports if types change)
* - /apps/storybook/stories/ProgressBar.stories.tsx (storybook stories)
diff --git a/packages/core/src/RadioList/README.md b/packages/core/src/RadioList/README.md
deleted file mode 100644
index 33d421a38a..0000000000
--- a/packages/core/src/RadioList/README.md
+++ /dev/null
@@ -1,176 +0,0 @@
-# RadioList
-
-A radio group component for single-value selection from a list of options.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Accessible**: Uses native `<input type="radio">` with proper `role="radiogroup"` and ARIA attributes
-- **Orientation**: Supports `vertical` and `horizontal` layouts
-- **Sizes**: `sm` (18px radio, 20px wrapper) and `md` (22px radio, 24px wrapper)
-- **Descriptions**: Optional description text per item
-- **Custom content**: `startContent` and `endContent` slots on each item
-- **Disabled state**: Supports disabling the entire group or individual items
-- **Field integration**: Uses `XDSField` for label, description, required/optional, and status messaging
-
-## Usage
-
-```tsx
-import { XDSRadioList, XDSRadioListItem } from '@xds/core/RadioList';
-
-// Basic usage
-<XDSRadioList
- label="Notification preference"
- value={selected}
- onChange={setSelected}
->
- <XDSRadioListItem label="Email" value="email" />
- <XDSRadioListItem label="SMS" value="sms" />
- <XDSRadioListItem label="Push" value="push" />
-</XDSRadioList>
-
-// With descriptions
-<XDSRadioList
- label="Plan"
- value={plan}
- onChange={setPlan}
->
- <XDSRadioListItem
- label="Free"
- value="free"
- description="Basic features, limited usage"
- />
- <XDSRadioListItem
- label="Pro"
- value="pro"
- description="All features, unlimited usage"
- />
-</XDSRadioList>
-
-// Horizontal layout
-<XDSRadioList
- label="Size"
- value={size}
- onChange={setSize}
- orientation="horizontal"
->
- <XDSRadioListItem label="Small" value="sm" />
- <XDSRadioListItem label="Medium" value="md" />
- <XDSRadioListItem label="Large" value="lg" />
-</XDSRadioList>
-
-// With status
-<XDSRadioList
- label="Required choice"
- value={choice}
- onChange={setChoice}
- isRequired
- status={{ type: 'error', message: 'Please select an option' }}
->
- <XDSRadioListItem label="Option A" value="a" />
- <XDSRadioListItem label="Option B" value="b" />
-</XDSRadioList>
-
-// Disabled group
-<XDSRadioList
- label="Locked selection"
- value="locked"
- onChange={() => {}}
- isDisabled
->
- <XDSRadioListItem label="Locked" value="locked" />
- <XDSRadioListItem label="Unavailable" value="unavailable" />
-</XDSRadioList>
-```
-
-### XDSRadioList
-
-Radio group container with field integration for label, description, and status.
-
-```tsx
-<XDSRadioList label="Notification preference" value={selected} onChange={setSelected}>
- <XDSRadioListItem label="Email" value="email" />
- <XDSRadioListItem label="SMS" value="sms" />
-</XDSRadioList>
-```
-
-| Prop | Type | Default | Description |
-| --------------- | ---------------------------- | ------------ | -------------------------------------------------------------------- |
-| `label` | `string` | — | Label text for the radio group (always rendered for accessibility) |
-| `isLabelHidden` | `boolean` | `false` | Whether to visually hide the label |
-| `description` | `string` | — | Description text displayed below the label |
-| `value` | `string` | — | The currently selected value |
-| `onChange` | `(value: string) => void` | — | Callback fired when the selected value changes |
-| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction of the radio items |
-| `isDisabled` | `boolean` | `false` | Whether all radio items are disabled |
-| `isRequired` | `boolean` | `false` | Whether the radio group is required |
-| `isOptional` | `boolean` | `false` | Whether the field is optional (mutually exclusive with `isRequired`) |
-| `status` | `XDSInputStatus` | — | Status indicator (`{ type, message }`) |
-| `size` | `'sm' \| 'md'` | `'md'` | Size of the radio controls |
-| `labelTooltip` | `string` | — | Tooltip text for an info icon next to the label |
-| `xstyle` | `StyleXStyles` | — | Additional styles for the outer container |
-| `data-testid` | `string` | — | Test ID for the outer container |
-| `children` | `ReactNode` | — | `XDSRadioListItem` elements |
-
-### XDSRadioListItem
-
-Individual radio item with label, description, and content slots.
-
-```tsx
-<XDSRadioListItem
- label="Pro"
- value="pro"
- description="All features, unlimited usage"
-/>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ----------- | ------- | ---------------------------------------------- |
-| `label` | `string` | — | Label text for the radio item |
-| `value` | `string` | — | Value of this radio item |
-| `description` | `string` | — | Description text displayed below the label |
-| `isDisabled` | `boolean` | `false` | Whether this individual radio item is disabled |
-| `startContent` | `ReactNode` | — | Content to render before the radio circle |
-| `endContent` | `ReactNode` | — | Content to render after the label |
-| `data-testid` | `string` | — | Test ID for the radio item container |
-
-## Theming
-
-Themes can override `RadioList` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- radioList: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | ----------------------- |
-| `root` | Root radio group styles |
-
-## Files
-
-| File | Role | Purpose |
-| ----------------------- | ----- | -------------------------------------------------- |
-| `index.ts` | Entry | Exports components and types |
-| `XDSRadioList.tsx` | Core | Radio group container with context provider |
-| `XDSRadioListItem.tsx` | Core | Individual radio item consuming `RadioListContext` |
-| `XDSRadioList.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- `XDSRadioList` creates a `RadioListContext` that provides `name`, `value`, `onChange`, `isDisabled`, `isRequired`, `size`, and `status` to child items
-- `XDSRadioListItem` must be used within an `XDSRadioList` — throws if context is missing
-- Uses a hidden native `<input type="radio">` with a custom visual overlay for consistent styling
-- Focus outline uses the standard XDS focus outline token with `2px` offset
-- Hover states use `color-mix()` for consistent overlay tinting
-- Size variants match `CheckboxInput` dimensions for visual consistency
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
new file mode 100644
index 0000000000..f88aaf161a
--- /dev/null
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -0,0 +1,244 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'RadioList',
+ description:
+ 'A radio group component for single-value selection from a list of options.',
+ features: [
+ 'Accessible — uses native <input type="radio"> with proper role="radiogroup" and ARIA attributes',
+ 'Orientation — supports vertical and horizontal layouts',
+ 'Sizes — sm (18px radio, 20px wrapper) and md (22px radio, 24px wrapper)',
+ 'Descriptions — optional description text per item',
+ 'Custom content — startContent and endContent slots on each item',
+ 'Disabled state — supports disabling the entire group or individual items',
+ 'Field integration — uses XDSField for label, description, required/optional, and status messaging',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSRadioList
+ label="Notification preference"
+ value={selected}
+ onChange={setSelected}
+>
+ <XDSRadioListItem label="Email" value="email" />
+ <XDSRadioListItem label="SMS" value="sms" />
+ <XDSRadioListItem label="Push" value="push" />
+</XDSRadioList>`,
+ },
+ {
+ label: 'With descriptions',
+ code: `<XDSRadioList
+ label="Plan"
+ value={plan}
+ onChange={setPlan}
+>
+ <XDSRadioListItem
+ label="Free"
+ value="free"
+ description="Basic features, limited usage"
+ />
+ <XDSRadioListItem
+ label="Pro"
+ value="pro"
+ description="All features, unlimited usage"
+ />
+</XDSRadioList>`,
+ },
+ {
+ label: 'Horizontal layout',
+ code: `<XDSRadioList
+ label="Size"
+ value={size}
+ onChange={setSize}
+ orientation="horizontal"
+>
+ <XDSRadioListItem label="Small" value="sm" />
+ <XDSRadioListItem label="Medium" value="md" />
+ <XDSRadioListItem label="Large" value="lg" />
+</XDSRadioList>`,
+ },
+ {
+ label: 'With status',
+ code: `<XDSRadioList
+ label="Required choice"
+ value={choice}
+ onChange={setChoice}
+ isRequired
+ status={{ type: 'error', message: 'Please select an option' }}
+>
+ <XDSRadioListItem label="Option A" value="a" />
+ <XDSRadioListItem label="Option B" value="b" />
+</XDSRadioList>`,
+ },
+ {
+ label: 'Disabled group',
+ code: `<XDSRadioList
+ label="Locked selection"
+ value="locked"
+ onChange={() => {}}
+ isDisabled
+>
+ <XDSRadioListItem label="Locked" value="locked" />
+ <XDSRadioListItem label="Unavailable" value="unavailable" />
+</XDSRadioList>`,
+ },
+ ],
+ theming: {
+ componentKey: 'radioList',
+ surfaces: [{name: 'root', description: 'Root radio group styles'}],
+ },
+ notes: [
+ 'XDSRadioList creates a RadioListContext that provides name, value, onChange, isDisabled, isRequired, size, and status to child items',
+ 'XDSRadioListItem must be used within an XDSRadioList — throws if context is missing',
+ 'Uses a hidden native <input type="radio"> with a custom visual overlay for consistent styling',
+ 'Focus outline uses the standard XDS focus outline token with 2px offset',
+ 'Hover states use color-mix() for consistent overlay tinting',
+ 'Size variants match CheckboxInput dimensions for visual consistency',
+ ],
+ components: [
+ {
+ name: 'XDSRadioList',
+ description:
+ 'Radio group container with field integration for label, description, and status.',
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSRadioList label="Notification preference" value={selected} onChange={setSelected}>
+ <XDSRadioListItem label="Email" value="email" />
+ <XDSRadioListItem label="SMS" value="sms" />
+</XDSRadioList>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the radio group (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'The currently selected value.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when the selected value changes.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSRadioListItem elements.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Whether to visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'orientation',
+ type: "'vertical' | 'horizontal'",
+ description: 'Layout direction of the radio items.',
+ default: "'vertical'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether all radio items are disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Whether the radio group is required.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Whether the field is optional (mutually exclusive with isRequired).',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: 'Status indicator ({ type, message }).',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Size of the radio controls.',
+ default: "'md'",
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text for an info icon next to the label.',
+ },
+ ],
+ },
+ {
+ name: 'XDSRadioListItem',
+ description:
+ 'Individual radio item with label, description, and content slots.',
+ examples: [
+ {
+ label: 'With description',
+ code: `<XDSRadioListItem
+ label="Pro"
+ value="pro"
+ description="All features, unlimited usage"
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for the radio item.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Value of this radio item.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this individual radio item is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description: 'Content to render before the radio circle.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content to render after the label.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/RadioList/XDSRadioList.tsx b/packages/core/src/RadioList/XDSRadioList.tsx
index d9e0631a20..5677a8cf9c 100644
--- a/packages/core/src/RadioList/XDSRadioList.tsx
+++ b/packages/core/src/RadioList/XDSRadioList.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSRadioList.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/RadioList/README.md
+ * - /packages/core/src/RadioList/RadioList.doc.mjs
* - /packages/core/src/RadioList/XDSRadioList.test.tsx
* - /packages/core/src/RadioList/index.ts
* - /apps/storybook/stories/RadioList.stories.tsx
diff --git a/packages/core/src/RadioList/XDSRadioListItem.tsx b/packages/core/src/RadioList/XDSRadioListItem.tsx
index 7b28c6aef8..4c35d602e7 100644
--- a/packages/core/src/RadioList/XDSRadioListItem.tsx
+++ b/packages/core/src/RadioList/XDSRadioListItem.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSRadioList.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/RadioList/README.md
+ * - /packages/core/src/RadioList/RadioList.doc.mjs
* - /packages/core/src/RadioList/XDSRadioList.test.tsx
* - /packages/core/src/RadioList/index.ts
* - /apps/storybook/stories/RadioList.stories.tsx
diff --git a/packages/core/src/Section/README.md b/packages/core/src/Section/README.md
deleted file mode 100644
index 0eaa8d5365..0000000000
--- a/packages/core/src/Section/README.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Section
-
-Section container component with background variants.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Overview
-
-XDSSection is a container with background variants for creating visually distinct regions. Sections automatically escape parent container padding for edge-to-edge fills.
-
-## Import
-
-```tsx
-import {XDSSection} from '@xds/core/Section';
-```
-
-## Usage
-
-```tsx
-<XDSSection variant="wash" width={300} height={250}>
- <XDSLayout
- content={<XDSLayoutContent>Content in wash section</XDSLayoutContent>}
- />
-</XDSSection>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------- | ---------------------------------------- | ----------- | ------------------------------------------------- |
-| `variant` | `'section' \| 'transparent' \| 'wash'` | `'section'` | Background variant |
-| `width` | `SizeValue` | — | Width (number = pixels, string = as-is) |
-| `height` | `SizeValue` | — | Height (number = pixels, string = as-is) |
-| `maxWidth` | `SizeValue` | — | Maximum width |
-| `minHeight` | `SizeValue` | — | Minimum height |
-| `children` | `ReactNode` | — | Content |
-| `dividers` | `Array<'top'\|'bottom'\|'start'\|'end'>` | — | Which sides have divider borders |
-| `isFullBleed` | `boolean` | `false` | Removes internal padding for edge-to-edge content |
-
-## Files
-
-| File | Role | Purpose |
-| ---------------- | --------- | -------------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSSection.tsx` | Component | Section container implementation |
-| `README.md` | Docs | This documentation |
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
new file mode 100644
index 0000000000..4ea97e5fb0
--- /dev/null
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -0,0 +1,94 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Section',
+ description:
+ 'Container with background variants for creating visually distinct regions that automatically escape parent container padding for edge-to-edge fills.',
+ features: [
+ 'Background variants: section, transparent, and wash',
+ 'Automatically escapes parent container padding for edge-to-edge fills',
+ 'Supports divider borders on any combination of sides (top, bottom, start, end)',
+ 'Flexible sizing via SizeValue for width, height, maxWidth, and minHeight',
+ 'Full-bleed mode removes internal padding for edge-to-edge content',
+ ],
+ examples: [
+ {
+ label: 'Wash variant',
+ code: `<XDSSection variant="wash" width={300} height={250}>
+ <XDSLayout
+ content={<XDSLayoutContent>Content in wash section</XDSLayoutContent>}
+ />
+</XDSSection>`,
+ },
+ {
+ label: 'Transparent variant',
+ code: `<XDSSection variant="transparent">
+ <XDSLayout
+ content={<XDSLayoutContent>Transparent background</XDSLayoutContent>}
+ />
+</XDSSection>`,
+ },
+ {
+ label: 'With dividers',
+ code: `<XDSSection variant="section" dividers={['top', 'bottom']}>
+ <XDSLayout
+ content={<XDSLayoutContent>Section with top and bottom borders</XDSLayoutContent>}
+ />
+</XDSSection>`,
+ },
+ {
+ label: 'Full bleed',
+ code: `<XDSSection variant="wash" isFullBleed>
+ <XDSLayout
+ content={<XDSLayoutContent>Edge-to-edge content</XDSLayoutContent>}
+ />
+</XDSSection>`,
+ },
+ ],
+ props: [
+ {
+ name: 'variant',
+ type: "'section' | 'transparent' | 'wash'",
+ description: 'Background variant applied to the section container.',
+ default: "'section'",
+ },
+ {
+ name: 'width',
+ type: 'SizeValue',
+ description:
+ 'Width of the section; a number is interpreted as pixels, a string is used as-is.',
+ },
+ {
+ name: 'height',
+ type: 'SizeValue',
+ description:
+ 'Height of the section; a number is interpreted as pixels, a string is used as-is.',
+ },
+ {
+ name: 'maxWidth',
+ type: 'SizeValue',
+ description: 'Maximum width of the section.',
+ },
+ {
+ name: 'minHeight',
+ type: 'SizeValue',
+ description: 'Minimum height of the section.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content rendered inside the section.',
+ },
+ {
+ name: 'dividers',
+ type: "Array<'top' | 'bottom' | 'start' | 'end'>",
+ description: 'Which sides of the section have divider borders.',
+ },
+ {
+ name: 'isFullBleed',
+ type: 'boolean',
+ description: 'Removes internal padding so content extends edge-to-edge.',
+ default: 'false',
+ },
+ ],
+};
diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsx
index dc8cfec101..28d0865113 100644
--- a/packages/core/src/Section/XDSSection.tsx
+++ b/packages/core/src/Section/XDSSection.tsx
@@ -5,7 +5,7 @@
* @position Core section container component
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Section/README.md (props table, features)
+ * - /packages/core/src/Section/Section.doc.mjs (props table, features)
* - /packages/core/src/Section/index.ts (exports if types change)
* - /apps/storybook/stories/Section.stories.tsx (storybook stories)
*/
diff --git a/packages/core/src/Section/index.ts b/packages/core/src/Section/index.ts
index 62796faf7a..5bb74d0356 100644
--- a/packages/core/src/Section/index.ts
+++ b/packages/core/src/Section/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSSection component and types
* @position Entry point for @xds/core/Section module
*
- * SYNC: When modified, update /packages/core/src/Section/README.md
+ * SYNC: When modified, update /packages/core/src/Section/Section.doc.mjs
*/
export {XDSSection} from './XDSSection';
diff --git a/packages/core/src/Selector/README.md b/packages/core/src/Selector/README.md
deleted file mode 100644
index 50c757acd6..0000000000
--- a/packages/core/src/Selector/README.md
+++ /dev/null
@@ -1,156 +0,0 @@
-# XDSSelector
-
-Dropdown selector for choosing from a list of options. Follows XDS input conventions with label, status, and field props.
-
-## Usage
-
-```tsx
-import {XDSSelector, XDSSelectorOption} from '@xds/core/Selector';
-
-// Basic usage (label is required)
-<XDSSelector
- label="Fruit"
- options={['Apple', 'Banana', 'Orange']}
- value={value}
- onChange={setValue}
-/>
-
-// With object options (supports disabled, icons)
-<XDSSelector
- label="Settings"
- options={[
- {value: 'profile', label: 'Profile', icon: UserIcon},
- {value: 'settings', label: 'Settings', icon: CogIcon, disabled: true},
- ]}
- value={value}
- onChange={setValue}
-/>
-
-// Sections (automatically include labeled dividers)
-<XDSSelector
- label="Fruit"
- options={[
- {value: 'apple', label: 'Apple'},
- {type: 'section', title: 'Citrus', options: [
- {value: 'orange', label: 'Orange'},
- ]},
- ]}
- value={value}
- onChange={setValue}
-/>
-
-// Custom rendering with XDSSelectorOption
-<XDSSelector label="User" options={users} value={value} onChange={setValue}>
- {option => (
- <XDSSelectorOption
- icon={UserIcon}
- label={option.label}
- description={option.email}
- />
- )}
-</XDSSelector>
-
-// With status and field props
-<XDSSelector
- label="Fruit"
- isRequired
- status={{type: 'error', message: 'Required'}}
- options={['Apple', 'Banana']}
- value={value}
- onChange={setValue}
-/>
-```
-
-### XDSSelector
-
-Dropdown selector for choosing from a list of options.
-
-```tsx
-<XDSSelector
- label="Fruit"
- options={['Apple', 'Banana', 'Orange']}
- value={value}
- onChange={setValue}
-/>
-```
-
-| Prop | Type | Description |
-| --------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- |
-| `label` | `string` | **Required.** Label text for accessibility |
-| `options` | `XDSSelectorOptionType[]` | **Required.** Array of options (strings, objects, dividers, sections) |
-| `value` | `string` | Selected value |
-| `onChange` | `(value: string) => void` | Selection callback |
-| `placeholder` | `string` | Placeholder text (default: `'Select...'`) |
-| `size` | `'sm' \| 'md' \| 'lg'` | Size variant (default: `'md'`) |
-| `isDisabled` | `boolean` | Disable selector |
-| `isLabelHidden` | `boolean` | Visually hide label |
-| `description` | `string` | Helper text below label |
-| `isOptional` / `isRequired` | `boolean` | Field requirement indicators |
-| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | Status with optional message |
-| `children` | `(option: XDSSelectorOptionData) => ReactNode` | Custom option renderer |
-
-## Option Types
-
-```tsx
-// String - converted to {value: 'Apple', label: 'Apple'}
-'Apple'
-
-// Object - with optional icon, disabled
-{value: 'apple', label: 'Apple', icon?: IconComponent, disabled?: boolean}
-
-// Divider - horizontal separator
-{type: 'divider'}
-
-// Section - grouped options with labeled divider
-{type: 'section', title: 'Group Name', options: [...]}
-```
-
-### XDSSelectorOption
-
-Helper for custom option rendering:
-
-```tsx
-<XDSSelectorOption
- icon={UserIcon}
- label="Primary text"
- description="Secondary"
-/>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | ------------- | ------- | ----------------------------- |
-| `icon` | `XDSIconType` | — | Icon before the label |
-| `label` | `ReactNode` | — | Primary label text (required) |
-| `description` | `ReactNode` | — | Secondary description text |
-
-## Keyboard
-
-↑↓ navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.
-
-## Accessibility
-
-Uses `role="combobox"` trigger, `role="listbox"` dropdown, `role="group"` for sections, `aria-activedescendant` for focus.
-
-## Theming
-
-Themes can override `Selector` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- selector: {
- trigger: myStyles,
- dropdown: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ---------- | ------------------------- |
-| `trigger` | Trigger button styles |
-| `dropdown` | Dropdown container styles |
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
new file mode 100644
index 0000000000..201ada2e39
--- /dev/null
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -0,0 +1,228 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Selector',
+ description:
+ 'Dropdown selector for choosing from a list of options. Follows XDS input conventions with label, status, and field props.',
+ features: [
+ 'Supports string items (auto-converted to {value, label}), object items with optional icon and disabled state, dividers, and labeled sections',
+ 'Custom item rendering via children render prop and XDSSelectorItem helper',
+ 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',
+ 'Size variants: sm, md, lg',
+ 'Full keyboard navigation with typeahead support',
+ 'Accessible — role="combobox" trigger, role="listbox" dropdown, role="group" for sections, aria-activedescendant for focus',
+ ],
+ keyboard:
+ '↑↓ navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.',
+ accessibility: [
+ 'Uses role="combobox" on the trigger button.',
+ 'Dropdown uses role="listbox".',
+ 'Section groups use role="group".',
+ 'aria-activedescendant tracks the focused option.',
+ ],
+ theming: {
+ componentKey: 'selector',
+ surfaces: [
+ {name: 'trigger', description: 'Trigger button styles'},
+ {name: 'dropdown', description: 'Dropdown container styles'},
+ ],
+ },
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSSelector
+ label="Fruit"
+ options={['Apple', 'Banana', 'Orange']}
+ value={value}
+ onChange={setValue}
+/>`,
+ },
+ {
+ label: 'With object items (icon, disabled)',
+ code: `<XDSSelector
+ label="Settings"
+ options={[
+ {value: 'profile', label: 'Profile', icon: UserIcon},
+ {value: 'settings', label: 'Settings', icon: CogIcon, disabled: true},
+ ]}
+ value={value}
+ onChange={setValue}
+/>`,
+ },
+ {
+ label: 'Sections',
+ code: `<XDSSelector
+ label="Fruit"
+ options={[
+ {value: 'apple', label: 'Apple'},
+ {type: 'section', title: 'Citrus', items: [
+ {value: 'orange', label: 'Orange'},
+ ]},
+ ]}
+ value={value}
+ onChange={setValue}
+/>`,
+ },
+ {
+ label: 'Custom rendering with XDSSelectorItem',
+ code: `<XDSSelector label="User" options={users} value={value} onChange={setValue}>
+ {user => (
+ <XDSSelectorItem
+ icon={UserIcon}
+ label={user.label}
+ description={user.email}
+ />
+ )}
+</XDSSelector>`,
+ },
+ {
+ label: 'With status and field props',
+ code: `<XDSSelector
+ label="Fruit"
+ isRequired
+ status={{type: 'error', message: 'Required'}}
+ options={['Apple', 'Banana']}
+ value={value}
+ onChange={setValue}
+/>`,
+ },
+ ],
+ components: [
+ {
+ name: 'XDSSelector',
+ description: 'Dropdown selector for choosing from a list of options.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for accessibility.',
+ required: true,
+ },
+ {
+ name: 'options',
+ type: 'XDSSelectorOption[]',
+ description:
+ 'Array of items — strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Currently selected value.',
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when the selection changes.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown when no value is selected.',
+ default: "'Select...'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant for the selector.',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the selector.',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hides the label while keeping it accessible.',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed below the label.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Marks the field as optional.',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Marks the field as required.',
+ },
+ {
+ name: 'status',
+ type: "{type: 'error' | 'warning' | 'success', message?: string}",
+ description: 'Validation status with an optional message.',
+ },
+ {
+ name: 'children',
+ type: '(item: XDSSelectorItemData) => ReactNode',
+ description: 'Custom render function for each item in the dropdown.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSSelector
+ label="Fruit"
+ options={['Apple', 'Banana', 'Orange']}
+ value={value}
+ onChange={setValue}
+/>`,
+ },
+ {
+ label: 'With object items',
+ code: `<XDSSelector
+ label="Settings"
+ options={[
+ {value: 'profile', label: 'Profile', icon: UserIcon},
+ {value: 'settings', label: 'Settings', icon: CogIcon, disabled: true},
+ ]}
+ value={value}
+ onChange={setValue}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSSelectorItem',
+ description:
+ 'Helper component for custom item rendering inside an XDSSelector children render prop.',
+ props: [
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: 'Primary label text for the item.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon displayed before the label.',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: 'Secondary description text displayed below the label.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Custom item rendering',
+ code: `<XDSSelector label="User" options={users} value={value} onChange={setValue}>
+ {user => (
+ <XDSSelectorItem
+ icon={UserIcon}
+ label={user.label}
+ description={user.email}
+ />
+ )}
+</XDSSelector>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsx
index 73fef9bcc6..d039ae796e 100644
--- a/packages/core/src/Selector/XDSSelector.tsx
+++ b/packages/core/src/Selector/XDSSelector.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update:
- * - /packages/core/src/Selector/README.md
+ * - /packages/core/src/Selector/Selector.doc.mjs
* - /packages/core/src/Selector/index.ts
*/
diff --git a/packages/core/src/SideNav/README.md b/packages/core/src/SideNav/README.md
deleted file mode 100644
index ed5926d915..0000000000
--- a/packages/core/src/SideNav/README.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# SideNav
-
-Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and responsive collapse.
-
-## Components
-
-### XDSSideNav
-
-Container with five zones: header, topContent, children (scrollable), footer, footerIcons.
-
-```tsx
-<XDSSideNav
- header={<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}
- topContent={<XDSButton label="Create new" variant="primary" />}>
- <XDSSideNavSection title="Main">
- <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
- <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
- </XDSSideNavSection>
-</XDSSideNav>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | -------------- | ------- | -------------------------------------------- |
-| `header` | `ReactNode` | — | Header area (XDSSideNavHeader). Sticky |
-| `topContent` | `ReactNode` | — | Content below header (e.g., create button) |
-| `children` | `ReactNode` | — | Navigation sections and items. Scrollable |
-| `footer` | `ReactNode` | — | Footer area above icon bar |
-| `footerIcons` | `ReactNode` | — | Footer icon bar |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
-| `data-testid` | `string` | — | Test ID |
-
-### XDSSideNavHeader
-
-Product/suite/account header with smart interaction boundary logic.
-
-```tsx
-<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
-```
-
-| Prop | Type | Default | Description |
-| ---------------- | -------------- | ------- | --------------------------------- |
-| `icon` | `ReactNode` | — | Product/app icon |
-| `title` | `string` | — | Product/app name (required) |
-| `titleHref` | `string` | — | Link for the title |
-| `supertitle` | `string` | — | Text above the title |
-| `supertitleHref` | `string` | — | Link for the supertitle |
-| `subtitle` | `string` | — | Text below the title |
-| `subtitleHref` | `string` | — | Link for the subtitle |
-| `menu` | `ReactNode` | — | Menu content in a popover |
-| `xstyle` | `StyleXStyles` | — | StyleX overrides |
-| `data-testid` | `string` | — | Test ID |
-
-### XDSSideNavItem
-
-Navigation item with icon, selected state, and nesting support.
-
-```tsx
-<XDSSideNavItem
- label="Dashboard"
- icon={HomeIcon}
- selectedIcon={HomeIconSolid}
- isSelected
- href="/dashboard"
- endContent={<XDSBadge>3</XDSBadge>}
-/>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ---------------------- | ------- | ------------------------------------ |
-| `as` | `XDSLinkComponentType` | — | Custom link component |
-| `label` | `string` | — | Item label (required) |
-| `icon` | `XDSIconType` | — | Icon (outline variant) |
-| `selectedIcon` | `XDSIconType` | — | Icon when selected (filled variant) |
-| `isSelected` | `boolean` | `false` | Current page indicator |
-| `isDisabled` | `boolean` | `false` | Disabled state |
-| `href` | `string` | — | Navigation URL |
-| `onClick` | `(e: MouseEvent) => void` | — | Click handler |
-| `endContent` | `ReactNode` | — | Right-side content (badges, counts) |
-| `children` | `ReactNode` | — | Sub-items for nesting |
-| `data-testid` | `string` | — | Test ID |
-
-### XDSSideNavSection
-
-Section grouping with optional title and end content.
-
-```tsx
-<XDSSideNavSection title="Settings" endContent={<XDSBadge>New</XDSBadge>}>
- <XDSSideNavItem label="General" href="/settings/general" />
- <XDSSideNavItem label="Security" href="/settings/security" />
-</XDSSideNavSection>
-```
-
-| Prop | Type | Default | Description |
-| ---------------- | ----------- | ------- | ------------------------------------------- |
-| `title` | `string` | — | Section title (required) |
-| `subtitle` | `string` | — | Section subtitle |
-| `children` | `ReactNode` | — | Section items |
-| `endContent` | `ReactNode` | — | Right-side content in section header |
-| `isHeaderHidden` | `boolean` | `false` | Visually hide header (still accessible) |
-| `data-testid` | `string` | — | Test ID |
-
-## Usage
-
-```tsx
-import {
- XDSSideNav,
- XDSSideNavHeader,
- XDSSideNavItem,
- XDSSideNavSection,
-} from '@xds/core/SideNav';
-```
-
-### With XDSAppShell + TopNav
-
-When used inside `XDSAppShell` alongside a `XDSTopNav`, **omit the header** — the TopNav already provides the app name and logo. Including `XDSSideNavHeader` would double the identity.
-
-```tsx
-// TopNav provides identity → SideNav has no header
-<XDSAppShell
- topNav={<XDSTopNav title={<XDSTopNavTitle title="My App" />} />}
- sideNav={
- <XDSSideNav>
- <XDSSideNavSection title="Main" isHeaderHidden>
- <XDSSideNavItem
- label="Dashboard"
- icon={HomeIcon}
- isSelected
- href="/dashboard"
- />
- <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
- </XDSSideNavSection>
- </XDSSideNav>
- }>
- <Content />
-</XDSAppShell>
-```
-
-### Standalone (no TopNav)
-
-Without a TopNav, include `XDSSideNavHeader` to provide app identity.
-
-```tsx
-// No TopNav → SideNav header provides identity
-<XDSAppShell
- sideNav={
- <XDSSideNav
- header={
- <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
- }
- topContent={<XDSButton label="Create new" variant="primary" />}
- footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}>
- <XDSSideNavSection title="Main">
- <XDSSideNavItem
- label="Dashboard"
- icon={HomeIcon}
- selectedIcon={HomeIconSolid}
- isSelected
- href="/dashboard"
- />
- <XDSSideNavItem
- label="Projects"
- icon={FolderIcon}
- href="/projects"
- endContent={<XDSBadge>3</XDSBadge>}
- />
- </XDSSideNavSection>
-
- <XDSSideNavSection title="Settings">
- <XDSSideNavItem label="General" href="/settings/general" />
- <XDSSideNavItem label="Security" href="/settings/security" />
- </XDSSideNavSection>
- </XDSSideNav>
- }>
- <Content />
-</XDSAppShell>
-```
-
-## Header Interaction Model
-
-| Props provided | Behavior |
-| --------------------------------------- | -------------------------------------------------------------- |
-| `titleHref` only, no menu | Whole header is one link |
-| `titleHref` + `supertitleHref`, no menu | Each text is an independent link |
-| `menu` only, no hrefs | Whole header is the popover trigger |
-| `menu` + hrefs | Links are independent `<a>`, chevron/remaining area is trigger |
-
-## Accessibility
-
-- `<nav aria-label="Side navigation">`
-- `aria-current="page"` on selected item
-- Sections: `role="group"` with `aria-labelledby`
-- Keyboard: Tab through items, Enter/Space to activate
-
-## Dependencies
-
-- `useXDSPopover` — for header menu popover
-- `XDSIcon` — for rendering icon components in nav items
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
new file mode 100644
index 0000000000..af07f05d9e
--- /dev/null
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -0,0 +1,351 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SideNav',
+ description:
+ 'Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and responsive collapse.',
+ features: [
+ 'Five-zone layout: header, topContent, children (scrollable), footer, footerIcons',
+ 'Smart header interaction boundary logic — links and menu trigger coexist without overlap',
+ 'Nested items via children on XDSSideNavItem',
+ 'Selected state with optional alternate icon for filled/outline variants',
+ 'Section grouping with optional title, subtitle, and end content',
+ 'Accessible — nav landmark, aria-current="page", role="group" with aria-labelledby on sections',
+ 'Keyboard navigable — Tab through items, Enter/Space to activate',
+ ],
+ accessibility: [
+ '<nav aria-label="Side navigation"> wraps the entire component',
+ 'aria-current="page" is applied to the selected item',
+ 'Sections use role="group" with aria-labelledby pointing to the section title',
+ 'isHeaderHidden visually hides the section title while keeping it accessible to screen readers',
+ ],
+ keyboard: 'Tab through items, Enter/Space to activate links',
+ notes: [
+ 'When used inside XDSAppShell alongside XDSTopNav, omit XDSSideNavHeader — the TopNav already provides app identity and including the header would duplicate it.',
+ 'Without a TopNav, include XDSSideNavHeader to provide app identity.',
+ 'Header interaction model: titleHref only → whole header is one link; titleHref + supertitleHref, no menu → each text is an independent link; menu only, no hrefs → whole header is the popover trigger; menu + hrefs → links are independent <a> elements, chevron/remaining area is the popover trigger.',
+ 'Depends on useXDSPopover for the header menu popover and XDSIcon for rendering icon components in nav items.',
+ ],
+ examples: [
+ {
+ label: 'With XDSAppShell + TopNav (no header)',
+ code: `// TopNav provides identity → SideNav has no header
+<XDSAppShell
+ topNav={<XDSTopNav title={<XDSTopNavTitle title="My App" />} />}
+ sideNav={
+ <XDSSideNav>
+ <XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
+ </XDSSideNavSection>
+ </XDSSideNav>
+ }>
+ <Content />
+</XDSAppShell>`,
+ },
+ {
+ label: 'Standalone (no TopNav)',
+ code: `// No TopNav → SideNav header provides identity
+<XDSAppShell
+ sideNav={
+ <XDSSideNav
+ header={
+ <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />
+ }
+ topContent={<XDSButton label="Create new" variant="primary" />}
+ footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ />
+ <XDSSideNavItem
+ label="Projects"
+ icon={FolderIcon}
+ href="/projects"
+ endContent={<XDSBadge>3</XDSBadge>}
+ />
+ </XDSSideNavSection>
+
+ <XDSSideNavSection title="Settings">
+ <XDSSideNavItem label="General" href="/settings/general" />
+ <XDSSideNavItem label="Security" href="/settings/security" />
+ </XDSSideNavSection>
+ </XDSSideNav>
+ }>
+ <Content />
+</XDSAppShell>`,
+ },
+ ],
+ components: [
+ {
+ name: 'XDSSideNav',
+ description:
+ 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons.',
+ props: [
+ {
+ name: 'header',
+ type: 'ReactNode',
+ description: 'Header area (typically XDSSideNavHeader). Sticky.',
+ },
+ {
+ name: 'topContent',
+ type: 'ReactNode',
+ description: 'Content below the header, e.g., a create button.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Navigation sections and items. Scrollable.',
+ },
+ {
+ name: 'footer',
+ type: 'ReactNode',
+ description: 'Footer area above the icon bar.',
+ },
+ {
+ name: 'footerIcons',
+ type: 'ReactNode',
+ description: 'Footer icon bar.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSSideNav
+ header={<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}
+ topContent={<XDSButton label="Create new" variant="primary" />}>
+ <XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
+ <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />
+ </XDSSideNavSection>
+</XDSSideNav>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSSideNavHeader',
+ description:
+ 'Product/suite/account header with smart interaction boundary logic for links and a menu popover.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Product/app name.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Product/app icon.',
+ },
+ {
+ name: 'titleHref',
+ type: 'string',
+ description: 'Link for the title.',
+ },
+ {
+ name: 'supertitle',
+ type: 'string',
+ description: 'Text above the title.',
+ },
+ {
+ name: 'supertitleHref',
+ type: 'string',
+ description: 'Link for the supertitle.',
+ },
+ {
+ name: 'subtitle',
+ type: 'string',
+ description: 'Text below the title.',
+ },
+ {
+ name: 'subtitleHref',
+ type: 'string',
+ description: 'Link for the subtitle.',
+ },
+ {
+ name: 'menu',
+ type: 'ReactNode',
+ description: 'Menu content rendered inside a popover.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Title link only',
+ code: `<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />`,
+ },
+ {
+ label: 'With supertitle and subtitle',
+ code: `<XDSSideNavHeader
+ icon={<AppIcon />}
+ supertitle="Acme Corp"
+ supertitleHref="/org"
+ title="My App"
+ titleHref="/"
+ subtitle="v2.0"
+/>`,
+ },
+ {
+ label: 'With menu',
+ code: `<XDSSideNavHeader
+ icon={<AppIcon />}
+ title="My App"
+ titleHref="/"
+ menu={<WorkspaceSwitcher />}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSSideNavItem',
+ description:
+ 'Navigation item with icon, selected state, optional end content, and nesting support via children.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Item label.',
+ required: true,
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom link component.',
+ },
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon displayed in the outline (unselected) variant.',
+ },
+ {
+ name: 'selectedIcon',
+ type: 'XDSIconType',
+ description:
+ 'Icon displayed when the item is selected (filled variant).',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: 'Marks this item as the current page.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disabled state.',
+ default: 'false',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Navigation URL.',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: 'Click handler.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Right-side content such as badges or counts.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Sub-items for nesting.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic link',
+ code: `<XDSSideNavItem label="Dashboard" icon={HomeIcon} href="/dashboard" />`,
+ },
+ {
+ label: 'Selected with alternate icon and badge',
+ code: `<XDSSideNavItem
+ label="Dashboard"
+ icon={HomeIcon}
+ selectedIcon={HomeIconSolid}
+ isSelected
+ href="/dashboard"
+ endContent={<XDSBadge>3</XDSBadge>}
+/>`,
+ },
+ {
+ label: 'Nested items',
+ code: `<XDSSideNavItem label="Settings" icon={GearIcon} href="/settings">
+ <XDSSideNavItem label="General" href="/settings/general" />
+ <XDSSideNavItem label="Security" href="/settings/security" />
+</XDSSideNavItem>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSSideNavSection',
+ description:
+ 'Section grouping with an optional title, subtitle, and end content.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Section title.',
+ required: true,
+ },
+ {
+ name: 'subtitle',
+ type: 'string',
+ description: 'Section subtitle.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Section items.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Right-side content in the section header.',
+ },
+ {
+ name: 'isHeaderHidden',
+ type: 'boolean',
+ description:
+ 'Visually hides the section header while keeping it accessible to screen readers.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic section',
+ code: `<XDSSideNavSection title="Main">
+ <XDSSideNavItem label="Dashboard" href="/dashboard" />
+ <XDSSideNavItem label="Projects" href="/projects" />
+</XDSSideNavSection>`,
+ },
+ {
+ label: 'With end content and hidden header',
+ code: `<XDSSideNavSection title="Settings" endContent={<XDSBadge>New</XDSBadge>}>
+ <XDSSideNavItem label="General" href="/settings/general" />
+ <XDSSideNavItem label="Security" href="/settings/security" />
+</XDSSideNavSection>`,
+ },
+ {
+ label: 'Hidden header (used with TopNav)',
+ code: `<XDSSideNavSection title="Main" isHeaderHidden>
+ <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />
+</XDSSideNavSection>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index 4cafa9bac9..53294526cc 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -8,7 +8,7 @@
* children (scrollable), footer, and footerIcons (sticky bottom).
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/SideNav.doc.mjs
* - /packages/core/src/SideNav/XDSSideNav.test.tsx
* - /packages/core/src/SideNav/index.ts
* - /apps/storybook/stories/SideNav.stories.tsx
diff --git a/packages/core/src/SideNav/XDSSideNavHeader.tsx b/packages/core/src/SideNav/XDSSideNavHeader.tsx
index 8d83f35be8..95eb1bf060 100644
--- a/packages/core/src/SideNav/XDSSideNavHeader.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeader.tsx
@@ -8,7 +8,7 @@
* Composes useXDSPopover internally when menu prop is provided.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/SideNav.doc.mjs
* - /packages/core/src/SideNav/XDSSideNav.test.tsx
* - /packages/core/src/SideNav/index.ts
* - /apps/storybook/stories/SideNav.stories.tsx
diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
index 8bd985a888..8ed41bd24c 100644
--- a/packages/core/src/SideNav/XDSSideNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -7,7 +7,7 @@
* Navigation item with icon, selected state, and nesting.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/SideNav.doc.mjs
* - /packages/core/src/SideNav/XDSSideNav.test.tsx
* - /packages/core/src/SideNav/index.ts
* - /apps/storybook/stories/SideNav.stories.tsx
diff --git a/packages/core/src/SideNav/XDSSideNavSection.tsx b/packages/core/src/SideNav/XDSSideNavSection.tsx
index 775fb2673b..b2a46d9f7f 100644
--- a/packages/core/src/SideNav/XDSSideNavSection.tsx
+++ b/packages/core/src/SideNav/XDSSideNavSection.tsx
@@ -7,7 +7,7 @@
* Section grouping for navigation items with optional title and end content.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/SideNav/README.md
+ * - /packages/core/src/SideNav/SideNav.doc.mjs
* - /packages/core/src/SideNav/XDSSideNav.test.tsx
* - /packages/core/src/SideNav/index.ts
* - /apps/storybook/stories/SideNav.stories.tsx
diff --git a/packages/core/src/SideNav/index.ts b/packages/core/src/SideNav/index.ts
index 40d6dfea8b..1ca276f88e 100644
--- a/packages/core/src/SideNav/index.ts
+++ b/packages/core/src/SideNav/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSSideNav, XDSSideNavHeader, XDSSideNavItem, XDSSideNavSection
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/SideNav/README.md
+ * SYNC: When modified, update this header and /packages/core/src/SideNav/SideNav.doc.mjs
*/
export {XDSSideNav} from './XDSSideNav';
diff --git a/packages/core/src/Skeleton/README.md b/packages/core/src/Skeleton/README.md
deleted file mode 100644
index 3710a87f95..0000000000
--- a/packages/core/src/Skeleton/README.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Skeleton
-
-A placeholder loading component that displays an animated pulsing effect while content is loading.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Pulsing Animation**: Smooth opacity animation using stepped timing for a subtle shimmer effect
-- **Staggered Animation**: Sequential skeletons can be staggered to create a wave effect
-- **High Contrast Support**: Automatically adjusts for users with `prefers-contrast: more`
-- **Flexible Sizing**: Width and height props accept pixels or any CSS value
-- **Token-aligned Radius**: Border radius options map directly to design tokens
-
-## Usage
-
-```tsx
-import { XDSSkeleton } from '@xds/core/Skeleton';
-
-// Basic text placeholder
-<XDSSkeleton width={200} height={16} />
-
-// Circular avatar placeholder
-<XDSSkeleton width={40} height={40} radius="rounded" />
-
-// Full-width with percentage
-<XDSSkeleton width="100%" height={20} />
-
-// Staggered animation for multiple skeletons
-<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
- <XDSSkeleton width={300} height={16} index={0} />
- <XDSSkeleton width={280} height={16} index={1} />
- <XDSSkeleton width={320} height={16} index={2} />
-</div>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------- | ------------------------------------------------------------------------- | ------------- | ----------------------------------------------- |
-| `width` | `number \| string` | `'100%'` | Width in pixels (number) or CSS value (string) |
-| `height` | `number \| string` | `'100%'` | Height in pixels (number) or CSS value (string) |
-| `radius` | `'none' \| 'inner' \| 'content' \| 'element' \| 'container' \| 'rounded'` | `'container'` | Border radius using design tokens |
-| `index` | `number` | `0` | Index for staggered animation timing |
-| `data-testid` | `string` | — | Test ID for testing |
-
-## Radius Options
-
-| Value | Use Case |
-| ----------- | --------------------------------------- |
-| `none` | Sharp corners (images, rectangles) |
-| `inner` | Inner elements |
-| `content` | Content areas |
-| `element` | Standard elements |
-| `container` | Container-level rounding (default) |
-| `rounded` | Fully rounded (avatars, pills, circles) |
-
-## Animation Timing
-
-The skeleton uses three timing constants:
-
-- **DELAY_TIME** (1000ms): Initial delay before animation starts
-- **FADE_TIME** (1000ms): Duration of one opacity cycle
-- **STAGGER_TIME** (100ms): Delay increment between sequential elements
-
-For element at index `n`, animation starts at: `DELAY_TIME + (STAGGER_TIME × n)`
-
-## Theming
-
-Themes can override `Skeleton` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- skeleton: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | ---------------------------- |
-| `root` | Root skeleton element styles |
-
-## Files
-
-| File | Role | Purpose |
-| ----------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSSkeleton.tsx` | Core | Component implementation |
-
-## Implementation Notes
-
-- Uses `steps(10, end)` timing function for a subtle shimmer effect
-- Animation alternates between 0.25 and 1.0 opacity
-- Background color comes from the `glimmer` token, with `glimmerHighContrast` for accessibility
-- Numeric dimensions are converted to pixels; strings are passed through as-is
diff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjs
new file mode 100644
index 0000000000..8ccd4fa5e4
--- /dev/null
+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs
@@ -0,0 +1,80 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Skeleton',
+ description:
+ 'A placeholder loading component that displays an animated pulsing effect while content is loading.',
+ features: [
+ 'Pulsing Animation: Smooth opacity animation using stepped timing for a subtle shimmer effect',
+ 'Staggered Animation: Sequential skeletons can be staggered to create a wave effect',
+ 'High Contrast Support: Automatically adjusts for users with prefers-contrast: more',
+ 'Flexible Sizing: Width and height props accept pixels or any CSS value',
+ 'Token-aligned Radius: Border radius options map directly to design tokens',
+ ],
+ props: [
+ {
+ name: 'width',
+ type: 'number | string',
+ description: 'Width in pixels (number) or CSS value (string).',
+ default: "'100%'",
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Height in pixels (number) or CSS value (string).',
+ default: "'100%'",
+ },
+ {
+ name: 'radius',
+ type: "'none' | 'inner' | 'content' | 'element' | 'container' | 'rounded'",
+ description:
+ 'Border radius using design tokens. Use none for sharp corners, rounded for fully rounded (avatars, pills, circles).',
+ default: "'container'",
+ },
+ {
+ name: 'index',
+ type: 'number',
+ description:
+ 'Index for staggered animation timing. For element at index n, animation starts at DELAY_TIME + (STAGGER_TIME × n).',
+ default: '0',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic text placeholder',
+ code: '<XDSSkeleton width={200} height={16} />',
+ },
+ {
+ label: 'Circular avatar placeholder',
+ code: '<XDSSkeleton width={40} height={40} radius="rounded" />',
+ },
+ {
+ label: 'Full-width with percentage',
+ code: '<XDSSkeleton width="100%" height={20} />',
+ },
+ {
+ label: 'Staggered animation for multiple skeletons',
+ code: `<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+ <XDSSkeleton width={300} height={16} index={0} />
+ <XDSSkeleton width={280} height={16} index={1} />
+ <XDSSkeleton width={320} height={16} index={2} />
+</div>`,
+ },
+ ],
+ theming: {
+ componentKey: 'skeleton',
+ surfaces: [
+ {
+ name: 'root',
+ description: 'Root skeleton element styles',
+ },
+ ],
+ },
+ notes: [
+ 'Uses steps(10, end) timing function for a subtle shimmer effect.',
+ 'Animation alternates between 0.25 and 1.0 opacity.',
+ 'Background color comes from the glimmer token, with glimmerHighContrast for accessibility.',
+ 'Numeric dimensions are converted to pixels; strings are passed through as-is.',
+ 'Animation timing constants: DELAY_TIME (1000ms) initial delay before animation starts, FADE_TIME (1000ms) duration of one opacity cycle, STAGGER_TIME (100ms) delay increment between sequential elements.',
+ ],
+};
diff --git a/packages/core/src/Skeleton/XDSSkeleton.tsx b/packages/core/src/Skeleton/XDSSkeleton.tsx
index 818584d1ef..e0c8beb178 100644
--- a/packages/core/src/Skeleton/XDSSkeleton.tsx
+++ b/packages/core/src/Skeleton/XDSSkeleton.tsx
@@ -5,7 +5,7 @@
* @position Core implementation of skeleton loading placeholder
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Skeleton/README.md
+ * - /packages/core/src/Skeleton/Skeleton.doc.mjs
* - /packages/core/src/Skeleton/index.ts
* - /apps/storybook/stories/Skeleton.stories.tsx
*/
diff --git a/packages/core/src/Slider/README.md b/packages/core/src/Slider/README.md
deleted file mode 100644
index 3e6d44cb21..0000000000
--- a/packages/core/src/Slider/README.md
+++ /dev/null
@@ -1,185 +0,0 @@
-# Slider
-
-A slider component for selecting numeric values or ranges with full keyboard and pointer support.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Single & range modes**: Pass a `number` for single thumb, `[number, number]` for range
-- **Orientation**: Supports `horizontal` and `vertical` layouts
-- **Value display**: Tooltip (default), inline text, or none
-- **Tick marks**: Optional marks at specified positions with labels
-- **Keyboard navigation**: Arrow keys, Page Up/Down, Home/End
-- **Drag interaction**: Pointer capture for smooth dragging
-- **Custom formatting**: `formatValue` function for display and `aria-valuetext`
-- **Field integration**: Uses `XDSField` for label, description, required/optional, and status messaging
-- **Accessible**: Uses `role="slider"` with full ARIA attributes
-
-## Usage
-
-```tsx
-import { XDSSlider } from '@xds/core/Slider';
-
-// Basic single value
-<XDSSlider label="Volume" value={50} onChange={setValue} />
-
-// Range slider
-<XDSSlider
- label="Price range"
- value={[20, 80]}
- onChange={setRange}
-/>
-
-// With custom formatting
-<XDSSlider
- label="Temperature"
- value={72}
- onChange={setTemp}
- min={32}
- max={212}
- formatValue={(v) => `${v}°F`}
-/>
-
-// With step and marks
-<XDSSlider
- label="Rating"
- value={3}
- onChange={setRating}
- min={1}
- max={5}
- step={1}
- marks={[
- { value: 1, label: 'Poor' },
- { value: 3, label: 'Average' },
- { value: 5, label: 'Excellent' },
- ]}
-/>
-
-// Text value display
-<XDSSlider
- label="Opacity"
- value={75}
- onChange={setOpacity}
- formatValue={(v) => `${v}%`}
- valueDisplay="text"
-/>
-
-// Range with minimum gap
-<XDSSlider
- label="Date range"
- value={[10, 90]}
- onChange={setDateRange}
- minStepsBetweenThumbs={5}
-/>
-
-// With onChangeEnd for committing value
-<XDSSlider
- label="Brightness"
- value={brightness}
- onChange={setBrightness}
- onChangeEnd={commitBrightness}
-/>
-
-// Vertical orientation
-<XDSSlider
- label="Level"
- value={60}
- onChange={setLevel}
- orientation="vertical"
-/>
-
-// Disabled
-<XDSSlider
- label="Locked"
- value={50}
- onChange={() => {}}
- isDisabled
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------- | ------------------------------------------ | -------------- | -------------------------------------------------------- |
-| `label` | `string` | — | Label text (always rendered for accessibility) |
-| `isLabelHidden` | `boolean` | `false` | Whether to visually hide the label |
-| `description` | `string` | — | Description text below the label |
-| `isDisabled` | `boolean` | `false` | Whether the slider is disabled |
-| `isOptional` | `boolean` | `false` | Whether the field is optional |
-| `isRequired` | `boolean` | `false` | Whether the field is required |
-| `status` | `XDSInputStatus` | — | Status indicator (`{ type, message }`) |
-| `labelTooltip` | `string` | — | Tooltip text for an info icon next to the label |
-| `min` | `number` | `0` | Minimum value |
-| `max` | `number` | `100` | Maximum value |
-| `step` | `number` | `1` | Step increment |
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the slider |
-| `formatValue` | `(value: number) => string` | — | Custom value formatting for display and `aria-valuetext` |
-| `valueDisplay` | `'tooltip' \| 'text' \| 'none'` | `'tooltip'` | How the current value is displayed |
-| `marks` | `Array<{ value: number; label?: string }>` | — | Tick marks at specified positions with optional labels |
-| `xstyle` | `StyleXStyles` | — | Additional styles |
-| `data-testid` | `string` | — | Test ID for the root element |
-
-### Single Value Mode
-
-| Prop | Type | Description |
-| ------------- | ------------------------- | ------------------------------------------ |
-| `value` | `number` | Current value |
-| `onChange` | `(value: number) => void` | Callback fired on value change during drag |
-| `onChangeEnd` | `(value: number) => void` | Callback fired when drag ends |
-
-### Range Mode
-
-| Prop | Type | Default | Description |
-| ----------------------- | ----------------------------------- | ------- | -------------------------------------- |
-| `value` | `[number, number]` | — | Current range `[min, max]` |
-| `onChange` | `(value: [number, number]) => void` | — | Callback fired on value change |
-| `onChangeEnd` | `(value: [number, number]) => void` | — | Callback fired when drag ends |
-| `minStepsBetweenThumbs` | `number` | `0` | Minimum number of steps between thumbs |
-
-## Theming
-
-Themes can override `Slider` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- slider: {
- root: myStyles,
- track: myStyles,
- filledTrack: myStyles,
- thumb: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------------- | -------------------------- |
-| `root` | Root container styles |
-| `track` | Background track styles |
-| `filledTrack` | Filled/active track styles |
-| `thumb` | Thumb handle styles |
-
-## Files
-
-| File | Role | Purpose |
-| -------------------- | ----- | --------------------------------------------------- |
-| `index.ts` | Entry | Exports XDSSlider component and all type variants |
-| `XDSSlider.tsx` | Core | Slider component with single and range mode support |
-| `XDSSlider.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- The component uses `forwardRef` — the ref is merged with an internal `trackRef` for pointer position calculations
-- Pointer capture is used during drag for smooth interaction even when the cursor leaves the track
-- `snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds
-- In range mode, the closest thumb is selected on track click based on distance to each thumb
-- `minStepsBetweenThumbs` prevents range thumbs from overlapping by enforcing a minimum gap
-- Keyboard navigation: Arrow keys ±1 step, Page Up/Down ±10 steps, Home/End jump to min/max
-- Tooltip display wraps each thumb in `XDSTooltip` with `delay={0}` and `focusTrigger="always"`
-- Vertical orientation inverts the Y axis (bottom = min, top = max)
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
new file mode 100644
index 0000000000..99a50878cf
--- /dev/null
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -0,0 +1,242 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Slider',
+ description:
+ 'A slider component for selecting numeric values or ranges with full keyboard and pointer support.',
+ features: [
+ 'Single & range modes: Pass a `number` for single thumb, `[number, number]` for range',
+ 'Orientation: Supports `horizontal` and `vertical` layouts',
+ 'Value display: Tooltip (default), inline text, or none',
+ 'Tick marks: Optional marks at specified positions with labels',
+ 'Keyboard navigation: Arrow keys, Page Up/Down, Home/End',
+ 'Drag interaction: Pointer capture for smooth dragging',
+ 'Custom formatting: `formatValue` function for display and `aria-valuetext`',
+ 'Field integration: Uses `XDSField` for label, description, required/optional, and status messaging',
+ 'Accessible: Uses `role="slider"` with full ARIA attributes',
+ ],
+ examples: [
+ {
+ label: 'Basic single value',
+ code: '<XDSSlider label="Volume" value={50} onChange={setValue} />',
+ },
+ {
+ label: 'Range slider',
+ code: `<XDSSlider
+ label="Price range"
+ value={[20, 80]}
+ onChange={setRange}
+/>`,
+ },
+ {
+ label: 'With custom formatting',
+ code: `<XDSSlider
+ label="Temperature"
+ value={72}
+ onChange={setTemp}
+ min={32}
+ max={212}
+ formatValue={(v) => \`\${v}°F\`}
+/>`,
+ },
+ {
+ label: 'With step and marks',
+ code: `<XDSSlider
+ label="Rating"
+ value={3}
+ onChange={setRating}
+ min={1}
+ max={5}
+ step={1}
+ marks={[
+ { value: 1, label: 'Poor' },
+ { value: 3, label: 'Average' },
+ { value: 5, label: 'Excellent' },
+ ]}
+/>`,
+ },
+ {
+ label: 'Text value display',
+ code: `<XDSSlider
+ label="Opacity"
+ value={75}
+ onChange={setOpacity}
+ formatValue={(v) => \`\${v}%\`}
+ valueDisplay="text"
+/>`,
+ },
+ {
+ label: 'Range with minimum gap',
+ code: `<XDSSlider
+ label="Date range"
+ value={[10, 90]}
+ onChange={setDateRange}
+ minStepsBetweenThumbs={5}
+/>`,
+ },
+ {
+ label: 'With onChangeEnd for committing value',
+ code: `<XDSSlider
+ label="Brightness"
+ value={brightness}
+ onChange={setBrightness}
+ onChangeEnd={commitBrightness}
+/>`,
+ },
+ {
+ label: 'Vertical orientation',
+ code: `<XDSSlider
+ label="Level"
+ value={60}
+ onChange={setLevel}
+ orientation="vertical"
+/>`,
+ },
+ {
+ label: 'Disabled',
+ code: `<XDSSlider
+ label="Locked"
+ value={50}
+ onChange={() => {}}
+ isDisabled
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'number | [number, number]',
+ description:
+ 'Current value — a `number` for single thumb mode or `[number, number]` for range mode.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: number) => void | (value: [number, number]) => void',
+ description: 'Callback fired on value change during drag.',
+ },
+ {
+ name: 'onChangeEnd',
+ type: '(value: number) => void | (value: [number, number]) => void',
+ description: 'Callback fired when drag ends.',
+ },
+ {
+ name: 'min',
+ type: 'number',
+ description: 'Minimum value.',
+ default: '0',
+ },
+ {
+ name: 'max',
+ type: 'number',
+ description: 'Maximum value.',
+ default: '100',
+ },
+ {
+ name: 'step',
+ type: 'number',
+ description: 'Step increment.',
+ default: '1',
+ },
+ {
+ name: 'orientation',
+ type: "'horizontal' | 'vertical'",
+ description: 'Orientation of the slider.',
+ default: "'horizontal'",
+ },
+ {
+ name: 'formatValue',
+ type: '(value: number) => string',
+ description:
+ 'Custom value formatting function used for display and `aria-valuetext`.',
+ },
+ {
+ name: 'valueDisplay',
+ type: "'tooltip' | 'text' | 'none'",
+ description: 'How the current value is displayed.',
+ default: "'tooltip'",
+ },
+ {
+ name: 'marks',
+ type: 'Array<{ value: number; label?: string }>',
+ description: 'Tick marks at specified positions with optional labels.',
+ },
+ {
+ name: 'minStepsBetweenThumbs',
+ type: 'number',
+ description:
+ 'Minimum number of steps between thumbs in range mode; prevents thumbs from overlapping.',
+ default: '0',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the slider is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Whether the field is optional.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Whether the field is required.',
+ default: 'false',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Whether to visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text rendered below the label.',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description:
+ 'Status indicator object (`{ type, message }`) for validation feedback.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text for an info icon displayed next to the label.',
+ },
+ ],
+ theming: {
+ componentKey: 'slider',
+ surfaces: [
+ {name: 'root', description: 'Root container element'},
+ {name: 'track', description: 'Background track element'},
+ {name: 'filledTrack', description: 'Filled/active portion of the track'},
+ {name: 'thumb', description: 'Draggable thumb handle'},
+ ],
+ },
+ accessibility: [
+ 'Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.',
+ 'The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',
+ 'Tooltip display uses `XDSTooltip` with `delay={0}` and `focusTrigger="always"` so value is always visible on focus.',
+ ],
+ keyboard:
+ 'Arrow keys ±1 step, Page Up/Down ±10 steps, Home/End jump to min/max.',
+ notes: [
+ 'The component uses `forwardRef` — the ref is merged with an internal `trackRef` used for pointer position calculations.',
+ 'Pointer capture is used during drag for smooth interaction even when the cursor leaves the track.',
+ '`snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds.',
+ 'In range mode, the closest thumb to the click position is selected automatically.',
+ '`minStepsBetweenThumbs` enforces a minimum gap between range thumbs.',
+ 'Vertical orientation inverts the Y axis so that bottom = min and top = max.',
+ ],
+};
diff --git a/packages/core/src/Slider/XDSSlider.tsx b/packages/core/src/Slider/XDSSlider.tsx
index eeb8aace06..a456a19bb7 100644
--- a/packages/core/src/Slider/XDSSlider.tsx
+++ b/packages/core/src/Slider/XDSSlider.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSSlider.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Slider/README.md
+ * - /packages/core/src/Slider/Slider.doc.mjs
* - /packages/core/src/Slider/XDSSlider.test.tsx
* - /packages/core/src/Slider/index.ts
* - /apps/storybook/stories/Slider.stories.tsx
diff --git a/packages/core/src/Spinner/README.md b/packages/core/src/Spinner/README.md
deleted file mode 100644
index c3ee269865..0000000000
--- a/packages/core/src/Spinner/README.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# Spinner
-
-A pure spinner component for indicating loading state. No layout, no text — just the spinning indicator.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **CSS Border Animation**: Lightweight border-based spinner with smooth 360° rotation
-- **Size Variants**: Three sizes (sm, md, lg) matching existing inline spinners
-- **Shade Support**: Default shade for light backgrounds, onMedia for dark/accent backgrounds
-- **Accessible**: `role="status"` and `aria-label="Loading"` by default
-
-## Usage
-
-```tsx
-import { XDSSpinner } from '@xds/core/Spinner';
-
-// Default spinner
-<XDSSpinner />
-
-// Small spinner
-<XDSSpinner size="sm" />
-
-// Large spinner on a dark background
-<XDSSpinner size="lg" shade="onMedia" />
-```
-
-### Composing with layout
-
-XDSSpinner is intentionally minimal. Compose with layout and text components for loading states:
-
-```tsx
-import {XDSSpinner} from '@xds/core/Spinner';
-import {XDSVStack} from '@xds/core/Layout';
-import {XDSText} from '@xds/core/Text';
-
-<XDSVStack gap="space2" align="center">
- <XDSSpinner size="lg" />
- <XDSText color="secondary">Loading...</XDSText>
-</XDSVStack>;
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------- | ------------------------ | ----------- | ----------------------------------------- |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Spinner size (12px, 20px, 28px) |
-| `shade` | `'default' \| 'onMedia'` | `'default'` | Color shade for light or dark backgrounds |
-| `data-testid` | `string` | — | Test ID for testing |
-
-## Size Reference
-
-| Size | Dimensions | Border Width | Use Case |
-| ---- | ---------- | ------------ | ----------------------------- |
-| `sm` | 12×12px | 2px | Inline with text, buttons |
-| `md` | 20×20px | 2px | Default, standalone indicator |
-| `lg` | 28×28px | 3px | Full-page or section loading |
-
-## Theming
-
-Themes can override `Spinner` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- spinner: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | --------------------------- |
-| `root` | Root spinner element styles |
-
-## Files
-
-| File | Role | Purpose |
-| --------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSSpinner.tsx` | Core | Component implementation |
-| `XDSSpinner.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Uses CSS `border` technique: three visible borders + one transparent for the gap
-- Animation: `rotate(360deg)` at 0.6s linear infinite
-- Color inherits from `currentColor`, controlled by shade styles using theme tokens
-- Element is a `<span>` with `display: inline-block` for inline composability
diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjs
new file mode 100644
index 0000000000..b33a107a58
--- /dev/null
+++ b/packages/core/src/Spinner/Spinner.doc.mjs
@@ -0,0 +1,65 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Spinner',
+ description:
+ 'A pure spinner component for indicating loading state. No layout, no text — just the spinning indicator.',
+ features: [
+ 'CSS Border Animation: Lightweight border-based spinner with smooth 360° rotation',
+ 'Size Variants: Three sizes (sm, md, lg) matching existing inline spinners',
+ 'Shade Support: Default shade for light backgrounds, onMedia for dark/accent backgrounds',
+ 'Accessible: role="status" and aria-label="Loading" by default',
+ ],
+ props: [
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Spinner size (10px, 14px, 18px).',
+ default: "'md'",
+ },
+ {
+ name: 'shade',
+ type: "'default' | 'onMedia'",
+ description: 'Color shade for light or dark backgrounds.',
+ default: "'default'",
+ },
+ ],
+ examples: [
+ {
+ label: 'Default',
+ code: `<XDSSpinner />`,
+ },
+ {
+ label: 'Small',
+ code: `<XDSSpinner size="sm" />`,
+ },
+ {
+ label: 'Large on dark background',
+ code: `<XDSSpinner size="lg" shade="onMedia" />`,
+ },
+ {
+ label: 'Composing with layout and text',
+ code: `<XDSVStack gap="space2" align="center">
+ <XDSSpinner size="lg" />
+ <XDSText color="secondary">Loading...</XDSText>
+</XDSVStack>`,
+ },
+ ],
+ theming: {
+ componentKey: 'spinner',
+ surfaces: [
+ {
+ name: 'root',
+ description: 'Root spinner element styles',
+ },
+ ],
+ },
+ notes: [
+ 'Uses CSS border technique: three visible borders + one transparent for the gap.',
+ 'Animation: rotate(360deg) at 0.75s linear infinite.',
+ 'Color inherits from currentColor, controlled by shade styles using theme tokens.',
+ 'Element is a <span> with display: inline-block for inline composability.',
+ 'XDSSpinner is intentionally minimal — compose with layout and text components for full loading states.',
+ 'Size reference: sm = 10×10px / 3px border, md = 14×14px / 3px border, lg = 18×18px / 3px border.',
+ ],
+};
diff --git a/packages/core/src/Spinner/XDSSpinner.tsx b/packages/core/src/Spinner/XDSSpinner.tsx
index 0ff51922d6..4fc930dd9c 100644
--- a/packages/core/src/Spinner/XDSSpinner.tsx
+++ b/packages/core/src/Spinner/XDSSpinner.tsx
@@ -5,7 +5,7 @@
* @position Core implementation of spinner loading indicator
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Spinner/README.md
+ * - /packages/core/src/Spinner/Spinner.doc.mjs
* - /packages/core/src/Spinner/XDSSpinner.test.tsx
* - /packages/core/src/Spinner/index.ts
* - /apps/storybook/stories/Spinner.stories.tsx
diff --git a/packages/core/src/Stack/README.md b/packages/core/src/Stack/README.md
deleted file mode 100644
index 7e3b31cdc9..0000000000
--- a/packages/core/src/Stack/README.md
+++ /dev/null
@@ -1,241 +0,0 @@
-# Stack
-
-Stack layout primitives for arranging items in horizontal or vertical sequences.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Overview
-
-The Stack system provides flexbox-based layout components with:
-
-- Horizontal (`XDSHStack`) and vertical (`XDSVStack`) stacking
-- Themed spacing via gap tokens
-- Individual item control via `XDSStackItem`
-- Polymorphic rendering support
-
-## Import
-
-```tsx
-import {
- XDSHStack,
- XDSVStack,
- XDSStackItem,
- stack,
- stackItem,
-} from '@xds/core/Layout';
-```
-
-## Components
-
-### XDSHStack
-
-Horizontal stack for arranging items left-to-right. Supports polymorphic rendering.
-
-```tsx
-// Basic horizontal stack
-<XDSHStack gap="space2">
- <Item />
- <Item />
-</XDSHStack>
-
-// With alignment
-<XDSHStack gap="space4" vAlign="center">
- <Item />
- <Item />
-</XDSHStack>
-
-// Polymorphic rendering
-<XDSHStack element="nav" gap="space2">
- <Link />
- <Link />
-</XDSHStack>
-```
-
-| Prop | Type | Default | Description |
-| ---------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------ |
-| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |
-| `vAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Vertical alignment |
-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
-| `element` | `ElementType` | `'div'` | HTML element to render |
-| `children` | `ReactNode` | — | Stack content |
-
-### XDSVStack
-
-Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering.
-
-```tsx
-// Basic vertical stack
-<XDSVStack gap="space2">
- <Item />
- <Item />
-</XDSVStack>
-
-// With alignment
-<XDSVStack gap="space4" hAlign="center">
- <Item />
- <Item />
-</XDSVStack>
-
-// Polymorphic rendering
-<XDSVStack element="main" gap="space4">
- <Header />
- <Content />
-</XDSVStack>
-```
-
-| Prop | Type | Default | Description |
-| ---------- | ------------------------------------------- | ----------- | ------------------------------------------------------------------------ |
-| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |
-| `hAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Horizontal alignment |
-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
-| `element` | `ElementType` | `'div'` | HTML element to render |
-| `children` | `ReactNode` | — | Stack content |
-
-### XDSStackItem
-
-Stack item for controlling individual item behavior within a stack. Supports polymorphic rendering.
-
-```tsx
-// Basic usage with fill
-<XDSHStack gap="space2">
- <XDSStackItem size="static">Logo</XDSStackItem>
- <XDSStackItem size="fill">Content</XDSStackItem>
- <XDSStackItem size="static">Actions</XDSStackItem>
-</XDSHStack>
-
-// Override alignment
-<XDSHStack vAlign="start">
- <XDSStackItem crossAlignSelf="center">Centered</XDSStackItem>
- <XDSStackItem>Top-aligned</XDSStackItem>
-</XDSHStack>
-
-// Polymorphic rendering
-<XDSStackItem element="section" size="fill">
- Section content
-</XDSStackItem>
-```
-
-| Prop | Type | Default | Description |
-| ---------------- | ------------------------------------------- | ---------- | ----------------------------- |
-| `size` | `'static' \| 'fill'` | `'static'` | Flex grow behavior |
-| `crossAlignSelf` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Override cross-axis alignment |
-| `element` | `ElementType` | `'div'` | HTML element to render |
-| `children` | `ReactNode` | — | Item content |
-
-## Utilities
-
-For advanced use cases, you can use the underlying StyleX utilities directly.
-
-### stack
-
-StyleX utility for creating flex containers.
-
-```tsx
-import {stack} from '@xds/core/Layout';
-import * as stylex from '@stylexjs/stylex';
-
-<div {...stylex.props(...stack({direction: 'horizontal', gap: 'space2'}))}>
- <Child />
- <Child />
-</div>;
-```
-
-| Option | Type | Default | Description |
-| ------------ | ------------------------------------------- | ---------- | ------------------------------------------------------------------------ |
-| `direction` | `'horizontal' \| 'vertical'` | Required | Stack direction |
-| `gap` | `SpacingScale` | — | Spacing token: `space0` `space1` `space2` `space3` `space4` `space5` ... |
-| `crossAlign` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Cross-axis alignment |
-| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
-
-### stackItem
-
-StyleX utility for controlling flex item behavior.
-
-```tsx
-import {stackItem} from '@xds/core/Layout';
-import * as stylex from '@stylexjs/stylex';
-
-<div {...stylex.props(...stackItem({size: 'fill'}))}>Content</div>;
-```
-
-| Option | Type | Default | Description |
-| ---------------- | ------------------------------------------- | ---------- | ----------------------------- |
-| `size` | `'static' \| 'fill'` | `'static'` | Flex grow behavior |
-| `crossAlignSelf` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | Override cross-axis alignment |
-
-## Spacing Scale
-
-The `gap` prop uses spacing tokens from the theme:
-
-| Token | Description |
-| ---------- | -------------------- |
-| `space0` | No spacing |
-| `space0.5` | Extra small spacing |
-| `space1` | Small spacing |
-| `space2` | Medium-small spacing |
-| `space3` | Medium spacing |
-| `space4` | Medium-large spacing |
-| `space5` | Large spacing |
-| `space6` | Extra large spacing |
-| `space7` | Maximum spacing |
-
-## Common Patterns
-
-### Header Layout
-
-```tsx
-<XDSHStack element="header" gap="space2">
- <XDSStackItem size="static">
- <Logo />
- </XDSStackItem>
- <XDSStackItem size="fill">
- <Navigation />
- </XDSStackItem>
- <XDSStackItem size="static">
- <UserMenu />
- </XDSStackItem>
-</XDSHStack>
-```
-
-### Sidebar Layout
-
-```tsx
-<XDSHStack gap="space4">
- <XDSStackItem size="static">
- <Sidebar />
- </XDSStackItem>
- <XDSStackItem size="fill">
- <MainContent />
- </XDSStackItem>
-</XDSHStack>
-```
-
-### Page Layout
-
-```tsx
-<XDSVStack element="main" gap="space6">
- <XDSStackItem size="static">
- <PageHeader />
- </XDSStackItem>
- <XDSStackItem size="fill">
- <PageContent />
- </XDSStackItem>
- <XDSStackItem size="static">
- <PageFooter />
- </XDSStackItem>
-</XDSVStack>
-```
-
-## Files
-
-| File | Role | Purpose |
-| ----------------------- | --------- | ------------------------------------------------- |
-| `index.ts` | Entry | Exports all stack utilities and components |
-| `stack.stylex.ts` | Utility | StyleX styles for stack (flex container) behavior |
-| `stackItem.stylex.ts` | Utility | StyleX styles for stack item behavior |
-| `XDSHStack.tsx` | Component | Horizontal stack component |
-| `XDSHStack.test.tsx` | Test | XDSHStack unit tests |
-| `XDSVStack.tsx` | Component | Vertical stack component |
-| `XDSVStack.test.tsx` | Test | XDSVStack unit tests |
-| `XDSStackItem.tsx` | Component | Stack item wrapper component |
-| `XDSStackItem.test.tsx` | Test | XDSStackItem unit tests |
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
new file mode 100644
index 0000000000..bd75fe3cc3
--- /dev/null
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -0,0 +1,322 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Stack',
+ description:
+ 'Stack layout primitives for arranging items in horizontal or vertical sequences using flexbox-based layout with themed spacing tokens.',
+ features: [
+ 'Horizontal (XDSHStack) and vertical (XDSVStack) stacking',
+ 'Themed spacing via gap tokens from the design system spacing scale',
+ 'Individual item control via XDSStackItem',
+ 'Polymorphic rendering support via the element prop',
+ 'Low-level StyleX utilities (stack, stackItem) for advanced use cases',
+ ],
+ examples: [
+ {
+ label: 'Header layout',
+ code: `<XDSHStack element="header" gap="space2">
+ <XDSStackItem size="static">
+ <Logo />
+ </XDSStackItem>
+ <XDSStackItem size="fill">
+ <Navigation />
+ </XDSStackItem>
+ <XDSStackItem size="static">
+ <UserMenu />
+ </XDSStackItem>
+</XDSHStack>`,
+ },
+ {
+ label: 'Sidebar layout',
+ code: `<XDSHStack gap="space4">
+ <XDSStackItem size="static">
+ <Sidebar />
+ </XDSStackItem>
+ <XDSStackItem size="fill">
+ <MainContent />
+ </XDSStackItem>
+</XDSHStack>`,
+ },
+ {
+ label: 'Page layout',
+ code: `<XDSVStack element="main" gap="space6">
+ <XDSStackItem size="static">
+ <PageHeader />
+ </XDSStackItem>
+ <XDSStackItem size="fill">
+ <PageContent />
+ </XDSStackItem>
+ <XDSStackItem size="static">
+ <PageFooter />
+ </XDSStackItem>
+</XDSVStack>`,
+ },
+ {
+ label: 'Override alignment per item',
+ code: `<XDSHStack vAlign="start">
+ <XDSStackItem crossAlignSelf="center">Centered</XDSStackItem>
+ <XDSStackItem>Top-aligned</XDSStackItem>
+</XDSHStack>`,
+ },
+ {
+ label: 'StyleX utility — advanced use',
+ code: `import {stack} from '@xds/core/Layout';
+import * as stylex from '@stylexjs/stylex';
+
+<div {...stylex.props(...stack({direction: 'horizontal', gap: 'space2'}))}>
+ <Child />
+ <Child />
+</div>`,
+ },
+ ],
+ notes: [
+ "Import from '@xds/core/Layout': XDSHStack, XDSVStack, XDSStackItem, stack, stackItem.",
+ 'The gap prop accepts spacing tokens: space0, space0.5, space1, space2, space3, space4, space5, space6, space7.',
+ 'stack and stackItem are low-level StyleX utilities for advanced cases where the component API is insufficient.',
+ ],
+ components: [
+ {
+ name: 'XDSHStack',
+ description:
+ 'Horizontal stack for arranging items left-to-right. Supports polymorphic rendering.',
+ props: [
+ {
+ name: 'gap',
+ type: 'SpacingScale',
+ description:
+ 'Spacing token controlling the gap between items: space0, space1, space2, space3, space4, space5, space6, space7.',
+ },
+ {
+ name: 'vAlign',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description: 'Vertical (cross-axis) alignment of items.',
+ default: "'stretch'",
+ },
+ {
+ name: 'wrap',
+ type: "'nowrap' | 'wrap' | 'wrap-reverse'",
+ description: 'Flex wrap behavior.',
+ default: "'nowrap'",
+ },
+ {
+ name: 'element',
+ type: 'ElementType',
+ description: 'HTML element to render as the stack container.',
+ default: "'div'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Stack content.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic horizontal stack',
+ code: `<XDSHStack gap="space2">
+ <Item />
+ <Item />
+</XDSHStack>`,
+ },
+ {
+ label: 'With vertical alignment',
+ code: `<XDSHStack gap="space4" vAlign="center">
+ <Item />
+ <Item />
+</XDSHStack>`,
+ },
+ {
+ label: 'Polymorphic rendering',
+ code: `<XDSHStack element="nav" gap="space2">
+ <Link />
+ <Link />
+</XDSHStack>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSVStack',
+ description:
+ 'Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering.',
+ props: [
+ {
+ name: 'gap',
+ type: 'SpacingScale',
+ description:
+ 'Spacing token controlling the gap between items: space0, space1, space2, space3, space4, space5, space6, space7.',
+ },
+ {
+ name: 'hAlign',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description: 'Horizontal (cross-axis) alignment of items.',
+ default: "'stretch'",
+ },
+ {
+ name: 'wrap',
+ type: "'nowrap' | 'wrap' | 'wrap-reverse'",
+ description: 'Flex wrap behavior.',
+ default: "'nowrap'",
+ },
+ {
+ name: 'element',
+ type: 'ElementType',
+ description: 'HTML element to render as the stack container.',
+ default: "'div'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Stack content.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic vertical stack',
+ code: `<XDSVStack gap="space2">
+ <Item />
+ <Item />
+</XDSVStack>`,
+ },
+ {
+ label: 'With horizontal alignment',
+ code: `<XDSVStack gap="space4" hAlign="center">
+ <Item />
+ <Item />
+</XDSVStack>`,
+ },
+ {
+ label: 'Polymorphic rendering',
+ code: `<XDSVStack element="main" gap="space4">
+ <Header />
+ <Content />
+</XDSVStack>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSStackItem',
+ description:
+ 'Stack item for controlling individual item behavior within a stack. Supports polymorphic rendering.',
+ props: [
+ {
+ name: 'size',
+ type: "'static' | 'fill'",
+ description:
+ 'Flex grow behavior: static keeps natural size, fill expands to consume remaining space.',
+ default: "'static'",
+ },
+ {
+ name: 'crossAlignSelf',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description:
+ 'Override the cross-axis alignment for this individual item, ignoring the parent stack alignment.',
+ },
+ {
+ name: 'element',
+ type: 'ElementType',
+ description: 'HTML element to render as the item wrapper.',
+ default: "'div'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Item content.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Static and fill sizing',
+ code: `<XDSHStack gap="space2">
+ <XDSStackItem size="static">Logo</XDSStackItem>
+ <XDSStackItem size="fill">Content</XDSStackItem>
+ <XDSStackItem size="static">Actions</XDSStackItem>
+</XDSHStack>`,
+ },
+ {
+ label: 'Override alignment per item',
+ code: `<XDSHStack vAlign="start">
+ <XDSStackItem crossAlignSelf="center">Centered</XDSStackItem>
+ <XDSStackItem>Top-aligned</XDSStackItem>
+</XDSHStack>`,
+ },
+ {
+ label: 'Polymorphic rendering',
+ code: `<XDSStackItem element="section" size="fill">
+ Section content
+</XDSStackItem>`,
+ },
+ ],
+ },
+ {
+ name: 'stack',
+ description:
+ 'Low-level StyleX utility for creating flex containers with stack behavior. Use when the component API is insufficient.',
+ props: [
+ {
+ name: 'direction',
+ type: "'horizontal' | 'vertical'",
+ description: 'Stack direction.',
+ required: true,
+ },
+ {
+ name: 'gap',
+ type: 'SpacingScale',
+ description:
+ 'Spacing token controlling the gap between items: space0, space1, space2, space3, space4, space5, space6, space7.',
+ },
+ {
+ name: 'crossAlign',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description: 'Cross-axis alignment of all items.',
+ },
+ {
+ name: 'wrap',
+ type: "'nowrap' | 'wrap' | 'wrap-reverse'",
+ description: 'Flex wrap behavior.',
+ default: "'nowrap'",
+ },
+ ],
+ examples: [
+ {
+ label: 'StyleX horizontal container',
+ code: `import {stack} from '@xds/core/Layout';
+import * as stylex from '@stylexjs/stylex';
+
+<div {...stylex.props(...stack({direction: 'horizontal', gap: 'space2'}))}>
+ <Child />
+ <Child />
+</div>`,
+ },
+ ],
+ },
+ {
+ name: 'stackItem',
+ description:
+ 'Low-level StyleX utility for controlling flex item behavior. Use when the component API is insufficient.',
+ props: [
+ {
+ name: 'size',
+ type: "'static' | 'fill'",
+ description:
+ 'Flex grow behavior: static keeps natural size, fill expands to consume remaining space.',
+ default: "'static'",
+ },
+ {
+ name: 'crossAlignSelf',
+ type: "'start' | 'center' | 'end' | 'stretch'",
+ description:
+ 'Override the cross-axis alignment for this individual item.',
+ },
+ ],
+ examples: [
+ {
+ label: 'StyleX fill item',
+ code: `import {stackItem} from '@xds/core/Layout';
+import * as stylex from '@stylexjs/stylex';
+
+<div {...stylex.props(...stackItem({size: 'fill'}))}>Content</div>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Stack/XDSHStack.tsx b/packages/core/src/Stack/XDSHStack.tsx
index 32e457f1f3..8a424639e5 100644
--- a/packages/core/src/Stack/XDSHStack.tsx
+++ b/packages/core/src/Stack/XDSHStack.tsx
@@ -5,7 +5,7 @@
* @position Layout/Stack component; wraps XDSStack with direction='horizontal'
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/Stack/README.md
+ * - /packages/core/src/Stack/Stack.doc.mjs
* - /packages/core/src/Layout/Stack/XDSHStack.test.tsx
* - /apps/storybook/stories/HStack.stories.tsx
*/
diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsx
index afc6a958af..fd5e455df9 100644
--- a/packages/core/src/Stack/XDSStack.tsx
+++ b/packages/core/src/Stack/XDSStack.tsx
@@ -5,7 +5,7 @@
* @position Layout/Stack component; uses stack.stylex.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/Stack/README.md
+ * - /packages/core/src/Stack/Stack.doc.mjs
* - /packages/core/src/Layout/Stack/XDSStack.test.tsx
* - /apps/storybook/stories/Stack.stories.tsx
*/
diff --git a/packages/core/src/Stack/XDSStackItem.tsx b/packages/core/src/Stack/XDSStackItem.tsx
index d0c15f6270..b6d95c2f8b 100644
--- a/packages/core/src/Stack/XDSStackItem.tsx
+++ b/packages/core/src/Stack/XDSStackItem.tsx
@@ -5,7 +5,7 @@
* @position Layout/Stack component; uses stackItem.stylex.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/README.md
+ * - /packages/core/src/Stack/Stack.doc.mjs
* - /packages/core/src/Layout/Stack/XDSStackItem.test.tsx
* - /apps/storybook/stories/StackItem.stories.tsx
*/
diff --git a/packages/core/src/Stack/XDSVStack.tsx b/packages/core/src/Stack/XDSVStack.tsx
index 0edcff80a9..9abf85701a 100644
--- a/packages/core/src/Stack/XDSVStack.tsx
+++ b/packages/core/src/Stack/XDSVStack.tsx
@@ -5,7 +5,7 @@
* @position Layout/Stack component; wraps XDSStack with direction='vertical'
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Layout/Stack/README.md
+ * - /packages/core/src/Stack/Stack.doc.mjs
* - /packages/core/src/Layout/Stack/XDSVStack.test.tsx
* - /apps/storybook/stories/VStack.stories.tsx
*/
diff --git a/packages/core/src/Stack/index.ts b/packages/core/src/Stack/index.ts
index 8d671f7803..fcdbef34ca 100644
--- a/packages/core/src/Stack/index.ts
+++ b/packages/core/src/Stack/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSStack, XDSHStack, XDSVStack, XDSStackItem components
* @position Entry point for Layout/Stack
*
- * SYNC: When modified, update /packages/core/src/Layout/README.md
+ * SYNC: When modified, update /packages/core/src/Stack/Stack.doc.mjs
*/
// Unified stack component
diff --git a/packages/core/src/Stack/stack.stylex.ts b/packages/core/src/Stack/stack.stylex.ts
index d81c569ba8..4e75441cff 100644
--- a/packages/core/src/Stack/stack.stylex.ts
+++ b/packages/core/src/Stack/stack.stylex.ts
@@ -4,7 +4,7 @@
* @output StyleX utility for stack (flex container) styling
* @position Layout utility; used by XDSHStack, XDSVStack components
*
- * SYNC: When modified, update /packages/core/src/Layout/README.md
+ * SYNC: When modified, update /packages/core/src/Stack/Stack.doc.mjs
*/
import * as stylex from '@stylexjs/stylex';
diff --git a/packages/core/src/Stack/stackItem.stylex.ts b/packages/core/src/Stack/stackItem.stylex.ts
index f3b4d530a2..f8ac6d7be2 100644
--- a/packages/core/src/Stack/stackItem.stylex.ts
+++ b/packages/core/src/Stack/stackItem.stylex.ts
@@ -4,7 +4,7 @@
* @output StyleX utility for stack item styling
* @position Layout utility; used by XDSStackItem and directly by components
*
- * SYNC: When modified, update /packages/core/src/Layout/README.md
+ * SYNC: When modified, update /packages/core/src/Stack/Stack.doc.mjs
*/
import * as stylex from '@stylexjs/stylex';
diff --git a/packages/core/src/StatusDot/README.md b/packages/core/src/StatusDot/README.md
deleted file mode 100644
index e34aff48f6..0000000000
--- a/packages/core/src/StatusDot/README.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# StatusDot
-
-A small colored dot indicator for status display (online/offline, severity, etc).
-
-## Exports
-
-| Export | Type | Description |
-| --------------------- | --------- | ------------------------ |
-| `XDSStatusDot` | Component | Main status dot component |
-| `XDSStatusDotProps` | Type | Props interface |
-| `XDSStatusDotVariant` | Type | Variant union type |
-| `XDSStatusDotSize` | Type | Size union type |
-
-## Props
-
-| Prop | Type | Default | Description |
-| ------------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------ |
-| `variant` | `'positive' \| 'warning' \| 'negative' \| 'info' \| 'neutral'` | - | Semantic color variant (required) |
-| `size` | `'sm' \| 'md'` | `'md'` | Dot size: sm=8px, md=10px |
-| `label` | `string` | - | Accessible label (required) |
-| `isPulsing` | `boolean` | `false` | Pulse animation, respects prefers-reduced-motion |
-| `xstyle` | `StyleXStyles` | - | Optional StyleX style override |
-| `data-testid` | `string` | - | Optional test ID |
-
-## Usage
-
-```tsx
-import {XDSStatusDot} from '@xds/core/StatusDot';
-
-// Basic status indicators
-<XDSStatusDot variant="positive" label="Online" />
-<XDSStatusDot variant="negative" label="Offline" />
-<XDSStatusDot variant="warning" label="Away" />
-
-// Small size
-<XDSStatusDot variant="positive" label="Active" size="sm" />
-
-// Pulsing animation
-<XDSStatusDot variant="positive" label="Live" isPulsing />
-```
-
-## Accessibility
-
-- Renders as `<span role="img" aria-label={label}>` for screen reader support
-- Not focusable (decorative indicator)
-- `isPulsing` animation respects `prefers-reduced-motion: reduce`
-
-## Files
-
-| File | Purpose |
-| ----------------------- | ------------------------ |
-| `XDSStatusDot.tsx` | Component implementation |
-| `XDSStatusDot.test.tsx` | Unit tests |
-| `index.ts` | Barrel exports |
diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjs
new file mode 100644
index 0000000000..7c028d2313
--- /dev/null
+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs
@@ -0,0 +1,62 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'StatusDot',
+ description:
+ 'A small colored dot indicator for status display (online/offline, severity, etc).',
+ features: [
+ 'Five semantic color variants: positive, warning, negative, info, neutral',
+ 'Two sizes: sm (8px) and md (10px)',
+ 'Optional pulse animation that respects prefers-reduced-motion',
+ 'Accessible — renders as <span role="img" aria-label={label}> for screen reader support',
+ 'Not focusable (decorative indicator)',
+ ],
+ props: [
+ {
+ name: 'variant',
+ type: "'positive' | 'warning' | 'negative' | 'info' | 'neutral'",
+ description: 'Semantic color variant.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label surfaced via aria-label.',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Dot size: sm=8px, md=10px.',
+ default: "'md'",
+ },
+ {
+ name: 'isPulsing',
+ type: 'boolean',
+ description:
+ 'Enables a pulse animation; respects prefers-reduced-motion: reduce.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic status indicators',
+ code: `<XDSStatusDot variant="positive" label="Online" />
+<XDSStatusDot variant="negative" label="Offline" />
+<XDSStatusDot variant="warning" label="Away" />`,
+ },
+ {
+ label: 'Small size',
+ code: `<XDSStatusDot variant="positive" label="Active" size="sm" />`,
+ },
+ {
+ label: 'Pulsing animation',
+ code: `<XDSStatusDot variant="positive" label="Live" isPulsing />`,
+ },
+ ],
+ accessibility: [
+ 'Renders as <span role="img" aria-label={label}> for screen reader support.',
+ 'Not focusable — intended as a decorative indicator only.',
+ 'isPulsing animation respects prefers-reduced-motion: reduce.',
+ ],
+};
diff --git a/packages/core/src/StatusDot/XDSStatusDot.tsx b/packages/core/src/StatusDot/XDSStatusDot.tsx
index cdc26cea5e..a219e80ae2 100644
--- a/packages/core/src/StatusDot/XDSStatusDot.tsx
+++ b/packages/core/src/StatusDot/XDSStatusDot.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/StatusDot/README.md (props table, features, implementation notes)
+ * - /packages/core/src/StatusDot/StatusDot.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/StatusDot/XDSStatusDot.test.tsx (tests for new/changed behavior)
* - /packages/core/src/StatusDot/index.ts (exports if types change)
* - /apps/storybook/stories/StatusDot.stories.tsx (storybook stories)
diff --git a/packages/core/src/Switch/README.md b/packages/core/src/Switch/README.md
deleted file mode 100644
index 4cf1a4c051..0000000000
--- a/packages/core/src/Switch/README.md
+++ /dev/null
@@ -1,116 +0,0 @@
-# Switch
-
-A toggle switch component for boolean values with integrated label support.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Boolean Toggle**: Clean on/off switch for boolean values (40x24px with 20px thumb)
-- **Label Integration**: Uses XDSFieldLabel for accessible labels with optional tooltip and icon
-- **Label Position**: Label can appear before or after the switch (`start` or `end`)
-- **Label Spacing**: Support for spread layout (label and switch on opposite ends)
-- **Description**: Optional description text below the label
-- **Optional/Required**: Visual indicators for field status
-- **Accessibility**: Uses native checkbox with `role="switch"`, proper ARIA attributes
-
-## Usage
-
-```tsx
-import { XDSSwitch } from '@xds/core/Switch';
-
-// Basic usage
-<XDSSwitch
- label="Enable notifications"
- value={enabled}
- onChange={setEnabled}
-/>
-
-// With description
-<XDSSwitch
- label="Dark mode"
- description="Switch to a darker color scheme"
- value={darkMode}
- onChange={setDarkMode}
-/>
-
-// With label icon and tooltip
-<XDSSwitch
- label="Auto-save"
- labelIcon={CloudArrowUpIcon}
- labelTooltip="Automatically save changes"
- value={autoSave}
- onChange={setAutoSave}
-/>
-
-// Label at start with spread spacing (settings panel style)
-<XDSSwitch
- label="Enable notifications"
- value={enabled}
- onChange={setEnabled}
- labelPosition="start"
- labelSpacing="spread"
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------- | -------------------------------------------- | ----------- | --------------------------------------------- |
-| `label` | `string` | — | Label text for the switch (required) |
-| `value` | `boolean` | — | Whether the switch is on or off |
-| `onChange` | `(checked: boolean, e: ChangeEvent) => void` | — | Callback fired when state changes |
-| `isLabelHidden` | `boolean` | `false` | Visually hide the label (still accessible) |
-| `description` | `string` | — | Description text below the label |
-| `isDisabled` | `boolean` | `false` | Whether the switch is disabled |
-| `isOptional` | `boolean` | `false` | Whether the field is optional |
-| `isRequired` | `boolean` | `false` | Whether the switch is required |
-| `onFocus` | `(e: FocusEvent) => void` | — | Callback on focus |
-| `onBlur` | `(e: FocusEvent) => void` | — | Callback on blur |
-| `labelIcon` | `XDSIconType` | — | Icon before the label |
-| `labelTooltip` | `string` | — | Tooltip on info icon after label |
-| `labelPosition` | `'start' \| 'end'` | `'end'` | Which side of the switch the label appears on |
-| `labelSpacing` | `'default' \| 'spread'` | `'default'` | Spacing behavior between label and switch |
-
-## Theming
-
-Themes can override `Switch` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- switch: {
- root: myStyles,
- track: myStyles,
- thumb: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | --------------------- |
-| `root` | Root container styles |
-| `track` | Switch track styles |
-| `thumb` | Switch thumb styles |
-
-## Files
-
-| File | Role | Purpose |
-| -------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSSwitch.tsx` | Core | Component implementation |
-| `XDSSwitch.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Fixed dimensions: 40px width, 24px height, 16px thumb (off) / 20px thumb (on)
-- Uses CSS custom properties for hover state management
-- Native checkbox input with `role="switch"` for proper semantics
-- Track and thumb animation with CSS transitions
-- Follows the same patterns as XDSCheckboxInput for consistency
-- `labelPosition="start"` with `labelSpacing="spread"` creates a settings panel style layout
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
new file mode 100644
index 0000000000..e550b40c9e
--- /dev/null
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -0,0 +1,207 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Switch',
+ description:
+ 'A toggle switch component for boolean values with integrated label support.',
+ features: [
+ 'Boolean toggle — fixed 40x24px track with animated 16px (off) / 20px (on) thumb',
+ 'Label integration — uses XDSFieldLabel for accessible labels with optional tooltip and icon',
+ 'Label position — label can appear before or after the switch via labelPosition',
+ 'Label spacing — supports spread layout to push label and switch to opposite ends',
+ 'Description — optional description text displayed below the label',
+ 'Optional/required indicators — visual markers for field status',
+ 'Status messages — error, warning, success, or info message boxes below the switch',
+ 'Async action support — onChangeAction with optimistic UI and built-in loading spinner',
+ 'Accessibility — native checkbox with role="switch", aria-describedby, aria-invalid, aria-busy',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSSwitch
+ label="Enable notifications"
+ value={enabled}
+ onChange={setEnabled}
+/>`,
+ },
+ {
+ label: 'With description',
+ code: `<XDSSwitch
+ label="Dark mode"
+ description="Switch to a darker color scheme"
+ value={darkMode}
+ onChange={setDarkMode}
+/>`,
+ },
+ {
+ label: 'With label icon and tooltip',
+ code: `<XDSSwitch
+ label="Auto-save"
+ labelIcon={CloudArrowUpIcon}
+ labelTooltip="Automatically save changes"
+ value={autoSave}
+ onChange={setAutoSave}
+/>`,
+ },
+ {
+ label: 'Settings panel style (label start, spread spacing)',
+ code: `<XDSSwitch
+ label="Enable notifications"
+ value={enabled}
+ onChange={setEnabled}
+ labelPosition="start"
+ labelSpacing="spread"
+/>`,
+ },
+ {
+ label: 'With async action and optimistic UI',
+ code: `<XDSSwitch
+ label="Sync to cloud"
+ value={syncEnabled}
+ onChange={setSyncEnabled}
+ onChangeAction={async (checked) => {
+ await updateSetting('sync', checked);
+ }}
+/>`,
+ },
+ {
+ label: 'With error status',
+ code: `<XDSSwitch
+ label="Two-factor authentication"
+ value={twoFactor}
+ onChange={setTwoFactor}
+ status={{type: 'error', message: 'Failed to save setting'}}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the switch (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'boolean',
+ description: 'Whether the switch is on or off.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void',
+ description: 'Callback fired when the switch state changes.',
+ },
+ {
+ name: 'onChangeAction',
+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
+ description:
+ 'Async action fired after onChange. Triggers optimistic UI and shows a loading spinner until the promise resolves.',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description:
+ 'Whether the switch is in a loading state, showing a spinner inside the thumb.',
+ default: 'false',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Visually hides the label while keeping it accessible to screen readers.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the switch is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Whether the field is optional. Mutually exclusive with isRequired.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description:
+ 'Whether the switch is required. Mutually exclusive with isOptional.',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description:
+ 'Status indicator with type and message. Displays a colored message box below the switch and sets aria-invalid when type is "error".',
+ },
+ {
+ name: 'onFocus',
+ type: '(e: FocusEvent<HTMLInputElement>) => void',
+ description: 'Callback fired when the switch receives focus.',
+ },
+ {
+ name: 'onBlur',
+ type: '(e: FocusEvent<HTMLInputElement>) => void',
+ description: 'Callback fired when the switch loses focus.',
+ },
+ {
+ name: 'labelIcon',
+ type: 'XDSIconType',
+ description: 'Icon displayed before the label text.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description:
+ 'Tooltip text shown in an info icon at the end of the label.',
+ },
+ {
+ name: 'labelPosition',
+ type: "'start' | 'end'",
+ description:
+ 'Which side of the switch the label appears on. "start" places the label before the switch.',
+ default: "'end'",
+ },
+ {
+ name: 'labelSpacing',
+ type: "'default' | 'spread'",
+ description:
+ 'Spacing behavior between label and switch. "spread" pushes them to opposite ends of the container (full width).',
+ default: "'default'",
+ },
+ ],
+ theming: {
+ componentKey: 'switch',
+ surfaces: [
+ {name: 'root', description: 'Root container flex wrapper'},
+ {name: 'track', description: 'Switch track background element'},
+ {name: 'thumb', description: 'Animated circular thumb inside the track'},
+ ],
+ },
+ accessibility: [
+ 'Renders a native <input type="checkbox" role="switch"> for correct switch semantics',
+ 'Label is always associated via htmlFor/id even when visually hidden',
+ 'Description text is linked via aria-describedby on the input element',
+ 'Status messages are linked via aria-describedby; aria-invalid is set when status type is "error"',
+ 'aria-busy is set during async onChangeAction execution',
+ ],
+ keyboard: 'Space toggles the switch; Tab/Shift+Tab moves focus in and out',
+ notes: [
+ 'Fixed dimensions: 40px width, 24px height, 16px thumb (off), 20px thumb (on)',
+ 'Track and thumb use CSS transitions for background-color, transform, width, and height',
+ 'Hover tints are applied via stylex.when.ancestor with a @media (hover: hover) guard',
+ 'onChangeAction uses React useTransition and useOptimistic for seamless async toggling',
+ 'labelPosition="start" with labelSpacing="spread" produces a settings panel style layout',
+ 'Follows the same patterns as XDSCheckboxInput for structural consistency',
+ ],
+};
diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsx
index cea70a1b76..8124b79ae9 100644
--- a/packages/core/src/Switch/XDSSwitch.tsx
+++ b/packages/core/src/Switch/XDSSwitch.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSSwitch.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Switch/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Switch/Switch.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Switch/XDSSwitch.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Switch/index.ts (exports if types change)
* - /apps/storybook/stories/Switch.stories.tsx (storybook stories)
diff --git a/packages/core/src/TabList/README.md b/packages/core/src/TabList/README.md
deleted file mode 100644
index 51ad962550..0000000000
--- a/packages/core/src/TabList/README.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# TabList
-
-XDSTabList component for tab navigation with overflow menu support.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Context-based communication**: `XDSTabListContext` passes value/onChange/size from XDSTabList to children
-- **Single-responsibility XDSTab**: Renders as `<button>` or `<a>` (when `href` is provided) in the nav
-- **Overflow menu**: `XDSTabMenu` accepts an `options` prop and renders menu items internally
-- **Dynamic trigger label**: Menu trigger shows the selected option's label when one is active
-- **Menu heading**: Dropdown includes an `XDSDivider` with the menu's `label` as a separator heading
-- **Selection indicator**: Selected menu items show a checkmark icon (matching XDSSelector pattern)
-- **Keyboard navigation**: Tab between items, ArrowUp/Down in menu, Home/End, Escape closes menu (via `useListFocus`)
-- **Hover state**: Unselected tabs show a gray underline on hover; no background hover overlay
-- **Accessibility**: `nav` landmark, `aria-current="page"` on selected tabs, `role="menu"` + `aria-label` on dropdown, `aria-controls` connecting trigger to menu, `role="menuitem"` for items, `role="separator"` for heading divider
-
-## Usage
-
-```tsx
-import { XDSTabList, XDSTab, XDSTabMenu } from '@xds/core/TabList';
-
-// Basic usage
-<XDSTabList value={activeTab} onChange={setActiveTab}>
- <XDSTab value="home" label="Home" />
- <XDSTab value="settings" label="Settings" />
-</XDSTabList>
-
-// With links
-<XDSTabList value={activeTab} onChange={setActiveTab}>
- <XDSTab value="home" label="Home" href="/home" />
- <XDSTab value="settings" label="Settings" href="/settings" />
-</XDSTabList>
-
-// With icons
-<XDSTabList value={activeTab} onChange={setActiveTab}>
- <XDSTab value="home" label="Home" icon={<HomeIcon />} selectedIcon={<HomeFilledIcon />} />
- <XDSTab value="settings" label="Settings" icon={<CogIcon />} />
-</XDSTabList>
-
-// With bottom divider
-<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>
- <XDSTab value="home" label="Home" />
- <XDSTab value="settings" label="Settings" />
-</XDSTabList>
-
-// With overflow menu (including icons on menu items)
-<XDSTabList value={activeTab} onChange={setActiveTab}>
- <XDSTab value="home" label="Home" />
- <XDSTab value="settings" label="Settings" />
- <XDSTabMenu
- label="More"
- options={[
- {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},
- {value: 'reports', label: 'Reports', icon: DocumentTextIcon},
- ]}
- />
-</XDSTabList>
-```
-
-## Props
-
-### XDSTabList
-
-```tsx
-<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>
- <XDSTab value="home" label="Home" />
- <XDSTab value="settings" label="Settings" />
-</XDSTabList>
-```
-
-| Prop | Type | Default | Description |
-| ------------ | ---------------------- | ------- | ---------------------------------- |
-| `value` | `string` | — | Active tab value |
-| `onChange` | `(v: string) => void` | — | Tab change callback |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant for tabs |
-| `hasDivider` | `boolean` | `false` | Show bottom divider under tab list |
-| `children` | `ReactNode` | — | XDSTab/XDSTabMenu items |
-
-### XDSTab
-
-```tsx
-<XDSTab value="home" label="Home" href="/home" icon={<HomeIcon />} />
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ----------- | ----------- | ----------------------------------------- |
-| `value` | `string` | — | Unique tab value |
-| `label` | `string` | — | Visible label text |
-| `href` | `string` | `undefined` | URL; renders as `<a>` when provided |
-| `icon` | `ReactNode` | `undefined` | Icon when not selected |
-| `selectedIcon` | `ReactNode` | `undefined` | Icon when selected (falls back to `icon`) |
-
-### XDSTabMenu
-
-```tsx
-<XDSTabMenu
- label="More"
- options={[
- {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},
- {value: 'reports', label: 'Reports', icon: DocumentTextIcon},
- ]}
-/>
-```
-
-| Prop | Type | Default | Description |
-| --------- | -------------------- | ------- | --------------------------------------------------------- |
-| `label` | `string` | — | Trigger label (shown when no option selected) and heading |
-| `options` | `XDSTabMenuOption[]` | — | Menu options rendered in dropdown |
-
-### XDSTabMenuOption
-
-| Field | Type | Description |
-| ------- | ------------- | ------------------------------ |
-| `value` | `string` | Option value |
-| `label` | `string` | Option display label |
-| `icon` | `XDSIconType` | Optional icon before the label |
-
-## Theming
-
-Themes can override `TabList` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- tabList: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | ------------------------- |
-| `root` | Root nav container styles |
-
-## Files
-
-| File | Role | Purpose |
-| ---------------------- | ------- | ------------------------------------------ |
-| `index.ts` | Entry | Exports all components and types |
-| `XDSTabListContext.ts` | Context | XDSTabListContext definition |
-| `XDSTabList.tsx` | Core | Nav wrapper providing XDSTabListContext |
-| `XDSTab.tsx` | Core | Tab button/link with `aria-current="page"` |
-| `XDSTabMenu.tsx` | Core | Menu trigger with `role="menu"` dropdown |
-| `XDSTabList.test.tsx` | Test | Unit tests |
-
-## Accessibility
-
-### XDSTab
-
-- Renders as `<button>` or `<a>` (no `role="tab"` — uses navigation pattern instead)
-- Selected tab has `aria-current="page"`
-- Hover shows gray underline; selected shows accent underline
-
-### XDSTabMenu
-
-- Trigger: `aria-haspopup="menu"` + `aria-expanded` + `aria-controls` pointing to menu
-- Dropdown: `role="menu"` + `id` (matching `aria-controls`) + `aria-label`
-- Heading: `XDSDivider` with `role="separator"`
-- Items: `role="menuitem"` + `aria-current="true"` for selected
-- Keyboard: ArrowUp/Down (wrapping), Home/End, Escape to close (via `useListFocus` hook)
-
-## Implementation Notes
-
-- `XDSTab` renders as `<button>` by default, `<a>` when `href` is provided
-- `XDSTabMenu` renders menu items internally from `options` prop — no child composition
-- Trigger label derives from `options.find(o => o.value === ctx.value)?.label ?? label`
-- Menu trigger underline scopes to the label text only (not the chevron icon)
-- Icons on menu items render via `XDSIcon` with `size="sm"` and `color="secondary"`
-- Selected menu items show a `CheckIcon` checkmark (matching XDSSelector pattern)
-- `hasDivider` on XDSTabList controls the bottom border (default: off)
-- Size uses hardcoded 28/32/36px heights (`sizeVars` not yet available on this branch)
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
new file mode 100644
index 0000000000..34844ed1b4
--- /dev/null
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -0,0 +1,238 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TabList',
+ description:
+ 'Tab navigation components with overflow menu support, rendering as a semantic nav landmark with button or anchor tab items.',
+ features: [
+ 'Context-based communication: XDSTabListContext passes value/onChange/size from XDSTabList to children',
+ 'Single-responsibility XDSTab: renders as <button> or <a> (when href is provided) in the nav',
+ 'Overflow menu: XDSTabMenu accepts an options prop and renders menu items internally from the dropdown',
+ "Dynamic trigger label: menu trigger shows the selected option's label when one is active",
+ "Menu heading: dropdown includes an XDSDivider with the menu's label as a separator heading",
+ 'Selection indicator: selected menu items show a checkmark icon (matching XDSSelector pattern)',
+ 'Keyboard navigation: Tab between items, ArrowUp/Down in menu, Home/End, Escape closes menu (via useListFocus)',
+ 'Hover state: unselected tabs show a gray underline on hover; no background hover overlay',
+ 'Accessibility: nav landmark, aria-current="page" on selected tabs, role="menu" + aria-label on dropdown, aria-controls connecting trigger to menu, role="menuitem" for items, role="separator" for heading divider',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>
+ <XDSTab value="home" label="Home" />
+ <XDSTab value="settings" label="Settings" />
+</XDSTabList>`,
+ },
+ {
+ label: 'With links',
+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>
+ <XDSTab value="home" label="Home" href="/home" />
+ <XDSTab value="settings" label="Settings" href="/settings" />
+</XDSTabList>`,
+ },
+ {
+ label: 'With icons',
+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>
+ <XDSTab value="home" label="Home" icon={<HomeIcon />} selectedIcon={<HomeFilledIcon />} />
+ <XDSTab value="settings" label="Settings" icon={<CogIcon />} />
+</XDSTabList>`,
+ },
+ {
+ label: 'With bottom divider',
+ code: `<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider>
+ <XDSTab value="home" label="Home" />
+ <XDSTab value="settings" label="Settings" />
+</XDSTabList>`,
+ },
+ {
+ label: 'With overflow menu',
+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>
+ <XDSTab value="home" label="Home" />
+ <XDSTab value="settings" label="Settings" />
+ <XDSTabMenu
+ label="More"
+ options={[
+ {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},
+ {value: 'reports', label: 'Reports', icon: DocumentTextIcon},
+ ]}
+ />
+</XDSTabList>`,
+ },
+ ],
+ theming: {
+ componentKey: 'tabList',
+ surfaces: [{name: 'root', description: 'Root nav container styles'}],
+ },
+ accessibility: [
+ 'XDSTabList renders as a <nav> landmark with aria-label="Tabs"',
+ 'XDSTab renders as <button> or <a> — uses navigation pattern, not role="tab"',
+ 'Selected XDSTab has aria-current="page"',
+ 'XDSTabMenu trigger has aria-haspopup="menu", aria-expanded, and aria-controls pointing to the menu element',
+ 'XDSTabMenu dropdown has role="menu" and aria-label matching the label prop',
+ 'XDSTabMenu heading divider has role="separator"',
+ 'XDSTabMenu items have role="menuitem" and aria-current="true" when selected',
+ ],
+ keyboard:
+ 'Tab moves focus between tab items; within the XDSTabMenu dropdown: ArrowUp/ArrowDown navigate items (wrapping), Home/End jump to first/last item, Escape closes the menu.',
+ notes: [
+ 'XDSTab renders as <button> by default and as <a> when href is provided',
+ 'XDSTabMenu renders menu items internally from the options prop — no child composition',
+ 'Trigger label derives from options.find(o => o.value === ctx.value)?.label ?? label',
+ 'Menu trigger underline scopes to the label text span only, not the chevron icon',
+ 'Icons on menu items render via XDSIcon with size="sm" and color="secondary"',
+ 'Selected menu items show a CheckIcon checkmark (matching XDSSelector pattern)',
+ 'hasDivider on XDSTabList controls the bottom border (default: off)',
+ 'Size uses sizeVars tokens for tab heights (sm/md/lg)',
+ ],
+ components: [
+ {
+ name: 'XDSTabList',
+ description:
+ 'Nav wrapper that provides XDSTabListContext (value, onChange, size) to XDSTab and XDSTabMenu children.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: 'The currently selected tab value.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when a tab is selected.',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant applied to all child tabs.',
+ default: "'md'",
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description:
+ 'Whether to show a bottom border divider under the tab list.',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSTab and XDSTabMenu items to render inside the nav.',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSTabList value={activeTab} onChange={setActiveTab}>
+ <XDSTab value="home" label="Home" />
+ <XDSTab value="settings" label="Settings" />
+</XDSTabList>`,
+ },
+ {
+ label: 'With divider',
+ code: `<XDSTabList value={activeTab} onChange={setActiveTab} hasDivider size="sm">
+ <XDSTab value="home" label="Home" />
+ <XDSTab value="settings" label="Settings" />
+</XDSTabList>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTab',
+ description:
+ 'Individual tab item that renders as a button or an anchor link, with selected-state styling and optional icons.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description:
+ 'Unique value for this tab, matched against XDSTabListContext.value.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Visible label text for this tab.',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description:
+ 'URL to navigate to; when provided, the tab renders as an anchor element.',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description:
+ 'Custom component to render instead of <a> for link tabs. Overrides the XDSLinkProvider default. Only applies when href is provided.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon element shown when the tab is not selected.',
+ },
+ {
+ name: 'selectedIcon',
+ type: 'ReactNode',
+ description:
+ 'Icon element shown when the tab is selected; falls back to icon if not provided.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Button tab',
+ code: '<XDSTab value="home" label="Home" />',
+ },
+ {
+ label: 'Link tab with icons',
+ code: '<XDSTab value="home" label="Home" href="/home" icon={<HomeIcon />} selectedIcon={<HomeFilledIcon />} />',
+ },
+ ],
+ },
+ {
+ name: 'XDSTabMenu',
+ description:
+ "Overflow menu trigger that opens a dropdown of additional tab options, showing the selected option's label as the trigger text.",
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label for the trigger button (shown when no option is selected) and the dropdown heading divider.',
+ required: true,
+ },
+ {
+ name: 'options',
+ type: 'XDSTabMenuOption[]',
+ description: 'Array of menu options rendered in the dropdown.',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ label: 'With icons',
+ code: `<XDSTabMenu
+ label="More"
+ options={[
+ {value: 'analytics', label: 'Analytics', icon: ChartBarIcon},
+ {value: 'reports', label: 'Reports', icon: DocumentTextIcon},
+ ]}
+/>`,
+ },
+ {
+ label: 'Text only',
+ code: `<XDSTabMenu
+ label="More"
+ options={[
+ {value: 'analytics', label: 'Analytics'},
+ {value: 'reports', label: 'Reports'},
+ ]}
+/>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/TabList/XDSTab.tsx b/packages/core/src/TabList/XDSTab.tsx
index 5c24efeb3a..329a64a295 100644
--- a/packages/core/src/TabList/XDSTab.tsx
+++ b/packages/core/src/TabList/XDSTab.tsx
@@ -5,7 +5,7 @@
* @position Core tab item; renders as button or anchor in navigation
*
* SYNC: When modified, update:
- * - /packages/core/src/TabList/README.md
+ * - /packages/core/src/TabList/TabList.doc.mjs
* - /packages/core/src/TabList/index.ts
* - /packages/core/src/TabList/XDSTabList.test.tsx
*/
diff --git a/packages/core/src/TabList/XDSTabList.tsx b/packages/core/src/TabList/XDSTabList.tsx
index fb21fb252d..e8db9b3be5 100644
--- a/packages/core/src/TabList/XDSTabList.tsx
+++ b/packages/core/src/TabList/XDSTabList.tsx
@@ -5,7 +5,7 @@
* @position Nav wrapper; provides XDSTabListContext to XDSTab and XDSTabMenu children
*
* SYNC: When modified, update:
- * - /packages/core/src/TabList/README.md
+ * - /packages/core/src/TabList/TabList.doc.mjs
* - /packages/core/src/TabList/index.ts
* - /packages/core/src/TabList/XDSTabList.test.tsx
*/
diff --git a/packages/core/src/TabList/XDSTabListContext.ts b/packages/core/src/TabList/XDSTabListContext.ts
index 4653a11738..aaa22947e5 100644
--- a/packages/core/src/TabList/XDSTabListContext.ts
+++ b/packages/core/src/TabList/XDSTabListContext.ts
@@ -4,7 +4,7 @@
* @output Exports XDSTabListContext, useXDSTabListContext
* @position Context provider; consumed by XDSTab.tsx, XDSTabMenu.tsx
*
- * SYNC: When modified, update /packages/core/src/TabList/README.md
+ * SYNC: When modified, update /packages/core/src/TabList/TabList.doc.mjs
*/
'use client';
diff --git a/packages/core/src/TabList/XDSTabMenu.tsx b/packages/core/src/TabList/XDSTabMenu.tsx
index c3e79342d3..3b18e026df 100644
--- a/packages/core/src/TabList/XDSTabMenu.tsx
+++ b/packages/core/src/TabList/XDSTabMenu.tsx
@@ -5,7 +5,7 @@
* @position Menu trigger button; opens dropdown of overflow menu items
*
* SYNC: When modified, update:
- * - /packages/core/src/TabList/README.md
+ * - /packages/core/src/TabList/TabList.doc.mjs
* - /packages/core/src/TabList/index.ts
* - /packages/core/src/TabList/XDSTabList.test.tsx
*/
diff --git a/packages/core/src/TabList/index.ts b/packages/core/src/TabList/index.ts
index e539436e1e..112bb768d7 100644
--- a/packages/core/src/TabList/index.ts
+++ b/packages/core/src/TabList/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSTabList, XDSTab, XDSTabMenu and their types
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/TabList/README.md
+ * SYNC: When modified, update this header and /packages/core/src/TabList/TabList.doc.mjs
*/
export {XDSTabList} from './XDSTabList';
diff --git a/packages/core/src/Table/README.md b/packages/core/src/Table/README.md
deleted file mode 100644
index 9d94ecb04e..0000000000
--- a/packages/core/src/Table/README.md
+++ /dev/null
@@ -1,385 +0,0 @@
-# Table
-
-Data-driven table with rich cell content via `renderCell`. Compose cells with
-XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Components
-
-| File | Export | Purpose |
-| ------------------------ | -------------------- | ------------------------------------------------------------ |
-| `XDSTable.tsx` | `XDSTable` | Styled, data-driven table with density, dividers, and hover |
-| `XDSBaseTable.tsx` | `XDSBaseTable` | Unstyled table with colgroup, plugin pipeline, children mode |
-| `XDSTableRow.tsx` | `XDSTableRow` | `<tr>` wrapper with context-aware styling + `xstyle` |
-| `XDSTableCell.tsx` | `XDSTableCell` | `<td>` wrapper with context-aware styling + `xstyle` |
-| `XDSTableHeaderCell.tsx` | `XDSTableHeaderCell` | `<th>` wrapper with context-aware header styling + `xstyle` |
-| `XDSTableContext.ts` | `XDSTableContext` | Context for passing styling props to row/cell components |
-
-## Hooks
-
-| File | Export | Purpose |
-| -------------------------- | ---------------------- | ---------------------------------------------------- |
-| `useXDSTableSelection.tsx` | `useXDSTableSelection` | Selection plugin hook — checkboxes, select-all, aria |
-
-## Utilities
-
-| File | Export | Purpose |
-| ---------------- | ------------------ | -------------------------------------------- |
-| `columnUtils.ts` | `proportional` | Create a proportional (fr-like) column width |
-| `columnUtils.ts` | `pixel` | Create a fixed pixel column width |
-| `columnUtils.ts` | `generateColumns` | Auto-generate columns from data object keys |
-| `columnUtils.ts` | `columnWidthToCSS` | Convert a ColumnWidth to a CSS width string |
-
-## Types
-
-| File | Export | Purpose |
-| -------------------------- | ------------------------------- | ------------------------------------------------ |
-| `types.ts` | `XDSTableColumn` | Column definition (key, header, width, renderer) |
-| `types.ts` | `ColumnWidth` | Proportional or pixel width union |
-| `types.ts` | `TablePlugin` | Plugin interface for transform-props pipeline |
-| `types.ts` | `XDSBaseTableProps` | Props for the unstyled base table |
-| `types.ts` | `TableRowComponentProps` | Props interface for Row components |
-| `types.ts` | `TableCellComponentProps` | Props interface for Cell components |
-| `types.ts` | `TableHeaderCellComponentProps` | Props interface for HeaderCell components |
-| `useXDSTableSelection.tsx` | `UseXDSTableSelectionConfig` | Config type for the selection hook |
-
-## Components
-
-### XDSTable
-
-Styled, data-driven table. Use `renderCell` on columns for rich cell content —
-compose with XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives.
-
-```tsx
-<XDSTable
- data={users}
- columns={[
- {
- key: 'name',
- header: 'Name',
- renderCell: user => (
- <XDSHStack gap="space2" align="center">
- <XDSAvatar name={user.name} size="small" />
- <XDSVStack gap="space1">
- <XDSText type="body" weight="semibold">
- {user.name}
- </XDSText>
- <XDSText type="supporting" color="secondary">
- {user.email}
- </XDSText>
- </XDSVStack>
- </XDSHStack>
- ),
- },
- {
- key: 'status',
- header: 'Status',
- width: pixel(140),
- renderCell: user => (
- <XDSHStack gap="space2" align="center">
- <XDSStatusDot status={user.isActive ? 'positive' : 'negative'} />
- <XDSBadge variant={user.isActive ? 'success' : 'error'}>
- {user.isActive ? 'Active' : 'Inactive'}
- </XDSBadge>
- </XDSHStack>
- ),
- },
- {
- key: 'role',
- header: 'Role',
- renderCell: user => (
- <XDSText type="label" color="secondary">
- {user.role}
- </XDSText>
- ),
- },
- ]}
- density="balanced"
- dividers="rows"
- hasHover
-/>
-```
-
-| Prop | Type | Default | Description |
-| ----------- | --------------------------------------- | ------------ | -------------------------------------------------------------- |
-| `data` | `T[]` | — | Array of data items |
-| `columns` | `XDSTableColumn<T>[]` | — | Column definitions with optional `renderCell` for rich content |
-| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
-| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Row density |
-| `dividers` | `XDSTableDividers` | `'rows'` | Divider style |
-| `isStriped` | `boolean` | `false` | Striped even rows |
-| `hasHover` | `boolean` | `false` | Hover highlight on rows |
-| `plugins` | `Record<string, TablePlugin<T>>` | — | Named plugins to extend behavior |
-| `children` | `ReactNode` | — | Children mode (manual rows) |
-
-### XDSBaseTable
-
-Unstyled table with colgroup, plugin pipeline, and components prop for custom rendering.
-
-```tsx
-<XDSBaseTable
- data={items}
- columns={columns}
- plugins={[myPlugin]}
- components={{Row: XDSTableRow, Cell: XDSTableCell}}
-/>
-```
-
-| Prop | Type | Default | Description |
-| ------------ | ------------------------------- | ------- | -------------------------------------- |
-| `data` | `T[]` | — | Array of data items |
-| `columns` | `XDSTableColumn<T>[]` | — | Column definitions |
-| `idKey` | `string \| (item: T) => string` | — | Row key for React reconciliation |
-| `plugins` | `TablePlugin<T>[]` | — | Ordered plugins for transform pipeline |
-| `components` | `{Row?, Cell?, HeaderCell?}` | — | Component overrides for table elements |
-| `children` | `ReactNode` | — | Children mode |
-| `tableProps` | `HTMLAttributes` | — | Additional attrs for `<table>` element |
-
-### XDSTableRow
-
-`<tr>` wrapper with context-aware styling and xstyle support.
-
-```tsx
-<XDSTableRow>
- <XDSTableCell>Alice</XDSTableCell>
- <XDSTableCell>30</XDSTableCell>
-</XDSTableRow>
-```
-
-| Prop | Type | Default | Description |
-| ---------- | ---------------- | ------- | --------------- |
-| `children` | `ReactNode` | — | Row cells |
-| `xstyle` | `StyleXStyles[]` | — | Style overrides |
-
-### XDSTableCell
-
-`<td>` wrapper with context-aware styling and xstyle support. Accepts any ReactNode
-as children — compose rich content with XDS components like XDSBadge, XDSStatusDot,
-XDSText, XDSAvatar, and layout primitives.
-
-```tsx
-<XDSTableCell>
- <XDSHStack gap="space2" align="center">
- <XDSStatusDot status="positive" />
- <XDSText weight="semibold">Active</XDSText>
- </XDSHStack>
-</XDSTableCell>
-```
-
-| Prop | Type | Default | Description |
-| ---------- | ------------------------------ | ------- | --------------- |
-| `children` | `ReactNode` | — | Cell content |
-| `xstyle` | `StyleXStyles \| StyleXStyles` | — | Style overrides |
-
-### XDSTableHeaderCell
-
-`<th>` wrapper with context-aware header styling and xstyle support.
-
-```tsx
-<XDSTableHeaderCell>Name</XDSTableHeaderCell>
-```
-
-| Prop | Type | Default | Description |
-| ---------- | -------------------------------- | ------- | --------------- |
-| `children` | `ReactNode` | — | Header content |
-| `xstyle` | `StyleXStyles \| StyleXStyles[]` | — | Style overrides |
-
-## Usage Patterns
-
-### Rich cell content with renderCell
-
-Use `renderCell` to compose XDS components inside table cells. This is the
-recommended pattern for any table that displays more than plain text.
-
-```tsx
-const columns = [
- {
- key: 'transaction',
- header: 'Transaction',
- renderCell: item => (
- <XDSVStack gap="space1">
- <XDSText type="body" weight="semibold">
- {item.description}
- </XDSText>
- <XDSText type="supporting" color="secondary">
- {item.date}
- </XDSText>
- </XDSVStack>
- ),
- },
- {
- key: 'amount',
- header: 'Amount',
- width: pixel(120),
- renderCell: item => (
- <XDSText
- type="body"
- weight="semibold"
- color={item.amount > 0 ? 'positive' : 'primary'}>
- {item.amount > 0 ? '+' : ''}
- {item.amount.toFixed(2)}
- </XDSText>
- ),
- },
- {
- key: 'status',
- header: 'Status',
- width: pixel(140),
- renderCell: item => (
- <XDSHStack gap="space2" align="center">
- <XDSStatusDot status={statusMap[item.status]} />
- <XDSBadge variant={badgeMap[item.status]}>{item.status}</XDSBadge>
- </XDSHStack>
- ),
- },
-];
-
-<XDSTable data={transactions} columns={columns} hasHover dividers="rows" />;
-```
-
-### Data-driven table (plain text)
-
-For simple tables where plain text is sufficient, columns default to `String(item[key])`:
-
-```tsx
-<XDSTable
- data={users}
- columns={[
- {key: 'name', header: 'Name'},
- {key: 'email', header: 'Email', width: proportional(2)},
- {key: 'age', header: 'Age', width: pixel(80)},
- ]}
- density="balanced"
- dividers="rows"
- hasHover
-/>
-```
-
-### Auto-generated columns
-
-```tsx
-// Columns auto-generated from data keys with capitalized headers
-<XDSTable data={users} isStriped />
-```
-
-### Children mode
-
-For fully custom row layouts, use children mode with XDSTableRow and XDSTableCell:
-
-```tsx
-<XDSTable density="balanced" dividers="rows" isStriped hasHover>
- <XDSTableRow>
- <XDSTableCell>
- <XDSHStack gap="space2" align="center">
- <XDSAvatar name="Alice" size="small" />
- <XDSText weight="semibold">Alice</XDSText>
- </XDSHStack>
- </XDSTableCell>
- <XDSTableCell>
- <XDSBadge variant="success">Active</XDSBadge>
- </XDSTableCell>
- </XDSTableRow>
-</XDSTable>
-```
-
-### Custom plugin
-
-```tsx
-const highlightPlugin: TablePlugin<User> = {
- transformBodyRow(props, item) {
- if (item.isActive) {
- return {...props, styles: [...props.styles, activeRowStyle]};
- }
- return props;
- },
-};
-
-<XDSTable data={users} plugins={{highlight: highlightPlugin}} />;
-```
-
-### Selection
-
-```tsx
-const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());
-
-const selectionPlugin = useXDSTableSelection<User>({
- getIsItemSelected: item => selectedKeys.has(item.id),
- onSelectItem: ({item, isSelected}) => {
- const next = new Set(selectedKeys);
- isSelected ? next.add(item.id) : next.delete(item.id);
- setSelectedKeys(next);
- },
- onSelectAll: ({isAllSelected}) => {
- setSelectedKeys(isAllSelected ? new Set(users.map(u => u.id)) : new Set());
- },
- getIsAllSelected: () => users.every(u => selectedKeys.has(u.id)),
- getIsIndeterminate: () => {
- const count = users.filter(u => selectedKeys.has(u.id)).length;
- return count > 0 && count < users.length;
- },
- // Optional: hide checkbox for non-selectable rows
- getIsItemSelectable: item => item.role !== 'admin',
- // Optional: disable checkbox for locked rows
- getIsItemEnabled: item => !item.isLocked,
-});
-
-<XDSTable
- data={users}
- columns={columns}
- plugins={{selection: selectionPlugin}}
-/>;
-```
-
-## Architecture
-
-Two-layer design: **XDSBaseTable** provides unstyled structure, the plugin pipeline, and a `components` prop for rendering custom elements. **XDSTable** wraps it, providing `XDSTableContext` with appearance configuration and passing styled components (`XDSTableRow`, `XDSTableCell`, `XDSTableHeaderCell`) that read context to apply density, dividers, isStriped, and hasHover styles.
-
-### Component-Based Styling
-
-Styling is owned by components rather than a styling plugin:
-
-- **XDSTableRow** — reads `XDSTableContext` for striped/hover/divider styles
-- **XDSTableCell** — reads `XDSTableContext` for density/divider styles
-- **XDSTableHeaderCell** — reads `XDSTableContext` for density/header/divider styles
-
-Each component accepts `xstyle` for additional styles from plugin transforms (e.g., selected row background from the selection plugin).
-
-### Plugin System
-
-Plugins transform render props at each structural level (`transformTable`, `transformHeaderRow`, `transformBodyRow`, etc.). XDSTable accepts plugins as a named record (`Record<string, TablePlugin<T>>`), while XDSBaseTable accepts an ordered array. XDSTable converts the record to an array internally.
-
-Plugins can also provide:
-
-- `transformTableContext` — wrap the table output in context providers (used by selection to provide `SelectionContext`)
-- Row transforms receive pre-rendered `children` (cells), allowing plugins to prepend/append elements
-
-### Selection Architecture
-
-The selection plugin uses React Context so that `SelectAllCheckbox` and `SelectionRowCheckbox` re-render independently from row content. The hook returns a stable plugin object via ref — only the context value updates when selection state changes. Selection cells render `XDSTableCell` and `XDSTableHeaderCell` directly, inheriting styling from `XDSTableContext`.
-
-### Performance
-
-Body rows are memoized via `React.memo` with a custom comparison function. When a single data item changes, only that row re-renders — unchanged rows are skipped. For this to work optimally, consumers should define `columns` outside the component or memoize them.
-
-## Theming
-
-Themes can override `Table` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- table: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | ----------------- |
-| `root` | Root table styles |
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
new file mode 100644
index 0000000000..28d168d483
--- /dev/null
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -0,0 +1,493 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Table',
+ description:
+ 'Data-driven table with rich cell content via renderCell. Compose cells with XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives. XDSBaseTable provides the unstyled structural core with a composable plugin pipeline.',
+ features: [
+ 'Data-driven rendering — pass data + columns, rows render automatically',
+ 'Rich cell content via renderCell — compose XDS components (XDSBadge, XDSStatusDot, XDSText, XDSAvatar) inside table cells',
+ 'Children mode — compose XDSTableRow/XDSTableCell directly for manual layouts',
+ 'Plugin system — extend table behavior with composable transform plugins',
+ 'Density variants: compact, balanced, spacious',
+ 'Divider styles: rows, columns, grid, none',
+ 'Striped even rows and hover highlight via XDSTableContext',
+ 'Selection via useXDSTableSelection — checkboxes, select-all, aria-selected',
+ 'Body rows memoized with custom comparison — only changed rows re-render',
+ 'Auto-generated columns from data object keys when columns prop is omitted',
+ 'Theming — root, headerRow, bodyRow, headerCell, bodyCell surfaces via ComponentStyles',
+ ],
+ examples: [
+ {
+ label: 'Basic data-driven table',
+ code: `<XDSTable
+ data={users}
+ columns={[
+ {
+ key: 'name',
+ header: 'Name',
+ renderCell: user => (
+ <XDSHStack gap="space2" align="center">
+ <XDSAvatar name={user.name} size="small" />
+ <XDSVStack gap="space1">
+ <XDSText type="body" weight="semibold">
+ {user.name}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {user.email}
+ </XDSText>
+ </XDSVStack>
+ </XDSHStack>
+ ),
+ },
+ {
+ key: 'status',
+ header: 'Status',
+ width: pixel(140),
+ renderCell: user => (
+ <XDSHStack gap="space2" align="center">
+ <XDSStatusDot status={user.isActive ? 'positive' : 'negative'} />
+ <XDSBadge variant={user.isActive ? 'success' : 'error'}>
+ {user.isActive ? 'Active' : 'Inactive'}
+ </XDSBadge>
+ </XDSHStack>
+ ),
+ },
+ {
+ key: 'role',
+ header: 'Role',
+ renderCell: user => (
+ <XDSText type="label" color="secondary">
+ {user.role}
+ </XDSText>
+ ),
+ },
+ ]}
+ density="balanced"
+ dividers="rows"
+ hasHover
+/>`,
+ },
+ {
+ label: 'Auto-generated columns',
+ code: `// Columns auto-generated from data keys with capitalized headers
+<XDSTable data={users} isStriped />`,
+ },
+ {
+ label: 'Rich cell content with renderCell',
+ code: `<XDSTable
+ data={transactions}
+ columns={[
+ {
+ key: 'description',
+ header: 'Transaction',
+ renderCell: tx => (
+ <XDSVStack gap="space1">
+ <XDSText weight="semibold">{tx.description}</XDSText>
+ <XDSText type="supporting" color="secondary">
+ {tx.date}
+ </XDSText>
+ </XDSVStack>
+ ),
+ },
+ {
+ key: 'amount',
+ header: 'Amount',
+ renderCell: tx => (
+ <XDSText
+ weight="semibold"
+ color={tx.amount > 0 ? 'positive' : 'negative'}>
+ {tx.amount > 0 ? '+' : ''}
+ {tx.amount.toFixed(2)}
+ </XDSText>
+ ),
+ },
+ {
+ key: 'status',
+ header: 'Status',
+ renderCell: tx => (
+ <XDSBadge
+ variant={
+ tx.status === 'completed'
+ ? 'success'
+ : tx.status === 'pending'
+ ? 'warning'
+ : 'error'
+ }>
+ {tx.status}
+ </XDSBadge>
+ ),
+ },
+ ]}
+ density="balanced"
+ dividers="rows"
+ hasHover
+/>`,
+ },
+ {
+ label: 'Children mode',
+ code: `<XDSTable density="balanced" dividers="rows" isStriped hasHover>
+ <XDSTableRow>
+ <XDSTableCell>
+ <XDSHStack gap="space2" align="center">
+ <XDSAvatar name="Alice" size="small" />
+ <XDSText weight="semibold">Alice</XDSText>
+ </XDSHStack>
+ </XDSTableCell>
+ <XDSTableCell>
+ <XDSBadge variant="success">Active</XDSBadge>
+ </XDSTableCell>
+ </XDSTableRow>
+</XDSTable>`,
+ },
+ {
+ label: 'Selection plugin',
+ code: `const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());
+
+const selectionPlugin = useXDSTableSelection<User>({
+ getIsItemSelected: item => selectedKeys.has(item.id),
+ onSelectItem: ({item, isSelected}) => {
+ const next = new Set(selectedKeys);
+ isSelected ? next.add(item.id) : next.delete(item.id);
+ setSelectedKeys(next);
+ },
+ onSelectAll: ({isAllSelected}) => {
+ setSelectedKeys(isAllSelected ? new Set(users.map(u => u.id)) : new Set());
+ },
+ getIsAllSelected: () => users.every(u => selectedKeys.has(u.id)),
+ getIsIndeterminate: () => {
+ const count = users.filter(u => selectedKeys.has(u.id)).length;
+ return count > 0 && count < users.length;
+ },
+});
+
+<XDSTable
+ data={users}
+ columns={columns}
+ plugins={{selection: selectionPlugin}}
+/>`,
+ },
+ {
+ label: 'Custom plugin',
+ code: `const highlightPlugin: TablePlugin<User> = {
+ transformBodyRow(props, item) {
+ if (item.isActive) {
+ return {...props, styles: [...props.styles, activeRowStyle]};
+ }
+ return props;
+ },
+};
+
+<XDSTable data={users} plugins={{highlight: highlightPlugin}} />`,
+ },
+ ],
+ theming: {
+ componentKey: 'table',
+ surfaces: [
+ {name: 'root', description: 'Root table element styles'},
+ {name: 'headerRow', description: 'Header row styles'},
+ {name: 'bodyRow', description: 'Body row styles'},
+ {name: 'headerCell', description: 'Header cell styles'},
+ {name: 'bodyCell', description: 'Body cell styles'},
+ ],
+ },
+ accessibility: [
+ 'Selection plugin sets aria-selected on selected body rows',
+ 'Select-all and per-row checkboxes use visually hidden labels ("Select all rows", "Select row") via isLabelHidden',
+ 'Non-selectable rows (getIsItemSelectable returns false) render no checkbox',
+ 'Disabled rows (getIsItemEnabled returns false) render a disabled checkbox',
+ ],
+ notes: [
+ 'Two-layer design: XDSBaseTable provides unstyled structure and the plugin pipeline; XDSTable wraps it with XDSTableContext and styled sub-components.',
+ 'Styling is owned by components (XDSTableRow, XDSTableCell, XDSTableHeaderCell), not by plugins — each reads XDSTableContext to apply density, dividers, striped, and hover styles.',
+ 'XDSTable accepts plugins as a named Record<string, TablePlugin<T>> and converts to an ordered array internally; XDSBaseTable accepts an ordered array directly.',
+ 'The selection plugin uses React Context so SelectAllCheckbox and SelectionRowCheckbox re-render independently from row content — only the context value updates when selection state changes.',
+ 'Body rows are memoized via React.memo with a custom comparison. For optimal performance, define columns outside the component or memoize them to avoid triggering full re-renders.',
+ 'Columns can be auto-generated from data keys using generateColumns(); column widths are expressed as proportional (fr-like) or fixed pixel values via the proportional() and pixel() helpers.',
+ 'tableProps on XDSBaseTable passes additional HTML attributes directly to the <table> element.',
+ ],
+ components: [
+ {
+ name: 'XDSTable',
+ description:
+ 'Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support.',
+ props: [
+ {
+ name: 'data',
+ type: 'T[]',
+ description: 'Array of data items to render as rows.',
+ },
+ {
+ name: 'columns',
+ type: 'XDSTableColumn<T>[]',
+ description:
+ 'Column definitions. If omitted, columns are auto-generated from data object keys.',
+ },
+ {
+ name: 'idKey',
+ type: '(keyof T & string) | ((item: T) => string | number)',
+ description:
+ 'Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Row density controlling cell padding and font size.',
+ default: "'balanced'",
+ },
+ {
+ name: 'dividers',
+ type: "'rows' | 'columns' | 'grid' | 'none'",
+ description: 'Divider style rendered between cells.',
+ default: "'rows'",
+ },
+ {
+ name: 'isStriped',
+ type: 'boolean',
+ description: 'Applies a background wash to even-numbered rows.',
+ default: 'false',
+ },
+ {
+ name: 'hasHover',
+ type: 'boolean',
+ description:
+ 'Applies a hover highlight background to rows on pointer devices.',
+ default: 'false',
+ },
+ {
+ name: 'plugins',
+ type: 'Record<string, TablePlugin<T>>',
+ description:
+ 'Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Children mode — render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Data-driven',
+ code: `<XDSTable
+ data={users}
+ columns={[
+ {key: 'name', header: 'Name'},
+ {key: 'email', header: 'Email', width: proportional(2)},
+ ]}
+ density="compact"
+ dividers="grid"
+ isStriped
+ hasHover
+/>`,
+ },
+ {
+ label: 'Children mode',
+ code: `<XDSTable density="balanced" dividers="rows">
+ <XDSTableRow>
+ <XDSTableCell>Alice</XDSTableCell>
+ <XDSTableCell>30</XDSTableCell>
+ </XDSTableRow>
+</XDSTable>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSBaseTable',
+ description:
+ 'Unstyled structural table component with a plugin transform pipeline and a components prop for swapping in custom row/cell renderers.',
+ props: [
+ {
+ name: 'data',
+ type: 'T[]',
+ description: 'Array of data items to render as rows.',
+ },
+ {
+ name: 'columns',
+ type: 'XDSTableColumn<T>[]',
+ description:
+ 'Column definitions. If omitted, columns are auto-generated from data object keys.',
+ },
+ {
+ name: 'idKey',
+ type: '(keyof T & string) | ((item: T) => string | number)',
+ description:
+ 'Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.',
+ },
+ {
+ name: 'plugins',
+ type: 'TablePlugin<T>[]',
+ description:
+ 'Ordered array of plugins applied as a sequential transform pipeline.',
+ },
+ {
+ name: 'components',
+ type: '{Row?: ComponentType<TableRowComponentProps>; Cell?: ComponentType<TableCellComponentProps>; HeaderCell?: ComponentType<TableHeaderCellComponentProps>}',
+ description:
+ 'Component overrides for row and cell elements. When provided, these components receive xstyle from plugin transforms.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Children mode — render rows directly in the tbody instead of using data-driven rendering.',
+ },
+ {
+ name: 'tableProps',
+ type: 'HTMLAttributes<HTMLTableElement>',
+ description:
+ 'Additional HTML attributes passed directly to the root <table> element.',
+ },
+ ],
+ examples: [
+ {
+ label: 'With styled components',
+ code: `<XDSBaseTable
+ data={items}
+ columns={columns}
+ plugins={[myPlugin]}
+ components={{Row: XDSTableRow, Cell: XDSTableCell, HeaderCell: XDSTableHeaderCell}}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTableRow',
+ description:
+ '<tr> wrapper that reads XDSTableContext to apply striped, hover, and divider styles when used inside XDSTable.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Row cell elements.',
+ required: true,
+ },
+ ],
+ examples: [
+ {
+ code: `<XDSTableRow>
+ <XDSTableCell>Alice</XDSTableCell>
+ <XDSTableCell>30</XDSTableCell>
+</XDSTableRow>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTableCell',
+ description:
+ '<td> wrapper that reads XDSTableContext to apply density padding, font size, and divider borders when used inside XDSTable.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Cell content.',
+ },
+ ],
+ examples: [
+ {
+ code: `<XDSTableCell>Cell content</XDSTableCell>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTableHeaderCell',
+ description:
+ '<th> wrapper that reads XDSTableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside XDSTable.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Header cell content.',
+ },
+ ],
+ examples: [
+ {
+ code: `<XDSTableHeaderCell>Name</XDSTableHeaderCell>`,
+ },
+ ],
+ },
+ {
+ name: 'useXDSTableSelection',
+ description:
+ 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
+ props: [
+ {
+ name: 'getIsItemSelected',
+ type: '(item: T) => boolean',
+ description: 'Returns whether the given item is currently selected.',
+ required: true,
+ },
+ {
+ name: 'onSelectItem',
+ type: '(event: {item: T; isSelected: boolean}) => void',
+ description:
+ 'Called when a row checkbox is toggled. isSelected is the new desired state.',
+ required: true,
+ },
+ {
+ name: 'onSelectAll',
+ type: '(event: {isAllSelected: boolean}) => void',
+ description: 'Called when the select-all header checkbox is toggled.',
+ required: true,
+ },
+ {
+ name: 'getIsAllSelected',
+ type: '() => boolean',
+ description:
+ 'Returns whether all selectable items are currently selected.',
+ required: true,
+ },
+ {
+ name: 'getIsIndeterminate',
+ type: '() => boolean',
+ description:
+ 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
+ },
+ {
+ name: 'getIsItemSelectable',
+ type: '(item: T) => boolean',
+ description:
+ 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
+ default: '() => true',
+ },
+ {
+ name: 'getIsItemEnabled',
+ type: '(item: T) => boolean',
+ description:
+ 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
+ default: '() => true',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic selection',
+ code: `const [selectedKeys, setSelectedKeys] = useState<Set<string>>(new Set());
+
+const selectionPlugin = useXDSTableSelection<User>({
+ getIsItemSelected: item => selectedKeys.has(item.id),
+ onSelectItem: ({item, isSelected}) => {
+ const next = new Set(selectedKeys);
+ isSelected ? next.add(item.id) : next.delete(item.id);
+ setSelectedKeys(next);
+ },
+ onSelectAll: ({isAllSelected}) => {
+ setSelectedKeys(isAllSelected ? new Set(users.map(u => u.id)) : new Set());
+ },
+ getIsAllSelected: () => users.every(u => selectedKeys.has(u.id)),
+ getIsIndeterminate: () => {
+ const count = users.filter(u => selectedKeys.has(u.id)).length;
+ return count > 0 && count < users.length;
+ },
+});
+
+<XDSTable
+ data={users}
+ columns={columns}
+ plugins={{selection: selectionPlugin}}
+/>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Table/XDSBaseTable.tsx b/packages/core/src/Table/XDSBaseTable.tsx
index 37b52334a8..5b417609cd 100644
--- a/packages/core/src/Table/XDSBaseTable.tsx
+++ b/packages/core/src/Table/XDSBaseTable.tsx
@@ -5,7 +5,7 @@
* @position Core structural component; wrapped by XDSTable.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Table/README.md (component description, props)
+ * - /packages/core/src/Table/Table.doc.mjs (component description, props)
* - /packages/core/src/Table/XDSTable.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Table/index.ts (exports if types change)
*/
diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsx
index 45de4676ed..4370627995 100644
--- a/packages/core/src/Table/XDSTable.tsx
+++ b/packages/core/src/Table/XDSTable.tsx
@@ -5,7 +5,7 @@
* @position Styled wrapper; the primary table API for consumers
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Table/README.md (props table, features, usage examples)
+ * - /packages/core/src/Table/Table.doc.mjs (props table, features, usage examples)
* - /packages/core/src/Table/XDSTable.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Table/index.ts (exports if types change)
* - /apps/storybook/stories/Table.stories.tsx (storybook stories)
diff --git a/packages/core/src/Table/XDSTableCell.tsx b/packages/core/src/Table/XDSTableCell.tsx
index ed5fe8e1cd..87024041fe 100644
--- a/packages/core/src/Table/XDSTableCell.tsx
+++ b/packages/core/src/Table/XDSTableCell.tsx
@@ -5,7 +5,7 @@
* @position Sub-component; used inside XDSTable children mode
*
* SYNC: When modified, update:
- * - /packages/core/src/Table/README.md
+ * - /packages/core/src/Table/Table.doc.mjs
* - /packages/core/src/Table/index.ts
*/
diff --git a/packages/core/src/Table/XDSTableHeaderCell.tsx b/packages/core/src/Table/XDSTableHeaderCell.tsx
index 89aa558777..1fa49e9005 100644
--- a/packages/core/src/Table/XDSTableHeaderCell.tsx
+++ b/packages/core/src/Table/XDSTableHeaderCell.tsx
@@ -5,7 +5,7 @@
* @position Sub-component; used inside XDSTable for header cells
*
* SYNC: When modified, update:
- * - /packages/core/src/Table/README.md
+ * - /packages/core/src/Table/Table.doc.mjs
* - /packages/core/src/Table/index.ts
*/
diff --git a/packages/core/src/Table/XDSTableRow.tsx b/packages/core/src/Table/XDSTableRow.tsx
index 5c7dd6d2cb..709f918c46 100644
--- a/packages/core/src/Table/XDSTableRow.tsx
+++ b/packages/core/src/Table/XDSTableRow.tsx
@@ -5,7 +5,7 @@
* @position Sub-component; used inside XDSTable children mode
*
* SYNC: When modified, update:
- * - /packages/core/src/Table/README.md
+ * - /packages/core/src/Table/Table.doc.mjs
* - /packages/core/src/Table/index.ts
*/
diff --git a/packages/core/src/Table/columnUtils.ts b/packages/core/src/Table/columnUtils.ts
index bbc9845f0d..fb7140cde3 100644
--- a/packages/core/src/Table/columnUtils.ts
+++ b/packages/core/src/Table/columnUtils.ts
@@ -5,7 +5,7 @@
* @position Utility layer; consumed by XDSBaseTable.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Table/README.md (utility descriptions)
+ * - /packages/core/src/Table/Table.doc.mjs (utility descriptions)
* - /packages/core/src/Table/index.ts (exports if functions change)
*/
diff --git a/packages/core/src/Table/index.ts b/packages/core/src/Table/index.ts
index 84a940a2e3..1c9f210741 100644
--- a/packages/core/src/Table/index.ts
+++ b/packages/core/src/Table/index.ts
@@ -4,7 +4,7 @@
* @output Exports all Table components, types, and utilities
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/Table/README.md
+ * SYNC: When modified, update this header and /packages/core/src/Table/Table.doc.mjs
*/
export {XDSBaseTable} from './XDSBaseTable';
diff --git a/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsx b/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsx
index 7b4dc0ff38..102fc5c961 100644
--- a/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsx
+++ b/packages/core/src/Table/plugins/selection/useXDSTableSelection.tsx
@@ -5,7 +5,7 @@
* @position Selection plugin; consumed by XDSTable via plugins prop
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Table/README.md (selection documentation)
+ * - /packages/core/src/Table/Table.doc.mjs (selection documentation)
* - /packages/core/src/Table/index.ts (exports)
*/
diff --git a/packages/core/src/Table/types.ts b/packages/core/src/Table/types.ts
index 1077eced29..6735254325 100644
--- a/packages/core/src/Table/types.ts
+++ b/packages/core/src/Table/types.ts
@@ -5,7 +5,7 @@
* @position Type foundation; consumed by XDSBaseTable and extended by XDSTable
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Table/README.md (type descriptions)
+ * - /packages/core/src/Table/Table.doc.mjs (type descriptions)
* - /packages/core/src/Table/index.ts (exports if types change)
*/
diff --git a/packages/core/src/Text/README.md b/packages/core/src/Text/README.md
deleted file mode 100644
index 43783411ee..0000000000
--- a/packages/core/src/Text/README.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# Text
-
-Typography components for the XDS design system.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Components
-
-| File | Export | Purpose |
-| -------------------- | ------------------------- | ---------------------------------------------------------- |
-| `XDSText.tsx` | `XDSText` | Body text with semantic variants (body, supporting, label) |
-| `XDSHeading.tsx` | `XDSHeading` | Headings with level and size props |
-| `XDSFontWrapper.tsx` | `XDSFontWrapper` | Wrapper that applies typography styles to native HTML |
-| `XDSFontWrapper.tsx` | `useXDSFontWrapperStyles` | Hook for programmatic StyleX access to typography styles |
-
-## Utilities
-
-| File | Export | Purpose |
-| ------------------ | --------------- | ---------------------------------------------------------- |
-| `text.stylex.ts` | Various | StyleX styles for color, weight, display, truncation, etc. |
-| `useTruncation.ts` | `useTruncation` | Hook for detecting text overflow |
-
-## Usage Patterns
-
-### XDSText
-
-Body text with semantic variants and truncation support.
-
-```tsx
-<XDSText type="body" color="primary">Body text content.</XDSText>
-```
-
-| Prop | Type | Default | Description |
-| -------------------- | --------------------------------------- | ---------- | --------------------------------------------- |
-| `type` | `XDSTextType` | — | Semantic text type (body, supporting, label) |
-| `size` | `XDSTextSize` | — | Explicit font size override |
-| `color` | `XDSTextColor` | — | Text color (defaults vary by type) |
-| `weight` | `XDSTextWeight` | — | Font weight override |
-| `display` | `XDSTextDisplay` | `'inline'` | Display type |
-| `maxLines` | `number` | `0` | Max lines before truncation |
-| `hasTruncateTooltip` | `boolean \| LayerPlacement` | `true` | Tooltip for truncated text |
-| `wordBreak` | `XDSWordBreak` | — | Word break behavior |
-| `textWrap` | `XDSTextWrap` | — | Text wrapping behavior |
-| `hasCapsize` | `boolean` | `false` | Enable optical alignment (text-box-trim) |
-| `hasStrikethrough` | `boolean` | `false` | Strikethrough decoration |
-| `hasTabularNumbers` | `boolean` | `false` | Use tabular (monospace) numbers |
-| `as` | `'span' \| 'p' \| 'div' \| 'label'` | `'span'` | HTML element to render |
-| `xstyle` | `StyleXStyles` | — | Constrained styles for layout integration |
-| `children` | `ReactNode` | — | Text content |
-
-### XDSHeading
-
-Headings with level-based styling and optional accessibility level override.
-
-```tsx
-<XDSHeading level={1} size="2xl">Page Title</XDSHeading>
-```
-
-| Prop | Type | Default | Description |
-| -------------------- | --------------------------- | ----------- | ---------------------------------------------- |
-| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | — | Visual heading level (required) |
-| `accessibilityLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | same as `level` | ARIA level override |
-| `variant` | `'default' \| 'editorial'` | `'default'` | Visual variant (dense vs editorial scale) |
-| `color` | `XDSTextColor` | `'primary'` | Text color |
-| `display` | `XDSTextDisplay` | `'block'` | Display type |
-| `maxLines` | `number` | `0` | Max lines before truncation |
-| `hasTruncateTooltip` | `boolean \| LayerPlacement` | `true` | Tooltip for truncated text |
-| `wordBreak` | `XDSWordBreak` | — | Word break behavior |
-| `textWrap` | `XDSTextWrap` | — | Text wrapping behavior |
-| `hasCapsize` | `boolean` | `false` | Enable optical alignment |
-| `hasStrikethrough` | `boolean` | `false` | Strikethrough decoration |
-| `xstyle` | `StyleXStyles` | — | Constrained styles for layout integration |
-| `children` | `ReactNode` | — | Heading content |
-
-### XDSFontWrapper
-
-Wrapper that applies typography styles to native HTML (for user content/markdown).
-
-```tsx
-<XDSFontWrapper variant="editorial">
- <article dangerouslySetInnerHTML={{__html: markdownContent}} />
-</XDSFontWrapper>
-```
-
-| Prop | Type | Default | Description |
-| ------------- | ---------------------------- | ----------- | ------------------------------- |
-| `variant` | `'default' \| 'editorial'` | `'default'` | Heading scale variant |
-| `children` | `ReactNode` | — | Content to style |
-| `data-testid` | `string` | — | Test ID |
-
-### useXDSFontWrapperStyles
-
-Use when you want StyleX-based styling with theme tokens:
-
-```tsx
-import {useXDSFontWrapperStyles} from '@xds/core';
-import * as stylex from '@stylexjs/stylex';
-
-function Article() {
- const {headingStyles, proseStyles} = useXDSFontWrapperStyles();
-
- return (
- <article>
- <h1 {...stylex.props(headingStyles?.h1)}>Title</h1>
- <p {...stylex.props(proseStyles?.p)}>Content...</p>
- </article>
- );
-}
-```
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
new file mode 100644
index 0000000000..344277c29b
--- /dev/null
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -0,0 +1,352 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Text',
+ description:
+ 'Typography components for the XDS design system, including semantic body text, headings, and a wrapper for applying typography styles to native HTML.',
+ examples: [
+ {
+ label: 'Body text',
+ code: '<XDSText type="body">Body text content.</XDSText>',
+ },
+ {
+ label: 'Supporting text',
+ code: '<XDSText type="supporting">Helper text beneath a field.</XDSText>',
+ },
+ {
+ label: 'Heading',
+ code: '<XDSHeading level={1}>Page Title</XDSHeading>',
+ },
+ {
+ label: 'Editorial heading',
+ code: '<XDSHeading level={1} variant="editorial">Article Title</XDSHeading>',
+ },
+ {
+ label: 'Truncated text with tooltip',
+ code: '<XDSText type="body" maxLines={2}>Very long text that will be clamped after two lines and show a tooltip on hover.</XDSText>',
+ },
+ {
+ label: 'Font wrapper for native HTML',
+ code: `<XDSFontWrapper variant="editorial">
+ <article dangerouslySetInnerHTML={{__html: markdownContent}} />
+</XDSFontWrapper>`,
+ },
+ ],
+ features: [
+ 'Semantic text types (body, large, label, supporting, code) driven by theme tokens',
+ 'Headings use native h1–h6 elements with optional aria-level override for decoupled visual vs document hierarchy',
+ 'Line-clamp truncation with automatic overflow-detecting tooltip',
+ 'Optical alignment (text-box-trim / capsize) for precise vertical rhythm',
+ 'XDSFontWrapper applies typography styles to native HTML — useful for user-generated content and markdown output',
+ 'useXDSFontWrapperStyles hook for programmatic StyleX access to heading and prose styles',
+ 'Tabular number support for aligned numeric data',
+ 'All typography driven by CSS custom properties — fully themeable per-component',
+ ],
+ accessibility: [
+ 'XDSHeading renders the correct semantic h1–h6 element based on the `level` prop.',
+ 'When `accessibilityLevel` differs from `level`, `aria-level` is set so screen readers announce the correct document outline position while preserving the visual style.',
+ 'Truncated text sets a native `title` attribute as a fallback, and also lazily renders an XDSTooltip for sighted keyboard users.',
+ ],
+ components: [
+ {
+ name: 'XDSText',
+ description:
+ 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSText type="body">Body text</XDSText>',
+ },
+ {
+ label: 'All types',
+ code: `<XDSText type="body">Body</XDSText>
+<XDSText type="large">Large body</XDSText>
+<XDSText type="label">Label</XDSText>
+<XDSText type="supporting">Supporting</XDSText>
+<XDSText type="code">{'const x = 1;'}</XDSText>`,
+ },
+ {
+ label: 'Truncation',
+ code: '<XDSText type="body" maxLines={2}>Clamped to two lines with a tooltip on hover.</XDSText>',
+ },
+ {
+ label: 'Styled text',
+ code: '<XDSText type="body" color="secondary" weight="bold" hasTabularNumbers>42,000</XDSText>',
+ },
+ {
+ label: 'Block with strikethrough',
+ code: '<XDSText type="body" display="block" hasStrikethrough>Deprecated item</XDSText>',
+ },
+ ],
+ props: [
+ {
+ name: 'type',
+ type: "'body' | 'large' | 'label' | 'supporting' | 'code'",
+ description:
+ 'Semantic text type. Determines size, weight, and line-height from the theme.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Text content.',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
+ description:
+ 'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',
+ },
+ {
+ name: 'color',
+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+ description:
+ "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
+ },
+ {
+ name: 'weight',
+ type: "'normal' | 'medium' | 'semibold' | 'bold'",
+ description: 'Font weight override.',
+ },
+ {
+ name: 'display',
+ type: "'inline' | 'block'",
+ description:
+ "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
+ default: "'inline'",
+ },
+ {
+ name: 'as',
+ type: "'span' | 'p' | 'div' | 'label'",
+ description: 'HTML element to render.',
+ default: "'span'",
+ },
+ {
+ name: 'maxLines',
+ type: 'number',
+ description:
+ 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
+ default: '0',
+ },
+ {
+ name: 'hasTruncateTooltip',
+ type: 'boolean | LayerPlacement',
+ description:
+ 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',
+ default: 'true',
+ },
+ {
+ name: 'wordBreak',
+ type: "'break-word' | 'break-all'",
+ description:
+ "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+ },
+ {
+ name: 'textWrap',
+ type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
+ description: 'Text wrapping behavior.',
+ },
+ {
+ name: 'hasCapsize',
+ type: 'boolean',
+ description:
+ 'Enable optical alignment using text-box-trim. Forces block display.',
+ default: 'false',
+ },
+ {
+ name: 'hasStrikethrough',
+ type: 'boolean',
+ description: 'Apply strikethrough text decoration.',
+ default: 'false',
+ },
+ {
+ name: 'hasTabularNumbers',
+ type: 'boolean',
+ description:
+ 'Use tabular (monospace) numbers for aligned numeric data.',
+ default: 'false',
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: 'HTML id attribute.',
+ },
+ ],
+ },
+ {
+ name: 'XDSHeading',
+ description:
+ 'Semantic heading component that renders h1–h6 elements with themed styling, optional editorial scale, and line-clamp truncation.',
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSHeading level={1}>Page Title</XDSHeading>',
+ },
+ {
+ label: 'Editorial scale',
+ code: '<XDSHeading level={1} variant="editorial">Article Title</XDSHeading>',
+ },
+ {
+ label: 'Accessibility level override',
+ code: '<XDSHeading level={2} accessibilityLevel={3}>Sidebar Section</XDSHeading>',
+ },
+ {
+ label: 'Truncated heading',
+ code: '<XDSHeading level={2} maxLines={1}>Very Long Section Title That Gets Clipped</XDSHeading>',
+ },
+ {
+ label: 'Muted heading',
+ code: '<XDSHeading level={3} color="secondary">Muted Heading</XDSHeading>',
+ },
+ ],
+ props: [
+ {
+ name: 'level',
+ type: '1 | 2 | 3 | 4 | 5 | 6',
+ description:
+ 'Visual heading level. Determines both the HTML element (h1–h6) and the styling from the theme.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Heading content.',
+ required: true,
+ },
+ {
+ name: 'accessibilityLevel',
+ type: '1 | 2 | 3 | 4 | 5 | 6',
+ description:
+ 'Accessibility level override. When set and different from `level`, applies `aria-level` so the document outline differs from the visual style.',
+ },
+ {
+ name: 'variant',
+ type: "'default' | 'editorial'",
+ description:
+ "Visual variant. 'default' uses a dense scale for internal tools (h1: 20px); 'editorial' uses a larger scale for content-heavy pages (h1: 32px).",
+ default: "'default'",
+ },
+ {
+ name: 'color',
+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+ description: 'Text color.',
+ default: "'primary'",
+ },
+ {
+ name: 'display',
+ type: "'inline' | 'block'",
+ description:
+ "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
+ default: "'block'",
+ },
+ {
+ name: 'maxLines',
+ type: 'number',
+ description:
+ 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
+ default: '0',
+ },
+ {
+ name: 'hasTruncateTooltip',
+ type: 'boolean | LayerPlacement',
+ description:
+ 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',
+ default: 'true',
+ },
+ {
+ name: 'wordBreak',
+ type: "'break-word' | 'break-all'",
+ description:
+ "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+ },
+ {
+ name: 'textWrap',
+ type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
+ description: 'Text wrapping behavior.',
+ },
+ {
+ name: 'hasCapsize',
+ type: 'boolean',
+ description:
+ 'Enable optical alignment using text-box-trim. Forces block display.',
+ default: 'false',
+ },
+ {
+ name: 'hasStrikethrough',
+ type: 'boolean',
+ description: 'Apply strikethrough text decoration.',
+ default: 'false',
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: 'HTML id attribute.',
+ },
+ ],
+ },
+ {
+ name: 'XDSFontWrapper',
+ description:
+ 'Wrapper that applies XDS typography styles to native HTML elements within its scope. Useful for user-generated content, markdown output, and other scenarios where XDSText and XDSHeading cannot be used directly.',
+ examples: [
+ {
+ label: 'Default variant',
+ code: `<XDSFontWrapper>
+ <h1>Page Title</h1>
+ <p>Body text with <strong>bold</strong> and <em>italic</em>.</p>
+ <ul>
+ <li>List item 1</li>
+ <li>List item 2</li>
+ </ul>
+</XDSFontWrapper>`,
+ },
+ {
+ label: 'Editorial variant',
+ code: `<XDSFontWrapper variant="editorial">
+ <article dangerouslySetInnerHTML={{__html: markdownContent}} />
+</XDSFontWrapper>`,
+ },
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content to style with XDS typography.',
+ required: true,
+ },
+ {
+ name: 'variant',
+ type: "'default' | 'editorial'",
+ description:
+ "Heading scale variant. 'default' uses a dense scale for internal tools; 'editorial' uses a larger scale for content-heavy pages.",
+ default: "'default'",
+ },
+ ],
+ },
+ {
+ name: 'useXDSFontWrapperStyles',
+ description:
+ 'Hook that returns StyleX style objects from the current theme for headings and prose elements, for use when applying typography styles to native HTML programmatically.',
+ examples: [
+ {
+ label: 'Basic usage',
+ code: `import {useXDSFontWrapperStyles} from '@xds/core';
+import * as stylex from '@stylexjs/stylex';
+
+function Article() {
+ const {headingStyles, proseStyles} = useXDSFontWrapperStyles();
+
+ return (
+ <article>
+ <h1 {...stylex.props(headingStyles?.h1)}>Title</h1>
+ <p {...stylex.props(proseStyles?.p)}>Content...</p>
+ </article>
+ );
+}`,
+ },
+ ],
+ props: [],
+ },
+ ],
+};
diff --git a/packages/core/src/Text/XDSFontWrapper.tsx b/packages/core/src/Text/XDSFontWrapper.tsx
index d4cf469af7..aa81704412 100644
--- a/packages/core/src/Text/XDSFontWrapper.tsx
+++ b/packages/core/src/Text/XDSFontWrapper.tsx
@@ -5,7 +5,7 @@
* @position Typography component; provides base styles for wrapped content
*
* SYNC: When modified, update:
- * - /packages/core/src/Text/README.md
+ * - /packages/core/src/Text/Text.doc.mjs
* - /packages/core/src/Text/index.ts
*/
diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsx
index 431f53fc95..945c3d13b2 100644
--- a/packages/core/src/Text/XDSHeading.tsx
+++ b/packages/core/src/Text/XDSHeading.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSHeading.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Text/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Text/XDSHeading.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Text/index.ts (exports if types change)
* - /apps/storybook/stories/Text.stories.tsx (storybook stories)
diff --git a/packages/core/src/Text/XDSText.tsx b/packages/core/src/Text/XDSText.tsx
index 8a39700eba..836a2fb368 100644
--- a/packages/core/src/Text/XDSText.tsx
+++ b/packages/core/src/Text/XDSText.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSText.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Text/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Text/XDSText.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Text/index.ts (exports if types change)
* - /apps/storybook/stories/Text.stories.tsx (storybook stories)
diff --git a/packages/core/src/Text/text.stylex.ts b/packages/core/src/Text/text.stylex.ts
index 07aac939a8..e049d5149d 100644
--- a/packages/core/src/Text/text.stylex.ts
+++ b/packages/core/src/Text/text.stylex.ts
@@ -5,7 +5,7 @@
* @position Styles module; consumed by XDSText.tsx, XDSHeading.tsx
*
* SYNC: When modified, update:
- * - /packages/core/src/Text/README.md
+ * - /packages/core/src/Text/Text.doc.mjs
*/
import * as stylex from '@stylexjs/stylex';
diff --git a/packages/core/src/Text/useTruncation.ts b/packages/core/src/Text/useTruncation.ts
index 07879aa752..954ae2c887 100644
--- a/packages/core/src/Text/useTruncation.ts
+++ b/packages/core/src/Text/useTruncation.ts
@@ -5,7 +5,7 @@
* @position Hook; consumed by XDSText.tsx, XDSHeading.tsx
*
* SYNC: When modified, update:
- * - /packages/core/src/Text/README.md
+ * - /packages/core/src/Text/Text.doc.mjs
*/
'use client';
diff --git a/packages/core/src/TextArea/README.md b/packages/core/src/TextArea/README.md
deleted file mode 100644
index 20b5ad963b..0000000000
--- a/packages/core/src/TextArea/README.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# TextArea
-
-A multi-line text input component for collecting longer user input.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Label Support**: Required label for accessibility (can be visually hidden)
-- **Description**: Optional description text displayed between the label and textarea
-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator
-- **Disabled State**: Support for disabled textarea with visual styling
-- **Accessible**: Label properly associated with textarea via htmlFor/id
-- **Styled with StyleX**: Uses XDS design tokens for consistent styling
-- **Resizable**: Vertical resize enabled by default with a minimum height
-
-## Usage
-
-```tsx
-import { XDSTextArea } from '@xds/core/TextArea';
-
-// Basic textarea with label
-<XDSTextArea label="Description" value={description} onChange={setDescription} />
-
-// With placeholder
-<XDSTextArea label="Notes" value={notes} onChange={setNotes} placeholder="Enter your notes..." />
-
-// With custom rows
-<XDSTextArea label="Message" rows={5} value={message} onChange={setMessage} />
-
-// Hidden label (for screen readers only)
-<XDSTextArea label="Comments" isLabelHidden value={comments} onChange={setComments} placeholder="Add a comment..." />
-
-// With description
-<XDSTextArea label="Bio" description="Tell us about yourself" value={bio} onChange={setBio} />
-
-// Optional field
-<XDSTextArea label="Additional Notes" isOptional value={notes} onChange={setNotes} />
-
-// Required field
-<XDSTextArea label="Feedback" isRequired value={feedback} onChange={setFeedback} />
-
-// Disabled field
-<XDSTextArea label="Disabled" isDisabled value="Cannot edit this" onChange={setDisabled} />
-```
-
-## Props
-
-| Prop | Type | Required | Description |
-| --------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
-| `label` | `string` | Yes | Label text for the textarea (always rendered for accessibility) |
-| `value` | `string` | Yes | Current value of the textarea |
-| `onChange` | `(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void` | Yes | Callback fired when textarea value changes |
-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |
-| `description` | `string` | No | Description text displayed between the label and textarea |
-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |
-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |
-| `placeholder` | `string` | No | Placeholder text |
-| `rows` | `number` | No | Number of visible text rows (default: 3) |
-| `isDisabled` | `boolean` | No | Whether the textarea is disabled (default: false) |
-
-## Theming
-
-Themes can override `TextArea` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- textArea: {
- wrapper: myStyles,
- textarea: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ---------- | ------------------------ |
-| `wrapper` | Wrapper container styles |
-| `textarea` | Textarea element styles |
-
-## Files
-
-| File | Role | Purpose |
-| ---------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSTextArea.tsx` | Core | Component implementation |
-| `XDSTextArea.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Uses `useId` hook for accessible label-textarea association
-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually
-- Hidden label uses CSS technique that remains accessible to screen readers
-- Wraps `XDSField` component for label, description, and optional/required handling
-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"
-- Optional/Required text appears on the same line as the label
-- Textarea has vertical resize enabled with a minimum height of 80px
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
new file mode 100644
index 0000000000..f156d58882
--- /dev/null
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -0,0 +1,209 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TextArea',
+ description:
+ 'A multi-line text input component for collecting longer user input.',
+ features: [
+ 'Label support — required label for accessibility, can be visually hidden',
+ 'Description — optional text displayed between the label and textarea',
+ 'Optional/Required indicators — displays "Optional" or "Required" text with bullet separator',
+ 'Status variants — warning, error, and success states with colored borders and icons',
+ 'Character counter — displays current/max length when maxLength is set',
+ 'Start icon — optional icon rendered inside the leading edge of the input',
+ 'Label tooltip — optional info icon with tooltip at the end of the label',
+ 'Loading state — shows a spinner and uses optimistic updates via useOptimistic',
+ 'Async action support — onChangeAction fires after onChange inside a React transition',
+ 'Disabled state — visual opacity and cursor changes, no interaction',
+ 'Accessible — label associated via htmlFor/id, aria-describedby, aria-required, aria-invalid, aria-busy',
+ 'Resizable — vertical resize enabled by default with a minimum height of 80px',
+ 'Spell check — browser spell checking enabled by default, configurable',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSTextArea label="Description" value={description} onChange={setDescription} />',
+ },
+ {
+ label: 'With placeholder and custom rows',
+ code: '<XDSTextArea label="Notes" rows={5} value={notes} onChange={setNotes} placeholder="Enter your notes..." />',
+ },
+ {
+ label: 'Hidden label',
+ code: '<XDSTextArea label="Comments" isLabelHidden value={comments} onChange={setComments} placeholder="Add a comment..." />',
+ },
+ {
+ label: 'With description and optional indicator',
+ code: '<XDSTextArea label="Bio" description="Tell us about yourself" isOptional value={bio} onChange={setBio} />',
+ },
+ {
+ label: 'Error status with message',
+ code: `<XDSTextArea
+ label="Feedback"
+ isRequired
+ value={feedback}
+ onChange={setFeedback}
+ status={{type: 'error', message: 'Feedback is required'}}
+/>`,
+ },
+ {
+ label: 'With character counter',
+ code: '<XDSTextArea label="Summary" maxLength={280} value={summary} onChange={setSummary} />',
+ },
+ {
+ label: 'Disabled',
+ code: '<XDSTextArea label="Read-only notes" isDisabled value="Cannot edit this" onChange={() => {}} />',
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the textarea — always rendered for accessibility.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Current value of the textarea.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void',
+ description: 'Callback fired when the textarea value changes.',
+ },
+ {
+ name: 'onChangeAction',
+ type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>',
+ description:
+ 'Async action fired after onChange inside a React transition. Enables optimistic updates via useOptimistic.',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Visually hides the label while keeping it accessible to screen readers.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed between the label and textarea.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Displays an "Optional" indicator next to the label. Mutually exclusive with isRequired.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description:
+ 'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the textarea, preventing interaction.',
+ default: 'false',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description:
+ 'Puts the textarea in a loading state, showing a spinner inside the input.',
+ default: 'false',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown when the textarea is empty.',
+ },
+ {
+ name: 'rows',
+ type: 'number',
+ description: 'Number of visible text rows.',
+ default: '3',
+ },
+ {
+ name: 'maxLength',
+ type: 'number',
+ description:
+ 'Maximum number of characters allowed. When set, a character counter (current/max) is displayed below the textarea.',
+ },
+ {
+ name: 'status',
+ type: "{ type: 'warning' | 'error' | 'success'; message?: string }",
+ description:
+ 'Status indicator that applies a colored border and icon. An optional message is displayed in a floating box below the textarea.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description:
+ 'Tooltip text displayed in an info icon at the end of the label.',
+ },
+ {
+ name: 'startIcon',
+ type: 'XDSIconType',
+ description:
+ 'Icon component rendered inside the leading edge of the textarea wrapper.',
+ },
+ {
+ name: 'hasSpellCheck',
+ type: 'boolean',
+ description: 'Enables or disables browser spell checking.',
+ default: 'true',
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Automatically focuses the textarea on mount.',
+ default: 'false',
+ },
+ {
+ name: 'onPaste',
+ type: '(e: ClipboardEvent<HTMLTextAreaElement>) => void',
+ description: 'Callback fired when content is pasted into the textarea.',
+ },
+ {
+ name: 'htmlName',
+ type: 'string',
+ description:
+ 'HTML name attribute for the textarea element, useful for form submissions.',
+ },
+ ],
+ theming: {
+ componentKey: 'textArea',
+ surfaces: [
+ {
+ name: 'wrapper',
+ description: 'Outer wrapper div that contains the textarea and icons.',
+ },
+ {
+ name: 'textarea',
+ description: 'The textarea element itself.',
+ },
+ ],
+ },
+ accessibility: [
+ 'Label is always rendered in the DOM; use isLabelHidden to hide it visually while keeping it accessible.',
+ 'The textarea id is generated via useId and linked to its label via htmlFor, ensuring correct label association.',
+ 'aria-describedby is set to the description and/or status message IDs when those elements are present.',
+ 'aria-required="true" is set when isRequired is true.',
+ 'aria-invalid="true" is set when status.type is "error".',
+ 'aria-busy is set while an optimistic update or loading state is active.',
+ ],
+ notes: [
+ 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" takes precedence.',
+ 'The component uses useOptimistic for instant UI feedback when onChangeAction returns a Promise.',
+ 'Textarea has vertical resize enabled via CSS with a minimum height of 80px.',
+ 'Wraps XDSField for consistent label, description, and status message layout.',
+ 'The character counter text turns red when value.length exceeds maxLength.',
+ ],
+};
diff --git a/packages/core/src/TextArea/XDSTextArea.tsx b/packages/core/src/TextArea/XDSTextArea.tsx
index 39e08b68ab..a7d7d96fe5 100644
--- a/packages/core/src/TextArea/XDSTextArea.tsx
+++ b/packages/core/src/TextArea/XDSTextArea.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSTextArea.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TextArea/README.md (props table, features, implementation notes)
+ * - /packages/core/src/TextArea/TextArea.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/TextArea/XDSTextArea.test.tsx (tests for new/changed behavior)
* - /packages/core/src/TextArea/index.ts (exports if types change)
* - /apps/storybook/stories/TextArea.stories.tsx (storybook stories)
diff --git a/packages/core/src/TextArea/index.ts b/packages/core/src/TextArea/index.ts
index 43b395cfad..49781c7c2e 100644
--- a/packages/core/src/TextArea/index.ts
+++ b/packages/core/src/TextArea/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSTextArea, XDSTextAreaProps, XDSTextAreaStatus, XDSTextAreaStatusType
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/TextArea/README.md
+ * SYNC: When modified, update this header and /packages/core/src/TextArea/TextArea.doc.mjs
*/
export {XDSTextArea} from './XDSTextArea';
diff --git a/packages/core/src/TextInput/README.md b/packages/core/src/TextInput/README.md
deleted file mode 100644
index f1b96791b4..0000000000
--- a/packages/core/src/TextInput/README.md
+++ /dev/null
@@ -1,103 +0,0 @@
-# TextInput
-
-A text input component for collecting user text input.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Label Support**: Required label for accessibility (can be visually hidden)
-- **Description**: Optional description text displayed between the label and input
-- **Optional/Required Indicators**: Display "Optional" or "Required" text with bullet separator
-- **Label Tooltip**: Optional info icon with tooltip at end of label
-- **Accessible**: Label properly associated with input via htmlFor/id
-- **Styled with StyleX**: Uses XDS design tokens for consistent styling
-
-## Usage
-
-```tsx
-import { XDSTextInput } from '@xds/core/TextInput';
-
-// Basic input with label
-<XDSTextInput label="Name" value={name} onChange={setName} />
-
-// With placeholder
-<XDSTextInput label="Email" value={email} onChange={setEmail} placeholder="[email protected]" />
-
-// Hidden label (for screen readers only)
-<XDSTextInput label="Search" isLabelHidden value={query} onChange={setQuery} placeholder="Search..." />
-
-// With description
-<XDSTextInput label="Email" description="We'll never share your email" value={email} onChange={setEmail} />
-
-// Optional field
-<XDSTextInput label="Nickname" isOptional value={nickname} onChange={setNickname} />
-
-// Required field
-<XDSTextInput label="Username" isRequired value={username} onChange={setUsername} />
-
-// With validation status (error, warning, or success)
-<XDSTextInput
- label="Email"
- value={email}
- onChange={setEmail}
- status={{ type: 'error', message: 'Invalid email address' }}
-/>
-```
-
-## Props
-
-| Prop | Type | Required | Description |
-| --------------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
-| `label` | `string` | Yes | Label text for the input (always rendered for accessibility) |
-| `value` | `string` | Yes | Current value of the input |
-| `onChange` | `(value: string, e: ChangeEvent<HTMLInputElement>) => void` | Yes | Callback fired when input value changes |
-| `size` | `'sm' \| 'md' \| 'lg'` | No | Size variant (default: `'md'`) |
-| `isLabelHidden` | `boolean` | No | Visually hide the label (still accessible to screen readers) |
-| `description` | `string` | No | Description text displayed between the label and input |
-| `isOptional` | `boolean` | No | Whether the field is optional (mutually exclusive with isRequired) |
-| `isRequired` | `boolean` | No | Whether the field is required (mutually exclusive with isOptional) |
-| `placeholder` | `string` | No | Placeholder text |
-| `labelTooltip` | `string` | No | Tooltip text to display in an info icon at the end of the label |
-| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | No | Validation status with optional message (sets aria-invalid for error) |
-
-## Theming
-
-Themes can override `TextInput` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- textInput: {
- wrapper: myStyles,
- input: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| --------- | ------------------------ |
-| `wrapper` | Wrapper container styles |
-| `input` | Input element styles |
-
-## Files
-
-| File | Role | Purpose |
-| ----------------------- | ----- | --------------------------- |
-| `index.ts` | Entry | Exports component and types |
-| `XDSTextInput.tsx` | Core | Component implementation |
-| `XDSTextInput.test.tsx` | Test | Unit tests |
-
-## Implementation Notes
-
-- Uses `useId` hook for accessible label-input association
-- Label is always rendered for accessibility; use `isLabelHidden` to hide visually
-- Hidden label uses CSS technique that remains accessible to screen readers
-- Wraps `XDSField` component for label, description, and optional/required handling
-- `isOptional` and `isRequired` are mutually exclusive; setting both will show "Optional"
-- Optional/Required text appears on the same line as the label
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
new file mode 100644
index 0000000000..8b223c6c5d
--- /dev/null
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -0,0 +1,204 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TextInput',
+ description:
+ 'A text input component for collecting user text input, with label, description, validation status, and optional/required indicators.',
+ features: [
+ 'Label support — required label for accessibility (can be visually hidden)',
+ 'Description — optional text displayed between the label and input',
+ 'Optional/Required indicators — "Optional" or "Required" text with bullet separator',
+ 'Label tooltip — optional info icon with tooltip at the end of the label',
+ 'Validation status — error, warning, and success states with colored borders and icons',
+ 'Start icon — optional icon displayed at the start of the input',
+ 'Loading state — shows a spinner and sets aria-busy while an async action is pending',
+ 'Disabled state — visually dims the input and prevents interaction',
+ 'Accessible — label is always associated with the input via htmlFor/id; sets aria-invalid, aria-required, aria-busy, and aria-describedby as appropriate',
+ 'Styled with StyleX — uses XDS design tokens for consistent styling',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSTextInput label="Name" value={name} onChange={setName} />',
+ },
+ {
+ label: 'With placeholder',
+ code: '<XDSTextInput label="Email" value={email} onChange={setEmail} placeholder="[email protected]" />',
+ },
+ {
+ label: 'Hidden label',
+ code: '<XDSTextInput label="Search" isLabelHidden value={query} onChange={setQuery} placeholder="Search..." />',
+ },
+ {
+ label: 'With description',
+ code: `<XDSTextInput
+ label="Email"
+ description="We'll never share your email"
+ value={email}
+ onChange={setEmail}
+/>`,
+ },
+ {
+ label: 'Optional and required',
+ code: `<XDSTextInput label="Nickname" isOptional value={nickname} onChange={setNickname} />
+<XDSTextInput label="Username" isRequired value={username} onChange={setUsername} />`,
+ },
+ {
+ label: 'Validation status',
+ code: `<XDSTextInput
+ label="Email"
+ value={email}
+ onChange={setEmail}
+ status={{type: 'error', message: 'Invalid email address'}}
+/>`,
+ },
+ {
+ label: 'With start icon',
+ code: `<XDSTextInput
+ label="Search"
+ value={query}
+ onChange={setQuery}
+ startIcon={MagnifyingGlassIcon}
+ placeholder="Search..."
+/>`,
+ },
+ {
+ label: 'Async action with loading state',
+ code: `<XDSTextInput
+ label="Username"
+ value={username}
+ onChange={setUsername}
+ onChangeAction={async (value) => {
+ await checkAvailability(value);
+ }}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Label text for the input — always rendered for accessibility.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Current value of the input.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string, e: ChangeEvent<HTMLInputElement>) => void',
+ description: 'Callback fired when the input value changes.',
+ },
+ {
+ name: 'onChangeAction',
+ type: '(value: string, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',
+ description:
+ 'Async action fired after onChange (if not prevented). Triggers optimistic update and shows a loading spinner while pending.',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant of the input.',
+ default: "'md'",
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Visually hides the label while keeping it accessible to screen readers.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed between the label and input.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Displays an "Optional" indicator next to the label. Mutually exclusive with isRequired.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description:
+ 'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description:
+ 'Disables the input, preventing interaction and dimming the element.',
+ default: 'false',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description:
+ 'Puts the input in a loading state, showing a spinner and setting aria-busy.',
+ default: 'false',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown when the input is empty.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description:
+ 'Tooltip text displayed in an info icon at the end of the label.',
+ },
+ {
+ name: 'startIcon',
+ type: 'XDSIconType',
+ description:
+ 'SVG icon component displayed at the start of the input (e.g. from heroicons or lucide).',
+ },
+ {
+ name: 'status',
+ type: "{type: 'error' | 'warning' | 'success', message?: string}",
+ description:
+ 'Validation status — applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid.',
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Automatically focuses the input on mount.',
+ default: 'false',
+ },
+ {
+ name: 'htmlName',
+ type: 'string',
+ description:
+ 'The HTML name attribute for the input, useful for form submissions.',
+ },
+ ],
+ theming: {
+ componentKey: 'textInput',
+ surfaces: [
+ {name: 'wrapper', description: 'Wrapper container element'},
+ {name: 'input', description: 'Input element'},
+ ],
+ },
+ accessibility: [
+ 'Label is always rendered and associated with the input via htmlFor/id (using useId). Use isLabelHidden to hide it visually while keeping it accessible to screen readers.',
+ 'aria-describedby is set automatically when description or a status message is present.',
+ 'aria-invalid="true" is set when status.type is "error".',
+ 'aria-required="true" is set when isRequired is true.',
+ 'aria-busy is set while an optimistic update or isLoading is active.',
+ ],
+ notes: [
+ 'isOptional and isRequired are mutually exclusive — if both are set, "Optional" is shown.',
+ 'onChangeAction fires after onChange inside a React transition, enabling useOptimistic for an instant UI update while the async work completes.',
+ 'The component wraps XDSField for label, description, and optional/required rendering.',
+ 'The size prop supports "sm", "md", and "lg".',
+ ],
+};
diff --git a/packages/core/src/TextInput/XDSTextInput.tsx b/packages/core/src/TextInput/XDSTextInput.tsx
index 694cb42e82..a2aa8471f2 100644
--- a/packages/core/src/TextInput/XDSTextInput.tsx
+++ b/packages/core/src/TextInput/XDSTextInput.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSTextInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TextInput/README.md (props table, features, implementation notes)
+ * - /packages/core/src/TextInput/TextInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/TextInput/XDSTextInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/TextInput/index.ts (exports if types change)
* - /apps/storybook/stories/TextInput.stories.tsx (storybook stories)
diff --git a/packages/core/src/TextInput/index.ts b/packages/core/src/TextInput/index.ts
index e83eabd27a..dd6c6e1a12 100644
--- a/packages/core/src/TextInput/index.ts
+++ b/packages/core/src/TextInput/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSTextInput, XDSTextInputProps, XDSTextInputSize, XDSTextInputStatus, XDSTextInputStatusType
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/TextInput/README.md
+ * SYNC: When modified, update this header and /packages/core/src/TextInput/TextInput.doc.mjs
*/
export {XDSTextInput} from './XDSTextInput';
diff --git a/packages/core/src/TimeInput/README.md b/packages/core/src/TimeInput/README.md
deleted file mode 100644
index 0c1dea3240..0000000000
--- a/packages/core/src/TimeInput/README.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# XDSTimeInput
-
-Time input with text parsing and keyboard navigation.
-
-## Import
-
-```tsx
-import {XDSTimeInput} from '@xds/core/TimeInput';
-```
-
-## Usage
-
-```tsx
-// Basic usage
-<XDSTimeInput
- label="Start time"
- value={time}
- onChange={setTime}
-/>
-
-// 24-hour format with clear button
-<XDSTimeInput
- label="Meeting time"
- value={time}
- onChange={setTime}
- hourFormat="24h"
- hasClear
-/>
-
-// With min/max constraints
-<XDSTimeInput
- label="Business hours"
- value={time}
- onChange={setTime}
- min="09:00"
- max="17:00"
-/>
-
-// With seconds and validation
-<XDSTimeInput
- label="Precise time"
- value={time}
- onChange={setTime}
- hasSeconds
- status={{ type: 'error', message: 'Invalid time' }}
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------- | ------------------------------------------------- | ----------------- | ---------------------------------------------- |
-| `label` | `string` | — | Label text (required for accessibility) |
-| `isLabelHidden` | `boolean` | `false` | Visually hide label |
-| `description` | `string` | — | Description text below label |
-| `isOptional` | `boolean` | `false` | Show "(optional)" indicator |
-| `isRequired` | `boolean` | `false` | Mark field as required |
-| `isDisabled` | `boolean` | `false` | Disable the input |
-| `value` | `ISOTimeString` | — | Selected time (HH:MM or HH:MM:SS) |
-| `onChange` | `(value: ISOTimeString \| undefined) => void` | — | Callback fired when time changes |
-| `min` | `ISOTimeString` | — | Minimum selectable time |
-| `max` | `ISOTimeString` | — | Maximum selectable time |
-| `hasSeconds` | `boolean` | `false` | Include seconds in the time input |
-| `hasClear` | `boolean` | `false` | Show clear button when value is set |
-| `hourFormat` | `'12h' \| '24h'` | `'12h'` | Hour display format |
-| `increment` | `number` | `1` | Increment in minutes for arrow keys |
-| `placeholder` | `string` | `"Select a time"` | Placeholder text |
-| `size` | `'sm' \| 'md'` | `'md'` | Input size |
-| `status` | `XDSInputStatus` | — | Status indicator (error/warning/success) |
-
-## Theming
-
-Themes can override `TimeInput` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- timeInput: {
- wrapper: myStyles,
- input: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| --------- | ------------------------- |
-| `wrapper` | Input wrapper styles |
-| `input` | Text input element styles |
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
new file mode 100644
index 0000000000..b793a1b19f
--- /dev/null
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -0,0 +1,213 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TimeInput',
+ description:
+ 'Time input with free-text entry, text parsing, and arrow-key navigation.',
+ features: [
+ 'Accepts free-text time entry and parses common formats (e.g. "2:30 PM", "14:30")',
+ 'Supports 12-hour and 24-hour display formats',
+ 'Arrow-up / arrow-down adjust the time by a configurable minute increment',
+ 'Optional seconds display via hasSeconds',
+ 'Optional clear button via hasClear',
+ 'Min / max range constraints reject out-of-range values',
+ 'Async action support via onChangeAction with optimistic UI and loading spinner',
+ 'Accessible — label, description, and status message are wired to aria-describedby; aria-required and aria-invalid reflect field state',
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSTimeInput
+ label="Start time"
+ value={time}
+ onChange={setTime}
+/>`,
+ },
+ {
+ label: '24-hour format with clear button',
+ code: `<XDSTimeInput
+ label="Meeting time"
+ value={time}
+ onChange={setTime}
+ hourFormat="24h"
+ hasClear
+/>`,
+ },
+ {
+ label: 'Min / max constraints',
+ code: `<XDSTimeInput
+ label="Business hours"
+ value={time}
+ onChange={setTime}
+ min="09:00"
+ max="17:00"
+/>`,
+ },
+ {
+ label: 'With seconds and error status',
+ code: `<XDSTimeInput
+ label="Precise time"
+ value={time}
+ onChange={setTime}
+ hasSeconds
+ status={{type: 'error', message: 'Invalid time'}}
+/>`,
+ },
+ {
+ label: 'Async action with optimistic update',
+ code: `<XDSTimeInput
+ label="Scheduled time"
+ value={time}
+ onChange={setTime}
+ onChangeAction={async (value) => {
+ await saveTime(value);
+ }}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for the input (required for accessibility).',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Visually hides the label while keeping it accessible to screen readers.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed between the label and input.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description:
+ 'Shows an "(optional)" indicator next to the label. Mutually exclusive with isRequired.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description:
+ 'Marks the field as required and sets aria-required. Mutually exclusive with isOptional.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the input and suppresses interactions.',
+ default: 'false',
+ },
+ {
+ name: 'value',
+ type: 'ISOTimeString',
+ description: 'Controlled time value in ISO format (HH:MM or HH:MM:SS).',
+ },
+ {
+ name: 'onChange',
+ type: '(value: ISOTimeString | undefined) => void',
+ description:
+ 'Callback fired when the time changes. Receives undefined when the input is cleared.',
+ },
+ {
+ name: 'onChangeAction',
+ type: '(value: ISOTimeString | undefined) => void | Promise<void>',
+ description:
+ 'Async action fired after onChange. Wrapped in a React transition to provide optimistic UI; triggers the loading spinner while pending.',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'Puts the input into a loading state, displaying a spinner.',
+ default: 'false',
+ },
+ {
+ name: 'min',
+ type: 'ISOTimeString',
+ description:
+ 'Minimum selectable time in ISO format. Values outside the range are rejected.',
+ },
+ {
+ name: 'max',
+ type: 'ISOTimeString',
+ description:
+ 'Maximum selectable time in ISO format. Values outside the range are rejected.',
+ },
+ {
+ name: 'hasSeconds',
+ type: 'boolean',
+ description: 'Includes seconds in the time display and parsing.',
+ default: 'false',
+ },
+ {
+ name: 'hasClear',
+ type: 'boolean',
+ description:
+ 'Shows a clear button when a value is set and the input is not disabled.',
+ default: 'false',
+ },
+ {
+ name: 'hourFormat',
+ type: "'12h' | '24h'",
+ description:
+ "Controls the display format. '12h' shows AM/PM (e.g. '2:30 PM'); '24h' uses 24-hour notation (e.g. '14:30').",
+ default: "'12h'",
+ },
+ {
+ name: 'increment',
+ type: 'number',
+ description:
+ 'Number of minutes to add or subtract when the user presses the up or down arrow key.',
+ default: '1',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description:
+ 'Placeholder text shown when no time is selected. When the input is focused and empty, a format hint overrides this text.',
+ default: "'Select a time'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Controls the height of the input element.',
+ default: "'md'",
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description:
+ 'Status indicator that colors the border and displays an icon. When a message is provided it is rendered below the input.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description:
+ 'Tooltip text rendered as an info icon at the end of the label row.',
+ },
+ ],
+ theming: {
+ componentKey: 'timeInput',
+ surfaces: [
+ {name: 'wrapper', description: 'Outer input wrapper div'},
+ {name: 'input', description: 'Text input element'},
+ ],
+ },
+ accessibility: [
+ 'The visible label is associated with the input via htmlFor / id.',
+ 'isLabelHidden visually hides the label while keeping it in the accessibility tree.',
+ 'description and status.message are linked to the input via aria-describedby.',
+ 'aria-required is set when isRequired is true.',
+ 'aria-invalid is set when status.type is "error".',
+ 'aria-busy reflects the loading / optimistic-pending state.',
+ 'The clear button has an explicit aria-label of "Clear time".',
+ ],
+ keyboard:
+ 'ArrowUp / ArrowDown adjust the current time by the configured increment in minutes. Typing a time string in common formats (e.g. "2:30 PM", "14:30") is parsed on blur. Pressing the clear button returns focus to the input.',
+};
diff --git a/packages/core/src/TimeInput/XDSTimeInput.tsx b/packages/core/src/TimeInput/XDSTimeInput.tsx
index 81be6152cf..c0c0250bfd 100644
--- a/packages/core/src/TimeInput/XDSTimeInput.tsx
+++ b/packages/core/src/TimeInput/XDSTimeInput.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSTimeInput.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TimeInput/README.md (props table, features, implementation notes)
+ * - /packages/core/src/TimeInput/TimeInput.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/TimeInput/XDSTimeInput.test.tsx (tests for new/changed behavior)
* - /packages/core/src/TimeInput/index.ts (exports if types change)
* - /apps/storybook/stories/TimeInput.stories.tsx (storybook stories)
diff --git a/packages/core/src/TimeInput/index.ts b/packages/core/src/TimeInput/index.ts
index 199efc953b..2912e80261 100644
--- a/packages/core/src/TimeInput/index.ts
+++ b/packages/core/src/TimeInput/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSTimeInput and related types
* @position Component entry point; re-exported by /packages/core/src/index.ts
*
- * SYNC: When modified, update this header and /packages/core/src/TimeInput/README.md
+ * SYNC: When modified, update this header and /packages/core/src/TimeInput/TimeInput.doc.mjs
*/
export {XDSTimeInput} from './XDSTimeInput';
diff --git a/packages/core/src/Token/README.md b/packages/core/src/Token/README.md
deleted file mode 100644
index dac65ee28d..0000000000
--- a/packages/core/src/Token/README.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# Token
-
-A chip/tag component for displaying entities inline. Renders as a `<span>` by default, `<button>` when `onClick` is provided, or `<a>` when `href` is provided.
-
-Long labels are automatically truncated with an ellipsis. When `onClick` is provided, the focus outline wraps the entire token (not just the label) via `:focus-within` on the container.
-
-## Exports
-
-| Export | Type | Description |
-| --------------- | --------- | -------------------- |
-| `XDSToken` | Component | Main token component |
-| `XDSTokenProps` | Type | Props interface |
-| `XDSTokenColor` | Type | Color union type |
-
-## Props
-
-| Prop | Type | Default | Description |
-| --------------- | --------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------- |
-| `label` | `string` | — | Text label (required) |
-| `color` | `'default' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'cyan' \| 'blue' \| 'purple' \| 'pink' \| 'gray'` | `'default'` | Color variant |
-| `icon` | `ReactNode` | — | Optional leading icon |
-| `isDisabled` | `boolean` | `false` | Whether the token is disabled |
-| `onRemove` | `(e: MouseEvent \| KeyboardEvent) => void` | — | Remove handler; shows X button when provided |
-| `onClick` | `(e: MouseEvent) => void` | — | Click handler; renders as `<button>` |
-| `href` | `string` | — | Link URL; renders as `<a>` |
-| `description` | `string` | — | Accessible description |
-| `endContent` | `ReactNode` | — | Content after the label |
-| `isLabelHidden` | `boolean` | `false` | Visually hide label (still accessible) |
-| `xstyle` | `StyleXStyles` | — | Additional StyleX styles |
-| `data-testid` | `string` | — | Test ID for testing frameworks |
-
-## Usage
-
-```tsx
-import {XDSToken} from '@xds/core/Token';
-
-// Basic
-<XDSToken label="Tag" />
-
-// Colored
-<XDSToken label="Status" color="green" />
-
-// Removable
-<XDSToken label="Filter" onRemove={(e) => handleRemove(e)} />
-
-// Clickable
-<XDSToken label="Category" onClick={() => navigate('/category')} />
-
-// As link
-<XDSToken label="Profile" href="/user/123" />
-
-// With icon
-<XDSToken label="User" icon={<UserIcon />} />
-```
-
-## Files
-
-| File | Purpose |
-| ------------------- | ------------------------ |
-| `XDSToken.tsx` | Component implementation |
-| `XDSToken.test.tsx` | Unit tests |
-| `index.ts` | Barrel exports |
diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjs
new file mode 100644
index 0000000000..a2bb01c335
--- /dev/null
+++ b/packages/core/src/Token/Token.doc.mjs
@@ -0,0 +1,114 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Token',
+ description:
+ 'A chip/tag component for displaying entities inline. Renders as a <span> by default, <a> when href is provided, or a <span> with an invisible <button> inside when onClick is provided.',
+ features: [
+ 'Polymorphic — renders as <span>, <a>, or interactive <span>+<button> based on props',
+ 'Invisible button pattern for onClick preserves real button semantics while allowing focus-within outline on the full token',
+ 'Remove button with expanded 14px hit-area tap target via ::after pseudo-element',
+ 'Eleven color variants including a neutral default',
+ 'Leading icon and trailing endContent slots',
+ 'Label can be visually hidden while remaining accessible to screen readers',
+ 'Disabled state reduces opacity and blocks pointer events',
+ ],
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Text label displayed inside the token.',
+ required: true,
+ },
+ {
+ name: 'color',
+ type: "'default' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'cyan' | 'blue' | 'purple' | 'pink' | 'gray'",
+ description: 'Color variant of the token.',
+ default: "'default'",
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Optional icon rendered before the label.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description:
+ 'Whether the token is disabled; reduces opacity and blocks interactions.',
+ default: 'false',
+ },
+ {
+ name: 'onRemove',
+ type: '(e: React.MouseEvent) => void',
+ description:
+ 'Callback fired when the remove button is clicked. When provided, an X button is rendered inside the token.',
+ },
+ {
+ name: 'onClick',
+ type: '(e: React.MouseEvent) => void',
+ description:
+ 'Click handler. When provided, the token renders as a <span> container with an invisible <button> inside for accessibility.',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description:
+ 'Link URL. When provided, the token renders as an <a> element.',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description:
+ 'Accessible description applied via aria-description on the root element.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description:
+ 'Content rendered after the label and before the remove button.',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description:
+ 'Visually hides the label using a screen-reader-only clip technique; the label remains accessible.',
+ default: 'false',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: '<XDSToken label="Tag" />',
+ },
+ {
+ label: 'Colored',
+ code: '<XDSToken label="Status" color="green" />',
+ },
+ {
+ label: 'Removable',
+ code: '<XDSToken label="Filter" onRemove={(e) => handleRemove(e)} />',
+ },
+ {
+ label: 'Clickable',
+ code: '<XDSToken label="Category" onClick={() => navigate(\'/category\')} />',
+ },
+ {
+ label: 'As link',
+ code: '<XDSToken label="Profile" href="/user/123" />',
+ },
+ {
+ label: 'With icon and hidden label',
+ code: '<XDSToken label="User" icon={<UserIcon />} isLabelHidden />',
+ },
+ ],
+ accessibility: [
+ 'When isLabelHidden is true, the label is clipped visually but exposed via aria-label on the root element so screen readers still announce it.',
+ 'The description prop maps to aria-description on the root element for supplementary context.',
+ 'When onClick is provided, the clickable content is wrapped in a real <button> so keyboard users can activate it with Enter or Space.',
+ 'The remove button has an automatic aria-label of "Remove <label>" and an expanded touch target via a ::after pseudo-element.',
+ 'When href is provided, aria-disabled is set on the <a> element when isDisabled is true.',
+ ],
+ keyboard:
+ 'Tab focuses the token (or its inner button when onClick is used). Enter/Space activate a clickable token or the remove button. Remove button is reachable as a separate Tab stop.',
+};
diff --git a/packages/core/src/Token/XDSToken.test.tsx b/packages/core/src/Token/XDSToken.test.tsx
index 913215ceb8..705c9149fb 100644
--- a/packages/core/src/Token/XDSToken.test.tsx
+++ b/packages/core/src/Token/XDSToken.test.tsx
@@ -328,7 +328,7 @@ describe('XDSToken text overflow', () => {
});
it('label element has overflow styles when onClick is provided', () => {
- const {container} = render(
+ const {container: _container} = render(
<XDSToken label="A very long clickable label" onClick={() => {}} />,
);
// In onClick mode, the label is inside the invisible button
diff --git a/packages/core/src/Token/XDSToken.tsx b/packages/core/src/Token/XDSToken.tsx
index e0302f2922..8aa4b9271e 100644
--- a/packages/core/src/Token/XDSToken.tsx
+++ b/packages/core/src/Token/XDSToken.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts, tested by XDSToken.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Token/README.md (props table, features, implementation notes)
+ * - /packages/core/src/Token/Token.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Token/XDSToken.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Token/index.ts (exports if types change)
* - /apps/storybook/stories/Token.stories.tsx (storybook stories)
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
new file mode 100644
index 0000000000..e74d222467
--- /dev/null
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -0,0 +1,212 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Tokenizer',
+ description:
+ 'Multi-select typeahead with token chips for selected items. Composes XDSBaseTypeahead for search and XDSToken for chips.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the input.',
+ required: true,
+ },
+ {
+ name: 'searchSource',
+ type: 'XDSSearchSource<T>',
+ description:
+ 'Data source providing search and bootstrap methods for populating the dropdown.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'T[]',
+ description: 'Array of currently selected items.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(items: T[], change: XDSTokenizerChange<T>) => void',
+ description:
+ "Called when selection changes. The change argument includes the affected item and type ('add' | 'remove' | 'reorder').",
+ required: true,
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description:
+ 'Input placeholder text. Only shown when no tokens are selected.',
+ },
+ {
+ name: 'maxEntries',
+ type: 'number',
+ description:
+ 'Maximum number of selections allowed. Input is hidden when the limit is reached.',
+ },
+ {
+ name: 'hasClear',
+ type: 'boolean',
+ description: 'Show a clear-all button for bulk removal of all tokens.',
+ default: 'false',
+ },
+ {
+ name: 'renderToken',
+ type: '(item: T, onRemove: () => void) => ReactNode',
+ description:
+ 'Custom render function for selected tokens. Default renders XDSToken with label and onRemove.',
+ },
+ {
+ name: 'renderItem',
+ type: '(item: T) => ReactNode',
+ description:
+ 'Custom render function for dropdown items. Default renders XDSTypeaheadItem.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the input and all token interactions.',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description:
+ 'Validation status object with type and message for error/warning/success states.',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hides the label while keeping it accessible.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed below the label.',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Marks the field as required.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Shows an optional indicator on the label.',
+ default: 'false',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text shown on the label.',
+ },
+ {
+ name: 'hasEntriesOnFocus',
+ type: 'boolean',
+ description: 'Show bootstrap results on focus before typing.',
+ default: 'false',
+ },
+ {
+ name: 'maxMenuItems',
+ type: 'number',
+ description: 'Maximum number of dropdown items to display.',
+ default: '10',
+ },
+ {
+ name: 'emptySearchResultsText',
+ type: 'string',
+ description: 'Text shown when search returns no results.',
+ default: "'No results found'",
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Auto-focus the input on mount.',
+ default: 'false',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Input and token size.',
+ default: "'md'",
+ },
+ {
+ name: 'debounceMs',
+ type: 'number',
+ description:
+ 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+ default: '150',
+ },
+ {
+ name: 'onChangeQuery',
+ type: '(query: string) => void',
+ description: 'Callback fired when the search query text changes.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic multi-select',
+ code: `const source = {
+ search: query => users.filter(u => u.label.includes(query)),
+ bootstrap: () => users.slice(0, 5),
+};
+
+<XDSTokenizer
+ label="Team Members"
+ searchSource={source}
+ value={selected}
+ onChange={(items, change) => {
+ setSelected(items);
+ }}
+ placeholder="Search people..."
+/>`,
+ },
+ {
+ label: 'With max entries and clear all',
+ code: `<XDSTokenizer
+ label="Tags"
+ searchSource={tagSource}
+ value={tags}
+ onChange={(items) => setTags(items)}
+ maxEntries={5}
+ hasClear
+ placeholder="Add up to 5 tags..."
+/>`,
+ },
+ {
+ label: 'Custom token rendering',
+ code: `<XDSTokenizer
+ label="Tags"
+ searchSource={tagSource}
+ value={tags}
+ onChange={(items) => setTags(items)}
+ renderToken={(item, onRemove) => (
+ <XDSToken
+ label={item.label}
+ color={item.auxiliaryData.color}
+ onRemove={onRemove}
+ />
+ )}
+ maxEntries={10}
+/>`,
+ },
+ ],
+ features: [
+ 'Token chips for each selected item with remove buttons',
+ 'Filtered search that automatically excludes already-selected items',
+ 'Max entries to limit number of selections — input hides when limit is reached',
+ 'Clear all button for bulk removal of all tokens',
+ 'Custom token and item rendering via renderToken and renderItem',
+ 'Backspace on empty input removes the last token',
+ "Change metadata: onChange receives a second argument with type ('add' | 'remove' | 'reorder')",
+ ],
+ accessibility: [
+ 'Wrapped in XDSField for label, description, and status message association.',
+ 'Token container has role="group" with aria-label.',
+ 'Clear all button has aria-label="Clear all".',
+ 'Combobox pattern provided by XDSBaseTypeahead with aria-expanded and aria-autocomplete.',
+ ],
+ keyboard:
+ 'Backspace on empty input removes last token; Arrow keys navigate dropdown; Enter selects highlighted item; Escape closes dropdown',
+};
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx b/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
index f752ad9e03..58314259cb 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.test.tsx
@@ -298,7 +298,7 @@ describe('XDSTokenizer', () => {
});
it('renders tokens as direct children of wrapper (not in a sub-container)', () => {
- const {container} = render(
+ const {container: _container} = render(
<XDSTokenizer
label="Members"
searchSource={userSource}
diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.md
deleted file mode 100644
index 28035c07de..0000000000
--- a/packages/core/src/TopNav/README.md
+++ /dev/null
@@ -1,246 +0,0 @@
-# TopNav
-
-Top navigation bar component for application headers.
-
-<!-- SYNC: When files in this directory change, update this document. -->
-
-## Features
-
-- **Slot-based layout**: `title`, `startContent`, `endContent` for flexible organization
-- **Companion components**: XDSTopNavTitle, XDSTopNavItem
-- **Accessible**: Proper ARIA roles and keyboard navigation
-- **Themeable**: Uses XDS design tokens for styling
-
-## Usage
-
-```tsx
-import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
-import {XDSNavIcon} from '@xds/core/NavIcon';
-import {XDSButton} from '@xds/core/Button';
-import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
-
-<XDSTopNav
- label="Main navigation"
- title={
- <XDSTopNavTitle
- title="My App"
- logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
- href="/"
- />
- }
- startContent={
- <>
- <XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />
- <XDSTopNavItem label="Products" href="/products" />
- <XDSTopNavItem label="Reports" href="/reports" />
- </>
- }
- endContent={
- <>
- <XDSButton
- label="Notifications"
- variant="ghost"
- icon={<BellIcon style={{width: 16, height: 16}} />}
- />
- <XDSButton
- label="Profile"
- variant="ghost"
- icon={<UserCircleIcon style={{width: 16, height: 16}} />}
- />
- </>
- }
-/>;
-```
-
-## Components
-
-- **XDSTopNav** — Main navigation container
-- **XDSTopNavTitle** — Title with logo and text
-- **XDSTopNavItem** — Navigation link item
-- **XDSTopNavMenu** — Navigation item with hover-triggered overflow menu
-
-For the circular icon container, use `XDSNavIcon` from `@xds/core/NavIcon`.
-
-## Props
-
-### XDSTopNav
-
-```tsx
-<XDSTopNav
- label="Main navigation"
- title={<XDSTopNavTitle title="My App" href="/" />}
- startContent={<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />}
- endContent={<XDSButton label="Profile" variant="ghost" />}
-/>
-```
-
-| Prop | Type | Default | Description |
-| -------------- | ----------- | ------- | ----------------------------------------------------- |
-| `title` | `ReactNode` | — | Title slot (logo, brand) - left aligned |
-| `startContent` | `ReactNode` | — | Start content (nav items, breadcrumbs) - left aligned |
-| `endContent` | `ReactNode` | — | End content (search, icons, profile) - right aligned |
-| `label` | `string` | — | Accessible label for navigation landmark |
-
-### XDSTopNavTitle
-
-```tsx
-<XDSTopNavTitle title="My App" logo={<XDSNavIcon icon={<HomeIcon />} />} href="/" />
-```
-
-| Prop | Type | Default | Description |
-| ------- | ----------- | ------- | -------------------------------- |
-| `title` | `string` | — | Title text to display |
-| `logo` | `ReactNode` | — | Logo element (image, XDSNavIcon) |
-| `href` | `string` | — | URL to navigate to when clicked |
-
-### XDSTopNavItem
-
-```tsx
-<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected icon={<HomeIcon />} />
-```
-
-| Prop | Type | Default | Description |
-| ------------ | ----------- | ------- | ------------------------------- |
-| `label` | `string` | — | Accessible label (required) |
-| `href` | `string` | — | Navigation target URL |
-| `isSelected` | `boolean` | `false` | Selected/highlighted state |
-| `isDisabled` | `boolean` | `false` | Disabled state |
-| `icon` | `ReactNode` | — | Optional icon element |
-| `children` | `ReactNode` | — | Custom content instead of label |
-
-### XDSTopNavMenu
-
-```tsx
-<XDSTopNavMenu
- label="Products"
- items={[
- {title: 'Analytics', description: 'View metrics', href: '/analytics'},
- {title: 'Reports', description: 'Generate reports', href: '/reports'},
- ]}
-/>
-```
-
-| Prop | Type | Default | Description |
-| ----------- | ------------------------- | ------- | ------------------------------------------- |
-| `label` | `string` | — | Visible label for the trigger (required) |
-| `items` | `XDSTopNavMenuItemData[]` | — | Menu items to display in the hover popover |
-| `delay` | `number` | `150` | Delay before showing on hover (ms) |
-| `hideDelay` | `number` | `200` | Delay before hiding after mouse leaves (ms) |
-
-#### XDSTopNavMenuItemData
-
-| Property | Type | Description |
-| ------------- | ------------ | -------------------------------- |
-| `title` | `string` | Display title (required) |
-| `description` | `string` | Optional description below title |
-| `icon` | `ReactNode` | Optional icon on the left |
-| `href` | `string` | URL to navigate to |
-| `onClick` | `() => void` | Callback on click |
-
-## Selected State
-
-When `isSelected` is true, nav items show:
-
-- **Background**: `--color-accent-deemphasized` (subtle accent tint)
-- **Text**: `--color-text-primary` with semibold weight
-- **Icon**: Primary color; use `selectedIcon` for filled variants
-
-## Theming
-
-Themes can override `TopNav` styles via `ComponentStyles`:
-
-```tsx
-// In your theme definition
-const theme: Theme = {
- // ...tokens...
- components: {
- topNav: {
- root: myStyles,
- },
- },
-};
-```
-
-### Available surfaces
-
-| Surface | Description |
-| ------- | ------------------- |
-| `root` | Root nav bar styles |
-
-## Files
-
-| File | Role | Purpose |
-| ------------------------ | ----- | --------------------------------- |
-| `index.ts` | Entry | Exports components and types |
-| `XDSTopNav.tsx` | Core | Main navigation container |
-| `XDSTopNavTitle.tsx` | Core | Title with logo and text |
-| `XDSTopNavItem.tsx` | Core | Navigation link item |
-| `XDSTopNavMenu.tsx` | Core | Nav item with hover overflow menu |
-| `XDSTopNav.test.tsx` | Test | Unit tests for TopNav components |
-| `XDSTopNavMenu.test.tsx` | Test | Unit tests for XDSTopNavMenu |
-
-## Layout Structure
-
-XDSTopNav works in XDSLayout's `header` slot via XDSLayoutHeader (which handles
-the divider) or directly. TopNav manages its own padding and height.
-
-```tsx
-import {XDSLayout, XDSLayoutContent, XDSLayoutPanel} from '@xds/core/Layout';
-import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
-
-<XDSLayout
- header={
- <XDSTopNav
- label="Main navigation"
- title={<XDSTopNavTitle title="My App" logo={<Logo />} />}
- startContent={
- <>
- <XDSTopNavItem label="Home" href="/" isSelected />
- <XDSTopNavItem label="Settings" href="/settings" />
- </>
- }
- endContent={<Avatar />}
- />
- }
- content={
- <XDSLayoutContent role="main">
- <MainContent />
- </XDSLayoutContent>
- }
-/>;
-```
-
-## Slot Layout Structure
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ [title] [startContent ...] [...endContent] │
-│ └─ left aligned ─────────────────────────── right aligned ─┤
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Three-column layout** (with `centerContent`):
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ [title] [start...] [centerContent...] [...endContent] │
-│ └─ 1fr start ──┘ └── auto center ──┘ └── 1fr end ───┤
-└─────────────────────────────────────────────────────────────┘
-```
-
-When `centerContent` is provided, the layout switches to a CSS grid with
-`gridTemplateColumns: '1fr auto 1fr'`. This guarantees the center column
-is always at the exact horizontal center of the nav bar, regardless of
-left/right content widths. The right column is always rendered (even when
-`endContent` is absent) to maintain the three-column grid structure.
-
-## Implementation Notes
-
-- XDSTopNav uses `role="navigation"` and accepts `aria-label` via the `label` prop
-- Without `centerContent`: title and startContent grow to push endContent right
-- With `centerContent`: switches to CSS grid (`1fr auto 1fr`) for true centering
-- XDSTopNavItem supports `aria-current="page"` when `isSelected` is true
-- Default height is 48px with 16px horizontal padding
-- Uses `--color-navbar` token for background (defaults to white)
-- Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself
-- Dividers are controlled by the layout system (e.g. XDSLayoutHeader's `hasDivider`), not TopNav
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
new file mode 100644
index 0000000000..bbbc516146
--- /dev/null
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -0,0 +1,475 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TopNav',
+ description:
+ 'Top navigation bar component for application headers with slot-based layout and companion nav item components.',
+ features: [
+ 'Slot-based layout — title, startContent, centerContent, and endContent slots for flexible organization',
+ 'Three-column centering — when centerContent is provided, switches to CSS grid (1fr auto 1fr) for true horizontal centering',
+ 'Companion components — XDSTopNavTitle, XDSTopNavItem, XDSTopNavMenu, XDSTopNavMegaMenu',
+ 'Accessible — uses role="navigation" with aria-label, aria-current="page" on selected items',
+ 'Themeable — supports root style override via theme ComponentStyles',
+ 'Link customization — XDSTopNavItem accepts an as prop to swap the anchor element (e.g. for React Router)',
+ ],
+ examples: [
+ {
+ label: 'Basic nav with title and items',
+ code: `<XDSTopNav
+ label="Main navigation"
+ title={
+ <XDSTopNavTitle
+ title="My App"
+ logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
+ href="/"
+ />
+ }
+ startContent={
+ <>
+ <XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />
+ <XDSTopNavItem label="Products" href="/products" />
+ <XDSTopNavItem label="Reports" href="/reports" />
+ </>
+ }
+ endContent={
+ <>
+ <XDSButton
+ label="Notifications"
+ variant="ghost"
+ icon={<BellIcon style={{width: 16, height: 16}} />}
+ />
+ <XDSButton
+ label="Profile"
+ variant="ghost"
+ icon={<UserCircleIcon style={{width: 16, height: 16}} />}
+ />
+ </>
+ }
+/>`,
+ },
+ {
+ label: 'With centered content (three-column layout)',
+ code: `<XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="My App" href="/" />}
+ startContent={<XDSTopNavItem label="Home" href="/" isSelected />}
+ centerContent={<SearchBar />}
+ endContent={<Avatar />}
+/>`,
+ },
+ {
+ label: 'With hover menu and mega menu',
+ code: `<XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="My App" href="/" />}
+ startContent={
+ <>
+ <XDSTopNavItem label="Home" href="/" isSelected />
+ <XDSTopNavMenu
+ label="Products"
+ items={[
+ {title: 'Analytics', description: 'View metrics', href: '/analytics'},
+ {title: 'Reports', description: 'Generate reports', href: '/reports'},
+ ]}
+ />
+ <XDSTopNavMegaMenu
+ label="Solutions"
+ items={[
+ {title: 'Enterprise', description: 'For large teams', icon: <BuildingIcon />, href: '/enterprise'},
+ {title: 'Startups', description: 'Move fast', icon: <RocketIcon />, href: '/startups'},
+ ]}
+ featured={{
+ title: 'New: AI Features',
+ description: 'Explore our latest AI-powered tools.',
+ linkText: 'Learn more →',
+ linkHref: '/ai',
+ }}
+ />
+ </>
+ }
+/>`,
+ },
+ {
+ label: 'In XDSLayout header slot',
+ code: `<XDSLayout
+ header={
+ <XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="My App" logo={<Logo />} href="/" />}
+ startContent={
+ <>
+ <XDSTopNavItem label="Home" href="/" isSelected />
+ <XDSTopNavItem label="Settings" href="/settings" />
+ </>
+ }
+ endContent={<Avatar />}
+ />
+ }
+ content={
+ <XDSLayoutContent role="main">
+ <MainContent />
+ </XDSLayoutContent>
+ }
+/>`,
+ },
+ ],
+ theming: {
+ componentKey: 'topNav',
+ surfaces: [{name: 'root', description: 'Root nav bar element'}],
+ },
+ accessibility: [
+ 'XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop',
+ 'XDSTopNavItem sets aria-current="page" when isSelected is true',
+ 'XDSTopNavItem sets aria-label for icon-only items (when icon is provided and no children or label text is visible)',
+ 'XDSTopNavItem sets aria-disabled and tabIndex=-1 when isDisabled is true',
+ 'XDSTopNavMenu sets aria-haspopup="true" on the trigger button',
+ 'XDSTopNavMegaMenu sets aria-haspopup="true" and aria-expanded on the trigger button',
+ 'XDSTopNavMegaMenu menu items are unreachable by keyboard (tabIndex=-1) when the panel is closed',
+ 'Escape key closes the XDSTopNavMegaMenu panel',
+ ],
+ keyboard:
+ 'Tab to navigate between items; Escape closes XDSTopNavMegaMenu panels',
+ notes: [
+ 'Default height is 48px (--spacing-12) with 16px horizontal padding',
+ 'Uses --color-navbar token for background (defaults to white)',
+ 'Without centerContent: title and startContent grow to push endContent right (flex layout)',
+ 'With centerContent: switches to CSS grid (gridTemplateColumns: 1fr auto 1fr) — the right column is always rendered even when endContent is absent to maintain the three-column structure',
+ 'Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself',
+ 'Dividers are controlled by the layout system (e.g. XDSLayoutHeader hasDivider), not TopNav',
+ 'XDSTopNavMegaMenu panels position relative to the nearest positioned ancestor — wrap XDSTopNav in a container with position: relative for correct full-width behavior',
+ ],
+ components: [
+ {
+ name: 'XDSTopNav',
+ description: 'Main navigation bar container with slot-based layout.',
+ props: [
+ {
+ name: 'title',
+ type: 'ReactNode',
+ description:
+ 'Title slot content (logo, brand) — positioned at the left edge of the nav bar.',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description:
+ 'Start content slot for navigation items or breadcrumbs — positioned after the title, left-aligned.',
+ },
+ {
+ name: 'centerContent',
+ type: 'ReactNode',
+ description:
+ 'Center content slot (tabs, search bar, primary navigation) — when provided, switches the layout to a three-column CSS grid for true horizontal centering.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description:
+ 'End content slot for search, icons, or user profile — positioned at the right edge.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label for the navigation landmark, applied as aria-label on the <nav> element.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="My App" href="/" />}
+ startContent={<XDSTopNavItem label="Dashboard" href="/dashboard" isSelected />}
+ endContent={<XDSButton label="Profile" variant="ghost" />}
+/>`,
+ },
+ {
+ label: 'With centered content',
+ code: `<XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="My App" href="/" />}
+ centerContent={<SearchInput placeholder="Search..." />}
+ endContent={<Avatar />}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTopNavTitle',
+ description:
+ 'Title component for the XDSTopNav title slot — displays a logo and/or title text, optionally as a clickable link.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Title text to display.',
+ },
+ {
+ name: 'logo',
+ type: 'ReactNode',
+ description:
+ 'Logo element to display before the title text. Can be an image, XDSNavIcon, or any ReactNode.',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description:
+ 'URL to navigate to when clicked. When provided, renders as an anchor element.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Logo with text link',
+ code: `<XDSTopNavTitle
+ title="My App"
+ logo={<img src="/logo.svg" alt="" width={24} height={24} />}
+ href="/"
+/>`,
+ },
+ {
+ label: 'With XDSNavIcon',
+ code: `<XDSTopNavTitle
+ title="Dashboard"
+ logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
+ href="/"
+/>`,
+ },
+ {
+ label: 'Logo only',
+ code: `<XDSTopNavTitle logo={<BrandLogo />} href="/" />`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTopNavItem',
+ description:
+ 'Navigation link item for use in XDSTopNav startContent — renders as an anchor with hover and selected states.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible label for the nav item. Used as visible text, or as aria-label for icon-only items.',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Navigation target URL.',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description:
+ 'Whether this nav item is currently selected. Sets aria-current="page" and applies highlighted styles.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description:
+ 'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ 'Optional icon to display before the label. If provided without children, the item becomes icon-only.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description:
+ 'Custom content to render instead of the label text. When omitted and an icon is provided, the item becomes icon-only.',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description:
+ 'Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic nav items',
+ code: `<>
+ <XDSTopNavItem label="Home" href="/" isSelected />
+ <XDSTopNavItem label="Products" href="/products" />
+ <XDSTopNavItem label="Settings" href="/settings" isDisabled />
+</>`,
+ },
+ {
+ label: 'With icon',
+ code: `<XDSTopNavItem
+ label="Settings"
+ href="/settings"
+ icon={<GearIcon style={{width: 16, height: 16}} />}
+/>`,
+ },
+ {
+ label: 'Icon only',
+ code: `<XDSTopNavItem
+ label="Notifications"
+ href="/notifications"
+ icon={<BellIcon style={{width: 16, height: 16}} />}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTopNavMenu',
+ description:
+ 'Navigation item that displays a hover-triggered popover menu with rich items containing an icon, title, and optional description.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Visible label for the trigger button.',
+ required: true,
+ },
+ {
+ name: 'items',
+ type: 'XDSTopNavMenuItemData[]',
+ description: 'Menu items to display in the hover popover.',
+ required: true,
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description:
+ 'Delay in milliseconds before showing the menu on hover.',
+ default: '150',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description:
+ 'Delay in milliseconds before hiding the menu after the mouse leaves.',
+ default: '200',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic hover menu',
+ code: `<XDSTopNavMenu
+ label="Products"
+ items={[
+ {title: 'Analytics', description: 'View metrics', href: '/analytics'},
+ {title: 'Reports', description: 'Generate reports', href: '/reports'},
+ ]}
+/>`,
+ },
+ {
+ label: 'With icons and click handlers',
+ code: `<XDSTopNavMenu
+ label="Tools"
+ items={[
+ {
+ title: 'Analytics',
+ description: 'Track and analyze user behavior',
+ icon: <ChartBarIcon />,
+ href: '/analytics',
+ },
+ {
+ title: 'Export',
+ description: 'Download your data',
+ icon: <ArrowDownTrayIcon />,
+ onClick: () => openExportDialog(),
+ },
+ ]}
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTopNavMegaMenu',
+ description:
+ 'Navigation item that displays a full-width mega menu panel on hover, with items in a two-column grid and an optional featured content area.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Visible label for the trigger button.',
+ required: true,
+ },
+ {
+ name: 'items',
+ type: 'XDSTopNavMegaMenuItemData[]',
+ description: 'Menu items to display in the mega menu panel.',
+ required: true,
+ },
+ {
+ name: 'featured',
+ type: 'XDSTopNavMegaMenuFeatured',
+ description:
+ 'Optional featured content displayed on the right side of the mega menu panel.',
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description:
+ 'Delay in milliseconds before showing the menu on hover.',
+ default: '150',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description:
+ 'Delay in milliseconds before hiding the menu after the mouse leaves.',
+ default: '250',
+ },
+ {
+ name: 'isSingleColumn',
+ type: 'boolean',
+ description:
+ 'Whether to use a single-column layout for menu items instead of two columns.',
+ default: 'false',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description:
+ 'Callback fired when the mega menu opens or closes. Useful for coordinating wrapper styles.',
+ },
+ ],
+ examples: [
+ {
+ label: 'With featured content',
+ code: `<div style={{position: 'relative'}}>
+ <XDSTopNav
+ startContent={
+ <XDSTopNavMegaMenu
+ label="Solutions"
+ items={[
+ {title: 'Enterprise', description: 'For large teams', icon: <BuildingIcon />, href: '/enterprise'},
+ {title: 'Startups', description: 'Move fast', icon: <RocketIcon />, href: '/startups'},
+ ]}
+ featured={{
+ title: 'New: AI Features',
+ description: 'Explore our latest AI-powered tools.',
+ linkText: 'Learn more →',
+ linkHref: '/ai',
+ }}
+ />
+ }
+ />
+</div>`,
+ },
+ {
+ label: 'Single column layout',
+ code: `<XDSTopNavMegaMenu
+ label="Products"
+ isSingleColumn
+ items={[
+ {title: 'Analytics', description: 'Track behavior', icon: <ChartIcon />, href: '/analytics'},
+ {title: 'Messaging', description: 'Real-time comms', icon: <ChatIcon />, href: '/messaging'},
+ {title: 'Storage', description: 'Manage your data', icon: <DatabaseIcon />, href: '/storage'},
+ ]}
+/>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 56c9149c1f..8a0dff0354 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -5,7 +5,7 @@
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TopNav/README.md
+ * - /packages/core/src/TopNav/TopNav.doc.mjs
* - /packages/core/src/TopNav/XDSTopNav.test.tsx
* - /packages/core/src/TopNav/index.ts
* - /apps/storybook/stories/TopNav.stories.tsx
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index 656dd13aa4..2d6ae4fcb8 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -5,7 +5,7 @@
* @position Navigation item component for XDSTopNav startContent
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TopNav/README.md
+ * - /packages/core/src/TopNav/TopNav.doc.mjs
* - /packages/core/src/TopNav/XDSTopNav.test.tsx
* - /packages/core/src/TopNav/index.ts
* - /apps/storybook/stories/TopNav.stories.tsx
diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
index 999f08d12b..9ec0bf2d48 100644
--- a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
@@ -9,7 +9,7 @@
* the nav wrapper.
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TopNav/README.md
+ * - /packages/core/src/TopNav/TopNav.doc.mjs
* - /packages/core/src/TopNav/index.ts
*/
diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsx
index e27a80e8ef..d484c56bbb 100644
--- a/packages/core/src/TopNav/XDSTopNavMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx
@@ -5,7 +5,7 @@
* @position Navigation item with hover-triggered overflow menu for XDSTopNav
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TopNav/README.md
+ * - /packages/core/src/TopNav/TopNav.doc.mjs
* - /packages/core/src/TopNav/XDSTopNavMenu.test.tsx
* - /packages/core/src/TopNav/index.ts
*/
diff --git a/packages/core/src/TopNav/XDSTopNavTitle.tsx b/packages/core/src/TopNav/XDSTopNavTitle.tsx
index 213fe11662..aa7d30670b 100644
--- a/packages/core/src/TopNav/XDSTopNavTitle.tsx
+++ b/packages/core/src/TopNav/XDSTopNavTitle.tsx
@@ -5,7 +5,7 @@
* @position Companion component for XDSTopNav title slot
*
* SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/TopNav/README.md
+ * - /packages/core/src/TopNav/TopNav.doc.mjs
* - /packages/core/src/TopNav/XDSTopNav.test.tsx
* - /packages/core/src/TopNav/index.ts
* - /apps/storybook/stories/TopNav.stories.tsx
diff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.ts
index cfc8206376..a9adb5a1ad 100644
--- a/packages/core/src/TopNav/index.ts
+++ b/packages/core/src/TopNav/index.ts
@@ -4,7 +4,7 @@
* @output Exports XDSTopNav and companion components
* @position Entry point for TopNav module
*
- * SYNC: When modified, update /packages/core/src/TopNav/README.md
+ * SYNC: When modified, update /packages/core/src/TopNav/TopNav.doc.mjs
*/
export {XDSTopNav} from './XDSTopNav';
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
new file mode 100644
index 0000000000..8cb13f5faf
--- /dev/null
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -0,0 +1,405 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Typeahead',
+ description:
+ 'Searchable dropdown components for single-item selection with keyboard navigation. Supports async and sync search via a searchSource interface.',
+ features: [
+ 'Async and sync search via a searchSource interface with search() and bootstrap() methods',
+ 'Bootstrap results shown on focus before typing (via hasEntriesOnFocus)',
+ 'Edit mode: clicking selected token enters edit mode with text pre-populated and selected',
+ 'Combobox ARIA pattern for full accessibility',
+ 'Debounced search with configurable delay (default 150ms, set to 0 for synchronous sources)',
+ 'Two-layer architecture: XDSBaseTypeahead provides the engine, XDSTypeahead adds field chrome',
+ ],
+ examples: [
+ {
+ label: 'Basic typeahead',
+ code: `const source = {
+ search: query => fruits.filter(f => f.label.includes(query)),
+ bootstrap: () => fruits.slice(0, 5),
+};
+
+<XDSTypeahead
+ label="Fruit"
+ searchSource={source}
+ value={selected}
+ onChange={setSelected}
+ placeholder="Search fruits..."
+/>`,
+ },
+ {
+ label: 'With custom item rendering',
+ code: `<XDSTypeahead
+ label="Assignee"
+ searchSource={userSource}
+ value={assignee}
+ onChange={setAssignee}
+ placeholder="Search users..."
+ hasEntriesOnFocus
+ renderItem={(item) => (
+ <XDSTypeaheadItem
+ item={item}
+ icon={<XDSAvatar src={item.auxiliaryData.avatar} size="sm" />}
+ description={item.auxiliaryData.role}
+ />
+ )}
+/>`,
+ },
+ {
+ label: 'With validation status',
+ code: `<XDSTypeahead
+ label="Manager"
+ searchSource={managerSource}
+ value={manager}
+ onChange={setManager}
+ isRequired
+ status={{ type: 'error', message: 'A manager is required' }}
+/>`,
+ },
+ ],
+ components: [
+ {
+ name: 'XDSTypeahead',
+ description:
+ 'Styled typeahead with label, description, validation, and all field features. Wraps XDSBaseTypeahead with XDSField for the primary use case.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the input.',
+ required: true,
+ },
+ {
+ name: 'searchSource',
+ type: 'XDSSearchSource<T>',
+ description:
+ 'Data source providing search and bootstrap methods for populating the dropdown.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'T | null',
+ description:
+ 'Currently selected item, or null if nothing is selected.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(item: T | null) => void',
+ description: 'Called when the selection changes.',
+ required: true,
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Input placeholder text.',
+ },
+ {
+ name: 'hasEntriesOnFocus',
+ type: 'boolean',
+ description: 'Show bootstrap results on focus before typing.',
+ default: 'false',
+ },
+ {
+ name: 'hasClear',
+ type: 'boolean',
+ description: 'Show clear button to deselect the current value.',
+ default: 'true',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the input.',
+ default: 'false',
+ },
+ {
+ name: 'maxMenuItems',
+ type: 'number',
+ description: 'Maximum number of dropdown items to display.',
+ default: '10',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description:
+ 'Validation status object with type and message for error/warning/success states.',
+ },
+ {
+ name: 'renderItem',
+ type: '(item: T) => ReactNode',
+ description:
+ 'Custom render function for dropdown items. Default renders XDSTypeaheadItem.',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hides the label while keeping it accessible.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed below the label.',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Marks the field as required.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Shows an optional indicator on the label.',
+ default: 'false',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text shown on the label.',
+ },
+ {
+ name: 'emptySearchResultsText',
+ type: 'string',
+ description: 'Text shown when search returns no results.',
+ default: "'No results found'",
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Auto-focus the input on mount.',
+ default: 'false',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Input and token size.',
+ default: "'md'",
+ },
+ {
+ name: 'debounceMs',
+ type: 'number',
+ description:
+ 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+ default: '150',
+ },
+ {
+ name: 'onChangeQuery',
+ type: '(query: string) => void',
+ description: 'Callback fired when the search query text changes.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback when the dropdown opens or closes.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSTypeahead
+ label="Assignee"
+ searchSource={userSource}
+ value={assignee}
+ onChange={setAssignee}
+ placeholder="Search users..."
+/>`,
+ },
+ {
+ label: 'With bootstrap on focus',
+ code: `<XDSTypeahead
+ label="Project"
+ searchSource={projectSource}
+ value={project}
+ onChange={setProject}
+ hasEntriesOnFocus
+ placeholder="Select a project..."
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSBaseTypeahead',
+ description:
+ 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by XDSTypeahead and XDSTokenizer for custom compositions.',
+ props: [
+ {
+ name: 'searchSource',
+ type: 'XDSSearchSource<T>',
+ description: 'Data source providing search and bootstrap methods.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'T | null',
+ description: 'Currently selected item.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(item: T | null) => void',
+ description: 'Called when the selection changes.',
+ required: true,
+ },
+ {
+ name: 'renderItem',
+ type: '(item: T) => ReactNode',
+ description: 'Custom render function for dropdown items.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Input placeholder text.',
+ default: "'Search...'",
+ },
+ {
+ name: 'hasEntriesOnFocus',
+ type: 'boolean',
+ description: 'Show bootstrap results on focus before typing.',
+ default: 'false',
+ },
+ {
+ name: 'maxMenuItems',
+ type: 'number',
+ description: 'Maximum dropdown items to display.',
+ default: '10',
+ },
+ {
+ name: 'emptySearchResultsText',
+ type: 'string',
+ description: 'Text shown when search returns no results.',
+ default: "'No results found'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the input is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Auto-focus the input on mount.',
+ default: 'false',
+ },
+ {
+ name: 'debounceMs',
+ type: 'number',
+ description:
+ 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+ default: '150',
+ },
+ {
+ name: 'anchorRef',
+ type: 'RefObject<HTMLElement | null>',
+ description:
+ 'Ref to the anchor element for dropdown positioning. If not provided, the input itself is used.',
+ },
+ {
+ name: 'inputXStyle',
+ type: 'StyleXStyles',
+ description: 'Additional StyleX styles for the input element.',
+ },
+ {
+ name: 'onKeyDown',
+ type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',
+ description:
+ 'Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.',
+ },
+ {
+ name: 'onChangeQuery',
+ type: '(query: string) => void',
+ description: 'Callback fired when the search query text changes.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback when the dropdown opens or closes.',
+ },
+ {
+ name: 'inputId',
+ type: 'string',
+ description: 'ID for the input element (for label association).',
+ },
+ {
+ name: 'ariaDescribedBy',
+ type: 'string',
+ description: 'Additional aria-describedby IDs.',
+ },
+ ],
+ examples: [
+ {
+ label: 'With custom wrapper',
+ code: `<XDSBaseTypeahead
+ searchSource={source}
+ value={selected}
+ onChange={setSelected}
+ anchorRef={wrapperRef}
+ placeholder="Search..."
+/>`,
+ },
+ ],
+ },
+ {
+ name: 'XDSTypeaheadItem',
+ description:
+ 'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',
+ props: [
+ {
+ name: 'item',
+ type: 'XDSSearchableItem',
+ description: 'The search result item to render.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon or avatar to display before the label.',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this item is visually disabled.',
+ default: 'false',
+ },
+ {
+ name: 'group',
+ type: 'string',
+ description: 'Group label for grouping items visually.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Custom renderItem with icon and description',
+ code: `<XDSTypeaheadItem
+ item={user}
+ icon={<XDSAvatar src={user.auxiliaryData.avatar} size="sm" />}
+ description={user.auxiliaryData.role}
+/>`,
+ },
+ ],
+ },
+ ],
+ accessibility: [
+ 'Uses combobox ARIA pattern with role="combobox", aria-expanded, aria-autocomplete="list".',
+ 'Dropdown uses role="listbox" with role="option" on each item.',
+ 'aria-activedescendant tracks the highlighted option.',
+ 'Selected item has aria-selected="true".',
+ 'Loading state has role="status" with aria-label="Loading".',
+ 'XDSTypeahead wraps in XDSField for label and description association.',
+ ],
+ keyboard:
+ 'Arrow keys navigate dropdown items; Enter selects highlighted item; Escape closes dropdown or restores previous value in edit mode; Home/End jump to first/last item',
+ notes: [
+ 'XDSSearchSource requires items to implement XDSSearchableItem ({ id: string; label: string; [key: string]: unknown }).',
+ 'Edit mode in XDSTypeahead: clicking the selected token removes it visually, populates the input with the label text, and selects all. Blurring without selecting restores the original token.',
+ 'XDSBaseTypeahead renders only the <input> and dropdown popover — consumers provide their own wrapper.',
+ 'If item has an element property, XDSTypeaheadItem renders it directly instead of the standard layout.',
+ ],
+};
diff --git a/packages/core/src/Typeahead/XDSTypeahead.test.tsx b/packages/core/src/Typeahead/XDSTypeahead.test.tsx
index 26f54b64d7..eddd916190 100644
--- a/packages/core/src/Typeahead/XDSTypeahead.test.tsx
+++ b/packages/core/src/Typeahead/XDSTypeahead.test.tsx
@@ -249,7 +249,7 @@ describe('XDSTypeahead edit mode', () => {
onChange={onChange}
/>,
);
- const input = screen.getByRole('combobox');
+ screen.getByRole('combobox');
// Click the token area to enter edit mode
const removeButton = screen.getByRole('button', {
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
new file mode 100644
index 0000000000..616590fd0a
--- /dev/null
+++ b/packages/core/src/docs-types.ts
@@ -0,0 +1,200 @@
+/**
+ * @file Type definitions for component documentation.
+ *
+ * Every component directory under `packages/core/src/` has a `{Name}.doc.mjs`
+ * that exports a single `docs` constant typed via JSDoc. The CLI imports these
+ * directly — no markdown parsing needed.
+ */
+
+/**
+ * Documents a single component prop. Each prop the component accepts
+ * should have an entry. Skip internal/styling props like `xstyle`,
+ * `className`, `style`, and `data-testid`.
+ *
+ * @example
+ * ```
+ * {name: 'label', type: 'string', description: 'Visible label text', required: true}
+ * {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Control size', default: "'md'"}
+ * {name: 'onChange', type: '(value: string) => void', description: 'Called when value changes.'}
+ * ```
+ */
+export interface PropDoc {
+ /** Prop name exactly as used in JSX, camelCased.
+ * Callbacks start with `on` (`"onChange"`, `"onToggle"`).
+ * Booleans use `is`/`has` prefix (`"isDisabled"`, `"hasHover"`). */
+ name: string;
+ /** TypeScript type signature as a string. Use single quotes for string
+ * literal unions. Keep close to the actual TS type.
+ *
+ * Simple: `"string"`, `"boolean"`, `"ReactNode"`
+ * Union: `"'primary' | 'secondary' | 'ghost'"`
+ * Function: `"(checked: boolean, e: ChangeEvent) => void"`
+ * Async: `"(e: MouseEvent) => void | Promise<void>"`
+ * Generic: `"XDSTableColumn<T>[]"` */
+ type: string;
+ /** What this prop does, in 1-2 sentences. Focus on behavior and
+ * consequences rather than restating the prop name.
+ *
+ * Good: `"Shows a loading spinner and disables interaction."`
+ * Weak: `"Shows a loading spinner."` */
+ description: string;
+ /** Default value as a string, if the prop is optional and has one.
+ * String literals in single quotes: `"'md'"`, `"'balanced'"`.
+ * Other values unquoted: `"false"`, `"0"`, `"() => true"`.
+ * Omit entirely for required props or optional props with no default. */
+ default?: string;
+ /** True if the prop must be provided. Omit (don't set to false) if optional. */
+ required?: boolean;
+}
+
+/**
+ * A usage example showing the component in JSX. Examples should progress
+ * from basic to advanced. Include 2-5 examples per component (complex
+ * components like Table or Layer may justify more).
+ *
+ * @example
+ * ```
+ * {label: 'Basic', code: '<XDSButton variant="primary">Save</XDSButton>'}
+ * {label: 'With icon', code: '<XDSButton icon={PlusIcon} variant="secondary">Add</XDSButton>'}
+ * ```
+ */
+export interface Example {
+ /** Short descriptive title in sentence case, 2-8 words.
+ * e.g. `"Basic"`, `"With icon"`, `"Rich cell content with renderCell"`.
+ * Omit only for trivial single-example sub-components. */
+ label?: string;
+ /** JSX code string. Use regular strings for single-line snippets and
+ * template literals for multi-line code. Prefer realistic variable names
+ * (`users`, `transactions`) over generic ones (`data`, `value1`). */
+ code: string;
+}
+
+/**
+ * A themeable style surface that consumers can override via their theme's
+ * `ComponentStyles`. Each component exposes named surfaces (e.g. `root`,
+ * `trigger`, `track`) that map to internal styled elements.
+ *
+ * @example
+ * ```
+ * {name: 'root', description: 'Outer wrapper element'}
+ * {name: 'track', description: 'Slider track background'}
+ * ```
+ */
+export interface ThemingSurface {
+ /** Surface key as used in the theme object, always camelCase.
+ * e.g. `"root"`, `"track"`, `"filledTrack"`, `"headerRow"`, `"bodyCell"` */
+ name: string;
+ /** Short noun phrase describing the DOM element or visual region.
+ * No trailing period. e.g. `"Outer wrapper element"`,
+ * `"Animated circular thumb inside the track"` */
+ description: string;
+}
+
+/**
+ * Documents one component within a multi-component directory. Used when a
+ * directory exports multiple public components (e.g. Table exports XDSTable,
+ * XDSBaseTable, XDSTableRow, XDSTableCell, XDSTableHeaderCell).
+ *
+ * Also use for hooks with config objects (e.g. useXDSTableSelection) —
+ * treat config options as "props". Order components with the primary/most-used
+ * component first.
+ */
+export interface ComponentEntry {
+ /** Full export name including XDS prefix. e.g. `"XDSTableRow"`,
+ * `"XDSDialogHeader"`, `"useXDSTableSelection"` */
+ name: string;
+ /** One-sentence description of what this specific component does.
+ * For sub-components, explain the role within the parent composition. */
+ description: string;
+ /** All public props for this component. */
+ props: PropDoc[];
+ /** At least one usage example for this component. */
+ examples: Example[];
+}
+
+/**
+ * Shared fields between single-component and multi-component docs.
+ * Do not use this interface directly — use `ComponentDoc` (the union type).
+ */
+interface BaseDoc {
+ /** Directory name without the XDS prefix, PascalCase.
+ * e.g. `"Button"`, `"Table"`, `"TextInput"`, `"AppShell"` */
+ name: string;
+ /** One-sentence summary of the component or component group.
+ * Be specific enough to differentiate from similar components.
+ * e.g. `"Data-driven table with rich cell content via renderCell."` */
+ description: string;
+ /** Top-level usage examples showing the component in real scenarios.
+ * For multi-component dirs, these show how the components work together.
+ * Start with the most common usage pattern, then progress to advanced.
+ * Include 2-5 examples (complex components may justify more). */
+ examples: Example[];
+ /** Key capabilities as short bullet points. Each string is one feature.
+ * Strongly recommended even though optional — all existing components
+ * include this field. Use "Category: details" format.
+ * e.g. `"Variants: 'primary', 'secondary', 'ghost', 'destructive'"`,
+ * `"Single & range modes: pass a number or [number, number]"` */
+ features?: string[];
+ /** Theming configuration. Include only if the component supports
+ * style overrides via the theme's `ComponentStyles`. */
+ theming?: {
+ /** The key used in the theme's `components` object.
+ * Always lowercase, matches the directory name.
+ * e.g. `"button"`, `"switch"`, `"table"` */
+ componentKey: string;
+ /** All styleable surfaces this component exposes. */
+ surfaces: ThemingSurface[];
+ };
+ /** Accessibility notes — ARIA patterns, screen reader behavior.
+ * Each string is one self-contained, declarative note.
+ * e.g. `"Uses native <dialog> with showModal() for correct ARIA modal semantics."`,
+ * `"Selection plugin sets aria-selected on selected body rows"` */
+ accessibility?: string[];
+ /** Keyboard interaction summary as a single string. Separate bindings
+ * with semicolons or commas. Use key names like `Arrow keys`, `Enter/Space`,
+ * `Escape`, `Tab/Shift+Tab`, `Home/End`.
+ * e.g. `"Space toggles the switch; Tab/Shift+Tab moves focus in and out"` */
+ keyboard?: string;
+ /** Additional technical notes — architecture decisions, performance
+ * considerations, implementation details, caveats. Each string is one
+ * self-contained note. Do not duplicate information from `features`,
+ * `accessibility`, or `keyboard`. */
+ notes?: string[];
+}
+
+/**
+ * Documentation for a directory that exports a single primary component.
+ * Props live directly on this object.
+ *
+ * Use this when the directory has one main `XDS*.tsx` file
+ * (e.g. Switch, Badge, Spinner, TextInput).
+ */
+export interface SingleComponentDoc extends BaseDoc {
+ /** All public props for the component. */
+ props: PropDoc[];
+}
+
+/**
+ * Documentation for a directory that exports multiple public components.
+ * Props live on each entry in `components`.
+ *
+ * Use this when the directory has multiple `XDS*.tsx` files
+ * (e.g. Table, Dialog, TabList, TopNav, Layout).
+ */
+export interface MultiComponentDoc extends BaseDoc {
+ /** Each public component/hook exported from this directory. */
+ components: ComponentEntry[];
+}
+
+/**
+ * The documentation type for a component directory's {Name}.doc.mjs file.
+ *
+ * Every .doc.mjs must export a single `docs` constant of this type:
+ *
+ * /\*\* \@type \{import('../docs-types').ComponentDoc\} *\/
+ * export const docs = \{ ... \};
+ *
+ * Use SingleComponentDoc (with `props`) for single-component directories.
+ * Use MultiComponentDoc (with `components`) for multi-component directories.
+ */
+export type ComponentDoc = SingleComponentDoc | MultiComponentDoc;
diff --git a/packages/core/src/theme/README.md b/packages/core/src/theme/README.md
index 46ace94a1d..a3704aa88b 100644
--- a/packages/core/src/theme/README.md
+++ b/packages/core/src/theme/README.md
@@ -83,7 +83,7 @@ const icons: Partial<XDSIconRegistry> = {
When no theme is active, components use built-in lightweight SVG fallbacks.
-See the [Icon README](../Icon/README.md) for the full list of semantic names.
+See the [Icon docs](../Icon/Icon.doc.mjs) for the full list of semantic names.
### Adding icons to a custom theme
diff --git a/packages/core/tsconfig.docs.json b/packages/core/tsconfig.docs.json
new file mode 100644
index 0000000000..dc9ba6edbc
--- /dev/null
+++ b/packages/core/tsconfig.docs.json
@@ -0,0 +1,10 @@
+{
+ "extends": "../../tsconfig.json",
+ "compilerOptions": {
+ "rootDir": "./src",
+ "allowJs": true,
+ "checkJs": true,
+ "noEmit": true
+ },
+ "include": ["src/**/*.doc.mjs", "src/docs-types.ts"]
+}
diff --git a/scripts/validate-readmes.mjs b/scripts/validate-readmes.mjs
deleted file mode 100644
index af8455c050..0000000000
--- a/scripts/validate-readmes.mjs
+++ /dev/null
@@ -1,205 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * @file Validate component README structure for CLI brief extractor compatibility.
- *
- * The XDS CLI's `extractBrief` function parses READMEs to generate LLM-friendly
- * docs. It expects a specific structure:
- *
- * - Multi-component directories: `### XDSComponentName` subsection per component,
- * each with a props table and code example.
- * - Single-component directories: `## Props` section with a table.
- *
- * This script scans all packages/core/src/* directories and reports any READMEs
- * that don't follow the expected structure.
- *
- * Usage: node scripts/validate-readmes.mjs
- * Exit code: 0 if all pass, 1 if any issues found.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(__dirname, '..');
-const SRC_DIR = path.join(ROOT, 'packages', 'core', 'src');
-const SKIP_DIRS = new Set(['hooks', 'utils', 'theme', '__tests__', 'node_modules']);
-
-/**
- * Find all XDS*.tsx component files in a directory (non-recursive),
- * excluding test files and Context files.
- */
-function findComponentFiles(dirPath) {
- if (!fs.existsSync(dirPath)) return [];
- return fs
- .readdirSync(dirPath)
- .filter(
- f =>
- /^XDS[A-Z]\w+\.tsx$/.test(f) &&
- !f.includes('.test') &&
- !f.includes('Context'),
- )
- .map(f => f.replace(/\.tsx$/, ''));
-}
-
-/**
- * Extract the content of a ### heading section from markdown lines.
- * Returns all lines from the heading until the next ### (or end of file).
- */
-function extractSection(lines, heading) {
- const headingRe = new RegExp(`^###\\s+${escapeRegex(heading)}\\s*$`);
- let inSection = false;
- const sectionLines = [];
-
- for (const line of lines) {
- if (headingRe.test(line)) {
- inSection = true;
- continue;
- }
- if (inSection && /^###\s+/.test(line)) {
- break;
- }
- if (inSection) {
- sectionLines.push(line);
- }
- }
-
- return inSection ? sectionLines : null;
-}
-
-/**
- * Check if lines contain a markdown props table.
- * Looks for at least one row like `| \`propName\` |`
- */
-function hasPropsTable(lines) {
- return lines.some(line => /^\|\s*`[a-zA-Z]/.test(line));
-}
-
-/**
- * Check if lines contain a code example with <XDS JSX.
- * Looks for ```tsx or ```jsx blocks containing <XDS.
- */
-function hasCodeExample(lines) {
- let inCode = false;
- for (const line of lines) {
- if (/^```(?:tsx|jsx)/.test(line)) {
- inCode = true;
- continue;
- }
- if (inCode && line.startsWith('```')) {
- inCode = false;
- continue;
- }
- if (inCode && line.includes('<XDS')) {
- return true;
- }
- }
- return false;
-}
-
-function escapeRegex(str) {
- return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function validate() {
- const issues = [];
- const entries = fs.readdirSync(SRC_DIR, {withFileTypes: true});
-
- for (const entry of entries) {
- if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
-
- const dirPath = path.join(SRC_DIR, entry.name);
- const components = findComponentFiles(dirPath);
- if (components.length === 0) continue;
-
- const readmePath = path.join(dirPath, 'README.md');
- const relReadme = path.relative(ROOT, readmePath);
-
- if (!fs.existsSync(readmePath)) {
- issues.push(`${relReadme}: README.md is missing.`);
- continue;
- }
-
- const content = fs.readFileSync(readmePath, 'utf-8');
- const lines = content.split('\n');
- const isMultiComponent = components.length > 1;
-
- if (isMultiComponent) {
- // Multi-component: each component needs ### XDSComponentName
- for (const comp of components) {
- const section = extractSection(lines, comp);
-
- if (!section) {
- issues.push(
- `${relReadme}: Missing section \`### ${comp}\`. ` +
- `Each component needs its own ### heading for the CLI brief extractor to work.`,
- );
- continue;
- }
-
- if (!hasPropsTable(section)) {
- issues.push(
- `${relReadme}: Section \`### ${comp}\` has no props table. ` +
- `Add a markdown table with | Prop | Type | Default | Description | columns.`,
- );
- }
-
- if (!hasCodeExample(section)) {
- issues.push(
- `${relReadme}: Section \`### ${comp}\` has no code example. ` +
- `Add a \`\`\`tsx block with <XDS JSX usage.`,
- );
- }
- }
- } else {
- // Single-component: needs ## Props with a table
- const hasPropsSection = /^## Props/m.test(content);
-
- if (!hasPropsSection) {
- issues.push(
- `${relReadme}: Missing \`## Props\` section. ` +
- `Single-component READMEs need a ## Props heading with a props table.`,
- );
- } else {
- // Extract the ## Props section content
- let inProps = false;
- const propsLines = [];
- for (const line of lines) {
- if (/^## Props/.test(line)) {
- inProps = true;
- continue;
- }
- if (inProps && /^## /.test(line)) break;
- if (inProps) propsLines.push(line);
- }
-
- if (!hasPropsTable(propsLines)) {
- issues.push(
- `${relReadme}: \`## Props\` section has no props table. ` +
- `Add a markdown table with | Prop | Type | Default | Description | columns.`,
- );
- }
- }
- }
- }
-
- return issues;
-}
-
-// Run validation
-const issues = validate();
-
-if (issues.length > 0) {
- console.error(`\n❌ Found ${issues.length} README structure issue(s):\n`);
- for (const issue of issues) {
- console.error(` • ${issue}`);
- }
- console.error(
- `\nSee docs/COMPONENT_README_GUIDE.md for the expected structure.\n`,
- );
- process.exit(1);
-} else {
- console.log('\n✅ All component READMEs follow the expected structure.\n');
- process.exit(0);
-}