Skip to content

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

TypeScript

feat(core): ship docs.mjs + README, fix vibe test fairness (#1577)

Cindy Zhangd2a66cd5ee5c
diff --git a/internal/vibe-tests/.baseline/README.md b/internal/vibe-tests/.baseline/README.md
new file mode 100644
index 0000000000..9bcab97601
--- /dev/null
+++ b/internal/vibe-tests/.baseline/README.md
@@ -0,0 +1,26 @@
+# shadcn/ui Baseline
+
+This project uses shadcn/ui components with Tailwind CSS.
+
+## Component Source
+
+All components live in `components/ui/`. Read the source to understand props, variants, and usage:
+
+```bash
+ls components/ui/ # list all components
+cat components/ui/button.tsx # read a component's source
+```
+
+Components use:
+
+- `cva` (class-variance-authority) for variant definitions
+- `cn()` from `@/lib/utils` for class merging
+- Radix UI primitives for behavior
+- Tailwind CSS utility classes for styling
+
+## Import Pattern
+
+```tsx
+import {Button} from '@/components/ui/button';
+import {Card, CardContent, CardHeader, CardTitle} from '@/components/ui/card';
+```
diff --git a/internal/vibe-tests/README.md b/internal/vibe-tests/README.md
index 8997fe3ed1..c1738763b4 100644
--- a/internal/vibe-tests/README.md
+++ b/internal/vibe-tests/README.md
@@ -1,310 +1,173 @@
-# Vibe Tests
+# XDS Vibe Tests
-Vibeability test harness for measuring how well LLMs can use the XDS component system.
+Structured evaluations that compare how well LLMs generate UI code under different design system configurations. Same prompts, different systems, measurable outcomes.
-## Quick Start - Interactive Mode (Navi / Claude Code)
+## Prompt Battery
-Run vibe tests interactively through Navi (the AI assistant) using sub-agents — no API key needed. The skill doc is auto-generated from the CLI before each run, so it always reflects the current branch's components.
+Prompts live in [`test-sets/default.json`](test-sets/default.json). Each prompt has:
-```
-/vibe-test 5
+```json
+{
+ "id": "fwc-6",
+ "category": "feature-with-constraint",
+ "prompt": "Build a shipping method selector with three options: Standard (free, 5-7 days), Express ($9.99, 2-3 days), Overnight ($19.99, next day)",
+ "expectedComponents": ["XDSRadioList", "XDSCard"],
+ "complexity": "simple"
+}
```
-Or ask Navi:
+- **`prompt`** — the task given to the agent (identical across all configs)
+- **`expectedComponents`** — used for evaluation ONLY, never shown to agents
+- **`category`** — groups prompts by type (feature-with-constraint, workflow-description, clone-with-modification, state-display, data-display, responsive-challenge, io-integration, page-setup, typography, theme-customization)
+- **`complexity`** — simple, moderate, complex
-```
-"Run a vibe test with 5 samples"
-```
+## Sub-Agent Prompts
-This will:
+Each target gets an equivalent prompt. The only thing that varies is the design system and where to find its docs.
-1. Generate the skill doc from source (auto-discovers components)
-2. Set up a test iteration
-3. Spawn parallel sub-agents to run each test
-4. Write results to runs.jsonl
-5. Aggregate and show results
+**XDS agent sees:**
-### How It Works (Interactive)
+```
+You are generating React/TSX code using the XDS design system.
-When running interactively through Navi:
+Read the package README at node_modules/@xds/core/README.md for how to look up
+component docs. Use what you find there to discover the components you need.
-1. **Generate skill doc** — Runs `bash scripts/generate-skill-doc.sh` which uses the XDS CLI to auto-discover components from source and generate `.generated/xds-skill.md`
-2. **Setup iteration** — Creates task files and manifest in `results/<iteration>/`
-3. **Spawn sub-agents** — Each test prompt is run by a parallel sub-agent that:
- - Reads the generated skill doc as context
- - Generates code for the prompt using XDS components
- - Self-evaluates the response
-4. **Aggregate** — Results are written to `runs.jsonl` and aggregated into a report
+## Task
-The skill doc is generated fresh each time, so it always reflects the current branch's components. No manual maintenance of component lists needed.
+Build a shipping method selector with three options: Standard (free, 5-7 days),
+Express ($9.99, 2-3 days), Overnight ($19.99, next day)
-## Quick Start - API Mode
+## Output
-```bash
-# Requires ANTHROPIC_API_KEY (direct Anthropic mode)
-yarn workspace @xds/vibe-tests test:xds:sample
+Write the TSX code to: internal/vibe-tests/results/<id>/results/fwc-6.tsx
+Write metadata to: internal/vibe-tests/results/<id>/results/fwc-6.json
-# Or use the Navi-orchestrated pipeline (no API key needed):
-# 1. Navi sub-agents generate TSX results
-# 2. GHA builds previews and captures screenshots
-# See: .github/workflows/vibe-screenshots.yml
+Metadata: {"completedAt": "<ISO timestamp>", "docsRead": [<component names you looked up>]}
+Write ONLY valid TSX. No markdown fences, no explanation.
```
-## What It Does
-
-The harness:
-
-1. **Tests** LLM responses against the component system using realistic prompts
-2. **Evaluates** whether the LLM used the right components and avoided escape hatches
-3. **Analyzes** failures to suggest documentation improvements
-4. **Tracks** degradation over conversation length
-
-## Directory Structure
+**Baseline (shadcn) agent sees:**
```
-internal/vibe-tests/
-├── src/
-│ ├── cli.ts # Command-line interface
-│ ├── types.ts # TypeScript types
-│ ├── runner.ts # Test orchestration
-│ ├── evaluator.ts # Response evaluation
-│ ├── analyst.ts # Results analysis
-│ ├── sampling.ts # Stratified sampling
-│ ├── universal-eval.ts # 5-dimension static analysis (code-level)
-│ ├── universal-aggregate.ts # Aggregate scores across prompts
-│ ├── universal-compare.ts # Compare XDS vs baseline vs HTML
-│ ├── design-judge.ts # 6th dimension: vision LLM visual fidelity judge
-│ ├── screenshot-previews.ts # Playwright screenshots of pre-built HTML
-│ ├── build-previews.ts # Build self-contained HTML from results
-│ ├── build-report.ts # Build static report HTML + inject data
-│ ├── deploy-report.ts # Deploy report + screenshots to gh-pages
-│ └── utils.ts # Utilities
-├── ideals/ # Human-provided reference images for design judge
-│ └── {promptId}[-{viewport}[-{theme}]].png
-├── prompts/
-│ ├── evaluator.md # Evaluator agent prompt
-│ ├── analyst.md # Analyst agent prompt
-│ └── personas/ # User personas
-├── test-sets/
-│ └── default.json # Test prompt battery
-├── results/ # Generated (gitignored)
-│ └── {iteration-id}/
-│ ├── runs.jsonl
-│ ├── analysis.json
-│ ├── universal.json # 5+1 dimension scores
-│ ├── design-scores.json # Design dimension raw judge output
-│ └── report.html
-└── iterations.json # Iteration lineage
-```
-
-## Test Protocols
-
-### One-shot
-
-Single turn: inject skill doc → prompt → evaluate
-
-### Degradation
-
-Multi-turn conversation with re-probes:
-
-- Turn 0: Initial probe
-- Turns 1-5: Filler questions
-- Turn 6: Re-probe
-- Turn 7: Distractor ("use Tailwind instead")
-- Turn 8: Re-probe
-- Turn 9: Recovery (re-inject doc)
-- Turn 10: Final re-probe
-
-### Persona Comparison
-
-Run same prompts with different personas:
-
-- **naive**: Plain language, no component names
-- **experienced**: Uses correct terminology
-- **adversarial**: Mixes in patterns from other frameworks
-
-## Escape Hatches
-
-Tracked behaviors when LLMs deviate from the component system:
-
-**Critical (Red tier - failures):**
-
-- `hallucination` - Invented props/events/components
-- `wrong_component` - Using a component incorrectly
-- `redundant_css` - CSS that duplicates a component prop
-
-**Anti-Patterns (Yellow tier - break theming):**
+You are generating React/TSX code using shadcn/ui components with Tailwind CSS.
-- `hardcoded_color` - Direct color values instead of CSS variables
-- `hardcoded_spacing` - Direct pixel values instead of spacing tokens
-- `hardcoded_size` - Direct pixel values instead of size tokens
-- `inline_style` - Inline styles instead of StyleX
+Read the baseline docs at internal/vibe-tests/.baseline-docs/
+and AGENTS.baseline.md for component guidance.
-**Acceptable (Green tier - gaps in system):**
+## Task
-- `supplemental_css` - StyleX for gaps in component coverage
-- `wrapper_div` - Structural HTML for composition
-- `custom_animation` - Animation not covered by XDS
-- `layout_workaround` - Layout patterns XDS doesn't support
+Build a shipping method selector with three options: Standard (free, 5-7 days),
+Express ($9.99, 2-3 days), Overnight ($19.99, next day)
-## Quality Tiers
-
-Results are scored into four quality tiers:
-
-- 🥇 **Gold** - Pure XDS, no escape hatches needed
-- 🟢 **Green** - Correct components, only acceptable escape hatches
-- 🟡 **Yellow** - Anti-patterns that break theming
-- 🔴 **Red** - Critical failures
-
-The aggregate report shows tier breakdown by category and generates suggestions for component/API improvements based on escape hatch patterns.
-
-## Configuration
-
-Set skill doc path:
-
-```bash
-SKILL_DOC=./path/to/skill.md yarn harness run
-# or
-yarn harness run --skill-doc ./path/to/skill.md
+## Output
+...same format...
```
-Choose model:
+**HTML agent sees:**
-```bash
-yarn harness run --model claude-sonnet-4-20250514
-yarn harness run --model gpt-4o
```
+You are generating React/TSX code using ONLY plain HTML elements and inline CSS.
+Do NOT use any component library. Use standard HTML elements (div, button, input, etc.)
+with inline styles or a styles object.
-## Output
+## Task
-After running tests:
+Build a shipping method selector with three options: Standard (free, 5-7 days),
+Express ($9.99, 2-3 days), Overnight ($19.99, next day)
+## Output
+...same format...
```
-Running vibeability tests...
- Protocol: one-shot
- Persona: naive
- Model: claude-sonnet-4-20250514
- Test set: default (21 prompts)
- Iteration: a1b2c3d4
-
- [████████████████████] 21/21
-
-Results:
- Overall: 86% success (18/21)
-
- Quality Tiers:
- 🥇 Gold (pure XDS): 5 (24%)
- 🟢 Green (acceptable): 10 (48%)
- 🟡 Yellow (anti-pattern): 3 (14%)
- 🔴 Red (critical): 3 (14%)
-
- Performance:
- Total time: 45.2s (avg 2.2s per test)
- Tokens: 125,000 total (100,000 in / 25,000 out)
-
- By category:
- feature-with-constraint: 100% [🥇2 🟢1 🟡0 🔴0]
- workflow-description: 67% [🥇0 🟢1 🟡1 🔴1]
- ...
-
- Critical issues (Red):
- - hallucination (3)
-
- Anti-patterns (Yellow):
- - hardcoded_color (2)
- - hardcoded_spacing (1)
- - inline_style (3)
-
- Acceptable escape hatches (Green):
- - supplemental_css (8)
- - wrapper_div (4)
-
- Gap Suggestions:
- 🎨 [trivial] Add semantic color token for: accent backgrounds (seen 2x)
- 🔧 [trivial] Add spacing/size prop to cover: card padding (seen 1x)
-
- HTML Report: results/a1b2c3d4/report.html
-```
-
-### HTML Report
-The aggregate command generates an interactive HTML report at `results/<iteration>/report.html` that shows:
+Note: no system-specific rules, no expected components, no pre-built commands. The agent discovers what it needs through the system's own docs.
-- Summary stats (success rate, timing, tokens)
-- Results by category with progress bars
-- Critical issues and escape hatches
-- Individual test results with expandable code responses
+## Checker Protocol
-After analysis:
+**Before running or modifying any vibe test, verify these 5 invariants.**
-```
-Analyzing iteration a1b2c3d4...
+### 1. Fair Evaluators
-Patterns detected:
- - Multi-step workflows trigger hallucinated state props
- - Adversarial persona causes Tailwind utility usage
+- Same evaluation logic across all configurations (tsc, scoring dimensions)
+- Same pass/fail criteria — don't score one config differently than another
+- Target-aware scoring is OK (different systems need different counting methods) but the judgments must be equivalent
+- Evaluation must be blind to which config produced the output
-Suggested refinements:
- 1. [examples] Add multi-step form example (confidence: 0.9, effort: trivial)
- 2. [skill_doc] Explicit "do not use Tailwind" note (confidence: 0.7, effort: trivial)
-```
+### 2. Only the System Under Test Varies
-## CI Integration
+- Same prompts across all configurations (same IDs, same text)
+- Same persona across all configurations
+- Same output format requirements
+- Equivalent sub-agent instructions — if one config gets "read the README", all get an analogous instruction
+- No system-specific coaching rules (e.g. "use StyleX" or "use Tailwind") — let the docs teach that
-### Screenshot Service (`.github/workflows/vibe-screenshots.yml`)
+### 3. Never Leak the Answer
-The primary workflow for nightly vibe tests. Triggered by Navi via `workflow_dispatch`:
+- `expectedComponents` is for evaluation ONLY — never include in the sub-agent prompt
+- Don't pre-build retrieval commands from expected components
+- Don't hint at which components to use
+- Don't include rules that only make sense for one system
+- The agent should discover the right approach through the system's own docs
-```bash
-gh workflow run vibe-screenshots.yml -f iterations="<id1>,<id2>,<id3>"
-```
+### 4. Representative Environment
-**What it does:**
+- Sub-agents should have a realistic project setup (node_modules, package.json)
+- The docs/tools available should match what a real consumer would have
+- Don't give sub-agents access to the source repo if a real user would only have the npm package
+- Test the actual delivery mechanism (README in node_modules, not hand-written skill docs)
-1. Builds self-contained HTML previews from TSX results (inlines all CSS via vite-plugin-singlefile)
-2. Captures Playwright screenshots at 4 combos: desktop/mobile × light/dark
-3. Uploads preview HTML and screenshots as artifacts (90-day retention)
+### 5. Context-Free Sub-Agents
-**No API keys required.** Code generation is handled by Navi sub-agents before this workflow runs.
+- Sub-agents must be spawned fresh with no prior conversation context
+- No inherited knowledge about the design system from the parent session
+- The sub-agent's only knowledge comes from what it discovers during the task
+- Don't reuse sub-agent sessions across prompts — each prompt gets a fresh agent
-### Design Judge (`src/design-judge.ts`)
+## How to Verify
-Vision LLM evaluation comparing rendered screenshots against human-provided ideal reference images.
+Before any test run, review the generated task prompts:
```bash
-# Dry run — shows what would be evaluated without API calls
-yarn workspace @xds/vibe-tests design-judge --iteration <id> --dry-run
+# Generate an iteration without running it
+node internal/vibe-tests/src/setup-iteration.mjs --sample 3 --target xds
+node internal/vibe-tests/src/setup-iteration.mjs --sample 3 --target baseline
-# Full run — 3 passes per screenshot, desktop + light
-yarn workspace @xds/vibe-tests design-judge --iteration <id>
-
-# Custom: specific prompts, 5 passes, mobile dark
-yarn workspace @xds/vibe-tests design-judge --iteration <id> --prompts cwm-1,ty-3 --passes 5 --viewport mobile --theme dark
+# Read the task files and compare:
+# - Are the prompts identical (same task text)?
+# - Does either prompt contain expectedComponents or pre-built commands?
+# - Does either prompt contain system-specific coaching rules?
+# - Do the doc retrieval instructions point to representative paths?
```
-**Requires:** `ANTHROPIC_API_KEY` environment variable. Uses Claude Sonnet for vision analysis.
-
-**Prerequisite:** Ideal reference images in `internal/vibe-tests/ideals/`. Only prompts with both screenshots and ideals are evaluated.
+For evaluation fairness, check `universal-eval.ts`:
-**Output:** `results/<iteration>/design-scores.json` — scores are automatically merged into `universal.json` when the aggregate runs.
+- Search for `target ===` to find all target-aware branches
+- Verify each branch is measuring the equivalent concept for its system
+- Watch for any target getting a skip/bonus the others don't
-### Direct API Mode (legacy)
+## Known Accepted Asymmetries
-The `test:xds:sample` script calls Anthropic directly and requires `ANTHROPIC_API_KEY`. This is the old all-in-one flow — prefer the Navi-orchestrated pipeline for nightly runs.
+These are intentional and documented — they slightly favor baseline, making XDS wins more credible:
-### Aggregate CLI Flags:
+- **Efficiency:** Tailwind's single-line `className` gets a lower styling-ratio than XDS's multi-line `stylex.create` blocks, despite encoding more decisions
+- **Maintainability:** Tailwind scale values (`p-4`, `text-sm`) count as semantic, which is generous compared to how raw `16px` is counted for HTML
-```bash
-# Standard output
-yarn workspace @xds/vibe-tests aggregate --iteration abc123
-
-# JSON output (for scripting)
-yarn workspace @xds/vibe-tests aggregate --iteration abc123 --json
+## Directory Structure
-# CI mode (GitHub Actions output format)
-yarn workspace @xds/vibe-tests aggregate --iteration abc123 --ci
```
-
-## For More Details
-
-See the source code and CLI help (`yarn workspace @xds/vibe-tests --help`) for the current test harness spec.
+internal/vibe-tests/
+├── test-sets/ # Prompt batteries (JSON)
+├── src/ # Runner scripts and evaluation
+│ ├── setup-iteration.mjs # Single-target iteration setup
+│ ├── setup-nightly.mjs # 3-target nightly setup
+│ ├── universal-eval.ts # Static analysis scoring (5 dimensions)
+│ ├── universal-aggregate.ts # Score aggregation
+│ ├── universal-compare.ts # Cross-target comparison
+│ ├── build-previews.ts # TSX → HTML compilation + tsc
+│ ├── screenshot-previews.ts # Playwright screenshots
+│ ├── build-report.ts # Vite HTML report
+│ └── deploy-report.ts # gh-pages deployment
+├── .baseline/ # Real shadcn/ui components for baseline tsc
+├── results/ # Iteration results (gitignored)
+└── README.md # This file
+```
diff --git a/internal/vibe-tests/src/setup-iteration.mjs b/internal/vibe-tests/src/setup-iteration.mjs
index 20b67ab531..b9f3bf2145 100644
--- a/internal/vibe-tests/src/setup-iteration.mjs
+++ b/internal/vibe-tests/src/setup-iteration.mjs
@@ -76,35 +76,10 @@ function samplePrompts(prompts, n) {
// ── Task prompt templates ────────────────────────────────────────────
function generateXdsTaskPrompt(prompt, iterDir) {
- const componentNames = (prompt.expectedComponents || [])
- .map(c => c.replace(/^XDS/, ''));
-
- const cliCommands = componentNames
- .map(c => `npx xds component ${c}`)
- .join('\n');
-
return `You are generating React/TSX code using the XDS design system.
-## IMPORTANT: Read component docs FIRST
-
-You MUST run the following commands on the MacBook CLI node (node: "cli:MacBook-Pro-2")
-to read the component API docs BEFORE writing any code:
-
-cd ~/xds/worktrees/main
-${cliCommands}
-
-Read the output carefully. Use ONLY the props documented in the CLI output.
-Do NOT guess prop names or values. If you need additional components beyond
-the ones listed above, look them up too: npx xds component <Name>
-
-## Rules
-
-1. Import from '@xds/core' (e.g. import { XDSButton } from '@xds/core')
-2. Use StyleX for custom styling (import * as stylex from '@stylexjs/stylex')
-3. Use CSS variables for tokens: var(--color-*), var(--spacing-*), var(--radius-*)
-4. Form inputs are controlled: value + onChange
-5. No <div> for layout — use XDSVStack, XDSHStack, XDSGrid
-6. Export default a single React component
+Read the package README at ${path.resolve(VIBE_DIR, '../../packages/core/README.md')} for how to look up
+component docs. Use what you find there to discover the components you need.
## Task
@@ -115,20 +90,15 @@ ${prompt.prompt}
Write the TSX code to: ${path.join(iterDir, 'results', `${prompt.id}.tsx`)}
Write metadata to: ${path.join(iterDir, 'results', `${prompt.id}.json`)}
-The metadata JSON should contain:
-{
- "completedAt": "<current ISO timestamp>",
- "docsRead": [<list of component names you looked up via CLI>]
-}
-
-Write ONLY valid TSX in the .tsx file. No markdown fences, no explanation.`;
+Metadata: {"completedAt": "<ISO timestamp>", "docsRead": [<component names you looked up>]}
+Write ONLY valid TSX. No markdown fences, no explanation.`;
}
function generateBaselineTaskPrompt(prompt, iterDir) {
return `You are generating React/TSX code using shadcn/ui components with Tailwind CSS.
-Read the baseline docs at /vercel/sandbox/repos/xds/internal/vibe-tests/.baseline-docs/
-and AGENTS.baseline.md for component guidance.
+Read the README at ${path.join(VIBE_DIR, '.baseline', 'README.md')} for component guidance.
+The actual component sources are in ${path.join(VIBE_DIR, '.baseline', 'components', 'ui')}/.
## Task
diff --git a/internal/vibe-tests/src/setup-nightly.mjs b/internal/vibe-tests/src/setup-nightly.mjs
index ff827c0815..1ddb1e0bca 100644
--- a/internal/vibe-tests/src/setup-nightly.mjs
+++ b/internal/vibe-tests/src/setup-nightly.mjs
@@ -78,36 +78,10 @@ function samplePrompts(prompts, n) {
// ── Task prompt templates ────────────────────────────────────────────
function generateXdsTaskPrompt(prompt, iterDir) {
- const componentNames = (prompt.expectedComponents || []).map(c =>
- c.replace(/^XDS/, ''),
- );
-
- const cliCommands = componentNames
- .map(c => `npx xds component ${c}`)
- .join('\n');
-
return `You are generating React/TSX code using the XDS design system.
-## IMPORTANT: Read component docs FIRST
-
-You MUST run the following commands on the MacBook CLI node (node: "cli:MacBook-Pro-2")
-to read the component API docs BEFORE writing any code:
-
-cd ~/xds/worktrees/main
-${cliCommands}
-
-Read the output carefully. Use ONLY the props documented in the CLI output.
-Do NOT guess prop names or values. If you need additional components beyond
-the ones listed above, look them up too: npx xds component <Name>
-
-## Rules
-
-1. Import from '@xds/core' (e.g. import { XDSButton } from '@xds/core')
-2. Use StyleX for custom styling (import * as stylex from '@stylexjs/stylex')
-3. Use CSS variables for tokens: var(--color-*), var(--spacing-*), var(--radius-*)
-4. Form inputs are controlled: value + onChange
-5. No <div> for layout — use XDSVStack, XDSHStack, XDSGrid
-6. Export default a single React component
+Read the package README at ${path.resolve(VIBE_DIR, '../../packages/core/README.md')} for how to look up
+component docs. Use what you find there to discover the components you need.
## Task
@@ -118,20 +92,15 @@ ${prompt.prompt}
Write the TSX code to: ${path.join(iterDir, 'results', `${prompt.id}.tsx`)}
Write metadata to: ${path.join(iterDir, 'results', `${prompt.id}.json`)}
-The metadata JSON should contain:
-{
- "completedAt": "<current ISO timestamp>",
- "docsRead": [<list of component names you looked up via CLI>]
-}
-
-Write ONLY valid TSX in the .tsx file. No markdown fences, no explanation.`;
+Metadata: {"completedAt": "<ISO timestamp>", "docsRead": [<component names you looked up>]}
+Write ONLY valid TSX. No markdown fences, no explanation.`;
}
function generateBaselineTaskPrompt(prompt, iterDir) {
return `You are generating React/TSX code using shadcn/ui components with Tailwind CSS.
-Read the baseline docs at ${VIBE_DIR}/.baseline-docs/
-and ${VIBE_DIR}/AGENTS.baseline.md for component guidance.
+Read the README at ${VIBE_DIR}/.baseline/README.md for component guidance.
+The actual component sources are in ${VIBE_DIR}/.baseline/components/ui/.
## Task
diff --git a/internal/vibe-tests/src/universal-eval.ts b/internal/vibe-tests/src/universal-eval.ts
index 8534c5bd4c..f29159882d 100644
--- a/internal/vibe-tests/src/universal-eval.ts
+++ b/internal/vibe-tests/src/universal-eval.ts
@@ -190,19 +190,14 @@ function analyzeAccessibility(code: string): DimensionScore {
// Form inputs without labels (skip XDS inputs with built-in labels)
if (line.match(/<(input|Input)\b/) && !line.includes('type="hidden"')) {
- const isXdsInput = /XDS(TextInput|NumberInput|DateInput|TimeInput)/.test(
- nearby,
- );
- if (!isXdsInput) {
- const hasLabel = /(label|Label|aria-label|ariaLabel)/.test(nearby);
- if (!hasLabel) {
- findings.push({
- rule: 'input-no-label',
- severity: 'critical',
- detail: 'Form input without associated label',
- line: lineNum,
- });
- }
+ const hasLabel = /(label|Label|aria-label|ariaLabel)/.test(nearby);
+ if (!hasLabel) {
+ findings.push({
+ rule: 'input-no-label',
+ severity: 'critical',
+ detail: 'Form input without associated label',
+ line: lineNum,
+ });
}
}
@@ -793,18 +788,6 @@ function analyzeMaintainability(
});
}
- // --- Dark mode support ---
- let darkModeSupport = false;
- if (target === 'xds') {
- darkModeSupport = /dark(Theme|Mode|_mode)|mode\s*=\s*["']dark/i.test(code);
- } else if (target === 'baseline') {
- darkModeSupport = /\bdark:|\buseTheme\b|ThemeProvider|data-theme/i.test(
- code,
- );
- } else {
- darkModeSupport = /prefers-color-scheme|dark-mode|data-theme/i.test(code);
- }
-
// --- State spread (locality) ---
const avgStateSpread = measureStateSpread(code);
@@ -827,11 +810,10 @@ function analyzeMaintainability(
magicValueCount: magic,
semanticValueCount: semantic,
avgStateSpread,
- darkModeSupport,
};
// Score: semantic ratio is the primary signal (0-60 points),
- // locality adds up to 20, dark mode adds 10, findings subtract
+ // locality adds up to 20, findings subtract
const semanticScore = semanticRatio * 60;
const localityScore =
avgStateSpread < 30
@@ -841,8 +823,7 @@ function analyzeMaintainability(
: avgStateSpread < 100
? 6
: 0;
- const darkModeScore = darkModeSupport ? 10 : 0;
- const baseScore = semanticScore + localityScore + darkModeScore + 10; // 10 free points
+ const baseScore = semanticScore + localityScore + 20; // 20 base points (was 10 + 10 dark mode)
const findingPenalty = findings.reduce((s, f) => {
switch (f.severity) {
diff --git a/packages/core/README.md b/packages/core/README.md
index 346e675873..ef9f2ef6a9 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,209 +1,30 @@
-# @xds/core
+# XDS
-A design system for building internal tools and products at Meta.
+XDS is a design system for building internal tools and products.
-## Installation
+## Component Docs
-```bash
-# Install core + a theme + the CLI (dev tooling)
-yarn add @xds/core @xds/theme-default
-yarn add -D @xds/cli
-
-# npm
-npm install @xds/core @xds/theme-default
-npm install -D @xds/cli
-
-# pnpm
-pnpm add @xds/core @xds/theme-default
-pnpm add -D @xds/cli
-```
-
-## Quick Start
-
-### 1. Import CSS
-
-Import the reset, base component styles, and your theme's CSS at the root of your application:
-
-```tsx
-// In your root layout or entry point
-import '@xds/core/reset.css'; // CSS reset (normalize + box-sizing)
-import '@xds/core/xds.css'; // Pre-compiled component styles
-import '@xds/theme-default/theme.css'; // Theme tokens
-```
-
-> **Building from source with the StyleX plugin?** You can skip `xds.css` —
-> the plugin compiles component styles at build time. See the
-> [Vite example](apps/example-vite/) for the source-path setup.
-
-### 2. Set Up the Theme Provider
-
-Wrap your application with the `XDSTheme` component:
-
-```tsx
-import {XDSTheme} from '@xds/core';
-import {defaultTheme} from '@xds/theme-default';
-
-function App() {
- return (
- <XDSTheme theme={defaultTheme}>
- <YourApp />
- </XDSTheme>
- );
-}
-```
-
-### 3. Use Components
-
-```tsx
-import {XDSButton, XDSText, XDSHeading} from '@xds/core';
-
-function Example() {
- return (
- <>
- <XDSHeading>Welcome</XDSHeading>
- <XDSText>Click the button below to get started.</XDSText>
- <XDSButton label="Get Started" onClick={() => console.log('clicked')} />
- </>
- );
-}
-```
-
-## Installation from dist (vendored)
-
-If you'd rather vendor XDS without a package manager:
-
-1. Ensure React is available. XDS peer-requires `react` and `react-dom` (>=19.0.0).
-2. Run `yarn build` to generate the dist files.
-3. Copy `packages/core/dist/` into your project (e.g., `vendor/xds/`).
-4. Import the CSS — `reset.css` for the reset, `xds.css` for all component styles:
-
-You can use a `<link>` tag or a CSS import (recommended):
-
-```
-import '../vendor/xds/reset.css';
-import '../vendor/xds/xds.css';
-```
-
-5. Import components. If you are using a bundler such as Vite/TS you can add a resolver so you can use standard imports:
-
-Add this to `vite.config.ts`:
-
-```
- resolve: {
- alias: {
- '@xds/core': path.resolve(__dirname, 'vendor/xds'),
- },
- },
-```
-
-Add this to `tsconfig.json`:
-
-```
- "paths": {
- "@xds/core/*": ["./vendor/xds/*"]
- },
-```
-
-Then you can use standard imports as described in "Use Components" above. Alternatively you can use relative imports:
-
-```
-// Import from index
-import {Button} from './vendor/xds/index.mjs'
-// Or import individual components (preferred)
-import {Button} from './vendor/xds/Button/index.mjs'
-```
-
-## CLI Tooling
-
-The `@xds/cli` package provides component docs, scaffolding, and upgrade tooling:
-
-```bash
-xds component --list # Browse all components by category
-xds component Button # Full docs for a component (props, usage, examples)
-xds docs principles # Design rules and anti-patterns
-xds docs tokens # Token reference (spacing, color, radius, type)
-xds template <name> [path] # Scaffold a page (blank, table, login)
-xds swizzle <Name> # Eject component source for customization
-```
-
-> If `@xds/cli` is installed as a devDependency, use `xds` directly (yarn/pnpm resolve it from `node_modules/.bin`). Otherwise, use `npx xds`.
-
-### Initialize your project
-
-Run `xds init` to set up project configuration:
-
-```bash
-xds init
-```
-
-This walks you through setting up agent docs, templates, and other project-level configuration.
-
-### AI Agent Setup
-
-If you use AI coding agents (Claude Code, Cursor, Codex, etc.), install the XDS component catalog into your project's agent docs:
+Look up any component's full API — props, types, best practices, and theming:
```bash
-xds init --features agents
+node node_modules/@xds/core/docs.mjs Button # full docs for a component
+node node_modules/@xds/core/docs.mjs --list # list all components
+node node_modules/@xds/core/docs.mjs --list --brief # brief summaries
```
-This injects a compact component index into your CLAUDE.md or AGENTS.md so your AI agent can discover and correctly use XDS components. Re-run after upgrading XDS to keep the index current.
-
-## Upgrading
-
-When upgrading to a new version, use the built-in upgrade command to automatically migrate breaking API changes:
+## XDS CLI
-```bash
-xds upgrade --apply
-```
-
-This bumps all `@xds/*` dependencies, runs `yarn install`, applies codemods for breaking changes, and refreshes agent docs if present. To migrate between specific versions:
+For richer documentation including templates, scaffolding, and tooling utilities, install the XDS CLI:
```bash
-xds upgrade --apply --from 0.0.1 --to 0.0.2
-```
-
-Preview what would change without writing to disk:
-
-```bash
-xds upgrade
-```
-
-## Themes
-
-XDS supports pluggable themes. Install a theme package and pass it to `XDSTheme`:
-
-| Package | Description |
-| -------------------- | --------------------------- |
-| `@xds/theme-default` | Clean, professional default |
-| `@xds/theme-neutral` | Muted, minimal aesthetic |
-
-Each theme package exports a JS theme object and a `theme.css` file:
-
-```bash
-yarn add @xds/theme-neutral
-```
-
-```tsx
-import '@xds/theme-neutral/theme.css';
-import {neutralTheme} from '@xds/theme-neutral';
-
-<XDSTheme theme={neutralTheme}>...</XDSTheme>;
-```
-
-### Custom Themes
-
-Build your own theme with `defineTheme()`. For a full guide on creating custom themes, token overrides, and component style customization:
-
-```bash
-xds docs theme
+npx xds --help # full listing of CLI capabilities
+npx xds component Button # full docs + related templates
+npx xds template --list # browse page and block templates
+npx xds template Dashboard --skeleton # scaffold a template
+npx xds docs # principles, tokens, theming, and styling reference
```
## Resources
- [Component Storybook](https://facebookexperimental.github.io/xds/)
- [GitHub Repository](https://github.com/facebookexperimental/xds)
-- [Changelog](https://github.com/facebookexperimental/xds/blob/main/packages/core/CHANGELOG.md)
-
-## License
-
-MIT
diff --git a/packages/core/docs.mjs b/packages/core/docs.mjs
new file mode 100644
index 0000000000..b18ab5929c
--- /dev/null
+++ b/packages/core/docs.mjs
@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+/**
+ * @file Lightweight XDS component docs — zero dependencies, ships with @xds/core.
+ *
+ * Usage:
+ * node node_modules/@xds/core/docs.mjs Button
+ * node node_modules/@xds/core/docs.mjs --list
+ * node node_modules/@xds/core/docs.mjs --list --brief
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+
+const coreDir = path.dirname(new URL(import.meta.url).pathname);
+const srcDir = path.join(coreDir, 'src');
+
+// ── Discovery ────────────────────────────────────────────────────────
+
+const CATEGORY_MAP = {
+ AspectRatio: 'Layout', Center: 'Layout', CollapsibleGroup: 'Layout',
+ Grid: 'Layout', Layout: 'Layout', Stack: 'Layout',
+ Avatar: 'Display', Badge: 'Display', Divider: 'Display',
+ Icon: 'Display', Skeleton: 'Display', Table: 'Display', Text: 'Display',
+ CheckboxInput: 'Form', DateInput: 'Form', Field: 'Form',
+ NumberInput: 'Form', RadioList: 'Form', Selector: 'Form',
+ Slider: 'Form', Switch: 'Form', TextArea: 'Form', TextInput: 'Form',
+ TimeInput: 'Form',
+ Button: 'Action', CloseButton: 'Action', DropdownMenu: 'Action', Link: 'Action',
+ TabList: 'Navigation', TopNav: 'Navigation',
+ Calendar: 'Overlay', Dialog: 'Overlay', Layer: 'Overlay',
+};
+const CATEGORY_ORDER = ['Layout', 'Display', 'Form', 'Action', 'Navigation', 'Overlay', 'Other'];
+const SKIP = new Set(['theme', 'hooks', 'utils', '__tests__', 'node_modules']);
+
+function discoverDocs() {
+ const results = [];
+ if (!fs.existsSync(srcDir)) return results;
+ for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
+ if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
+ const docPath = findDocFile(entry.name);
+ if (docPath) results.push({dir: entry.name, docPath});
+ }
+ return results;
+}
+
+function findDocFile(name) {
+ const direct = path.join(srcDir, name, `${name}.doc.mjs`);
+ if (fs.existsSync(direct)) return direct;
+ const dir = path.join(srcDir, name);
+ if (!fs.existsSync(dir)) return null;
+ for (const sub of fs.readdirSync(dir, {withFileTypes: true})) {
+ if (sub.isDirectory()) {
+ const nested = path.join(dir, sub.name, `${sub.name}.doc.mjs`);
+ if (fs.existsSync(nested)) return nested;
+ }
+ }
+ return null;
+}
+
+function findDocByComponent(name) {
+ let docPath = findDocFile(name);
+ if (docPath) return docPath;
+ for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
+ if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
+ const nested = path.join(srcDir, entry.name, name, `${name}.doc.mjs`);
+ if (fs.existsSync(nested)) return nested;
+ }
+ // Fuzzy: find XDS{Name}.tsx and use parent doc
+ for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
+ if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
+ const dir = path.join(srcDir, entry.name);
+ if (hasXDSFile(dir, name)) {
+ const doc = findDocInDir(dir);
+ if (doc) return doc;
+ }
+ }
+ return null;
+}
+
+function hasXDSFile(dir, name) {
+ const target = `XDS${name}.tsx`;
+ try {
+ for (const f of fs.readdirSync(dir, {withFileTypes: true})) {
+ if (f.name === target) return true;
+ if (f.isDirectory() && hasXDSFile(path.join(dir, f.name), name)) return true;
+ }
+ } catch {}
+ return false;
+}
+
+function findDocInDir(dir) {
+ try {
+ for (const f of fs.readdirSync(dir)) {
+ if (f.endsWith('.doc.mjs')) return path.join(dir, f);
+ }
+ } catch {}
+ return null;
+}
+
+// ── Loading ──────────────────────────────────────────────────────────
+
+async function loadDoc(docPath) {
+ const mod = await import(pathToFileURL(docPath).href);
+ return mod.docs;
+}
+
+// ── Formatting ───────────────────────────────────────────────────────
+
+function formatPropsTable(props) {
+ if (!props?.length) return '';
+ const lines = ['| Prop | Type | Default | Description |', '|------|------|---------|-------------|'];
+ 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');
+}
+
+function formatFull(docs) {
+ const s = [];
+ s.push(`# ${docs.name}\n`);
+ s.push((docs.usage?.description || '') + '\n');
+
+ if (docs.usage?.anatomy?.length) {
+ s.push('## Anatomy\n');
+ s.push('| Element | Required | Description |');
+ s.push('|---------|----------|-------------|');
+ for (const el of docs.usage.anatomy)
+ s.push(`| ${el.name} | ${el.required ? 'Yes' : 'No'} | ${el.description} |`);
+ s.push('');
+ }
+
+ if (docs.usage?.bestPractices?.length) {
+ s.push('## Best Practices\n');
+ for (const bp of docs.usage.bestPractices)
+ s.push(`- ${bp.guidance ? '**Do:**' : "**Don't:**"} ${bp.description}`);
+ s.push('');
+ }
+
+ if ('props' in docs) {
+ s.push('## Props\n');
+ s.push(formatPropsTable(docs.props) + '\n');
+ }
+
+ if ('components' in docs) {
+ s.push('## Components\n');
+ for (const comp of docs.components) {
+ s.push(`### ${comp.name}\n`);
+ s.push(comp.description + '\n');
+ s.push(formatPropsTable(comp.props) + '\n');
+ }
+ }
+
+ if (docs.theming?.targets?.length) {
+ s.push('## Theming\n');
+ s.push('| Class | Variants | States |');
+ s.push('|-------|----------|--------|');
+ for (const t of docs.theming.targets) {
+ const variants = t.visualProps?.join(', ') || '—';
+ const states = t.states?.join(', ') || '—';
+ s.push(`| \`${t.className}\` | ${variants} | ${states} |`);
+ }
+ s.push('');
+ const publicVars = docs.theming.vars?.filter(v => !v.private && !v.derived) || [];
+ if (publicVars.length) {
+ s.push('| CSS Variable | Default | Description |');
+ s.push('|-------------|---------|-------------|');
+ for (const v of publicVars)
+ s.push(`| \`${v.name}\` | \`${v.default}\` | ${v.description} |`);
+ s.push('');
+ }
+ }
+
+ return s.join('\n');
+}
+
+function formatBrief(docs) {
+ const desc = docs.usage?.description || '';
+ const short = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;
+ const props = docs.props || docs.components?.[0]?.props || [];
+ const sig = props
+ .filter(p => p.type.includes('|') && !p.type.includes('ReactNode'))
+ .map(p => `${p.name}: ${p.type.replace(/['"]/g, '').split('|').map(v => v.trim()).join('|')}`)
+ .join(', ');
+ return sig ? `XDS${docs.name}(${sig}) ${short}` : `XDS${docs.name} ${short}`;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const isList = args.includes('--list');
+const isBrief = args.includes('--brief');
+const name = args.find(a => !a.startsWith('--'));
+
+if (isList) {
+ const docs = discoverDocs();
+ const grouped = {};
+ for (const {dir, docPath} of docs) {
+ const cat = CATEGORY_MAP[dir] || 'Other';
+ if (!grouped[cat]) grouped[cat] = [];
+ grouped[cat].push({dir, docPath});
+ }
+ for (const cat of CATEGORY_ORDER) {
+ if (!grouped[cat]) continue;
+ console.log(`\n${cat}:`);
+ for (const {dir, docPath} of grouped[cat]) {
+ if (isBrief) {
+ try {
+ const d = await loadDoc(docPath);
+ console.log(' ' + formatBrief(d));
+ } catch {
+ console.log(` XDS${dir} (error loading docs)`);
+ }
+ } else {
+ console.log(` ${dir}`);
+ }
+ }
+ }
+} else if (name) {
+ const docPath = findDocByComponent(name);
+ if (!docPath) {
+ console.error(`Component "${name}" not found. Run with --list to see available components.`);
+ process.exit(1);
+ }
+ const docs = await loadDoc(docPath);
+ console.log(formatFull(docs));
+} else {
+ console.log('Usage:');
+ console.log(' node docs.mjs <ComponentName> Show full component docs');
+ console.log(' node docs.mjs --list List all components');
+ console.log(' node docs.mjs --list --brief List with brief descriptions');
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index c7b74c4e47..40bb9f1961 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -39,7 +39,7 @@
"import": "./dist/theme/syntax/index.mjs",
"require": "./dist/theme/syntax/index.js"
},
- "./xds.md": "./xds.md",
+ "./docs.mjs": "./docs.mjs",
"./AlertDialog": {
"source": "./src/AlertDialog/index.ts",
"types": "./dist/AlertDialog/index.d.ts",
@@ -524,7 +524,8 @@
"files": [
"dist",
"src",
- "xds.md"
+ "docs.mjs",
+ "README.md"
],
"scripts": {
"prepack": "yarn build",
diff --git a/packages/core/xds.md b/packages/core/xds.md
deleted file mode 100644
index 3fe6d7785f..0000000000
--- a/packages/core/xds.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# XDS
-
-XDS is a design system for building internal tools and products.
-
-## Getting Started
-
-Use the XDS CLI for component docs, scaffolding, and tooling:
-
-```bash
-npx xds component --list # browse all components by category
-npx xds component Button # full docs for a component
-npx xds --detail brief component --list # brief summaries of all components
-npx xds docs # principles and tokens reference
-```
-
-### For AI-assisted development
-
-Run `xds init --features agents` in your project to install the XDS component catalog into your AGENTS.md:
-
-```bash
-npx xds init --features agents
-```
-
-This adds an auto-generated component index that AI coding agents use to discover and correctly use XDS components. Re-run after updating XDS to keep the index current.
-
-### Resources
-
-- [Component Storybook](https://facebookexperimental.github.io/xds/)
-- [GitHub Repository](https://github.com/facebookexperimental/xds)
diff --git a/scripts/sync-exports.js b/scripts/sync-exports.js
index 7f4290153d..66a0d872d5 100644
--- a/scripts/sync-exports.js
+++ b/scripts/sync-exports.js
@@ -62,7 +62,7 @@ const STATIC_EXPORTS = {
import: './dist/theme/syntax/index.mjs',
require: './dist/theme/syntax/index.js',
},
- './xds.md': './xds.md',
+ './docs.mjs': './docs.mjs',
};
/**