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.mdnew file mode 100644index 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.mdindex 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.mjsindex 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')}/.## Taskdiff --git a/internal/vibe-tests/src/setup-nightly.mjs b/internal/vibe-tests/src/setup-nightly.mjsindex 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/.## Taskdiff --git a/internal/vibe-tests/src/universal-eval.ts b/internal/vibe-tests/src/universal-eval.tsindex 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 subtractconst 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.mdindex 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--MITdiff --git a/packages/core/docs.mjs b/packages/core/docs.mjsnew file mode 100644index 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.jsonindex 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.mddeleted file mode 100644index 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.jsindex 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',};/**