Skip to content

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

TypeScript

chore: migrate .context to GitHub wiki (#365)

Cindy Zhangdce961a58b61
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
index daace81f30..5ba7fbdc45 100644
--- a/.claude/commands/create-component.md
+++ b/.claude/commands/create-component.md
@@ -180,7 +180,7 @@ Available tokens from `tokens.stylex`:
## Reference
-See `.context/explorations/component-reference.md` for the complete Button implementation with advanced patterns like loading states and hover overlays.
+See the [Component Authoring Guide](https://github.com/facebookexperimental/xds/wiki/Component-Authoring-Guide) on the wiki for the complete Button implementation with advanced patterns like loading states and hover overlays.
## After Creation
diff --git a/.context/README.md b/.context/README.md
deleted file mode 100644
index ca7211b638..0000000000
--- a/.context/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# .context
-
-Internal knowledge base for XDS — consumed by AI and humans.
-
-## Structure
-
-```
-.context/
-├── decisions/ # Architecture Decision Records (ADRs)
-├── explorations/ # Research, analysis, brainstorms
-├── proposals/ # Feature proposals, RFCs
-├── architecture.md # System overview (create when ready)
-└── glossary.md # Terms and conventions (create when ready)
-```
-
-## Purpose
-
-- Share state between people and AI instances
-- Document architecture decisions and rationale
-- Capture explorations and brainstorms
-- Not intended as polished public documentation
diff --git a/.context/decisions/api-guidance.md b/.context/decisions/api-guidance.md
deleted file mode 100644
index af6d65832e..0000000000
--- a/.context/decisions/api-guidance.md
+++ /dev/null
@@ -1,541 +0,0 @@
-# API Guidance
-
-<!-- Referenced from CLAUDE.md for discoverability -->
-
-Consolidated reference for XDS component API conventions. This is a decision doc — it states what the conventions **are**.
-
-For detailed patterns on specific topics, see:
-
-- [Input Props Convention](./input-props-convention.md) — standard props for all input components
-- [React Transitions](../explorations/react-transitions.md) — async action patterns with `useOptimistic`
-
----
-
-## Component Naming
-
-### Anatomy
-
-```
-<System><Namespace><Variant><Type><Postfixes>
-```
-
-| Segment | Required | Example | Notes |
-| --------- | -------- | ----------------- | ------------------------------------------------------------------------------ |
-| System | ✓ | `XDS` | Always `XDS` for this design system |
-| Namespace | | `Layout` | Groups related components (e.g. `XDSLayoutHeader`, `XDSLayoutPanel`) |
-| Variant | | `Icon` | Distinguishes visual/behavioral variants (use sparingly — prefer concise APIs) |
-| Type | ✓ | `Input`, `Button` | The component's role |
-| Postfixes | | `Item`, `Group` | Compositional parts |
-
-**Examples:** `XDSButton`, `XDSTextInput`, `XDSSelector`, `XDSCheckboxInput`, `XDSVStack`
-
-### File Naming
-
-Files match export names (prefixed). This is the LLM-friendly default — no re-export indirection.
-
-```
-packages/core/src/Button/
-├── XDSButton.tsx → exports XDSButton
-├── XDSButton.test.tsx
-├── README.md
-└── index.ts → re-exports from XDSButton.tsx
-
-apps/storybook/stories/
-└── Button.stories.tsx → Storybook stories (separate from core)
-```
-
-> **Tip:** A `create-component` CLI command exists to scaffold this structure, though it may need manual adjustments.
-
-### File Structure
-
-Component source lives in `packages/core/src/`, stories live in `apps/storybook/stories/`:
-
-| File | Purpose |
-| --------------------------------------------- | ---------------------------- |
-| `packages/core/src/<Name>/XDS<Name>.tsx` | Component implementation |
-| `packages/core/src/<Name>/XDS<Name>.test.tsx` | Colocated unit tests |
-| `packages/core/src/<Name>/index.ts` | Public exports |
-| `packages/core/src/<Name>/README.md` | Component documentation |
-| `packages/core/src/<Name>/types.ts` | Shared types (if needed) |
-| `packages/core/src/<Name>/utils.ts` | Internal helpers (if needed) |
-| `packages/core/src/<Name>/hooks.ts` | Internal hooks (if needed) |
-| `apps/storybook/stories/<Name>.stories.tsx` | Storybook stories |
-
-### File Header
-
-Every component file includes a structured header for traceability:
-
-```tsx
-/**
- * @file XDSButton.tsx
- * @input Uses React forwardRef, ButtonHTMLAttributes, ReactNode
- * @output Exports XDSButton component, XDSButtonProps, XDSButtonVariant types
- * @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
- * - /packages/core/src/Button/XDSButton.test.tsx
- * - /packages/core/src/Button/index.ts
- * - /apps/storybook/stories/Button.stories.tsx
- */
-```
-
----
-
-## Hook Naming
-
-Public hooks use the `useXDS` prefix:
-
-| Prefix | Scope | Examples |
-|--------|-------|---------|
-| `useXDS` | Public API | `useXDSCollapsible`, `useXDSPopover`, `useXDSTheme` |
-| `use` (no prefix) | Internal only | `useFocusTrap`, `useControllableState` |
-
-Utility hooks that can be generally applied and have no strict connection to XDS concepts can skip the prefix (e.g., `useGridFocus`, `useListFocus`).
-
----
-
-## Prop Naming
-
-### Booleans
-
-Always prefix with `is` or `has`.
-
-| Prefix | Meaning | Examples |
-| ------ | ------------------ | ---------------------------------------------------------------------- |
-| `is` | State or condition | `isDisabled`, `isRequired`, `isOptional`, `isLabelHidden`, `isLoading` |
-| `has` | Feature toggle | `hasAutoFocus`, `hasClear`, `hasSeconds` |
-
-### Callbacks
-
-Pattern: `on{Verb}{Scope?}`
-
-Scope is optional — use it when a component has multiple parts that could apply to the same verb, to disambiguate. When there's only one thing the verb could apply to, omit the scope.
-
-| Type | Pattern | Examples |
-| -------------- | ----------------- | ------------------------------------------------ |
-| Sync handler | `on{Verb}` | `onClick`, `onChange`, `onBlur`, `onToggle` |
-| Scoped handler | `on{Verb}{Scope}` | `onSidebarCollapsedChange`, `onVisibilityChange` |
-| Async action | `on{Verb}Action` | `onClickAction`, `onChangeAction` |
-
-**When to add scope:** If a component has multiple things that could toggle, change, or collapse, add scope to clarify which one. For example, `XDSAppShell` has `onSidebarCollapsedChange` because the shell could have multiple collapsible areas. But `XDSPopover` uses `onToggle` because there's only one thing toggling.
-
-### Enums / String Unions
-
-Use `camelCase` values:
-
-```ts
-variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';
-size?: 'sm' | 'md' | 'lg';
-```
-
-### Common Enum Values
-
-Enum values should align with CSS token names where applicable:
-
-| Prop | Values | Matches Token |
-| --------- | ---------------------- | ------------------------------------- |
-| `size` | `'sm' \| 'md' \| 'lg'` | `--size-sm`, `--size-md`, `--size-lg` |
-| `padding` | `'sm' \| 'md' \| 'lg'` | `--spacing-*` tokens |
-| `margin` | `'sm' \| 'md' \| 'lg'` | `--spacing-*` tokens |
-| `variant` | component-specific | — |
-
-### Directional Props
-
-Use `start`/`end` instead of `left`/`right` for RTL support:
-
-| ✅ Do | ❌ Don't |
-| ------------ | -------------- |
-| `startIcon` | `leftIcon` |
-| `paddingEnd` | `paddingRight` |
-| `endContent` | `rightContent` |
-
-### HTML Attribute Collisions
-
-Prefix with `html` when wrapping native attributes to avoid collisions:
-
-```ts
-htmlName?: string; // maps to <input name="...">
-htmlFor?: string; // maps to <label htmlFor="...">
-```
-
----
-
-## Required vs Optional Props
-
-| Prop Category | Required? | Rationale |
-| ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `label` (interactive elements) | ✓ | Accessibility — buttons and inputs need labels. Not required for display components (e.g. `XDSText`, `XDSLink` where content _is_ the label). |
-| `value` / `onChange` | ✓ | Controlled components need both |
-| `children` | ✓ | When the component has no meaningful output without content (e.g. `XDSButton` needs a label or children) |
-| Visual variants | Optional | Safe defaults exist (`variant='secondary'`, `size='md'`) |
-| Boolean flags | Optional | Default to `false` |
-| Event handlers | Optional | Not all uses need them |
-
-**Principle:** Make behavioral/structural props required. Make presentation props optional with sensible defaults.
-
----
-
-## Composition vs Config
-
-| Use Composition When | Use Config (Props) When |
-| ------------------------------------------- | ----------------------------------------- |
-| Content is arbitrary/user-defined | Options are finite and well-known |
-| Children need access to parent context | Prop controls a single visual attribute |
-| Flexibility is needed for unknown use cases | Consistency matters more than flexibility |
-
-**Examples:**
-
-- **Config:** `variant`, `size`, `isDisabled` — finite, well-known values
-- **Composition:** `children`, `icon` as ReactNode, render functions for custom items
-
-```tsx
-// Config: finite variants
-<XDSButton variant="primary" size="md" label="Save" />
-
-// Composition: custom content via render function
-<XDSSelector items={items} value={v} onChange={setV} label="Pick">
- {(item) => <CustomItem icon={item.icon} label={item.label} />}
-</XDSSelector>
-```
-
----
-
-## Styling
-
-### Rules
-
-1. **No `className` or `style` props.** Components `Omit` these from HTML attributes.
-2. **Use `xstyle` for overrides** — accepts `StyleXStyles` only (compile-time validated).
-3. **Constrained over freeform:** Higher-level components (Button, TextInput) expose specific props (`variant`, `size`). Primitive/layout components (Stack, Box) accept `xstyle`.
-
-### `xstyle` Pattern
-
-```tsx
-import type {StyleXStyles} from '@stylexjs/stylex';
-
-interface Props {
- xstyle?: StyleXStyles;
-}
-
-// Apply xstyle last so consumer styles override defaults
-<div {...stylex.props(styles.base, xstyle)} />;
-```
-
-### Theme Overrides
-
-Components read from `ThemeContext` for theme-level variant overrides. Theme styles are applied after base styles but before consumer `xstyle`:
-
-```tsx
-const themeOverride = themeContext?.theme.components?.button?.variants?.[variant];
-// Order: base → theme override → consumer xstyle
-{...stylex.props(styles.base, variants[variant], themeOverride)}
-```
-
----
-
-## State Management
-
-### Controlled Components
-
-All input components are controlled — they require `value` and `onChange`/`onChangeAction`.
-
-| Prop | Type | Description |
-| ---------------- | ---------------------------- | -------------------------------- |
-| `value` | varies | Current value (source of truth) |
-| `onChange` | `(value, event?) => void` | Sync change handler |
-| `onChangeAction` | `(value, event?) => Promise` | Async action (replaces onChange) |
-| `isLoading` | `boolean` | External loading state |
-
-### Uncontrolled Defaults
-
-When supporting uncontrolled mode, prefix default values with `initial`. For booleans, maintain the `is`/`has` prefix convention:
-
-```ts
-initialValue?: string; // not defaultValue
-initialIsOpen?: boolean; // not defaultOpen (keeps `is` prefix)
-initialHasSelection?: boolean;
-```
-
-### onChange Signature
-
-The `onChange` signature varies by input type:
-
-| Input Type | Signature |
-| ------------ | -------------------------------------------- |
-| Text-based | `(value: string, e: ChangeEvent) => void` |
-| Boolean | `(checked: boolean, e: ChangeEvent) => void` |
-| Parsed value | `(value: T \| undefined) => void` (no event) |
-| Selection | `(value: string) => void` |
-
-**Convention:** Include the event when the raw DOM element is useful. Omit it when the value is parsed/transformed.
-
----
-
-## Async Actions (React Transitions)
-
-See [React Transitions exploration](../explorations/react-transitions.md) for full implementation details.
-
-### Two Patterns
-
-| Pattern | Prop | Hook | Used By |
-| -------------- | ---------------- | --------------- | ---------- |
-| Button actions | `onClickAction` | `useTransition` | XDSButton |
-| Input actions | `onChangeAction` | `useOptimistic` | All inputs |
-
-### Input Pattern: `onChangeAction` + `useOptimistic`
-
-```tsx
-const [optimisticValue, setOptimisticValue] = useOptimistic(value);
-const isBusy = isLoading || optimisticValue !== value;
-
-const handleChange = e => {
- const newValue = e.target.value;
- if (onChangeAction) {
- startTransition(() => {
- setOptimisticValue(newValue); // Immediate UI feedback
- onChangeAction(newValue, e); // Async — auto-rollback on failure
- });
- } else if (onChange) {
- onChange(newValue, e);
- }
-};
-```
-
-- Render `optimisticValue`, not `value`
-- `isBusy` drives visual feedback (opacity, `aria-busy`) — **never** disables the input (prevents focus loss)
-- `onChangeAction` has the same signature as `onChange`
-
-### Button Pattern: `onClickAction` + `useTransition`
-
-```tsx
-const [isPending, startTransition] = useTransition();
-const isBusy = isLoading || isPending;
-
-const handleClick = e => {
- if (onClickAction) {
- startTransition(() => {
- onClickAction(e);
- });
- } else if (onClick) {
- onClick(e);
- }
-};
-```
-
-- `isBusy` disables the button and shows a spinner
-- When combined with `href`, navigation defers until action completes
-
-### Naming
-
-- `onClick` / `onChange` — synchronous, immediate
-- `onClickAction` / `onChangeAction` — async, wrapped in transition
-- `isLoading` — external loading state (consolidated from `loading`, `isBusy`)
-
----
-
-## Accessibility
-
-### Required Patterns
-
-| Requirement | Implementation |
-| ----------------- | ----------------------------------------------------- |
-| Label | `label` prop → `<label htmlFor={id}>` or `aria-label` |
-| Hidden label | `isLabelHidden` — visually hidden, still in DOM |
-| Description | `aria-describedby` linking to description element |
-| Required state | `aria-required="true"` when `isRequired` |
-| Invalid state | `aria-invalid="true"` when `status.type === 'error'` |
-| Disabled state | Native `disabled` attribute (correct semantics) |
-| Busy state | `aria-busy="true"` during async operations |
-| Icon-only buttons | `label` used as `aria-label` when no visible text |
-
-### Disabled vs Busy
-
-| State | Interaction | Focus | `disabled` attr | Visual |
-| ------------ | ------------------ | ----- | --------------- | ----------------------------------------------- |
-| `isDisabled` | Blocked | Lost | ✓ | 50% opacity, `not-allowed` cursor |
-| `isBusy` | Guarded in handler | Kept | ✗ | Reduced opacity, spinner (buttons), `aria-busy` |
-
-**Key rule:** Neither inputs nor buttons use native `disabled` for busy state. Busy is visual-only (`aria-busy`, `aria-disabled`, opacity). Buttons guard against re-triggering in the click handler. This prevents focus loss during async operations.
-
----
-
-## Refs and Imperative Handles
-
-### `forwardRef` Convention
-
-All components use `forwardRef` to expose the root DOM element:
-
-```tsx
-export const XDSButton = forwardRef<HTMLButtonElement, XDSButtonProps>(
- (props, ref) => {
- return <button ref={ref} {...props} />;
- },
-);
-
-XDSButton.displayName = 'XDSButton';
-```
-
-**Always set `displayName`** — required for React DevTools and error messages.
-
-### Ref Types
-
-| Component Type | Ref Target |
-| -------------- | ------------------- |
-| Button | `HTMLButtonElement` |
-| Text input | `HTMLInputElement` |
-| Container | `HTMLDivElement` |
-| Link button | `HTMLAnchorElement` |
-
-### Generic Components
-
-Components with generics (e.g., `XDSSelector<T>`) cannot use `forwardRef` directly. Use a regular function component instead:
-
-```tsx
-export function XDSSelector<T extends XDSSelectorOption>(
- props: XDSSelectorProps<T>,
-) { ... }
-```
-
----
-
-## Variant and Size Types
-
-### Deriving from StyleX
-
-Derive variant/size types from the StyleX object keys:
-
-```tsx
-const variants = stylex.create({
- primary: { ... },
- secondary: { ... },
- ghost: { ... },
-});
-
-export type XDSButtonVariant = keyof typeof variants;
-```
-
-### Standard Sizes
-
-| Size | Height Token | Use Case |
-| ---- | ------------------ | ------------------------- |
-| `sm` | `--size-sm` (18px) | Compact UIs, tables |
-| `md` | `--size-md` (26px) | Default for most contexts |
-| `lg` | `--size-lg` | Prominent actions |
-
----
-
-## Status / Validation
-
-### Status Object
-
-```ts
-interface XDSInputStatus {
- type: 'error' | 'warning' | 'success';
- message?: string;
-}
-```
-
-- `type` controls border color and status icon
-- `message` is optional — renders below the input when provided
-- Components re-export with component-specific aliases: `XDSTextInputStatus`, `XDSSelectorStatus`, etc.
-
----
-
-## Test ID Convention
-
-Use the `data-testid` prop for test framework integration:
-
-```tsx
-interface Props {
- 'data-testid'?: string;
-}
-
-// In JSX
-<button data-testid={testId} />;
-```
-
-Pass through to the primary interactive element (the button, input, or trigger — not a wrapper div).
-
----
-
-## Module Augmentation for Themes
-
-Components register their variant types with the theme system via module augmentation. This avoids circular dependencies between components and the theme type system:
-
-```tsx
-declare module '../theme/types' {
- interface ComponentStyles {
- button?: {
- variants?: Partial<Record<XDSButtonVariant, StyleXStyles>>;
- };
- }
-}
-```
-
----
-
-## Export Conventions
-
-### From Component `index.ts`
-
-Export the component, its props type, and any variant/status types:
-
-```ts
-export {XDSButton} from './XDSButton';
-export type {
- XDSButtonProps,
- XDSButtonVariant,
- XDSButtonSize,
-} from './XDSButton';
-```
-
-### From Package `src/index.ts`
-
-Re-export all component directories:
-
-```ts
-export * from './Button';
-export * from './TextInput';
-```
-
-### `tsup.config.ts`
-
-Add each component directory as a separate entry point for tree-shaking:
-
-```ts
-entry: [
- 'src/index.ts',
- 'src/Button/index.ts',
- 'src/TextInput/index.ts',
-],
-```
-
----
-
-## JSDoc Convention
-
-All exported props and components should have JSDoc comments. These serve both human developers and LLM code generation:
-
-````tsx
-/**
- * A text input component for collecting user input.
- *
- * @example
- * ```tsx
- * <XDSTextInput label="Name" value={name} onChange={setName} />
- * ```
- */
-export const XDSTextInput = forwardRef<HTMLInputElement, XDSTextInputProps>(
-````
-
-For props, describe what it does, not how:
-
-```tsx
-/**
- * Whether the input is in a loading state.
- * Shows a spinner and disables interaction.
- * @default false
- */
-isLoading?: boolean;
-```
diff --git a/.context/decisions/input-props-convention.md b/.context/decisions/input-props-convention.md
deleted file mode 100644
index 345fbc219b..0000000000
--- a/.context/decisions/input-props-convention.md
+++ /dev/null
@@ -1,128 +0,0 @@
-# Input Component Props Convention
-
-This document defines the standard props that all XDS input components should implement for consistency.
-
-## Core Field Props
-
-All input components that represent a form field should include these props:
-
-| Prop | Type | Default | Required | Description |
-| --------------- | --------- | ------- | -------- | ------------------------------------------------------------------ |
-| `label` | `string` | - | ✓ | Accessible label text (always rendered for screen readers) |
-| `isLabelHidden` | `boolean` | `false` | | Visually hide the label while keeping it accessible |
-| `description` | `string` | - | | Helper text displayed between label and input |
-| `isOptional` | `boolean` | `false` | | Shows "(Optional)" indicator. Mutually exclusive with `isRequired` |
-| `isRequired` | `boolean` | `false` | | Marks field as required. Mutually exclusive with `isOptional` |
-| `isDisabled` | `boolean` | `false` | | Disables the input |
-
-## Value Props
-
-| Prop | Type | Description |
-| ---------- | ------------------------- | --------------------------------- |
-| `value` | varies | The controlled value of the input |
-| `onChange` | `(value, event?) => void` | Callback when value changes |
-
-### onChange Signature Convention
-
-- **Text-based inputs** (TextInput, TextArea): Include the event for access to the DOM element
-
- ```ts
- onChange: (value: string, e: ChangeEvent<HTMLInputElement>) => void
- ```
-
-- **Parsed value inputs** (DateInput, TimeInput): Event is omitted since value is parsed/transformed
-
- ```ts
- onChange: (value: ISODateString | undefined) => void
- onChange: (value: ISOTimeString | undefined) => void
- ```
-
-- **Boolean inputs** (CheckboxInput): Include the event
- ```ts
- onChange: (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void
- ```
-
-## Optional Common Props
-
-| Prop | Type | Default | Applicable To | Description |
-| -------------- | ------------------ | ------- | -------------------------- | ---------------------------------- |
-| `placeholder` | `string` | varies | Text-based inputs | Placeholder text when empty |
-| `size` | `'sm' \| 'md'` | `'md'` | Most inputs | Size variant |
-| `status` | `{type, message?}` | - | Inputs with validation | Error/warning/success state |
-| `labelTooltip` | `string` | - | Inputs needing explanation | Tooltip on info icon next to label |
-| `startIcon` | `XDSIconType` | - | Inputs with icon support | Icon at start of input |
-
-## Size Variants
-
-Standard sizes across components:
-
-| Size | Input Height | Use Case |
-| ---- | ------------ | -------------------------------- |
-| `sm` | 18px | Compact UIs, tables, dense forms |
-| `md` | 26px | Default, most forms |
-
-## Status Object
-
-For inputs that support validation status, use the shared `XDSInputStatus` type from `@xds/core`:
-
-```ts
-import type {XDSInputStatus, XDSInputStatusType} from '@xds/core';
-
-// XDSInputStatusType = 'error' | 'warning' | 'success'
-
-interface XDSInputStatus {
- type: XDSInputStatusType;
- message?: string; // Optional message displayed below input
-}
-```
-
-Each input component re-exports these types with component-specific aliases for convenience:
-
-- `XDSTextInputStatus`, `XDSTextInputStatusType`
-- `XDSDateInputStatus`, `XDSDateInputStatusType`
-- `XDSTimeInputStatus`, `XDSTimeInputStatusType`
-
-## Current Implementation Status
-
-| Component | label | isLabelHidden | description | isOptional | isRequired | isDisabled | size | status | placeholder |
-| ---------------- | ----- | ------------- | ----------- | ---------- | ---------- | ---------- | ---- | ------ | ----------- |
-| XDSTextInput | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| XDSTextArea | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ |
-| XDSCheckboxInput | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - |
-| XDSDateInput | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| XDSTimeInput | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-
-### Gaps to Address
-
-1. **status**: Add to TextArea for validation feedback
-2. **isOptional**: Add to CheckboxInput for consistency
-3. **size**: Add to TextArea for consistency
-4. **labelTooltip**: Consider adding to all field-based inputs
-
-## Boolean Prop Naming
-
-All boolean props must be prefixed with `is` or `has`:
-
-- `is` prefix: State or condition (`isDisabled`, `isRequired`, `isOptional`, `isLabelHidden`)
-- `has` prefix: Feature toggle (`hasSeconds`, `hasClear`, `hasAutoFocus`)
-
-## forwardRef Pattern
-
-All input components should use `forwardRef` to expose the underlying input element:
-
-```tsx
-export const XDSInput = forwardRef<HTMLInputElement, Props>((props, ref) => {
- // ...
- return <input ref={ref} ... />;
-});
-
-XDSInput.displayName = 'XDSInput';
-```
-
-## Accessibility Requirements
-
-1. **Label**: Always associate label with input via `htmlFor`/`id`
-2. **Description**: Use `aria-describedby` to link description to input
-3. **Required**: Set `aria-required="true"` when `isRequired` is true
-4. **Invalid**: Set `aria-invalid="true"` when status type is `'error'`
-5. **Disabled**: Use native `disabled` attribute (provides correct semantics)
diff --git a/.context/explorations/ai-design-system-gaps.md b/.context/explorations/ai-design-system-gaps.md
deleted file mode 100644
index af70c52815..0000000000
--- a/.context/explorations/ai-design-system-gaps.md
+++ /dev/null
@@ -1,195 +0,0 @@
-# AI + Design Systems: Gaps in Current Stack
-
-*Exploration — January 2026*
-
-## Context
-
-Research into problems with the current standard stack (Tailwind CSS, shadcn/ui, utility-first CSS) when used with AI code generation. Focus on design system adherence issues.
-
----
-
-## Findings
-
-### 1. Design System Adherence Problems
-
-**Utility-class drift**
-- AI generates arbitrary values (`mt-[13px]`) instead of design tokens
-- Different prompts produce different class combinations for same intent
-- No enforcement of spacing scales, color palettes, or typography
-
-**Inconsistency across generations**
-- Each AI session may produce different styling approaches
-- "Style and structure inconsistencies" — fragmented codebases that appear disjointed
-- Lost context means suggestions drift from established patterns
-
-### 2. Architectural Blindness
-
-**Local optimization, not systemic**
-- AI "optimizes for local correctness, not systemic soundness"
-- Doesn't understand *why* previous decisions were made
-- Generates code without knowing if it belongs in that module
-
-**No shared architecture**
-- When developers use different AI sessions, there's no shared ownership
-- Design discussions replaced by autocomplete — no collaborative reasoning
-- Coupling emerges accidentally, not intentionally
-
-### 3. Tailwind-Specific Issues at Scale
-
-**The "utility-class mess"**
-- Bloated markup: dozens of classes per element
-- Without governance, "flexibility turns into chaos"
-- Inconsistent spacing, mismatched colors across teams
-
-**Abstraction gap**
-- Tailwind is low-level; design systems need high-level primitives
-- Requires manual component abstraction that AI often skips
-- No semantic meaning in class names for AI to learn from
-
-### 4. LLM Code Generation Weaknesses
-
-From academic research on LLM failures:
-- **Complexity degradation**: Accuracy drops exponentially with complexity
-- **API misuse**: Wrong arguments, incorrect attribute inference
-- **Corner case failures**: Over 54% of logic errors are edge cases
-- **Real-world gap**: Models underperform on production vs benchmarks
-
----
-
-## Strategies for Injecting Design System Opinions
-
-### Strategy 1: Context Documents (Cursor Rules, CLAUDE.md, etc.)
-
-**Approach**: Write design guidelines in markdown files, have AI read them as context.
-
-**Results**:
-- ❌ **Rules are suggestions, not constraints** — AI can ignore them without consequences
-- ❌ **No verification system** — Can't confirm AI actually followed rules vs claimed compliance
-- ❌ **Context window degradation** — Performance deteriorates within conversations; rules "forgotten"
-- ❌ **Model-specific behavior** — Some models agree with everything without genuine adherence
-- ❌ **Requires constant reinforcement** — Users report needing to restart sessions to maintain rule-following
-
-**Community workarounds**:
-- Place critical rules prominently with explicit reinforcement
-- Use numbered prefixes for rule priority
-- Reference actual code examples, not abstract instructions
-
-### Strategy 2: Prompt Engineering / System Prompts
-
-**Approach**: Include design tokens and guidelines in system prompts.
-
-**Results**:
-- ⚠️ **Token budget constraints** — Full design systems don't fit in context
-- ⚠️ **Dilution effect** — More instructions = less attention to each one
-- ⚠️ **No enforcement** — Still just suggestions the model can ignore
-- ✅ **Works for simple constraints** — "Always use Tailwind" is followable; "use these 47 spacing values" is not
-
-### Strategy 3: Schema-Enforced Structured Output
-
-**Approach**: Define JSON schema, use API-level constraints to force valid output.
-
-**Results**:
-- ✅ **Actually enforced** — API contract constrains generation itself, not post-hoc parsing
-- ✅ **Type safety** — Compile-time + runtime validation
-- ✅ **Deterministic** — Predictable response shapes
-- ⚠️ **Limited to data, not code** — Works for JSON output, not JSX/TSX generation
-
-### Strategy 4: Typed Component APIs
-
-**Approach**: Constrain what's possible at the TypeScript level.
-
-**Results**:
-- ✅ **Enforcement at compile time** — Invalid props = type error
-- ✅ **AI learns from constraints** — Autocomplete only shows valid options
-- ✅ **Self-documenting** — Types become the source of truth
-- ⚠️ **Requires well-designed API** — Constraint design is hard
-- ⚠️ **Reactive, not proactive** — Types catch errors after generation, not before
-
-**Research on first-try accuracy**:
-- LLMs pass all tests only 46-65% on first attempt (arxiv.org/html/2412.14841v1)
-- Claude 3 Opus: 84.9% pass@1 on HumanEval; GPT-4 raw: ~86%
-- Models with error feedback loops ("Reflexion") jump to 95-98%
-- Best models fix 59% of incorrect code when given error info
-
-**API misuse is common**:
-- Research found "significant challenges in API usage, particularly hallucination and intent misalignment" (arxiv.org/abs/2503.22821v1)
-- Study annotated 3,892 method-level and 2,560 parameter-level misuses
-
-**Key insight**: Types are guardrails for iteration, not first-try guidance. The value is in fast recovery (instant compile error) rather than preventing the mistake.
-
-### Strategy 5: JSDoc / Code Comments
-
-**Approach**: Annotate components with JSDoc to guide AI understanding.
-
-**Results**:
-- ❌ **Not reliably read** — Comments are one signal among many (surrounding code, open tabs, cursor context)
-- ❌ **No privileged status** — GitHub Copilot docs show comments compete with other context sources
-- ❌ **Token inefficient** — Verbose JSDoc bloats context window without enforcement
-- ❌ **No verification** — Can't confirm AI actually read or followed the docs
-
-**Research findings**:
-- Type constraints reduce LLM code generation errors by >50% (arxiv.org/abs/2504.09246)
-- The `llms.txt` standard emerged specifically because traditional docs (including JSDoc) fail for LLM consumption
-- Shorter prompts (<50 words) outperform verbose documentation
-- Concrete code examples work better than abstract documentation
-
-### Key Insight
-
-The pattern is clear:
-
-| Strategy | Enforcement Level | Reliability |
-|----------|------------------|-------------|
-| Context docs / rules | None (suggestions) | Low |
-| System prompts | None (suggestions) | Low |
-| JSDoc / comments | None (suggestions) | Low |
-| Schema-enforced output | API-level | High (for JSON) |
-| Typed component APIs | Compile-time (reactive) | High — via iteration |
-
-**Context injection fails because it's optional.** The AI can always ignore guidance. Typed APIs are reliable but *reactive* — they enable fast error→fix loops rather than preventing mistakes. First-try accuracy is only 46-65%; the value of types is making recovery instant.
-
----
-
-## Implications for XDS
-
-These gaps suggest opportunities for differentiation:
-
-| Gap | Potential XDS Approach |
-|-----|------------------------|
-| Arbitrary values | Constrained API — only valid tokens accepted |
-| Style drift | Semantic component names AI can learn |
-| Lost context | Typed APIs > JSDoc (types are enforced, docs are ignored) |
-| No enforcement | Plugin system for validation |
-| Spacing chaos | Automatic spacing compensation |
-| Abstraction gap | Pre-composed patterns, not utilities |
-| Docs not read | Types as documentation — context arrives on import; skip llms.txt (not adopted by AI systems) |
-
----
-
-## Sources
-
-- [Vibe coding is destroying architecture](https://dev.to/dev_tips/vibe-coding-is-destroying-architecture-the-silent-rot-in-our-ai-built-systems-4p1n)
-- [Mastering Tailwind CSS for Enterprise Apps](https://veduis.com/blog/mastering-tailwind-css-enterprise-apps-scalable-design-system/)
-- [Vibe Coding Mistakes](https://dev.to/tirumalaraonaidu/vibe-coding-mistakes-when-using-ai-tools-and-how-to-avoid-them-2p7c)
-- [What is Wrong with LLM Generated Code](https://arxiv.org/html/2407.06153)
-- [Cursor rules are meaningless](https://forum.cursor.com/t/cursor-actively-admitting-that-rules-are-meaningless-and-it-doesnt-have-to-follow-them/131826)
-- [Setting Up Cursor Rules Guide](https://dev.to/stamigos/setting-up-cursor-rules-the-complete-guide-to-ai-enhanced-development-24cg)
-- [Schema-Enforced Outputs](https://dev.to/dthompsondev/llm-structured-json-building-production-ready-ai-features-with-schema-enforced-outputs-4j2j)
-- [The crisis of context](https://standardbeagle.com/ai-coding-assistants-and-context/)
-- [Type-Constrained Code Generation with LLMs](https://arxiv.org/abs/2504.09246) — Types reduce errors by >50%
-- [llms.txt: What It Is and How It Works](https://apidog.com/blog/llms-txt/) — AI-friendly docs standard
-- [ZenML's llms.txt Implementation](https://www.zenml.io/blog/llms-txt) — Tiered token budgets for docs
-- [GitHub Copilot: Responsible Use](https://docs.github.com/en/enterprise-cloud@latest/copilot/responsible-use/copilot-code-completion) — How Copilot uses context
-- [Using LLMs for Code](https://simonwillison.net/2025/Mar/11/using-llms-for-code/) — Context > documentation
-- [LLM Code Generation Accuracy Guide](https://www.prompthub.us/blog/using-llms-for-code-generation-a-guide-to-improving-accuracy-and-addressing-common-issues) — Short prompts outperform verbose
-- [Testing and Static Analysis Feedback for LLMs](https://arxiv.org/html/2412.14841v1/) — 46-65% first-try accuracy, 59% fix rate with feedback
-- [API Misuse in LLMs](https://arxiv.org/abs/2503.22821v1) — Taxonomy of 3,892 method-level misuses
-- [HumanEval Benchmark](https://klu.ai/glossary/humaneval-benchmark) — pass@1 scores across models
-
----
-
-## Open Questions
-
-- How constrained should the API be vs flexibility for edge cases?
-- ~~What JSDoc patterns work best for LLM consumption?~~ **Answered**: JSDoc doesn't reliably work — types beat comments. See Strategy 5.
-- How do we measure "design system adherence" in AI-generated code?
-- ~~Should XDS ship an `llms.txt` for AI-friendly documentation?~~ **Answered**: No — no AI system currently reads llms.txt. See `ai-trajectory-predictions.md`.
diff --git a/.context/explorations/ai-trajectory-predictions.md b/.context/explorations/ai-trajectory-predictions.md
deleted file mode 100644
index 200ea408c0..0000000000
--- a/.context/explorations/ai-trajectory-predictions.md
+++ /dev/null
@@ -1,152 +0,0 @@
-# AI Model Trajectory: What to Build For
-
-*Exploration — January 2026*
-
-## Context
-
-Investigating predictable vs unpredictable aspects of LLM improvement to inform XDS design decisions. Goal: avoid building for current limitations that may disappear, while investing in solutions for fundamental limits that won't.
-
----
-
-## What's Predictable About Model Improvement
-
-### Scaling Laws Are Real (But Slowing)
-
-Performance improves predictably with compute/data/parameters in proportion. However:
-- **Data scarcity** is becoming the bottleneck — high-quality training data is running out
-- **Capability density rising** — newer models achieve same performance with fewer parameters
-- Focus shifting from scale to efficiency and architecture
-
-Source: [LLM Scaling Laws Analysis 2026](https://research.aimultiple.com/llm-scaling-laws/)
-
-### Emergent Abilities Appear Unpredictably
-
-Certain capabilities "jump" suddenly at scale thresholds:
-- Three-digit addition: 8% → 80% accuracy between 13B and 175B parameters
-- Chain-of-thought reasoning emerges above certain model sizes
-- **Cannot predict when abilities will emerge from smaller models**
-
-Source: [Emergent Abilities in LLMs Survey](https://arxiv.org/html/2503.05788v1)
-
----
-
-## Fundamental Limits (Won't Improve With Scale)
-
-Research identifies **irreducible limits** that scaling cannot overcome:
-
-| Limit | Why It's Fundamental |
-|-------|---------------------|
-| **Hallucination** | Mathematically proven — "no computable LLM can be universally correct over open-ended queries" |
-| **Effective context** | 128K tokens nominal, but effective context is far shorter due to positional encoding decay |
-| **Reasoning degradation** | Models optimize pattern completion, not logical inference |
-| **Long-tail knowledge** | Sample complexity scales linearly with fact count — prohibitively expensive |
-| **Creativity-factuality tradeoff** | Mechanisms enabling creativity necessarily increase hallucination |
-
-### Key Findings
-
-**Hallucination is mathematically inevitable:**
-- Theorem proves any enumerable model class must fail on adversarially constructed inputs
-- Undecidable problems force infinite failure sets
-- "Hallucination is an intrinsic property of learning systems operating over unbounded, open-ended query spaces"
-
-**Context window is deceptive:**
-- Positional under-training: gradient flow to long-range positions is negligible
-- Encoding attenuation: dot products vanish for large separations
-- Result: effective context scales sub-linearly with nominal window size
-
-**Data pathologies compound problems:**
-- Web-scraped text contains 2-3% false claims learned indiscriminately
-- 50%+ of time-dependent facts become stale within months
-- Benchmark contamination creates "illusions of competence"
-
-Source: [On the Fundamental Limits of LLMs at Scale](https://arxiv.org/html/2511.12869)
-
----
-
-## Implications for XDS
-
-### Always Build For (Fundamental Limits)
-
-These won't improve, so invest heavily:
-
-| Limit | XDS Design Response |
-|-------|---------------------|
-| Hallucination persists | Constraints beat suggestions — invalid output should be impossible |
-| Effective context limited | Keep API surface small; don't rely on LLM reading extensive docs |
-| Pattern completion, not reasoning | Make correct patterns obvious and consistent |
-| Long-tail knowledge fails | Don't expect LLM to know XDS conventions — enforce via types |
-
-### Build For Now, Accept May Become Unnecessary
-
-Current weaknesses that may improve:
-
-| Weakness | Likely to Improve? | XDS Response |
-|----------|-------------------|--------------|
-| First-try accuracy (46-65%) | **Yes** — emergent abilities | Design for iteration, don't assume stays bad |
-| API misuse | **Yes** — tool use improving | Typed constraints help now, remain valuable later |
-| Following docs/rules | **Uncertain** | Don't rely on it, but don't assume permanent |
-
-### Don't Over-Optimize For (Likely to Improve)
-
-Avoid investing heavily in workarounds for:
-- Poor first-try accuracy (will likely improve)
-- Inability to follow complex instructions (improving with reasoning models)
-- Limited context understanding (architectural innovations ongoing)
-
----
-
-## The Framework
-
-```
-┌─────────────────────────────────────────────────────┐
-│ ALWAYS BUILD FOR (fundamental limits) │
-│ • Constraints over suggestions │
-│ • Small API surface │
-│ • Type enforcement │
-│ • Clear error messages │
-│ • Consistent patterns │
-├─────────────────────────────────────────────────────┤
-│ BUILD FOR NOW, MAY BECOME UNNECESSARY │
-│ • Iteration-friendly design │
-│ • Explicit over implicit │
-│ • Reduced prop optionality │
-├─────────────────────────────────────────────────────┤
-│ DON'T OVER-OPTIMIZE FOR (likely to improve) │
-│ • Workarounds for poor reasoning │
-│ • Dumbing down API for current limitations │
-│ • Assuming models can't follow patterns │
-└─────────────────────────────────────────────────────┘
-```
-
----
-
-## On llms.txt
-
-**Status**: Proposed standard, not implemented by any major AI system.
-
-- John Mueller (Google): "no AI system currently uses llms.txt"
-- Server logs show zero visits from AI bots
-- Not a viable path for XDS component documentation
-
-**What works instead at scale:**
-- Types as documentation (context arrives on import)
-- Consistent patterns (learn once, apply everywhere)
-- Optional MCP server for on-demand component docs
-
----
-
-## Open Questions
-
-- How do we measure whether our API design is "AI-friendly"?
-- Should we track LLM success rates against XDS components over time?
-- At what point do we revisit assumptions as models improve?
-
----
-
-## Sources
-
-- [LLM Scaling Laws Analysis 2026](https://research.aimultiple.com/llm-scaling-laws/)
-- [Emergent Abilities in LLMs Survey](https://arxiv.org/html/2503.05788v1)
-- [On the Fundamental Limits of LLMs at Scale](https://arxiv.org/html/2511.12869)
-- [Semrush: What Is LLMs.txt](https://www.semrush.com/blog/llms-txt/) — No AI systems currently use it
-- [DigitalOcean: Copilot vs Cursor](https://www.digitalocean.com/resources/articles/github-copilot-vs-cursor) — Context handling comparison
diff --git a/.context/explorations/animation-system.md b/.context/explorations/animation-system.md
deleted file mode 100644
index c3d5464f4c..0000000000
--- a/.context/explorations/animation-system.md
+++ /dev/null
@@ -1,540 +0,0 @@
-# Animation System
-
-*Exploration, January 2026*
-
-## Context
-
-XDS's core architecture enforces constraints: zero styling, theme-driven tokens, typed APIs. This exploration examines how animation fits into that constraint-based model.
-
-The question isn't "which animation library should we use?" but rather "how does animation integrate with XDS's philosophy of no arbitrary values, theme as source of truth, and AI-friendly by constraint?"
-
-**Assumption:** This document assumes XDS uses StyleX for styling (see `stylex-vs-tailwind.md` for that exploration). Animation implementation aligns with StyleX's compile-time, zero-runtime philosophy.
-
----
-
-## Core Principle
-
-**Animation is styling's sibling. Same rules apply.**
-
-| XDS Principle | Animation Application |
-|---------------|----------------------|
-| **Zero-styling**: no inline styles, no style props | **Zero animation code**: no `animate={{}}`, no transition props |
-| **Theme as source of truth** | Animation config lives in `theme.motion` |
-| **Props define intent, not style** | `open={true}` expresses intent; animation is implementation detail |
-| **Typed, constrained APIs** | Animation types are enums (`'fade' \| 'scale'`), not arbitrary values |
-| **Swizzle for edge cases** | Swizzle component to override animation behavior |
-| **AI-friendly by constraint** | AI writes `<Dialog open>`, knows nothing about animation |
-
-```tsx
-// What developers write:
-<Dialog open={isOpen}>
- <DialogTitle>Confirm</DialogTitle>
- <DialogContent>Are you sure?</DialogContent>
-</Dialog>
-
-// Animation just happens (configured in theme)
-```
-
----
-
-## Why CSS Over an Animation Library
-
-AI can implement animations easily either way, whether it's Motion or StyleX. The question is whether the tradeoffs justify adding a dependency.
-
-| | CSS / StyleX | Motion (motion/react) |
-|--|--------------|----------------------|
-| **Enter animations** | ✅ `@starting-style` handles it | ✅ `initial → animate` |
-| **Exit animations** | ⚠️ Need custom unmount delay | ✅ `AnimatePresence` for free |
-| **Gesture animations** | ⚠️ More verbose, manual | ✅ First-class drag/swipe |
-| **Spring physics** | ⚠️ Cubic-bezier approx (or DIY, but then why not Motion?) | ✅ Real springs |
-| **Bundle size** | ✅ 0KB | ⚠️ ~18KB |
-| **Philosophy fit** | ✅ Compile-time, no runtime | ⚠️ Runtime JS |
-
-**The honest assessment:**
-- For internal tools and standard UI, CSS handles 90% of animation needs
-- Exit animations matter less than enter animations. Instant removal is acceptable
-- Fancy gesture animations (drag-to-dismiss, spring physics) require more code with CSS, but AI can still write it
-
-**Decision:** Start with CSS. Avoid the dependency unless we want to go all-in on animations. If exit animations or gestures become critical later, we can adopt Motion for specific components. The public API (`<Dialog open>`) stays the same either way.
-
----
-
-## Theme API Design
-
-### Full Motion Config
-
-```tsx
-createTheme({
- motion: {
- // ─────────────────────────────────────────────
- // GLOBAL CONTROLS
- // ─────────────────────────────────────────────
-
- enabled: true, // Kill switch for all animations
- reducedMotion: 'respect', // 'respect' | 'always-reduce' | 'ignore'
-
- // ─────────────────────────────────────────────
- // TIMING TOKENS
- // ─────────────────────────────────────────────
-
- duration: {
- instant: 0,
- fast: 100,
- normal: 200,
- slow: 300,
- },
-
- // ─────────────────────────────────────────────
- // EASING TOKENS
- // ─────────────────────────────────────────────
-
- easing: {
- linear: 'linear',
- default: 'cubic-bezier(0.4, 0, 0.2, 1)',
- easeIn: 'cubic-bezier(0.4, 0, 1, 1)',
- easeOut: 'cubic-bezier(0, 0, 0.2, 1)',
- easeInOut: 'cubic-bezier(0.4, 0, 0.2, 1)',
- spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
- },
-
- // ─────────────────────────────────────────────
- // PER-COMPONENT DEFAULTS
- // ─────────────────────────────────────────────
-
- components: {
- dialog: { type: 'fade', duration: 'normal', easing: 'easeOut' },
- drawer: { type: 'slide', duration: 'normal', easing: 'easeOut' },
- accordion: { type: 'collapse', duration: 'fast', easing: 'easeOut' },
- popover: { type: 'fade', duration: 'fast', easing: 'default' },
- tooltip: { type: 'fade', duration: 'fast', easing: 'default' },
- bottomSheet: { type: 'slide-up', duration: 'normal', easing: 'spring' },
- toast: { type: 'slide', duration: 'fast', easing: 'easeOut' },
- menu: { type: 'fade', duration: 'fast', easing: 'default' },
- ...
- [typeof Component]: { ... }, // Type-safe config for all components
- },
- }
-})
-```
-
-### Type Safety
-
-The motion config is fully typed. Each component only accepts animation types that make sense for it:
-
-```tsx
-type DurationToken = 'instant' | 'fast' | 'normal' | 'slow';
-type EasingToken = 'linear' | 'default' | 'easeIn' | 'easeOut' | 'easeInOut' | 'spring';
-
-// Each component defines which animation types it supports
-type DialogAnimationType = 'fade' | 'scale' | 'none';
-type DrawerAnimationType = 'slide' | 'none';
-type AccordionAnimationType = 'collapse' | 'none';
-// ... etc
-
-// Theme authors get constrained autocomplete
-createTheme({
- motion: {
- components: {
- dialog: { type: 'fade' }, // ✅ Valid
- dialog: { type: 'slide' }, // ❌ Type error: dialog doesn't support 'slide'
- drawer: { type: 'slide' }, // ✅ Valid
- accordion: { type: 'collapse' }, // ✅ Valid
- },
- }
-})
-```
-
-### StyleX Token Definition
-
-The theme's motion config generates StyleX variables that components consume internally:
-
-```tsx
-import * as stylex from '@stylexjs/stylex';
-
-// Theme defines motion tokens via defineVars
-export const motionTokens = stylex.defineVars({
- // Durations
- durationInstant: '0ms',
- durationFast: '100ms',
- durationNormal: '200ms',
- durationSlow: '300ms',
-
- // Easings
- easingLinear: 'linear',
- easingDefault: 'cubic-bezier(0.4, 0, 0.2, 1)',
- easingEaseIn: 'cubic-bezier(0.4, 0, 1, 1)',
- easingEaseOut: 'cubic-bezier(0, 0, 0.2, 1)',
- easingSpring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
-});
-
-// Components use tokens in stylex.create()
-const dialogStyles = stylex.create({
- overlay: {
- opacity: 1,
- transition: `opacity ${motionTokens.durationNormal} ${motionTokens.easingEaseOut}`,
- },
-});
-```
-
-### Theme Variants
-
-**Snappy theme** (power users, internal tools):
-```tsx
-const snappyTheme = createTheme({
- motion: {
- duration: { fast: 50, normal: 100, slow: 150 },
- easing: { default: 'linear' },
- }
-})
-```
-
-**Smooth theme** (consumer-facing):
-```tsx
-const smoothTheme = createTheme({
- motion: {
- duration: { fast: 150, normal: 250, slow: 400 },
- easing: { default: 'spring' },
- components: {
- dialog: { type: 'scale', easing: 'spring' },
- bottomSheet: { easing: 'spring' },
- },
- }
-})
-```
-
-**No animation theme** (accessibility, performance, testing):
-```tsx
-const noMotionTheme = createTheme({
- motion: { enabled: false }
-})
-```
-
----
-
-## Swizzle Integration
-
-Animation customization follows the dual-path swizzle model from `swizzle-layer-ergonomics.md`.
-
-### Path A: Theme Customization
-
-For timing/easing/type changes:
-
-```bash
-npx xds customize motion --theme=corporate
-```
-
-Generates `themes/corporate/motion.ts`:
-
-```tsx
-import { extendTheme } from '@xds/core';
-
-export const corporateMotionTheme = extendTheme({
- motion: {
- duration: { fast: 80, normal: 160, slow: 240 },
- easing: { default: 'easeOut', spring: 'cubic-bezier(...)' },
- components: {
- dialog: { type: 'scale' },
- bottomSheet: { easing: 'spring' },
- },
- }
-});
-```
-
-**AI vibes:** ✅ Excellent: structured config, no animation code.
-
-### Path B: Component Swizzle
-
-For completely custom animation behavior:
-
-```bash
-npx xds swizzle Dialog
-```
-
-Full component source with animation implementation. Yours to modify.
-
-**AI vibes:** ⚠️ Medium: code, but documented customization points.
-
----
-
-## Component Animation Patterns
-
-Components fall into a few animation patterns. Here's how each works with the system.
-
-### Pattern 1: Overlay Components (Dialog, Drawer, BottomSheet, AlertDialog)
-
-**What animates:** Backdrop fades in, content slides/scales in.
-
-**How it works:** Component reads `open` prop, applies styles based on `data-state="open|closed"`. StyleX styles use `@starting-style` for enter animation.
-
-```tsx
-// Internal implementation (user never sees this)
-const styles = stylex.create({
- overlay: {
- opacity: {
- default: 1,
- '@starting-style': 0,
- },
- transition: `opacity ${motionTokens.durationNormal} ${motionTokens.easingEaseOut}`,
- },
- content: {
- transform: {
- default: 'translateY(0)',
- '@starting-style': 'translateY(100%)',
- },
- transition: `transform ${motionTokens.durationNormal} ${motionTokens.easingEaseOut}`,
- },
-});
-```
-
-**Theme config:** `motion.components.dialog`, `motion.components.drawer`, etc.
-
-### Pattern 2: Collapse Components (Accordion, Collapsible)
-
-**What animates:** Height from 0 to auto.
-
-**How it works:** CSS grid trick: `grid-template-rows: 0fr` to `1fr`. No JS measurement needed. See [Appendix: CSS Grid Height Trick](#appendix-css-grid-height-trick) for implementation.
-
-**Theme config:** `motion.components.accordion`, `motion.components.collapsible`
-
-### Pattern 3: Popup Components (Popover, Tooltip, Menu)
-
-**What animates:** Fade in (optionally scale from anchor point).
-
-**How it works:** Similar to overlays but positioned relative to trigger. Fast timing.
-
-```tsx
-const styles = stylex.create({
- popup: {
- opacity: {
- default: 1,
- '@starting-style': 0,
- },
- transition: `opacity ${motionTokens.durationFast} ${motionTokens.easingDefault}`,
- },
-});
-```
-
-**Theme config:** `motion.components.popover`, `motion.components.tooltip`, `motion.components.menu`
-
-### Pattern 4: Notification Components (Toast)
-
-**What animates:** Slide in from edge of screen.
-
-**How it works:** Positioned fixed, slides from off-screen. May need exit animation for dismiss.
-
-```tsx
-const styles = stylex.create({
- toast: {
- transform: {
- default: 'translateX(0)',
- '@starting-style': 'translateX(100%)',
- },
- transition: `transform ${motionTokens.durationFast} ${motionTokens.easingEaseOut}`,
- },
-});
-```
-
-**Theme config:** `motion.components.toast`
-
-### Pattern 5: Tab Content (Tabs)
-
-**What animates:** Content panel crossfade (optional).
-
-**How it works:** If enabled, outgoing panel fades out while incoming fades in. Often skipped. Instant switch is fine.
-
-**Theme config:** `motion.components.tabs` (default: `{ type: 'none' }`)
-
----
-
-## Design Decisions
-
-### Reduced Motion
-
-Handled by default. XDS respects `prefers-reduced-motion` automatically. Duration becomes `0ms` when the OS preference is set. Developers write no motion-awareness code.
-
-Themes can optionally override via `motion.reducedMotion`:
-- `'respect'` (default): honor OS preference
-- `'always-reduce'`: force reduced motion
-- `'ignore'`: ignore OS preference (accessibility concern)
-
-### Animation Primitives
-
-Not exported. Animation is internal implementation detail. Swizzle is the escape hatch for custom behavior.
-
----
-
-## Next Steps
-
-1. **Prototype a few components with StyleX animations** to validate this approach works well in practice
-2. Test `@starting-style` behavior across browsers (Chrome, Safari, Firefox fallback)
-3. Ensure the developer experience is not too cumbersome for building animated components
-4. Evaluate if exit animations are truly skippable or if we need the `useAnimatedUnmount` hook
-
----
-
-## Open Questions
-
-- Should exit animations be skipped entirely (instant removal), or should we implement a small `useAnimatedUnmount` hook to delay unmount?
-- Are we definitely using StyleX? (See `stylex-vs-tailwind.md`, this doc assumes yes)
-
----
-
-# Appendix: Alternatives Considered
-
-*This section documents approaches that were evaluated but not selected.*
-
----
-
-## Alternative: Motion Library (motion/react)
-
-We chose CSS/StyleX over Motion. Here's the detailed comparison:
-
-| Aspect | CSS / StyleX | Motion |
-|--------|--------------|--------|
-| **Bundle size** | ~0KB | ~18KB |
-| **Enter animations** | ✅ `@starting-style` | ✅ `initial → animate` |
-| **Exit animations** | ⚠️ Hacky or skip | ✅ `AnimatePresence` |
-| **Spring physics** | ⚠️ Cubic-bezier approx (or build our own, but then why not just use Motion?) | ✅ Real springs |
-| **Philosophy fit** | ✅ Compile-time | ⚠️ Runtime |
-
-**Browser support note:** `@starting-style` works in Chrome 117+, Safari 17.4+. Firefox falls back to no enter animation (content just appears, not broken, just not animated).
-
-**StyleX animation example:**
-```tsx
-import * as stylex from '@stylexjs/stylex';
-import { motionTokens } from '@xds/theme';
-
-const styles = stylex.create({
- dialog: {
- opacity: 1,
- transform: 'scale(1)',
- transition: `opacity ${motionTokens.durationNormal} ${motionTokens.easingEaseOut}, transform ${motionTokens.durationNormal} ${motionTokens.easingEaseOut}`,
- },
-});
-```
-
----
-
-## Alternative A: Expose Animation Primitives
-
-Ship `<Fade>`, `<Slide>`, `<Collapse>` as public components.
-
-```tsx
-import { Fade } from '@xds/motion'
-
-<Fade in={isOpen}>
- <Dialog>...</Dialog>
-</Fade>
-```
-
-### Why Not Selected
-
-| Issue | Impact |
-|-------|--------|
-| **Wrapper div problem** | Primitives wrap children in a `<div>`, breaks flexbox/grid, CSS selectors, accessibility |
-| **Cognitive load** | Devs must know which primitive goes with which component |
-| **Inconsistency** | Team A uses `<Fade>`, Team B uses `<Scale>`, leads to disjointed UX |
-| **AI complexity** | AI must generate animation code, more failure modes |
-| **Contradicts philosophy** | XDS promises no styling decisions; exposing animation primitives is a styling decision |
-
-### Workarounds Considered
-
-- `asChild` pattern (Radix-style) to merge into child element
-- `useAnimation` hook for devs who want no wrapper
-- Render props pattern
-
-All add complexity. If animation is internal, none of this is needed.
-
----
-
-## Alternative B: Animation Props on Components
-
-Add `transition` prop to each component:
-
-```tsx
-<Dialog open={isOpen} transition="fade" duration="normal">
- ...
-</Dialog>
-```
-
-### Why Not Selected
-
-- Animation decisions scattered across component usage
-- Different devs choose different animations, leads to inconsistent UX
-- Every component needs animation props
-- Still requires animation knowledge from developers
-
----
-
-## Libraries Evaluated
-
-| Library | Size | Exit Animations | Layout Animations | Notes |
-|---------|------|-----------------|-------------------|-------|
-| **CSS-only** | 0KB | ❌ | ❌ | Limited capability |
-| **Headless UI Transition** | ~3KB | ✅ | ❌ | Class-string API, Tailwind-flavored |
-| **@formkit/auto-animate** | ~2KB | ✅ | ✅ | Magic "just works", less control |
-| **Motion (motion/react)** | ~18KB | ✅ | ✅ | Full capability, best DX |
-| **React Transition Group** | ~7KB | ✅ | ❌ | Dated API, class-based |
-| **View Transitions API** | 0KB | ✅ | ✅ | Browser-native, Chrome/Safari only |
-
-**Why not Headless UI Transition?** Class-string API (`enter="transition duration-200"`) exposes styles, contradicting XDS philosophy.
-
-**Why not View Transitions API?** Good for page-level transitions, not component-level. Firefox still behind flag.
-
----
-
-## What Other Design Systems Do
-
-| Design System | Animation Approach | Dependency |
-|--------------|-------------------|------------|
-| **Radix UI** | CSS-only, `data-state` attributes for enter (no exit) | None |
-| **shadcn/ui** | Tailwind animations, optional Framer | CSS or Framer |
-| **Chakra UI** | Built on Framer Motion | Framer (~30KB) |
-| **Material UI** | Internal Transition components | Internal ~5KB |
-| **Ant Design** | rc-motion (internal lib) | Internal ~8KB |
-| **Headless UI** | `<Transition>` component, CSS + JS lifecycle | ~3KB |
-| **Mantine** | CSS transitions, optional Framer | CSS or Framer |
-
-**Pattern:** Most serious design systems either ship CSS-only (limited) or build/use a thin transition layer (3-8KB) for exit animations.
-
----
-
-## Appendix: CSS Grid Height Trick
-
-Animating `height: auto` is historically difficult. The CSS grid trick makes it work without JS measurement:
-
-```tsx
-const styles = stylex.create({
- wrapper: {
- display: 'grid',
- gridTemplateRows: '0fr',
- transition: `grid-template-rows ${motionTokens.durationFast} ${motionTokens.easingDefault}`,
- },
- wrapperOpen: {
- gridTemplateRows: '1fr',
- },
- content: {
- overflow: 'hidden',
- },
-});
-```
-
-Works in all modern browsers. See [CSS-Tricks: CSS Grid Can Do Auto Height Transitions](https://css-tricks.com/css-grid-can-do-auto-height-transitions/).
-
----
-
-## Related
-
-- `zero-styling-architecture.md`: Core philosophy this extends
-- `swizzle-layer-ergonomics.md`: Customization paths referenced for theme/swizzle integration
-- `stylex-vs-tailwind.md`: Styling approach decision (this doc assumes StyleX)
-- `ai-design-system-gaps.md`: Why constraints matter for AI code generation
-
----
-
-## Sources
-
-- [CSS @starting-style - MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/@starting-style)
-- [Motion Library (motion/react)](https://motion.dev)
-- [Animating height: auto - CSS Grid Trick](https://css-tricks.com/css-grid-can-do-auto-height-transitions/)
-- [prefers-reduced-motion - MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
diff --git a/.context/explorations/component-naming-conventions.md b/.context/explorations/component-naming-conventions.md
deleted file mode 100644
index 60d767306e..0000000000
--- a/.context/explorations/component-naming-conventions.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Component Naming Conventions
-
-## Context
-
-XDS uses the `XDS` prefix for all design system components (e.g., `XDSButton`, `XDSVStack`). This document explores how file naming affects LLM discoverability and contribution patterns.
-
-## Empirical Observation
-
-When asked to create a new component `XDSVStack`, an LLM (Claude) naturally created files with the prefix included:
-- `XDSVStack.tsx`
-- `XDSVStack.test.tsx`
-
-This happened despite an earlier discussion about keeping files unprefixed. This suggests:
-
-1. **Prefixed filenames are the natural LLM default** — When the component name includes a prefix, LLMs instinctively name files to match
-2. **Re-export pattern requires extra context** — The pattern `Button.tsx → export as XDSButton` is a learned convention, not intuitive
-3. **Consistency reduces cognitive load** — Matching file names to export names eliminates a layer of indirection
-
-## Options
-
-### Option A: Files match export names (prefixed)
-
-```
-Button/
-├── XDSButton.tsx → exports XDSButton
-├── XDSButton.test.tsx
-└── index.ts
-```
-
-**Evidence for:**
-- LLMs naturally default to this pattern
-- No mental translation between file name and component name
-- Editor tabs show the exact component name
-- Grep/search for "XDSButton" finds both file and component
-
-**Evidence against:**
-- Redundancy with directory name (`Button/XDSButton.tsx`)
-- Harder to change prefix in the future (affects all file names)
-
-### Option B: Files unprefixed, re-export with prefix
-
-```
-Button/
-├── Button.tsx → exports Button internally
-├── Button.test.tsx
-└── index.ts → export { Button as XDSButton }
-```
-
-**Evidence for:**
-- Simpler file names
-- Easier to support prefix customization for forks
-- Follows some existing library patterns
-
-**Evidence against:**
-- LLMs don't naturally follow this pattern without explicit instruction
-- Requires learning and maintaining a convention
-- `import { XDSButton } from './Button'` may cause confusion
-
-## Decision
-
-Given the empirical evidence that LLMs naturally default to prefixed file names:
-
-**Use prefixed file names (`XDSButton.tsx`)** for maximum LLM-friendliness.
-
-The slight redundancy with directory names is a minor cost compared to:
-- More intuitive LLM contributions
-- No need for explicit re-export conventions
-- Direct match between file names and what developers see in code
-
-## Key Insight
-
-> When LLMs are given a component name with a prefix, they naturally create files with that prefix. Fighting this instinct requires explicit conventions that must be re-learned in each context. It's simpler to align file naming with LLM intuition.
diff --git a/.context/explorations/component-reference.md b/.context/explorations/component-reference.md
deleted file mode 100644
index 2878f45a38..0000000000
--- a/.context/explorations/component-reference.md
+++ /dev/null
@@ -1,267 +0,0 @@
-# XDS Component Reference
-
-Patterns and techniques for building XDS components with StyleX.
-
-## Component Architecture
-
-### File Structure
-
-```
-/packages/core/src/{ComponentName}/
-├── {ComponentName}.tsx # Main component implementation
-├── index.ts # Exports
-├── README.md # Documentation
-├── {ComponentName}.stories.tsx # Storybook stories
-└── {ComponentName}.test.tsx # Tests
-```
-
-### Basic Component Template
-
-```tsx
-import {forwardRef, type HTMLAttributes, type ReactNode} from 'react';
-import * as stylex from '@stylexjs/stylex';
-import {colorTokens, spacingTokens} from '../theme/tokens.stylex';
-
-const styles = stylex.create({
- base: {
- // Base styles using tokens
- },
-});
-
-const variants = stylex.create({
- default: {
- /* ... */
- },
- // Add more variants as needed
-});
-
-// Derive type from StyleX object
-export type ComponentVariant = keyof typeof variants;
-
-export interface ComponentProps extends HTMLAttributes<HTMLElement> {
- variant?: ComponentVariant;
- children: ReactNode;
-}
-
-export const Component = forwardRef<HTMLElement, ComponentProps>(
- ({variant = 'default', children, ...props}, ref) => {
- return (
- <div
- ref={ref}
- {...stylex.props(styles.base, variants[variant])}
- {...props}>
- {children}
- </div>
- );
- },
-);
-
-Component.displayName = 'Component';
-```
-
-## Type Derivation Pattern
-
-Derive variant types from StyleX objects to keep types in sync with styles:
-
-```tsx
-const variants = stylex.create({
- primary: {
- /* ... */
- },
- secondary: {
- /* ... */
- },
- ghost: {
- /* ... */
- },
-});
-
-export type ButtonVariant = keyof typeof variants;
-// Results in: 'primary' | 'secondary' | 'ghost'
-```
-
-When you add or remove a variant from the StyleX object, the type automatically updates.
-
-## StyleX Patterns
-
-### Using Tokens
-
-Always use tokens from `tokens.stylex` instead of hardcoded values:
-
-```tsx
-import {
- colorTokens,
- spacingTokens,
- radiusTokens,
- transitionTokens,
- typographyTokens,
-} from '../theme/tokens.stylex';
-
-const styles = stylex.create({
- base: {
- backgroundColor: colorTokens.surface,
- padding: spacingTokens.space3,
- borderRadius: radiusTokens.element,
- fontFamily: typographyTokens.fontFamilyBody,
- transitionDuration: transitionTokens.fast,
- },
-});
-```
-
-### Conditional Styles
-
-Apply styles conditionally using `stylex.props`:
-
-```tsx
-{...stylex.props(
- styles.base,
- variants[variant],
- isDisabled && styles.disabled,
- isLoading && styles.loading
-)}
-```
-
-### Pseudo-selectors
-
-StyleX supports common pseudo-selectors:
-
-```tsx
-const styles = stylex.create({
- interactive: {
- backgroundColor: {
- default: null,
- ':hover': colorTokens.hoverOverlay,
- ':active': colorTokens.pressedOverlay,
- },
- outline: {
- default: null,
- ':focus-visible': `2px solid ${colorTokens.focusOutline}`,
- },
- outlineOffset: {
- default: null,
- ':focus-visible': '3px',
- },
- },
-});
-```
-
-### Animations
-
-Use `stylex.keyframes` for animations:
-
-```tsx
-const styles = stylex.create({
- spinner: {
- animationName: stylex.keyframes({
- to: {transform: 'rotate(360deg)'},
- }),
- animationDuration: '0.6s',
- animationTimingFunction: 'linear',
- animationIterationCount: 'infinite',
- },
-});
-```
-
-## Advanced Patterns
-
-### Overlay Hover/Active States
-
-For interactive elements where you want hover/active colors to layer on top of the base background (not replace it), use `backgroundImage`:
-
-```tsx
-const variants = stylex.create({
- primary: {
- backgroundColor: colorTokens.accent,
- backgroundImage: {
- default: null,
- ':hover': `linear-gradient(${colorTokens.hoverOverlay}, ${colorTokens.hoverOverlay})`,
- ':active': `linear-gradient(${colorTokens.pressedOverlay}, ${colorTokens.pressedOverlay})`,
- },
- },
-});
-```
-
-This works because `background-image` renders on top of `background-color`.
-
-### Variant-Specific Focus Colors
-
-Some components need different focus outline colors per variant:
-
-```tsx
-const variants = stylex.create({
- primary: {
- outline: {
- default: null,
- ':focus-visible': `2px solid ${colorTokens.focusOutline}`,
- },
- outlineOffset: {
- default: null,
- ':focus-visible': '3px',
- },
- },
- destructive: {
- outline: {
- default: null,
- ':focus-visible': `2px solid ${colorTokens.negative}`,
- },
- outlineOffset: {
- default: null,
- ':focus-visible': '3px',
- },
- },
-});
-```
-
-### Loading States
-
-Pattern for components with loading indicators:
-
-```tsx
-const loadingStyles = stylex.create({
- loading: {
- position: 'relative',
- color: 'transparent', // Hide text while loading
- },
- spinner: {
- position: 'absolute',
- // Spinner styles...
- },
-});
-
-// In component:
-{...stylex.props(
- styles.base,
- loading && loadingStyles.loading
-)}
-{loading && <span {...stylex.props(loadingStyles.spinner)} />}
-```
-
-## Known StyleX Limitations
-
-See `.context/explorations/stylex-patterns.md` for detailed notes:
-
-1. **No runtime `stylex.create()`** - All styles must be compiled at build time
-2. **Combined pseudo-selectors don't work** - `:hover::after` is not supported
-3. **Use `backgroundImage` for overlays** - Instead of `::after` pseudo-elements
-
-## Token Reference
-
-Available tokens from `tokens.stylex`:
-
-| Category | Tokens |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `colorTokens` | accent, surface, textPrimary, textSecondary, hoverOverlay, pressedOverlay, focusOutline, negative, positive, etc. |
-| `spacingTokens` | space0, space0_5, space1, space2, space3, space4, space5, space6, space7 |
-| `radiusTokens` | rounded, container, element, content |
-| `transitionTokens` | fast, normal |
-| `typographyTokens` | fontFamilyBody, fontFamilyCode, fontFamilyHeading |
-
-## Example: Button Component
-
-See `/packages/core/src/Button/Button.tsx` for a complete implementation demonstrating:
-
-- Multiple variants (primary, secondary, ghost, destructive)
-- Loading state with spinner
-- Overlay hover/active states
-- Variant-specific focus colors
-- Type derivation from StyleX object
diff --git a/.context/explorations/component-swizzling.md b/.context/explorations/component-swizzling.md
deleted file mode 100644
index 2fe2180403..0000000000
--- a/.context/explorations/component-swizzling.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Component Swizzling
-
-Exploration of how customized components could be distributed alongside themes.
-
-## Problem
-
-Themes in XDS control design tokens (colors, spacing, typography, etc.), but some design systems need deeper customization at the component level. For example:
-
-- **shadcn buttons** handle variants differently than XDS buttons
-- A brand might want different hover behaviors, animations, or structural changes
-- Token-level theming can't always achieve the desired visual output
-
-## Swizzling Concept
-
-"Swizzling" (term from Docusaurus) means ejecting/overriding a component to customize it. The question: how could swizzled components be distributed as easily as themes?
-
-## Current State
-
-```
-Theme Distribution:
-├── defaultTheme.stylex.ts (complete, copyable template)
-├── neutralTheme.stylex.ts (demonstrates customization)
-└── Consumer creates custom themes by copying/modifying
-```
-
-Themes are self-contained files that can be copied and modified. Could components follow a similar pattern?
-
-## Possible Approaches
-
-### 1. Component Recipes (like shadcn)
-Provide component source files that consumers copy into their project:
-```
-npx xds add XDSButton
-→ copies XDSButton.tsx into your project
-```
-
-Pros: Full control, no abstraction leak
-Cons: No automatic updates, divergence over time
-
-### 2. Component Variants as Theme Extensions
-Extend the theme object to include component-specific overrides:
-```tsx
-const myTheme = {
- ...defaultTheme,
- components: {
- XDSButton: {
- variants: {
- primary: { /* custom styles */ },
- },
- },
- },
-};
-```
-
-Pros: Stays within theme system
-Cons: Limited to style overrides, can't change structure
-
-### 3. Component Slots/Composition
-Design components with explicit customization points:
-```tsx
-<XDSButton
- renderIcon={(props) => <CustomIcon {...props} />}
- styles={{ hover: customHoverStyles }}
-/>
-```
-
-Pros: Controlled flexibility
-Cons: API complexity, can't anticipate all needs
-
-### 4. Component Registry
-Allow registering custom component implementations:
-```tsx
-import { registerComponent } from '@xds/core';
-import { MyXDSButton } from './MyXDSButton';
-
-registerComponent('XDSButton', MyXDSButton);
-```
-
-Pros: Clean swap mechanism
-Cons: Runtime overhead, type safety challenges
-
-## Questions to Explore
-
-1. What level of customization do consumers actually need?
-2. Should swizzled components be "blessed" variants or fully custom?
-3. How do we handle breaking changes in base components?
-4. Can we version component APIs separately from token APIs?
-
-## Relationship to Themes
-
-Ideally, swizzled components would:
-- Be as portable as theme files
-- Work with any theme (not coupled to specific tokens)
-- Be discoverable/shareable across teams
-- Have clear upgrade paths
-
-## Next Steps
-
-- Survey how shadcn, Radix, and other systems handle this
-- Identify which XDS components are most likely to need swizzling
-- Prototype one approach with Button component
diff --git a/.context/explorations/distribution-methods.md b/.context/explorations/distribution-methods.md
deleted file mode 100644
index a4a36872c2..0000000000
--- a/.context/explorations/distribution-methods.md
+++ /dev/null
@@ -1,141 +0,0 @@
-# Distribution Methods for XDS
-
-*Exploration — January 2026*
-
-## Context
-
-Research into how to distribute various XDS artifacts: AI assistant skills/rules, code snippets, component recipes, and starter templates. Goal: make XDS easy to adopt across different tooling ecosystems.
-
----
-
-## 1. AI Assistant Skills/Rules
-
-How to distribute Cursor rules, Claude Code commands, and similar AI configurations.
-
-| Method | How It Works | Pros | Cons |
-|--------|--------------|------|------|
-| **PRPM** | Package manager for Cursor rules via npm. `prpm install xds-rules` | Cross-platform (Cursor, Claude, Windsurf), versioned, CLI install | External dependency, community-run |
-| **npm package** | Ship rules in npm package, postinstall copies to `.cursor/rules/` | Bundled with library, versioned with components | Manual setup, may conflict |
-| **Repo distribution** | Include `.cursor/rules/` and `.claude/commands/` in XDS repo | Zero setup for monorepo users | Doesn't work for npm consumers |
-| **Claude Code skills** | Ship skills in `~/.claude/skills/` structure | Auto-activating, trigger-based | Manual install, no package manager yet |
-
-### Claude Code Specifics
-
-- Skills are stored in `~/.claude/skills/`
-- Commands in `~/.claude/commands/`
-- Skills auto-activate based on triggers (file saves, commits, etc.)
-- Distribution: commit to repo or copy to user's `~/.claude/` directory
-
-### Cursor Specifics
-
-- Rules stored in `.cursor/rules/` in project
-- PRPM provides cross-editor package management
-- Can convert between Cursor, Claude, Windsurf formats automatically
-
-**Recommendation**: Ship rules/skills in npm package + provide PRPM package for standalone install.
-
-Source: [PRPM Package Manager](https://forum.cursor.com/t/prpm-a-package-manager-for-cursor-rules-1800-cursor-rules-installable-via-the-cli/139557)
-
----
-
-## 2. Code Snippets/Templates
-
-VS Code snippets and similar editor integrations.
-
-| Method | How It Works | Pros | Cons |
-|--------|--------------|------|------|
-| **VS Code extension** | Publish `.code-snippets` as extension | Auto-updates, marketplace discovery | Maintenance overhead, VS Code only |
-| **Repo snippets** | Include `.vscode/xds.code-snippets` in XDS repo | Zero config for repo users | Doesn't travel with npm package |
-| **npm postinstall** | Copy snippets to project `.vscode/` on install | Bundled with library | May overwrite user config |
-
-**Recommendation**: Include snippets in repo, document manual copy for npm users.
-
----
-
-## 3. Component Recipes (Composed Patterns)
-
-Pre-built compositions like "form with validation" or "data table with pagination".
-
-| Method | How It Works | Pros | Cons |
-|--------|--------------|------|------|
-| **shadcn-style CLI** | `npx xds add form-with-validation` copies source to project | Full ownership, customizable, AI-friendly | Maintenance of CLI, versioning complexity |
-| **npm subpackages** | `@xds/recipes` package with pre-composed patterns | Standard npm workflow | Less customizable, bundle size |
-| **Storybook recipes** | Document recipes in Storybook with copy button | Visual docs, no CLI needed | Manual copy-paste |
-| **Documentation site** | Dedicated recipes section with code examples | Searchable, contextual | Not automated |
-
-### Why shadcn-style Works
-
-From shadcn/ui docs: "A flat-file schema and command-line tool make it easy to distribute components."
-
-Key benefits:
-- **Transparency**: Developers see exactly how components function
-- **Customization**: Direct code modification replaces style-override workarounds
-- **AI Integration**: LLMs can read, understand, and improve component code
-- **Open Code**: Top layer remains editable, not locked in library
-
-This aligns with XDS zero-styling architecture — users get the code, can customize, AI can read/modify.
-
-**Recommendation**: shadcn-style CLI for recipes.
-
-Source: [shadcn/ui Documentation](https://ui.shadcn.com/docs)
-
----
-
-## 4. Starter Templates
-
-Full project scaffolds for new apps.
-
-| Method | How It Works | Pros | Cons |
-|--------|--------------|------|------|
-| **`create-xds` CLI** | `npx create-xds my-app` scaffolds full project | Familiar pattern (CRA, Vite), batteries-included | Maintenance of templates |
-| **GitHub template repos** | "Use this template" button on GitHub | Zero tooling, GitHub-native | No customization prompts |
-| **degit** | `npx degit xds/starter my-app` | Lightweight, no git history | Less discoverable |
-| **Stackblitz/CodeSandbox** | One-click cloud templates | Instant try-before-install | Not local-first |
-
-**Recommendation**: `create-xds` CLI with prompts for variants (Next.js, Vite, etc.) + GitHub template repos as fallback.
-
----
-
-## Recommended Architecture
-
-```
-xds/
-├── packages/
-│ ├── core/ # Components (npm)
-│ ├── cli/ # `npx xds add <recipe>` (shadcn-style)
-│ └── create-xds/ # `npx create-xds` scaffolder
-├── templates/
-│ ├── nextjs-starter/ # GitHub template repo
-│ └── vite-starter/
-├── skills/
-│ ├── .cursor/rules/ # Cursor rules (also on PRPM)
-│ └── .claude/commands/ # Claude Code commands
-└── .vscode/
- └── xds.code-snippets # VS Code snippets
-```
-
-### Distribution Channels
-
-| Artifact | Primary Channel | Secondary Channel |
-|----------|-----------------|-------------------|
-| Components | npm (`@xds/core`) | — |
-| Recipes | CLI (`npx xds add`) | Docs site |
-| Starters | CLI (`npx create-xds`) | GitHub templates |
-| AI rules | npm + PRPM | Repo inclusion |
-| Snippets | Repo `.vscode/` | Docs (manual copy) |
-
----
-
-## Open Questions
-
-- Should PRPM be a dependency or optional enhancement?
-- How do we version AI rules separately from components?
-- Can we auto-detect IDE and install appropriate snippets/rules?
-
----
-
-## Sources
-
-- [PRPM: Package Manager for Cursor Rules](https://forum.cursor.com/t/prpm-a-package-manager-for-cursor-rules-1800-cursor-rules-installable-via-the-cli/139557)
-- [shadcn/ui CLI Documentation](https://ui.shadcn.com/docs)
-- [Claude Code Skills Guide](https://gist.github.com/alirezarezvani/a0f6e0a984d4a4adc4842bbe124c5935)
diff --git a/.context/explorations/frontend-developer-jtbd.md b/.context/explorations/frontend-developer-jtbd.md
deleted file mode 100644
index cc35356e63..0000000000
--- a/.context/explorations/frontend-developer-jtbd.md
+++ /dev/null
@@ -1,149 +0,0 @@
-# Frontend Developer Jobs To Be Done
-
-*Exploration — January 2026*
-
-## Context
-
-Research into the jobs frontend developers are trying to accomplish when setting up and building with UI systems. Goal: ensure XDS serves the right jobs and doesn't over-engineer for jobs that don't exist.
-
----
-
-## Research Findings
-
-### Core Developer Jobs (from research)
-
-| Job | Description | Frequency |
-|-----|-------------|-----------|
-| **Translate designs to code** | Convert mockups/specs into functional UI | Daily |
-| **Maintain consistency** | Ensure visual/behavioral consistency across app | Ongoing |
-| **Test across environments** | Verify UI works in different browsers/devices | Per feature |
-| **Collaborate with team** | Work with designers, backend, other devs | Daily |
-| **Optimize performance** | Reduce load times, improve responsiveness | Periodic |
-| **Debug issues** | Fix visual bugs, interaction problems | As needed |
-
-Source: [Guvi: What Does a Front End Developer Do](https://www.guvi.in/blog/what-does-a-front-end-developer-do/)
-
-### Design System-Specific Jobs
-
-| Job | Pain Point When Unmet |
-|-----|----------------------|
-| **Discover available components** | "Teams don't know what's available in the system" |
-| **Trust component documentation** | "Developers question whether documented components match production reality" |
-| **Integrate with existing toolchain** | "System components don't fit existing toolchains or workflows" |
-| **Reduce design-to-code translation** | "Manual interpretation creates rework and inconsistency" |
-| **Keep implementations current** | "Updating implementations when systems evolve" |
-
-Source: [Netguru: Design System Adoption Pitfalls](https://www.netguru.com/blog/design-system-adoption-pitfalls)
-
-### Key Insight: Adoption > Features
-
-"Design systems aren't failing because they're poorly built—they're failing because no one's using them."
-
-The solution isn't technical—it's organizational, requiring:
-- Clear ownership structures
-- Active team engagement
-- Easy discovery
-- Trust in the system
-
----
-
-## XDS Builder Jobs Framework
-
-Based on research, here are the jobs XDS should serve:
-
-### Setup Phase Jobs
-
-| Job | What Success Looks Like |
-|-----|------------------------|
-| **Set up project styling** | Define tokens, themes in one place; immediate visual consistency |
-| **Configure for my stack** | Works with my build tools, framework, IDE |
-| **Adopt incrementally** | Can start with one component, expand over time |
-
-### Build Phase Jobs
-
-| Job | What Success Looks Like |
-|-----|------------------------|
-| **Construct pages from components** | Compose UI quickly with typed props, autocomplete |
-| **Customize component appearance** | Theme changes propagate everywhere automatically |
-| **Handle edge cases** | Swizzle when needed, clear escalation path |
-| **Stay consistent with design** | Components match design specs out of the box |
-
-### Maintain Phase Jobs
-
-| Job | What Success Looks Like |
-|-----|------------------------|
-| **Update to new versions** | Clear migration path, deprecation warnings |
-| **Debug visual issues** | Predictable styles, easy to trace |
-| **Scale to more features** | System grows with app, no breaking changes |
-
-### Collaborate Phase Jobs
-
-| Job | What Success Looks Like |
-|-----|------------------------|
-| **Share patterns with team** | Components are self-documenting, Storybook integration |
-| **Onboard new developers** | Props-only API, familiar patterns |
-| **Work with AI assistants** | Typed APIs, constrained options, predictable patterns |
-
----
-
-## How XDS Maps to Jobs
-
-| XDS Layer | Primary Jobs Served |
-|-----------|---------------------|
-| **Theme Layer** | Set up styling, customize appearance, maintain consistency |
-| **Component API** | Construct pages, stay consistent, onboard developers, work with AI |
-| **Swizzle Layer** | Handle edge cases, customize beyond theme |
-| **CLI/Tooling** | Configure for stack, adopt incrementally, update versions |
-| **Storybook/Docs** | Discover components, share patterns, trust documentation |
-
----
-
-## Jobs XDS Should NOT Try to Serve
-
-| Anti-Job | Why Not |
-|----------|---------|
-| **Backend/API development** | Out of scope |
-| **State management** | Different concern, many solutions exist |
-| **Routing/navigation logic** | Framework-specific |
-| **Data fetching** | Not a styling/component concern |
-| **Animation authoring** | Future phase, not core |
-
----
-
-## Implications for Architecture
-
-### Must-Haves (serves core jobs)
-
-- Typed props API (construct pages, work with AI)
-- Theme system (set up styling, customize appearance)
-- Swizzle API (handle edge cases)
-- Good docs/Storybook (discover components, trust documentation)
-
-### Nice-to-Haves (serves secondary jobs)
-
-- CLI for scaffolding (configure for stack)
-- Migration tooling (update versions)
-- Tailwind interop (adopt incrementally for Tailwind users)
-
-### Won't-Do (not our jobs)
-
-- State management solutions
-- Routing components
-- Data layer abstractions
-
----
-
-## Open Questions
-
-- Should we formally interview developers to validate these jobs?
-- Are there jobs specific to AI-assisted development we're missing?
-- How do enterprise vs indie developer jobs differ?
-
----
-
-## Sources
-
-- [Guvi: What Does a Front End Developer Do](https://www.guvi.in/blog/what-does-a-front-end-developer-do/)
-- [Netguru: Design System Adoption Pitfalls](https://www.netguru.com/blog/design-system-adoption-pitfalls)
-- [Netguru: Frontend Development Process](https://www.netguru.com/blog/front-end-development-process)
-- [Digital Leadership: JTBD in UX Design](https://digitalleadership.com/glossary/jobs-to-be-done-ux/)
diff --git a/.context/explorations/layer-components.md b/.context/explorations/layer-components.md
deleted file mode 100644
index e3b270fa73..0000000000
--- a/.context/explorations/layer-components.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Layer Components
-
-Status tracking for layer component implementation.
-
-## Completed ✓
-
-| Component | Hook | Status |
-|-----------|------|--------|
-| useXDSLayer | — | ✓ Core hook with context/fixed modes |
-| XDSHoverCard | useXDSHoverCard | ✓ Interactive hover content |
-| XDSTooltip | useXDSTooltip | ✓ Inverted colors, non-interactive |
-
-All completed components are themeable via `ComponentStyles`.
-
-See `/packages/core/src/Layer/README.md` for full API documentation.
-
-## Planned
-
-### Anchored Layers (useXDSLayer)
-
-Position relative to trigger element via CSS anchor positioning.
-
-| Component | Trigger | Notes |
-|-----------|---------|-------|
-| Popover | Click | Light-dismiss with `popover="auto"` |
-| Menu | Click | Keyboard navigation, selection |
-
-### Modal Layers (`<dialog>`)
-
-Use `<dialog>` element with `showModal()` for focus trap, backdrop, Escape handling.
-
-| Component | Behavior | Notes |
-|-----------|----------|-------|
-| Dialog | Centered | Scale/fade animation |
-| Sheet | Edge-anchored | Slides from edge |
-
-### Viewport Layers (popover + fixed)
-
-Position relative to viewport, not an anchor element.
-
-| Component | Position | Notes |
-|-----------|----------|-------|
-| Toast | Corner (e.g., top-right) | Stacks multiple, auto-dismiss |
-
-Toast uses `popover="manual"` for top-layer + `position: fixed` for viewport positioning.
-
-## XDSLayerProvider
-
-Unified provider for all imperative layers (Dialog, Sheet, Toast).
-
-```tsx
-<XDSLayerProvider toastInset={{ bottom: 60 }}> {/* Clear footer */}
- <App />
-</XDSLayerProvider>
-```
-
-Responsibilities:
-- Stacking order enforcement (Toast > Dialog > Sheet)
-- Toast positioning configuration (`toastInset`, `toastPosition`)
-- Imperative API via hooks (`useDialog`, `useSheet`, `useToast`)
-
-## References
-
-- [CSS Anchor Positioning](https://drafts.csswg.org/css-anchor-position-1/)
-- [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
diff --git a/.context/explorations/required-props-pattern.md b/.context/explorations/required-props-pattern.md
deleted file mode 100644
index 16f07a0f9b..0000000000
--- a/.context/explorations/required-props-pattern.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# Required Props Pattern
-
-*Exploration — January 2026*
-
-## Context
-
-Exploring whether making all component props required (no defaults) improves AI code generation. Hypothesis: explicit APIs are more "vibe-able" because every example demonstrates all props and errors are more actionable.
-
-Inspired by Rust's reputation for being LLM-friendly due to explicit, detailed compiler errors.
-
----
-
-## Research Findings
-
-### Why Rust Works Well for LLMs
-
-**Not because everything is required — because errors are explicit and actionable.**
-
-Microsoft's RustAssistant achieved 74% accuracy fixing Rust compilation errors because the compiler provides:
-- Error code
-- Exact location
-- Documentation and examples for the error type
-
-This enables fast iterate-until-correct loops. The LLM knows exactly what's wrong and how to fix it.
-
-Source: [RustAssistant: Using LLMs to Fix Compilation Errors in Rust Code](https://www.microsoft.com/en-us/research/publication/rustassistant-using-llms-to-fix-compilation-errors-in-rust-code/)
-
-### Arguments FOR Required Props
-
-| Benefit | Explanation |
-|---------|-------------|
-| Actionable errors | "Missing prop X" is specific; silent wrong defaults are not |
-| Complete examples | Every usage shows every prop — no hidden behavior |
-| Forced intentionality | Can't accidentally rely on implicit defaults |
-| Training data quality | LLMs learn from complete specifications |
-
-### Arguments AGAINST / Caveats
-
-| Concern | Explanation |
-|---------|-------------|
-| LLMs struggle with detail | Research shows models "overlook details in prompts" — more required props = more to miss |
-| No direct research | No studies found comparing all-required vs optional for LLM accuracy |
-| Human DX cost | Sensible defaults reduce decision fatigue for humans |
-| Rust uses builders | Even Rust uses builder patterns for optional fields |
-
-**Key finding from LLM failure analysis:**
-- Complexity alone doesn't predict failure
-- Semantic understanding is the bottleneck
-- 76/148 tasks failed across *all* models when prompts were underspecified
-
-Source: [Where Do LLMs Still Struggle?](https://arxiv.org/html/2511.04355)
-
-### How Rust Actually Handles This
-
-Rust doesn't make everything required. Instead:
-
-1. **Structs require all fields** — but builders provide optional fields
-2. **Type state pattern** — compile-time enforcement of which fields are set
-3. **Recommendation**: Only use for "types with at least five parts or complex interdependencies"
-
-Source: [Build Rust API with Builder Pattern](https://blog.logrocket.com/build-rust-api-builder-pattern/)
-
----
-
-## Implications for XDS
-
-The insight isn't "all props required" — it's "explicit errors with actionable messages."
-
-### Proposed Approach
-
-| Prop Type | Required? | Rationale |
-|-----------|-----------|-----------|
-| Behavioral props | Yes | Affects component behavior; must be explicit |
-| Structural props | Yes | Affects DOM structure; must be explicit |
-| Styling/presentation | Optional | Pure visual; safe defaults exist |
-
-### Error Message Design
-
-More important than required-vs-optional is error quality:
-
-```
-// Bad: silent wrong behavior
-<XDSButton>Click</XDSButton> // defaults to type="button", looks like submit
-
-// Better: required prop
-<XDSButton>Click</XDSButton> // Error: missing required prop 'type'
-
-// Best: actionable error with guidance
-<XDSButton>Click</XDSButton>
-// Error: XDSButton requires 'type' prop.
-// Options: "button" | "submit" | "reset"
-// Example: <XDSButton type="button">Click</XDSButton>
-```
-
----
-
-## Open Questions
-
-- How do we measure "error actionability" for LLMs?
-- ~~Should XDS provide an `llms.txt` with component examples for each prop combination?~~ **Answered**: No — no AI system currently reads llms.txt. Not worth investment. See `ai-trajectory-predictions.md`.
-- Can we A/B test required vs optional props with AI coding assistants?
-
----
-
-## Related
-
-- `ai-design-system-gaps.md` — Strategy 4: Typed Component APIs
-- `zero-styling-architecture.md` — Zero styling = nothing optional anyway
-
----
-
-## Sources
-
-- [RustAssistant: Using LLMs to Fix Compilation Errors](https://www.microsoft.com/en-us/research/publication/rustassistant-using-llms-to-fix-compilation-errors-in-rust-code/) — 74% accuracy with explicit errors
-- [Where Do LLMs Still Struggle?](https://arxiv.org/html/2511.04355) — Semantic understanding > complexity
-- [Build Rust API with Builder Pattern](https://blog.logrocket.com/build-rust-api-builder-pattern/) — Required vs optional in Rust
-- [Sensible Defaults](https://www.thoughtworks.com/insights/blog/technology-strategy/better-tech-decision-making-underpinned-by-sensible-defaults) — Value of good defaults
diff --git a/.context/explorations/rsc-utilities.md b/.context/explorations/rsc-utilities.md
deleted file mode 100644
index 6b614618c8..0000000000
--- a/.context/explorations/rsc-utilities.md
+++ /dev/null
@@ -1,366 +0,0 @@
-# RSC Utilities
-
-Generic primitives for lazy loading, intersection observation, and React Server Component streaming.
-
-## Overview
-
-| Component | Fetches | Renders | Use Case |
-| ------------------------ | ----------- | ------------------- | --------------------------- |
-| `XDSSkeleton` | — | Shimmer placeholder | Loading states |
-| `XDSSpinner` | — | Spinning indicator | In-progress states |
-| `XDSIntersectionTrigger` | — | Fires callback | Custom intersection logic |
-| `XDSLazy` | Data (JSON) | Client-side | Lazy cell/field values |
-| `XDSStream` | RSC flight | Server components | Infinite scroll, pagination |
-
-## XDSSkeleton
-
-Loading placeholder with shimmer animation:
-
-```tsx
-<XDSSkeleton /> // Full width
-<XDSSkeleton width={100} /> // Fixed width
-<XDSSkeleton width="50%" /> // Percentage
-<XDSSkeleton height={20} /> // Custom height
-<XDSSkeleton shape="circle" /> // Avatar placeholder
-<XDSSkeleton animate={false} /> // No animation
-```
-
-## XDSSpinner
-
-Loading spinner for in-progress states:
-
-```tsx
-<XDSSpinner />
-<XDSSpinner size="small" />
-<XDSSpinner size="large" />
-```
-
-## XDSIntersectionTrigger
-
-Fires a callback when element enters viewport. For client-side pagination with callbacks:
-
-```tsx
-<XDSIntersectionTrigger
- onIntersect={loadMore}
- rootMargin="200px"
- disabled={!hasMore}>
- {isLoading && <XDSSpinner />}
-</XDSIntersectionTrigger>
-```
-
-### Props
-
-```tsx
-interface XDSIntersectionTriggerProps {
- onIntersect: () => void; // Callback when visible
- rootMargin?: string; // Intersection margin (default: '100px')
- threshold?: number; // Visibility threshold (default: 0)
- disabled?: boolean; // Disable observation
- children?: ReactNode; // Content to render
-}
-```
-
-### Implementation
-
-```tsx
-'use client';
-
-function XDSIntersectionTrigger({
- onIntersect,
- rootMargin = '100px',
- threshold = 0,
- disabled = false,
- children,
-}) {
- const ref = useRef<HTMLDivElement>(null);
-
- useEffect(() => {
- if (disabled || !ref.current) return;
-
- const observer = new IntersectionObserver(
- ([entry]) => {
- if (entry.isIntersecting) {
- onIntersect();
- }
- },
- {rootMargin, threshold},
- );
-
- observer.observe(ref.current);
- return () => observer.disconnect();
- }, [disabled, onIntersect, rootMargin, threshold]);
-
- return <div ref={ref}>{children}</div>;
-}
-```
-
-## XDSLazy
-
-Lazy load wrapper that fetches data on intersection and renders client-side:
-
-```tsx
-<XDSLazy
- fetch={() => fetchScore(user.id)}
- fallback={<XDSSkeleton width={60} />}>
- {score => <span>{score}</span>}
-</XDSLazy>
-```
-
-### Props
-
-```tsx
-interface XDSLazyProps<T> {
- fetch: () => Promise<T>; // Data fetcher
- fallback: ReactNode; // Loading placeholder
- children: (data: T) => ReactNode; // Render function
- rootMargin?: string; // Intersection margin (default: '100px')
-}
-```
-
-### Implementation
-
-```tsx
-'use client';
-
-function XDSLazy<T>({
- fetch,
- fallback,
- children,
- rootMargin = '100px',
-}: XDSLazyProps<T>) {
- const ref = useRef<HTMLDivElement>(null);
- const [data, setData] = useState<T | null>(null);
- const [loading, setLoading] = useState(false);
- const [triggered, setTriggered] = useState(false);
-
- useEffect(() => {
- if (triggered || !ref.current) return;
-
- const observer = new IntersectionObserver(
- async ([entry]) => {
- if (entry.isIntersecting) {
- setTriggered(true);
- setLoading(true);
- observer.disconnect();
-
- try {
- const result = await fetch();
- setData(result);
- } finally {
- setLoading(false);
- }
- }
- },
- {rootMargin},
- );
-
- observer.observe(ref.current);
- return () => observer.disconnect();
- }, [triggered, fetch, rootMargin]);
-
- if (data !== null) {
- return <>{children(data)}</>;
- }
-
- return <div ref={ref}>{loading || triggered ? fallback : null}</div>;
-}
-```
-
-## XDSStream
-
-Fetches RSC flight response on intersection and renders server components. For React Server Component pagination:
-
-```tsx
-<XDSStream
- endpoint="/api/users"
- params={{cursor: nextCursor}}
- loading={<XDSSpinner />}
-/>
-```
-
-### Props
-
-```tsx
-interface XDSStreamProps {
- endpoint: string; // RSC endpoint URL
- params?: Record<string, string>; // Query params (cursor, limit, etc.)
- rootMargin?: string; // Intersection margin (default: '200px')
- loading?: ReactNode; // Loading indicator
- disabled?: boolean; // Disable fetching
-}
-```
-
-### Implementation
-
-```tsx
-'use client';
-
-function XDSStream({
- endpoint,
- params,
- rootMargin = '200px',
- loading,
- disabled = false,
-}) {
- const ref = useRef<HTMLDivElement>(null);
- const [content, setContent] = useState<ReactNode>(null);
- const [fetching, setFetching] = useState(false);
-
- useEffect(() => {
- if (disabled || fetching || content) return;
-
- const observer = new IntersectionObserver(
- async ([entry]) => {
- if (entry.isIntersecting) {
- setFetching(true);
- observer.disconnect();
-
- const url = params
- ? `${endpoint}?${new URLSearchParams(params)}`
- : endpoint;
-
- const response = await fetch(url, {
- headers: {RSC: '1'},
- });
-
- // Framework-specific flight response handling
- const serverContent = await createFromReadableStream(response.body);
- setContent(serverContent);
- setFetching(false);
- }
- },
- {rootMargin},
- );
-
- if (ref.current) observer.observe(ref.current);
- return () => observer.disconnect();
- }, [disabled, fetching, content, endpoint, params, rootMargin]);
-
- // Already fetched - render server content
- if (content) return <>{content}</>;
-
- // Disabled - render nothing
- if (disabled) return null;
-
- // Sentinel + loading state
- return <div ref={ref}>{fetching && loading}</div>;
-}
-```
-
-### Recursive Pattern
-
-The server endpoint returns content + next trigger, creating a chain:
-
-```tsx
-// /api/users endpoint (server)
-async function UsersEndpoint({searchParams}) {
- const cursor = searchParams.cursor;
- const {items, nextCursor, hasMore} = await fetchUsers({
- after: cursor,
- limit: 20,
- });
-
- return (
- <>
- {items.map(item => (
- <Item key={item.id} data={item} />
- ))}
-
- {hasMore && (
- <XDSStream endpoint="/api/users" params={{cursor: nextCursor}} />
- )}
- </>
- );
-}
-```
-
-Each fetch returns:
-
-1. New content
-2. Next `XDSStream` sentinel (if more data exists)
-
-This creates infinite scroll without client-side state management.
-
-### Considerations
-
-- **Framework coupling**: Flight response parsing varies (Next.js, Waku, etc.)
-- **Error handling**: Consider adding error boundary or error state
-- **Retry**: Could add retry logic on fetch failure
-- **Deduplication**: Prevent double-fetches on rapid scroll
-
-## Usage Examples
-
-### List with Infinite Scroll
-
-```tsx
-async function UserListPage() {
- const {users, nextCursor, hasMore} = await fetchUsers({limit: 20});
-
- return (
- <XDSList>
- {users.map(user => (
- <XDSListItem key={user.id}>{user.name}</XDSListItem>
- ))}
-
- {hasMore && (
- <XDSStream
- endpoint="/api/users"
- params={{cursor: nextCursor}}
- loading={<XDSSpinner />}
- />
- )}
- </XDSList>
- );
-}
-```
-
-### Card Grid with Lazy Images
-
-```tsx
-<div className="grid">
- {items.map(item => (
- <Card key={item.id}>
- <XDSLazy
- fetch={() => fetchThumbnail(item.id)}
- fallback={<XDSSkeleton shape="rectangle" height={200} />}>
- {src => <img src={src} alt={item.title} />}
- </XDSLazy>
- <h3>{item.title}</h3>
- </Card>
- ))}
-</div>
-```
-
-### Client-Side Pagination
-
-```tsx
-function ClientPaginatedList() {
- const [items, setItems] = useState(initialItems);
- const [cursor, setCursor] = useState(initialCursor);
- const [loading, setLoading] = useState(false);
- const [hasMore, setHasMore] = useState(true);
-
- const loadMore = async () => {
- setLoading(true);
- const {items: newItems, nextCursor} = await fetchItems({after: cursor});
- setItems(prev => [...prev, ...newItems]);
- setCursor(nextCursor);
- setHasMore(!!nextCursor);
- setLoading(false);
- };
-
- return (
- <ul>
- {items.map(item => (
- <li key={item.id}>{item.name}</li>
- ))}
-
- <XDSIntersectionTrigger
- onIntersect={loadMore}
- disabled={!hasMore || loading}>
- {loading && <XDSSpinner />}
- </XDSIntersectionTrigger>
- </ul>
- );
-}
-```
diff --git a/.context/explorations/stylex-patterns.md b/.context/explorations/stylex-patterns.md
deleted file mode 100644
index 8519b2441a..0000000000
--- a/.context/explorations/stylex-patterns.md
+++ /dev/null
@@ -1,135 +0,0 @@
-# StyleX Patterns and Challenges
-
-Notes on StyleX usage patterns discovered while building XDS components.
-
-## The `xstyle` Prop Pattern
-
-When components need configurable styles, use the `xstyle` prop with `StyleXStyles` type. This ensures consumers use StyleX instead of inline styles, maintaining compile-time optimization and consistency.
-
-### Implementation
-
-```tsx
-import type {StyleXStyles} from '@stylexjs/stylex';
-
-export interface MyComponentProps extends Omit<
- HTMLAttributes<HTMLElement>,
- 'style' | 'className'
-> {
- // Component-specific props...
-
- /** StyleX styles to apply to the component. */
- xstyle?: StyleXStyles;
-
- children?: ReactNode;
-}
-
-export const MyComponent = forwardRef<HTMLElement, MyComponentProps>(
- function MyComponent({xstyle, children, ...props}, ref) {
- const stylexProps = stylex.props(styles.base, xstyle);
-
- return (
- <div ref={ref} {...stylexProps} {...props}>
- {children}
- </div>
- );
- },
-);
-```
-
-### Key Points
-
-1. **Omit `style` and `className`**: Use `Omit<HTMLAttributes<HTMLElement>, 'style' | 'className'>` to prevent inline styles and ensure StyleX usage.
-
-2. **Merge styles correctly**: Pass `xstyle` as the last argument to `stylex.props()` so consumer styles can override component defaults.
-
-3. **Constrained vs. freeform styles**:
- - **Higher-level components** (e.g., Button, Card): Prefer constrained APIs with specific props (`variant`, `size`) over open `xstyle`. This enforces design consistency.
- - **Primitive/layout components** (e.g., Stack, Box): It's acceptable to allow freeform `xstyle` since these are building blocks that need flexibility.
-
-### Usage Example
-
-```tsx
-import * as stylex from '@stylexjs/stylex';
-import { colorTokens } from '@xds/core';
-
-const customStyles = stylex.create({
- highlight: {
- backgroundColor: colorTokens.wash,
- borderRadius: radiusTokens.element,
- },
-});
-
-// Consumer usage
-<XDSHStack gap="space2" xstyle={customStyles.highlight}>
- <Item />
- <Item />
-</XDSHStack>
-
-// Multiple styles via array
-<XDSVStack xstyle={[styles.container, styles.padded]}>
- <Content />
-</XDSVStack>
-```
-
-## Compile-Time Requirement
-
-StyleX requires all styles to be compiled at build time via the Babel plugin. You cannot use `stylex.create()` at runtime (e.g., in Storybook's preview.tsx).
-
-**Solution**: Have the consuming app handle the build for proper style deduping, merging, and bundling.
-
-## Theme Variables with light-dark()
-
-StyleX works well with CSS `light-dark()` function for automatic dark mode support:
-
-```tsx
-const colorTheme = stylex.createTheme(colorTokens, {
- accent: 'light-dark(#0064E0, #2694FE)',
- surface: 'light-dark(#FFFFFF, #1C1C1C)',
-});
-```
-
-The Theme provider sets `color-scheme` property to control which value is used:
-
-```tsx
-const wrapperStyles = stylex.create({
- light: {colorScheme: 'light'},
- dark: {colorScheme: 'dark'},
- system: {colorScheme: 'light dark'},
-});
-```
-
-## Public CSS Variables
-
-To expose StyleX tokens as predictable CSS variables for non-StyleX consumers, use the `--` key syntax with `defineVars`.
-
-```tsx
-export const publicVariables = {
- all: {
- '--xds-accent': colorTokens.accent,
- '--xds-surface': colorTokens.surface,
- // ... map all tokens
- },
-};
-
-export const allTokens = stylex.defineVars(publicVariables.all);
-```
-
-Use in `stylex.create` calls or apply a theme using `stylex.createTheme()`:
-
-```tsx
-// Use in stylex.create() calls:
-const styles = stylex.create({
- container: {
- backgroundColor: allTokens['--xds-surface'],
- borderColor: allTokens['--xds-accent'],
- },
-});
-
-// Or create a theme override with stylex.createTheme():
-const customTheme = stylex.createTheme(allTokens, {
- '--xds-accent': '#ff0000',
- '--xds-surface': '#ffffff',
-});
-```
-
-Consumers can then use `var(--xds-surface)` in plain CSS or inline styles.
diff --git a/.context/explorations/stylex-vs-tailwind.md b/.context/explorations/stylex-vs-tailwind.md
deleted file mode 100644
index e7300350ae..0000000000
--- a/.context/explorations/stylex-vs-tailwind.md
+++ /dev/null
@@ -1,1382 +0,0 @@
-# StyleX vs Tailwind: Theming Architecture Comparison
-
-*Exploration — January 2026*
-
-## Context
-
-Evaluating StyleX and Tailwind CSS for XDS theming infrastructure. Key considerations:
-- Previous success with StyleX-based theme systems
-- Tailwind's superior API ergonomics
-- AI ecosystem pressure (most AI UIs use Tailwind)
-- Alignment with zero-styling architecture
-
----
-
-## Core Differences
-
-| Aspect | StyleX | Tailwind CSS (v4) |
-|--------|--------|-------------------|
-| **Architecture** | CSS-in-JS with compile-time extraction | Utility-first CSS framework |
-| **Output** | Static atomic CSS, zero runtime | Static CSS from build |
-| **Theming** | `defineVars()` + `createTheme()` — type-safe, scoped | `@theme` directive — CSS-based, generates utilities |
-| **Type safety** | Full TypeScript integration, constrained props | Limited — arbitrary values still possible |
-| **Bundle scaling** | Plateaus — atomic CSS deduplicated | Grows with unique utility combinations |
-| **AI familiarity** | Low — less training data | High — dominant in AI training data |
-| **DX/Ergonomics** | Verbose JS objects | Concise class strings |
-
----
-
-## StyleX Deep Dive
-
-### How It Works
-
-StyleX is a **build-time compiler**:
-1. Developers write styles in JavaScript using `stylex.create()`
-2. Babel plugin scans codebase during build
-3. Each unique style property-value pair generates a deterministic atomic class
-4. JavaScript code is replaced with generated atomic CSS class strings
-
-### Theming Architecture
-
-**Define variables:**
-```javascript
-export const colors = stylex.defineVars({
- primaryText: { default: 'black', [DARK]: 'white' },
- accent: 'blue',
- background: { default: 'white', [DARK]: '#1a1a1a' },
-});
-```
-
-**Create theme overrides:**
-```javascript
-export const dracula = stylex.createTheme(colors, {
- primaryText: { default: 'purple', [DARK]: 'lightpurple' },
- accent: 'red',
- background: { default: '#555', [DARK]: 'black' },
-});
-```
-
-**Apply scoped theme:**
-```javascript
-<div {...stylex.props(dracula, styles.container)}>
- {/* All children use dracula theme tokens */}
-</div>
-```
-
-### Strengths
-
-| Benefit | Details |
-|---------|---------|
-| **True constraint enforcement** | TypeScript prevents invalid tokens at compile time |
-| **Scoped theming** | Themes apply to subtrees, enabling component-level overrides |
-| **Predictable merging** | Last style wins, like `Object.assign()` |
-| **Zero runtime** | Compile-time extraction, no JS execution for styles |
-| **Bundle plateaus** | CSS size grows sublinearly with app size |
-| **Cross-project composition** | Components using StyleX compose correctly when published to npm |
-
-### Weaknesses
-
-| Issue | Details |
-|-------|---------|
-| **Lower AI familiarity** | Less training data than Tailwind |
-| **Verbose syntax** | JS objects vs class strings |
-| **Tooling maturity** | Smaller ecosystem |
-| **Learning curve** | Different mental model from utility CSS |
-
-Sources: [StyleX Official Docs](https://stylexjs.com/docs/learn/), [BetterStack Guide](https://betterstack.com/community/guides/scaling-nodejs/stylex-metas/)
-
----
-
-## Complex Selectors: StyleX vs Tailwind
-
-### The Problem
-
-Parent-child state relationships are common:
-- Show delete button when list item is hovered
-- Change icon color when card is focused
-- Reveal actions when row is selected
-
-### Tailwind: Simple with `group-*`
-
-Tailwind has first-class support via the `group` pattern:
-
-```html
-<div class="group">
- <h3>Item Title</h3>
- <button class="opacity-0 group-hover:opacity-100 transition-opacity">
- Delete
- </button>
-</div>
-```
-
-That's it. One `group` class on parent, `group-hover:*` on children. No extra setup.
-
-**Nested groups**:
-```html
-<div class="group/card">
- <div class="group/actions">
- <button class="group-hover/card:opacity-50 group-hover/actions:opacity-100">
- Edit
- </button>
- </div>
-</div>
-```
-
-### StyleX: CSS Variables Pattern
-
-StyleX doesn't support descendant selectors. The workaround uses CSS variables:
-
-**Step 1: Define variables**
-```typescript
-// tokens.stylex.ts
-export const parentState = stylex.defineVars({
- childOpacity: '0',
-});
-```
-
-**Step 2: Parent sets values on hover**
-```typescript
-const styles = stylex.create({
- card: {
- [parentState.childOpacity]: {
- default: '0',
- ':hover': '1',
- },
- },
-});
-```
-
-**Step 3: Child reads variables**
-```typescript
-const styles = stylex.create({
- button: {
- opacity: parentState.childOpacity,
- transition: 'opacity 0.2s',
- },
-});
-```
-
-### Ergonomics Comparison
-
-| Aspect | Tailwind | StyleX |
-|--------|----------|--------|
-| **Lines of code** | 2 classes | 3 files, ~15 lines |
-| **Setup required** | None | Define variables first |
-| **Readability** | `group-hover:opacity-100` is self-explanatory | Variable indirection |
-| **Nested groups** | `group/name` naming | Multiple variable sets |
-| **Learning curve** | Intuitive | Requires understanding pattern |
-
-**Tailwind wins on ergonomics** for this use case.
-
-### Why StyleX Chose This Approach
-
-| StyleX Principle | Benefit | Cost |
-|------------------|---------|------|
-| **Explicit relationships** | Child opts into parent observation | More verbose |
-| **No "styles at a distance"** | Easier to trace where styles come from | Setup overhead |
-| **Encapsulation** | Child controls what it reads | Indirection |
-| **Static analysis** | All styles traceable at build time | No dynamic selectors |
-
-From StyleX docs: "All styles on an element should be caused by class names on that element itself."
-
-### Performance: Both Are Pure CSS
-
-Both approaches are CSS-only — no JavaScript re-renders:
-- Tailwind: Browser applies `:hover` styles via generated classes
-- StyleX: Browser updates CSS variable, children read via `var()`
-
-No `useState`, no event handlers, no re-renders in either case.
-
-### What This Means for XDS
-
-This is a real ergonomics gap with StyleX. Options:
-
-**Option 1: Accept the verbosity**
-- The pattern works, it's just more setup
-- Document it well, provide helpers
-
-**Option 2: Build abstractions**
-```typescript
-// Potential helper in @xds/variants
-const { parent, child } = createStateRelationship('listItem', {
- actionOpacity: { default: '0', ':hover': '1' },
-});
-
-// Parent
-<div {...stylex.props(parent.container)}>
-
-// Child
-<button {...stylex.props(child.action)}>
-```
-
-**Option 3: Use Tailwind for layout, StyleX for components**
-- Components use StyleX (encapsulation)
-- Page layouts can use Tailwind (ergonomics)
-- The Tailwind preset makes tokens consistent
-
-### Recommendation
-
-Document the CSS variables pattern clearly and consider building a helper abstraction. The verbosity is the cost of StyleX's encapsulation guarantees — worth it for a component library, but should be as painless as possible.
-
-Source: [StyleX: Variables for Descendant Styles](https://stylexjs.com/docs/learn/recipes/descendant-styles/)
-
----
-
-## Tailwind v4 Deep Dive
-
-### How Theming Works
-
-The `@theme` directive defines design tokens that generate both CSS variables AND utility classes:
-
-```css
-@theme {
- --color-primary: oklch(0.72 0.11 178);
- --spacing-sm: 0.5rem;
-}
-```
-
-This creates:
-- CSS variable: `var(--color-primary)`
-- Utility classes: `bg-primary`, `text-primary`, etc.
-
-### Constraining the Theme
-
-**Remove defaults and define only allowed tokens:**
-```css
-@theme {
- --color-*: initial; /* Remove all default colors */
- --color-white: #fff;
- --color-primary: #3f3cbb;
- --color-secondary: #6366f1;
-
- --spacing-*: initial; /* Remove all default spacing */
- --spacing-sm: 0.5rem;
- --spacing-md: 1rem;
- --spacing-lg: 2rem;
-}
-```
-
-Now only `bg-primary`, `bg-secondary`, `bg-white` exist — not `bg-red-500`.
-
-### Theme Variable Namespaces
-
-| Namespace | Utilities Generated |
-|-----------|-------------------|
-| `--color-*` | `bg-*`, `text-*`, `fill-*`, etc. |
-| `--font-*` | `font-sans`, `font-serif`, etc. |
-| `--text-*` | `text-xl`, `text-2xl`, etc. |
-| `--spacing-*` | `px-4`, `max-h-16`, `gap-8`, etc. |
-| `--breakpoint-*` | Responsive variants: `sm:*`, `md:*` |
-| `--shadow-*` | `shadow-md`, `shadow-lg`, etc. |
-| `--radius-*` | `rounded-sm`, `rounded-lg`, etc. |
-
-### Strengths
-
-| Benefit | Details |
-|---------|---------|
-| **Excellent AI generation** | Dominant in training data, LLMs generate it fluently |
-| **`@theme` constrains utilities** | Only defined tokens generate classes |
-| **Ergonomic DX** | Concise class syntax |
-| **Shareable themes** | CSS files can be imported across projects |
-| **Large ecosystem** | Extensive component libraries, templates |
-
-### Weaknesses
-
-| Issue | Details |
-|-------|---------|
-| **Arbitrary values bypass constraints** | `mt-[13px]`, `bg-[#ff0000]` still compile |
-| **Type safety is weak** | No compile-time enforcement of valid classes |
-| **Readability at scale** | Class strings become unwieldy |
-| **Scoped theming is awkward** | Requires CSS variable overrides, not first-class |
-
-Sources: [Tailwind v4 Theme Docs](https://tailwindcss.com/docs/theme), [Tailwind at Scale Issues](https://dev.to/gouranga-das-khulna/why-tailwind-css-might-be-hurting-your-large-scale-projects-3k73)
-
----
-
-## Zero-Styling Architecture Alignment
-
-Recall the core concept from `zero-styling-architecture.md`:
-- Components ship with no styles
-- All styling through theme file
-- Swizzling for structural/behavioral flexibility
-
-| Requirement | StyleX | Tailwind v4 |
-|-------------|--------|-------------|
-| No inline styles on components | ✅ Styles defined in JS, applied via props | ⚠️ Classes are inline, but constrained via `@theme` |
-| Theme as single source of truth | ✅ `defineVars()` creates tokens | ✅ `@theme` creates tokens + utilities |
-| Compile-time enforcement | ✅ TypeScript catches invalid tokens | ❌ Arbitrary values still compile |
-| AI can't generate arbitrary values | ✅ Types prevent it | ❌ AI can still use `[arbitrary]` syntax |
-| Scoped theme overrides (swizzling) | ✅ `createTheme()` scopes to subtree | ⚠️ Requires CSS variable overrides |
-
-**Key insight**: StyleX aligns better with zero-styling architecture because constraints are enforced, not suggested.
-
----
-
-## The Semantic Leakage Problem
-
-### The Problem
-
-Exposing raw CSS variables creates an implicit public API that's hard to evolve:
-
-```
-Consumer A: uses --xds-color-primary because "it's the brand color" ✓ semantic
-Consumer B: uses --xds-color-primary because "it's close to purple I wanted" ✗ presentational
-
-When you change primary → both break
-But only Consumer A was using it "correctly"
-```
-
-At scale (10k+ products), you can't distinguish intent from misuse. Changing "primary" becomes a breaking change for everyone, even those who shouldn't have depended on the specific value.
-
-### Token Tier Architecture
-
-Research recommends a three-tier structure where only the outermost layer is public:
-
-```
-┌─────────────────────────────────────────────────────┐
-│ PRIMITIVE TOKENS (never expose) │
-│ --color-purple-500: #8b5cf6 │
-│ --spacing-16: 1rem │
-├─────────────────────────────────────────────────────┤
-│ SEMANTIC TOKENS (internal) │
-│ --color-primary: var(--color-purple-500) │
-│ --spacing-component-gap: var(--spacing-16) │
-├─────────────────────────────────────────────────────┤
-│ COMPONENT API (the public contract) │
-│ <XDSButton variant="primary" /> │
-│ NOT: style={{ color: 'var(--xds-color-primary)' }}│
-└─────────────────────────────────────────────────────┘
-```
-
-Source: [Rangle.io Token Structure](https://Rangle.io/blog/developing-your-token-structure)
-
-### Tradeoffs of NOT Exposing CSS Variables
-
-| Benefit | Drawback |
-|---------|----------|
-| Full control over evolution | Less flexibility for edge cases |
-| Can distinguish semantic from presentational | Consumers can't do quick one-off styling |
-| Breaking changes are intentional | May push consumers to swizzle more |
-| Clear public API contract | Harder to integrate with CSS-variable-expecting tools |
-| Prevents "close enough" misuse | Can't use CSS features that depend on variables (color-mix, calc) |
-
-### The Swizzling Consideration
-
-**Key question**: Should swizzled components have access to internal tokens?
-
-This creates a tiered access model:
-
-| Usage Mode | Token Access | Rationale |
-|------------|--------------|-----------|
-| **Standard usage** | Props only, no raw tokens | Maximum evolution freedom |
-| **Swizzled components** | Internal tokens available | Maintain consistency while customizing |
-| **Fully custom** | No XDS tokens | You're on your own |
-
-**Argument FOR exposing tokens to swizzled components:**
-- Swizzling is an explicit opt-out of guardrails
-- Consumers still want visual consistency with the system
-- Without tokens, swizzled components can't stay in sync with theme changes
-- It's the "middle ground" between full constraint and full freedom
-
-**Argument AGAINST:**
-- Swizzled components become coupled to internal implementation
-- Token renames/restructuring still breaks swizzled code
-- Creates a "semi-public" API that's hard to version
-
-### Proposed Token Access Model
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ PUBLIC API (versioned, stable) │
-│ - Component props: <XDSButton variant="primary" /> │
-│ - Theme customization: <Theme theme={myTheme} /> │
-│ - Zero styling — no CSS exposure │
-├─────────────────────────────────────────────────────────────┤
-│ SEMANTIC TOKENS (available for swizzle) │
-│ - CSS variables: --xds-color-primary, --xds-spacing-md │
-│ - Documented, versioned with deprecation warnings │
-│ - The "escape hatch" for swizzled components │
-├─────────────────────────────────────────────────────────────┤
-│ BASE/PRIMITIVE TOKENS (documentation only) │
-│ - Not in code — only in design docs │
-│ - purple-500, spacing-16, etc. │
-│ - No CSS variables, no runtime exposure │
-│ - Can change without notice │
-└─────────────────────────────────────────────────────────────┘
-```
-
-This gives:
-- **Standard users**: Props only → maximum evolution freedom
-- **Swizzlers**: Access to semantic CSS variables → consistency while customizing
-- **Base colors**: Not even in code — purely documentation, fully internal
-
-**Key insight**: By not exposing base colors as code at all, they can't leak into consumer codebases. Semantic tokens are the lowest level consumers can access.
-
-### How This Affects the StyleX vs Tailwind Decision
-
-| Factor | StyleX | Tailwind |
-|--------|--------|----------|
-| Can hide internal tokens | ✅ Tokens are JS, not exposed to CSS cascade | ❌ `@theme` generates CSS variables by default |
-| Swizzle token access | ✅ Export specific vars via `defineVars` | ⚠️ All theme vars are public |
-| Evolution safety | ✅ Change internals without breaking consumers | ❌ All tokens are implicit API |
-
-**StyleX advantage**: You choose what to expose. Internal tokens stay internal.
-
-**Tailwind challenge**: `@theme` vars become public CSS variables automatically. Hard to have "private" tokens.
-
----
-
-## Hybrid Approaches
-
-Given the tension between StyleX's enforcement and Tailwind's ecosystem:
-
-### Option 1: StyleX Internally, Tailwind-Compatible Output
-
-- Components use StyleX for type-safe theming
-- Generated atomic classes follow Tailwind naming conventions
-- AI-generated Tailwind code works alongside XDS
-
-**Pros**: Best constraint enforcement, AI compatibility via naming
-**Cons**: Complex build pipeline, potential naming collisions
-
-### Option 2: Tailwind v4 with Strict Constraints
-
-- Use `@theme` to lock down tokens
-- Build-time lint to reject arbitrary values `[...]`
-- Components only expose allowed class combinations via typed props
-
-**Pros**: Native Tailwind, familiar to AI and developers
-**Cons**: Enforcement is tooling-dependent, not language-level
-
-### Option 3: Dual-Mode Components
-
-- Ship both StyleX and Tailwind versions
-- Let consumers choose their styling runtime
-- Shared theme tokens exported to both formats
-
-**Pros**: Maximum flexibility
-**Cons**: Double maintenance, complexity
-
-### Option 4: StyleX Core + Tailwind Interop Layer
-
-- Core components use StyleX (constraint enforcement)
-- Export theme tokens as CSS variables
-- Provide Tailwind preset that uses XDS tokens
-- AI-generated Tailwind code uses same tokens
-
-**Pros**: Strict internals, compatible externally
-**Cons**: Two mental models for contributors
-
-### Migration Tool: tw-to-stylex
-
-[tw-to-stylex](https://github.com/nmn/tw-to-stylex) is a code translator created by Naman Goel (StyleX maintainer at Meta) that converts Tailwind CSS code to StyleX syntax.
-
-**What it does**:
-```tsx
-// Input (Tailwind)
-<div className={cn("m-1 text-red-500", prop.className)} />
-
-// Output (StyleX)
-// Converts to stylex.create() and stylex.props()
-```
-
-**Current status** (as of January 2025):
-- ✅ Handles `cn()` patterns and converts to StyleX props
-- ✅ Manages multiple StyleX imports
-- ✅ Prevents duplicate `stylex.create` calls
-- ❌ Dynamic values with template literals not yet supported
-- ❌ Custom `tw` function (planned)
-
-**Relevance to XDS**:
-
-| Use Case | Value |
-|----------|-------|
-| **Migration path** | Existing Tailwind code → StyleX conversion |
-| **AI-generated code** | LLM generates Tailwind (more training data) → convert to StyleX |
-| **Incremental adoption** | Start with Tailwind, migrate components gradually |
-
-**Limitations**: The tool has gaps with dynamic tokens and template literals. For XDS component authoring, writing StyleX directly is still recommended.
-
-**Potential workflow**:
-1. AI generates Tailwind code (familiar, more training data)
-2. tw-to-stylex converts to StyleX
-3. Manual cleanup for edge cases
-4. Full compile-time enforcement
-
-This could bridge the "AI familiarity gap" — LLMs generate what they know (Tailwind), then tooling converts to what we want (StyleX).
-
-Source: [tw-to-stylex GitHub](https://github.com/nmn/tw-to-stylex)
-
----
-
-## Variant Management Tools: tw-classed, CVA, and Tailwind Variants
-
-### The Problem These Solve
-
-When using Tailwind, components need to manage variants (sizes, colors, states) while staying DRY. Options include:
-- Manual string concatenation: `className={isLarge ? 'px-8 py-4' : 'px-4 py-2'}` (messy at scale)
-- Wrapper libraries that provide type-safe variant APIs
-
-### Three Popular Options
-
-| Tool | Description | Bundle Size | Key Features |
-|------|-------------|-------------|--------------|
-| **tw-classed** | Tailwind + CSS-in-JS DX | ~0kb | Type-safe, variants, compounds, defaults |
-| **CVA** | Class Variance Authority | Small | Framework-agnostic, simple API |
-| **Tailwind Variants** | Official variant management | Small | Slots, responsive variants, conflict resolution |
-
-### tw-classed Deep Dive
-
-**What It Is**: "Make your Tailwind components re-usable" with "Tailwind CSS and CSS-in-JS, the best of both worlds."
-
-**Core API**:
-```typescript
-import { classed } from 'tw-classed';
-
-const Button = classed('button', {
- variants: {
- variant: {
- primary: 'bg-blue-500 text-white',
- secondary: 'bg-gray-200 text-gray-900',
- },
- size: {
- sm: 'text-sm px-2 py-1',
- md: 'text-base px-4 py-2',
- lg: 'text-lg px-6 py-3',
- }
- },
- compoundVariants: [
- {
- variant: 'primary',
- size: 'lg',
- class: 'shadow-lg', // Applied when both conditions match
- }
- ],
- defaultVariants: {
- variant: 'primary',
- size: 'md',
- }
-});
-
-// Usage
-<XDSButton variant="secondary" size="lg">Click me</XDSButton>
-```
-
-**Strengths**:
-- Full TypeScript inference — `variant` prop is typed
-- Zero runtime overhead (~0kb)
-- No `forwardRef` boilerplate
-- Automatic variant autocomplete
-
-**Weaknesses**:
-- Still allows arbitrary Tailwind classes if used outside the variant system
-- No built-in slot/sub-part styling
-- Tied to Tailwind ecosystem
-
-Source: [tw-classed Official Docs](https://tw-classed.vercel.app/)
-
-### Tailwind Variants Deep Dive
-
-**What It Is**: NextUI's official variant management tool with advanced features.
-
-**Slots API** (sub-part styling):
-```typescript
-import { tv } from 'tailwind-variants';
-
-const card = tv({
- slots: {
- base: 'md:flex bg-slate-100 rounded-xl p-8',
- avatar: 'w-24 h-24 md:w-48 rounded-full',
- wrapper: 'flex-1 pt-6 md:p-8',
- title: 'text-xl font-medium',
- description: 'text-gray-500',
- },
- variants: {
- color: {
- primary: {
- base: 'bg-blue-50',
- title: 'text-blue-900',
- },
- secondary: {
- base: 'bg-gray-50',
- title: 'text-gray-900',
- }
- }
- }
-});
-
-const { base, avatar, wrapper, title, description } = card({ color: 'primary' });
-
-// Usage
-<div className={base()}>
- <img className={avatar()} />
- <div className={wrapper()}>
- <h3 className={title()}>...</h3>
- <p className={description()}>...</p>
- </div>
-</div>
-```
-
-**Strengths**:
-- **Slots enable sub-part styling** — exactly what XDS needs
-- Responsive variants
-- Compound slots (apply same classes to multiple slots)
-- Built-in conflict resolution
-- Slot-level overrides
-
-**Weaknesses**:
-- More verbose API than tw-classed
-- Requires understanding slots concept
-- Still Tailwind-dependent
-
-Source: [Tailwind Variants Slots Docs](https://www.tailwind-variants.org/docs/slots)
-
-### CVA (Class Variance Authority)
-
-**What It Is**: Framework-agnostic variant management.
-
-**Core API**:
-```typescript
-import { cva } from 'class-variance-authority';
-
-const button = cva('font-semibold rounded', {
- variants: {
- variant: {
- primary: 'bg-blue-500 text-white',
- secondary: 'bg-gray-200 text-gray-900',
- },
- size: {
- sm: 'text-sm px-2 py-1',
- md: 'text-base px-4 py-2',
- }
- },
- defaultVariants: {
- variant: 'primary',
- size: 'md',
- }
-});
-
-// Usage
-<button className={button({ variant: 'secondary', size: 'lg' })}>
- Click me
-</button>
-```
-
-**Strengths**:
-- Framework-agnostic (works with any CSS)
-- Simplest API
-- Small bundle size
-
-**Weaknesses**:
-- No slots/sub-part styling
-- No responsive variants
-- No conflict resolution
-- Not Tailwind-specific (can use any classes)
-
-Source: [CVA vs Tailwind Variants Comparison](https://dev.to/webdevlapani/cva-vs-tailwind-variants-choosing-the-right-tool-for-your-design-system-12am)
-
-### How Variant Tools Affect XDS Architecture
-
-**Alignment with Zero-Styling Goals**:
-
-| Requirement | tw-classed | Tailwind Variants | CVA | StyleX |
-|-------------|-----------|-------------------|-----|--------|
-| Type-safe props | ✅ | ✅ | ✅ | ✅ |
-| Sub-part styling (slots) | ❌ | ✅ | ❌ | ✅ |
-| Arbitrary value prevention | ⚠️ Partial | ⚠️ Partial | ⚠️ Partial | ✅ Full |
-| Intent-based API | ✅ | ✅ | ✅ | ✅ |
-| Theme token integration | ⚠️ Via Tailwind | ⚠️ Via Tailwind | ⚠️ Manual | ✅ Native |
-| Evolution safety | ❌ Classes are public | ❌ Classes are public | ❌ Classes are public | ✅ Internal tokens |
-
-### The Slot Problem
-
-XDS needs sub-part styling (icon slots, label slots, etc.). Only **Tailwind Variants** and **StyleX** support this natively.
-
-### The Arbitrary Value Problem
-
-All Tailwind-based tools (tw-classed, Tailwind Variants, CVA with Tailwind) **still allow arbitrary values**:
-
-```typescript
-// All of these would work even with variant tools
-<XDSButton className="mt-[13px]" />
-<XDSButton className="bg-[#ff0000]" />
-```
-
-Only StyleX prevents this at compile time through TypeScript.
-
-### Option 5: Tailwind Variants + Strict Linting
-
-Use Tailwind Variants for ergonomics and slots, but add strict safeguards:
-
-1. **Tailwind Variants for component definition** — slots + variants
-2. **Constrained theme via `@theme`** — only allowed tokens exist
-3. **Lint to prevent arbitrary values** — build-time enforcement
-4. **TypeScript wrapper to hide class strings** — components expose props, not className
-
-**Pros**:
-- Slots for sub-part styling (like XDS theming proposal)
-- Tailwind ecosystem compatibility
-- Type-safe variant API
-- Familiar to developers and AI
-
-**Cons**:
-- Enforcement still relies on lint rules (not compile-time)
-- Can't prevent all arbitrary value leakage
-- Theme tokens are public CSS variables
-
----
-
-## Achieving tw-classed Ergonomics Without Exposed CSS Classes
-
-### The Challenge
-
-tw-classed provides excellent variant API ergonomics:
-```typescript
-const Button = classed('button', {
- variants: { variant: { primary: '...' } }
-});
-```
-
-But it has a fundamental constraint issue: **CSS classes are public**. Consumers can:
-- Bypass the variant API with `className` overrides
-- Depend on generated class names (coupling)
-- Use arbitrary Tailwind values
-
-Can we get the ergonomics without the exposed classes?
-
-### Option A: StyleX + Variant Wrapper (Recommended)
-
-Build a variant API wrapper around StyleX that mimics tw-classed ergonomics but maintains enforcement.
-
-**Core implementation**:
-```typescript
-// @xds/variants — Internal wrapper around StyleX
-import * as stylex from '@stylexjs/stylex';
-
-export function createVariants(config) {
- const { base, slots = {}, variants, compoundVariants = [], defaultVariants } = config;
-
- return function(variantProps) {
- // Compute which styles to apply based on variant selection
- const appliedVariants = Object.entries(variantProps).map(([key, value]) => {
- return variants[key]?.[value];
- });
-
- // Apply compound variants
- const appliedCompounds = compoundVariants
- .filter(cv => {
- return Object.entries(cv).every(([key, value]) => {
- if (key === 'style') return true; // Skip the style key
- return variantProps[key] === value;
- });
- })
- .map(cv => cv.style);
-
- return {
- base: () => stylex.props(base, ...appliedVariants, ...appliedCompounds),
- slots: Object.fromEntries(
- Object.entries(slots).map(([name, slotStyles]) => [
- name,
- () => stylex.props(slotStyles)
- ])
- ),
- };
- };
-}
-```
-
-**Usage**:
-```typescript
-// Component definition
-import { createVariants } from '@xds/variants';
-import * as stylex from '@stylexjs/stylex';
-
-const button = createVariants({
- base: stylex.create({
- root: {
- padding: 8,
- borderRadius: 4,
- cursor: 'pointer',
- }
- }).root,
-
- slots: {
- icon: stylex.create({
- root: { width: 16, height: 16, marginRight: 8 }
- }).root,
- label: stylex.create({
- root: { fontWeight: 500 }
- }).root,
- },
-
- variants: {
- variant: {
- primary: stylex.create({
- root: {
- backgroundColor: 'var(--xds-color-primary)',
- color: 'var(--xds-color-on-primary)',
- }
- }).root,
- secondary: stylex.create({
- root: {
- backgroundColor: 'var(--xds-color-secondary)',
- color: 'var(--xds-color-on-secondary)',
- }
- }).root,
- },
- size: {
- sm: stylex.create({
- root: { fontSize: 14, padding: 4 }
- }).root,
- md: stylex.create({
- root: { fontSize: 16, padding: 8 }
- }).root,
- lg: stylex.create({
- root: { fontSize: 18, padding: 12 }
- }).root,
- }
- },
-
- compoundVariants: [
- {
- variant: 'primary',
- size: 'lg',
- style: stylex.create({
- root: { boxShadow: '0 4px 6px rgba(0,0,0,0.1)' }
- }).root,
- }
- ],
-
- defaultVariants: {
- variant: 'primary',
- size: 'md',
- }
-});
-
-// Component using the variant system
-export function Button({ variant = 'primary', size = 'md', icon, children }) {
- const styles = button({ variant, size });
-
- return (
- <button {...styles.base()}>
- {icon && <span {...styles.slots.icon()}>{icon}</span>}
- <span {...styles.slots.label()}>{children}</span>
- </button>
- );
-}
-```
-
-**What this achieves**:
-- ✅ tw-classed-like variant API
-- ✅ Slot-based sub-part styling
-- ✅ Compound variants
-- ✅ Default variants
-- ✅ **No exposed CSS classes** — consumers only see props
-- ✅ TypeScript inference for variant values
-- ✅ Compile-time enforcement via StyleX
-
-**Type inference**:
-```typescript
-type ButtonVariants = {
- variant: 'primary' | 'secondary';
- size: 'sm' | 'md' | 'lg';
-};
-
-// Inferred from variant definition
-type ButtonProps = ButtonVariants & { children: ReactNode; icon?: ReactNode };
-```
-
-**Tradeoffs**:
-| Benefit | Drawback |
-|---------|----------|
-| Zero CSS class exposure | More verbose than tw-classed (JS objects vs strings) |
-| Full compile-time enforcement | Requires custom wrapper (not off-the-shelf) |
-| StyleX bundle benefits | Team needs to learn StyleX |
-| Sub-part styling native | More complex implementation |
-
-### Option B: Tokenami
-
-[Tokenami](https://github.com/tokenami/tokenami) is a design token system that generates **typed CSS properties** instead of classes.
-
-**How it works**:
-```typescript
-import { css } from '@tokenami/css';
-
-// Define tokens
-const tokens = {
- color: {
- primary: '#0066cc',
- secondary: '#6b7280',
- },
- spacing: {
- sm: '0.5rem',
- md: '1rem',
- }
-};
-
-// Usage — CSS properties, not classes
-<button
- style={css({
- backgroundColor: 'var(--color-primary)',
- padding: 'var(--spacing-md)',
- })}
->
- Click me
-</button>
-```
-
-**Variant wrapper**:
-```typescript
-const button = createTokenamiVariants({
- variants: {
- variant: {
- primary: { backgroundColor: 'var(--color-primary)' },
- secondary: { backgroundColor: 'var(--color-secondary)' },
- }
- }
-});
-
-// No classes generated — only CSS variables
-```
-
-**Tradeoffs**:
-| Benefit | Drawback |
-|---------|----------|
-| No CSS classes at all | Less mature ecosystem |
-| Token-first architecture | Different mental model |
-| Type-safe CSS properties | Verbose inline styles |
-
-**Verdict**: Interesting but immature. Not worth the risk for XDS core.
-
-### Option C: Tailwind Variants Internal, Props-Only Public
-
-Use Tailwind Variants internally but hide classes from consumers.
-
-**Implementation**:
-```typescript
-import { tv } from 'tailwind-variants';
-
-// Internal variant definition (not exported)
-const buttonVariants = tv({
- slots: {
- base: 'rounded cursor-pointer',
- icon: 'w-4 h-4 mr-2',
- label: 'font-medium',
- },
- variants: {
- variant: {
- primary: {
- base: 'bg-primary text-on-primary',
- },
- secondary: {
- base: 'bg-secondary text-on-secondary',
- }
- }
- }
-});
-
-// Public component — props only
-export function Button({ variant = 'primary', size = 'md', icon, children }) {
- const styles = buttonVariants({ variant, size });
-
- return (
- <button className={styles.base()}>
- {icon && <span className={styles.slots.icon()}>{icon}</span>}
- <span className={styles.slots.label()}>{children}</span>
- </button>
- );
-}
-
-// className prop not exposed — no escape hatch
-```
-
-**Enforcement strategy**:
-1. Don't expose `className` prop on components
-2. Internal Tailwind Variants definition
-3. Lint rules to prevent `className` on XDS components
-4. TypeScript types enforce props-only API
-
-**Tradeoffs**:
-| Benefit | Drawback |
-|---------|----------|
-| Uses mature Tailwind Variants | Classes still exist in DOM (inspectable) |
-| Slots for sub-parts | Can't prevent consumers from finding class names |
-| Tailwind ecosystem compatible | Arbitrary values still possible in internal code |
-| Simpler implementation | Enforcement relies on conventions, not compiler |
-
-**Key weakness**: Classes are in the DOM. Savvy consumers can inspect and depend on them.
-
-### Comparison
-
-| Approach | Enforcement Level | Ergonomics | Maturity | Recommendation |
-|----------|------------------|------------|----------|----------------|
-| **StyleX + Variant Wrapper** | ✅ Compile-time | ⚠️ Verbose | ✅ Proven (StyleX) | **Best for XDS** |
-| **Tokenami** | ✅ No classes | ⚠️ Different model | ❌ Immature | Too risky |
-| **Tailwind Variants (hidden)** | ⚠️ Convention-based | ✅ Simple | ✅ Proven | Classes leak to DOM |
-
-### Recommendation: Option A
-
-**Build `@xds/variants` as a lightweight wrapper around StyleX** that provides:
-- tw-classed-like API ergonomics
-- Slot-based sub-part styling
-- Compound variants
-- Default variants
-- Full compile-time enforcement
-- Zero CSS class exposure
-
-This combines:
-- The ergonomics benefit of variant tools
-- The enforcement guarantees of StyleX
-- The evolution safety of encapsulated tokens
-- The AI compatibility of typed props
-
-**Implementation plan**:
-1. Create `@xds/variants` package
-2. Build `createVariants()` wrapper around StyleX
-3. Use it for all core components
-4. Document migration from tw-classed for adopters
-
----
-
-## Recommendation
-
-Given zero-styling architecture requirements:
-
-| Factor | Winner | Rationale |
-|--------|--------|-----------|
-| Constraint enforcement | **StyleX** | Types prevent arbitrary values; Tailwind can't |
-| AI compatibility | **Tailwind** | LLMs know it; StyleX requires learning |
-| Theming architecture | **StyleX** | Scoped themes are first-class |
-| Ergonomics | **Tailwind** | Concise class syntax |
-| Ecosystem pressure | **Tailwind** | More AI UIs, more templates |
-| No class exposure | **StyleX** | Classes are implementation detail |
-
-### Proposed Path: StyleX + Variant Wrapper + Tailwind Interop
-
-Combines the best of all approaches:
-
-**1. `@xds/variants` wrapper around StyleX**
-- tw-classed-like ergonomics for component authors
-- Slots for sub-part styling
-- Compound variants, default variants
-- Full compile-time enforcement
-- Zero CSS class exposure to consumers
-
-**2. StyleX for core constraint layer**
-- Zero-styling architecture depends on enforcement
-- Type-safe theming with scoped overrides
-- Classes are atomic and opaque (not semantic)
-
-**3. Export theme tokens as CSS variables (semantic tier only)**
-- `--xds-color-primary`, `--xds-spacing-sm`, etc.
-- Available for swizzled components
-- Base/primitive tokens not exposed
-
-**4. Provide Tailwind preset for ecosystem compatibility**
-```css
-@theme {
- --color-primary: var(--xds-color-primary);
- --spacing-sm: var(--xds-spacing-sm);
-}
-```
-- Tailwind users get XDS tokens as utilities
-- Interop without compromising core enforcement
-
-**5. Document migration path**
-- tw-classed → @xds/variants for adopters
-- Tailwind → XDS for teams wanting stricter enforcement
-
-This gives:
-- **Strict enforcement internally** (StyleX + types)
-- **Ergonomic authoring** (@xds/variants API)
-- **No class exposure** (props-only public API)
-- **Compatibility externally** (Tailwind preset uses same tokens)
-- **AI-friendly surface** (typed props, constrained tokens)
-
----
-
-## AI Considerations for StyleX + Variants Approach
-
-### The Author vs Consumer Gap
-
-The "AI gap" with StyleX is primarily for **component authors**, not **component consumers**.
-
-| Role | API Surface | AI Difficulty |
-|------|-------------|---------------|
-| **Consumer** | `<XDSButton variant="primary" size="md">` | Trivial — typed props, autocomplete |
-| **Author** | `createVariants({ ... stylex.create() ... })` | Higher — unfamiliar StyleX patterns |
-| **Swizzler** | Semantic CSS variables + custom StyleX | Medium — documented patterns |
-
-**Why this matters**: Since XDS ships pre-built components, most users are consumers. They never touch StyleX — they just use typed props, which is extremely AI-friendly.
-
-**For component authors** (XDS maintainers or contributors):
-- StyleX is less common in training data than Tailwind
-- LLMs may hallucinate incorrect StyleX APIs
-- TypeScript catches errors immediately → fast iteration
-- Codebase context teaches patterns quickly
-
-### Type Inference for Variants
-
-`@xds/variants` needs tw-classed-style type inference:
-
-```typescript
-// The goal: infer variant types from definition
-const button = createVariants({
- variants: {
- variant: {
- primary: stylex.create({...}).root,
- secondary: stylex.create({...}).root,
- },
- size: {
- sm: stylex.create({...}).root,
- md: stylex.create({...}).root,
- }
- }
-});
-
-// TypeScript infers:
-// { variant: 'primary' | 'secondary', size: 'sm' | 'md' }
-type ButtonVariants = Parameters<typeof button>[0];
-```
-
-**Implementation approach**:
-```typescript
-function createVariants<
- TVariants extends Record<string, Record<string, StyleXStyles>>
->(config: {
- base?: StyleXStyles;
- variants: TVariants;
- defaultVariants?: Partial<VariantProps<TVariants>>;
-}): VariantFunction<TVariants>;
-
-type VariantProps<T> = {
- [K in keyof T]: keyof T[K]
-};
-```
-
-This gives the same strong typing as tw-classed — variants only match the defined set.
-
-### Distributable Themes Tradeoff
-
-When themes are separate packages, there's tension between type safety and AI context:
-
-```
-@company/dark-theme @xds/core
-├── theme.ts ├── Button.tsx
-│ variants: { │ variant: ???
-│ primary, │ // What variants are valid?
-│ secondary │ // Component doesn't know
-│ } │
-```
-
-**Three approaches**:
-
-| Approach | Type Safety | AI Context Required | AI Difficulty |
-|----------|-------------|---------------------|---------------|
-| **Generic components** | ✅ Full | Theme type in scope | Medium — needs to understand generics |
-| **Superset variants** | ⚠️ Runtime | Just component | Low — simple props |
-| **Codegen** | ✅ Full | Generated component | Low — types are concrete |
-
-**Recommended pattern: Re-export with concrete types**
-
-```typescript
-// src/components/index.ts — App-level typed components
-import { Button as XDSButton } from '@xds/core';
-import { theme } from '@company/dark-theme';
-
-// Re-export with concrete types
-export const Button = XDSButton<typeof theme>;
-// Now variant is concretely typed: 'primary' | 'secondary'
-```
-
-This gives AI a single file with concrete types — no need to reason about generics or cross-package relationships.
-
-### Swizzle API Vibe-ability
-
-The swizzle API must also be AI-friendly. When users swizzle a component, AI needs to help them customize it.
-
-**What swizzlers have access to**:
-- Semantic CSS variables: `var(--xds-color-primary)`
-- The original StyleX code to modify
-- Documented patterns for common customizations
-
-**Making swizzle AI-friendly**:
-
-| Strategy | How It Helps |
-|----------|--------------|
-| **Consistent variable naming** | `--xds-{category}-{name}` is predictable |
-| **JSDoc on swizzled code** | Inline documentation for the code AI will read |
-| **Example customizations** | Common patterns in the swizzled file |
-| **Simple entry points** | Clear "this is where you customize" markers |
-
-**Swizzle template structure**:
-```typescript
-// Button.tsx (swizzled)
-/**
- * Swizzled Button component.
- *
- * Available semantic tokens:
- * - --xds-color-primary, --xds-color-secondary, etc.
- * - --xds-spacing-sm, --xds-spacing-md, etc.
- *
- * Common customizations:
- * - Add new variant: add to `variants.variant`
- * - Change sizing: modify `variants.size`
- * - Add animation: add to base styles
- */
-
-const button = createVariants({
- // 👇 CUSTOMIZE: Base styles applied to all variants
- base: stylex.create({
- root: { /* ... */ }
- }).root,
-
- // 👇 CUSTOMIZE: Add or modify variants here
- variants: {
- variant: {
- primary: stylex.create({
- root: { backgroundColor: 'var(--xds-color-primary)' }
- }).root,
- // Add custom variants below:
- }
- }
-});
-```
-
-**The key insight**: Swizzled code is essentially "AI context" — structure it so LLMs can read and modify it effectively.
-
-| Swizzle Design Choice | AI Impact |
-|-----------------------|-----------|
-| Comments marking customization points | Guides where to edit |
-| Semantic variables (not raw values) | Predictable, learnable |
-| Flat structure (not deeply nested) | Easier to navigate |
-| TypeScript types on everything | Catches errors immediately |
-
----
-
-## Does the Swizzle API Lead to Over-Componentization?
-
-### Research Says: Over-Componentization Is Not a Real Problem
-
-Design system research identifies different challenges:
-
-| Cited Problem | What It Means |
-|---------------|---------------|
-| **Adoption failure** | "Design systems aren't failing because they're poorly built—they're failing because no one's using them" |
-| **Poor ownership** | Unclear accountability, systems "sit on a digital shelf" |
-| **Limited collaboration** | Teams work in isolation, don't contribute back |
-| **Discovery issues** | Hard to find the right component (organization problem, not quantity) |
-
-Notably missing: "we have too many components."
-
-Sources: [Netguru: Design System Adoption Pitfalls](https://www.netguru.com/blog/design-system-adoption-pitfalls), [UXPin: Component-Based Design Guide](https://www.uxpin.com/studio/blog/component-based-design-complete-implementation-guide/)
-
-### Why More Components Is Often Better
-
-| More Components | Fewer Components + CSS Escape Hatches |
-|-----------------|--------------------------------------|
-| Explicit, named patterns | Implicit, undocumented variations |
-| Discoverable via autocomplete | Hidden in CSS overrides |
-| Testable individually | Side effects hard to trace |
-| AI can learn discrete patterns | AI generates arbitrary styling |
-
-Creating a `<XDSButtonWithIcon>` variant costs minutes. Debugging why `<XDSButton className="custom-override">` broke in a refactor costs hours.
-
-### When Over-Componentization IS a Problem
-
-| Scenario | Why It's Actually Bad | Root Cause |
-|----------|----------------------|------------|
-| One-off components | "Only used once" should be a composition | Poor judgment |
-| Prop explosion | 30+ props means should be split | Missing abstraction |
-| Naming collisions | `ButtonPrimary` vs `PrimaryButton` | Governance failure |
-| No composition | Every variation is new instead of composing | Not understanding composition |
-
-These are **governance failures**, not "too many components."
-
-### How the Swizzle API Reduces Component Proliferation
-
-The swizzle API provides a middle ground that actually *reduces* unnecessary components:
-
-```
-┌────────────────────────────────────────────────────────────┐
-│ Need │ Without Swizzle API │
-├──────────────────────────────┼────────────────────────────┤
-│ Slight color tweak │ New component OR CSS hack │
-│ Structural change │ New component │
-│ Behavioral change │ New component │
-└──────────────────────────────┴────────────────────────────┘
-
-┌────────────────────────────────────────────────────────────┐
-│ Need │ With Swizzle API │
-├──────────────────────────────┼────────────────────────────┤
-│ Slight color tweak │ Swizzle, use semantic var │
-│ Structural change │ Swizzle component │
-│ Behavioral change │ New component (explicit) │
-└──────────────────────────────┴────────────────────────────┘
-```
-
-**Result**: New components are reserved for genuinely new patterns, not styling edge cases.
-
-### The Real Risks to Watch For
-
-| Risk | Mitigation |
-|------|------------|
-| Undiscoverable components | Good organization, Storybook, search |
-| Ungoverned components | Clear ownership, contribution guidelines |
-| Swizzle becomes default | Document when to swizzle vs. request new component |
-| Semantic tokens misused | Lint for direct CSS variable usage outside swizzle |
-
----
-
-## Open Questions
-
-### @xds/variants Implementation
-- How do we type-infer variant props from the `createVariants` definition?
-- Should variants be defined per-component or centralized in theme?
-- How does the variant wrapper integrate with theme context?
-- Should responsive variants be part of the API or handled separately?
-
-### Complex Selectors / Parent-Child State
-- Should we build a `createStateRelationship()` helper to reduce CSS variable boilerplate?
-- Is the ergonomics gap with Tailwind's `group-hover:*` acceptable for XDS?
-- Should XDS components have built-in state variables for common patterns (hover reveal, focus highlight)?
-- Could we generate the variable definitions automatically from component slots?
-
-### Distributable Themes
-- Generic components vs superset variants vs codegen — which approach for multi-theme type safety?
-- How do we make the re-export pattern discoverable for users?
-- Should XDS provide a CLI to generate typed component re-exports from a theme?
-- How do we handle theme switching at runtime while maintaining type safety?
-
-### Swizzle API
-- What's the right level of inline documentation for swizzled components?
-- Should swizzled components include example customizations as comments?
-- How do we version swizzled component templates separately from the main library?
-
-### Token and Theming
-- How do we lint/prevent arbitrary Tailwind values in consumer codebases?
-- Should the Tailwind preset be opt-in or default?
-- Can we generate Tailwind classes from StyleX definitions automatically?
-- How do we handle the DX gap between StyleX and Tailwind for contributors?
-- What tokens belong in the "swizzle API" vs staying fully internal?
-- How do we version the swizzle API separately from the component API?
-- Should swizzle tokens use a different naming convention to signal instability?
-
----
-
-## Related
-
-- `zero-styling-architecture.md` — Core architecture this serves
-- `ai-design-system-gaps.md` — Why constraints matter for AI
-- `ai-trajectory-predictions.md` — Fundamental limits inform this choice
-
----
-
-## Sources
-
-- [StyleX Official Documentation](https://stylexjs.com/docs/learn/)
-- [StyleX Theming Guide](https://stylexjs.com/docs/learn/theming/creating-themes/)
-- [BetterStack: StyleX for Scalable CSS](https://betterstack.com/community/guides/scaling-nodejs/stylex-metas/)
-- [Tailwind v4 Theme Documentation](https://tailwindcss.com/docs/theme)
-- [Tailwind at Scale Issues](https://dev.to/gouranga-das-khulna/why-tailwind-css-might-be-hurting-your-large-scale-projects-3k73)
-- [tw-to-stylex: Tailwind to StyleX Converter](https://github.com/nmn/tw-to-stylex)
diff --git a/.context/explorations/swizzle-layer-ergonomics.md b/.context/explorations/swizzle-layer-ergonomics.md
deleted file mode 100644
index 7e69f73f64..0000000000
--- a/.context/explorations/swizzle-layer-ergonomics.md
+++ /dev/null
@@ -1,522 +0,0 @@
-# Swizzle Layer Ergonomics
-
-*Exploration — January 2026*
-
-## Context
-
-The swizzle layer has competing tensions:
-- **Close to core** (StyleX, XDS patterns) → easy contributions, shared utilities
-- **Close to builder** (Tailwind, familiar patterns) → AI can help, team can maintain
-
-## Decision Criteria (from product discussions)
-
-| Question | Answer | Implication |
-|----------|--------|-------------|
-| Is contribution back to core important? | Yes, but **unblocking builders is more important** | Optimize for builder ergonomics first |
-| What gets swizzled? | Most swizzled content is **use-case dependent** | Won't flow back to core anyway |
-| Small tweaks or structural changes? | **Two camps**: DS teams (heavy customization) + Regular builders (functionality > styling) | Need to serve both personas |
-| Is AI assistance critical? | **Yes** — common workflow to unblock builders | Must be AI-friendly |
-| Can we invest in tooling/docs? | **Absolutely** | Can build abstractions to bridge the gap |
-
-## Personas Using Swizzle
-
-### Persona 1: Design System Team
-
-**Who**: Designers/engineers maintaining company design system
-**Goal**: Customize components to match brand guidelines
-**Skill level**: High — willing to learn StyleX
-**Swizzle use**: Heavy customization, styling-focused
-
-**Example needs**:
-- Custom button variants matching brand hierarchy
-- Specific spacing/sizing variants
-- Custom animations/transitions
-- Brand-specific slots (e.g., badge on buttons)
-
-### Persona 2: Regular Builder
-
-**Who**: Product engineers shipping features
-**Goal**: Unblock a specific functionality need
-**Skill level**: Medium — wants to ship fast
-**Swizzle use**: Functionality-focused, minimal styling changes
-
-**Example needs**:
-- Add click tracking to button
-- Custom validation logic in input
-- Different keyboard navigation behavior
-- Integration with non-XDS libraries
-
-## Proposed Architecture: Dual-Path Swizzle
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ SWIZZLE PATH A: STYLING CUSTOMIZATION │
-│ Target: DS teams, styling-focused │
-│ │
-│ npx xds customize XDSButton --theme=myTheme │
-│ → Generates theme extension (AI-friendly) │
-│ │
-│ Format: Theme config (JSON-like) │
-│ AI vibes: ✅ High (structured data) │
-│ Contribution back: ✅ Possible (just config) │
-├─────────────────────────────────────────────────────────────────┤
-│ SWIZZLE PATH B: FUNCTIONAL OVERRIDE │
-│ Target: Regular builders, functionality-focused │
-│ │
-│ npx xds swizzle XDSButton │
-│ → Copies component source with AI-friendly annotations │
-│ │
-│ Format: Full source (StyleX + detailed comments) │
-│ AI vibes: ⚠️ Medium (unfamiliar but documented) │
-│ Contribution back: ❌ Unlikely (too use-case specific) │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Path A: Styling Customization (Theme Extension)
-
-For DS teams that want to customize appearance without changing structure.
-
-**Command**:
-```bash
-npx xds customize XDSButton --theme=corporate
-```
-
-**Generated file** (`themes/corporate/button.ts`):
-```typescript
-// Auto-generated by XDS customize
-// AI-friendly format: structured config, not code
-
-import { extendTheme } from '@xds/core';
-
-export const corporateButtonTheme = extendTheme({
- component: 'button',
-
- // Add new variants
- variants: {
- 'brand-primary': {
- background: '--corporate-blue',
- color: 'white',
- hoverBackground: '--corporate-blue-dark',
- },
- 'brand-secondary': {
- background: '--corporate-gray',
- color: '--corporate-blue',
- }
- },
-
- // Modify existing sizes
- sizes: {
- lg: {
- padding: '16px 32px', // Override default
- fontSize: '18px',
- }
- },
-
- // Customize slots
- slots: {
- icon: {
- marginRight: '12px', // Override default
- }
- }
-});
-```
-
-**Why this is AI-friendly**:
-- Structured config format (AI can generate JSON-like structures easily)
-- Clear property names (`background`, `color`, `padding`)
-- No StyleX syntax to learn
-- Predictable schema
-
-**Usage**:
-```tsx
-import { Theme } from '@xds/core';
-import { corporateButtonTheme } from './themes/corporate/button';
-
-<Theme theme={corporateButtonTheme}>
- <XDSButton variant="brand-primary">Corporate CTA</XDSButton>
-</Theme>
-```
-
-### Path B: Functional Override (Full Swizzle)
-
-For builders who need to change behavior or structure.
-
-**Command**:
-```bash
-npx xds swizzle XDSButton
-```
-
-**Generated file** (`components/xds/Button/Button.tsx`):
-```typescript
-/**
- * 🎨 SWIZZLED COMPONENT: XDSButton
- *
- * Source: @xds/[email protected]
- * Swizzled: 2026-01-09
- *
- * ⚠️ This component is now your responsibility.
- * Changes here won't receive automatic updates from XDS.
- *
- * COMMON CUSTOMIZATIONS:
- *
- * 1. Add custom behavior:
- * - Add onClick tracking: see line 45
- * - Add loading state: see line 52
- * - Custom keyboard handling: see line 67
- *
- * 2. Modify structure:
- * - Add new slots: see line 89
- * - Change DOM structure: see line 102
- *
- * 3. Styling changes:
- * - Use semantic tokens: var(--xds-color-primary)
- * - Available tokens documented at line 15
- */
-
-import * as stylex from '@stylexjs/stylex';
-import { createVariants } from '@xds/variants';
-
-// 👇 AVAILABLE SEMANTIC TOKENS
-// Colors: --xds-color-primary, --xds-color-secondary, --xds-color-danger
-// Spacing: --xds-spacing-sm, --xds-spacing-md, --xds-spacing-lg
-// Typography: --xds-font-button, --xds-font-weight-medium
-
-const button = createVariants({
- // 👇 CUSTOMIZE: Base styles applied to all variants
- base: stylex.create({
- root: {
- cursor: 'pointer',
- borderRadius: 4,
- transition: 'all 0.2s',
- // Add custom styles here:
- }
- }).root,
-
- slots: {
- // 👇 CUSTOMIZE: Icon slot
- icon: stylex.create({
- root: { width: 16, height: 16, marginRight: 8 }
- }).root,
-
- // 👇 CUSTOMIZE: Label slot
- label: stylex.create({
- root: { fontWeight: 500 }
- }).root,
- },
-
- variants: {
- variant: {
- // 👇 CUSTOMIZE: Add or modify variants
- primary: stylex.create({
- root: {
- backgroundColor: 'var(--xds-color-primary)',
- color: 'var(--xds-color-on-primary)',
- }
- }).root,
- }
- },
-});
-
-interface ButtonProps {
- variant?: 'primary' | 'secondary';
- children: React.ReactNode;
- onClick?: () => void;
- // 👇 CUSTOMIZE: Add new props here
-}
-
-export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
- const styles = button({ variant });
-
- // 👇 CUSTOMIZE: Add custom behavior (tracking, analytics, etc.)
- const handleClick = () => {
- // Example: Add analytics
- // analytics.track('button_clicked', { variant });
- onClick?.();
- };
-
- return (
- <button {...stylex.props(styles.base())} onClick={handleClick}>
- {/* 👇 CUSTOMIZE: Modify structure, add slots */}
- <span {...stylex.props(styles.slots.label())}>
- {children}
- </span>
- </button>
- );
-}
-```
-
-**Why this works for AI despite StyleX**:
-1. **Extensive inline documentation** — AI reads comments
-2. **Clear customization points** — 👇 CUSTOMIZE markers
-3. **Examples in comments** — "Add onClick tracking: see line 45"
-4. **Semantic tokens only** — no raw StyleX internals exposed
-5. **Flat structure** — not deeply nested
-
-**The pattern**: Swizzled code is essentially AI context. Structure it so LLMs know exactly where and how to modify.
-
----
-
-## Implementation Plan
-
-### Phase 1: Path A (Theme Extension)
-
-**Build**: `npx xds customize` command
-- Generates theme extension config files
-- JSON-like structure, AI-friendly
-- Type-safe with theme validation
-
-**DX improvements**:
-- `npx xds customize XDSButton --interactive` — CLI prompts
-- Auto-generates TypeScript types from config
-- Preview in Storybook
-
-### Phase 2: Path B (Functional Swizzle)
-
-**Build**: Enhanced swizzle templates
-- Heavy inline documentation
-- Clear customization markers
-- Example modifications in comments
-- Semantic tokens only (no raw StyleX internals)
-
-**AI assistance**:
-- Templates designed as "AI context"
-- Common modifications documented inline
-- Codebase examples in comments
-
-### Phase 3: AI Tooling
-
-**Build**: AI-specific helpers
-- `npx xds customize XDSButton --with-ai-context` — generates extra context file
-- `.xds/ai-context.md` — component customization guide for AI
-- Cursor/Claude rules for XDS patterns
-
----
-
-## Tailwind Ergonomics Option
-
-For builders who prefer Tailwind patterns, we can offer a Tailwind-flavored swizzle that still uses XDS tokens.
-
-### Path A with Tailwind Syntax
-
-**Command**:
-```bash
-npx xds customize XDSButton --theme=corporate --format=tailwind
-```
-
-**Generated file** (`themes/corporate/button.config.ts`):
-```typescript
-// Tailwind-style config format — AI-friendly, familiar to most builders
-import { defineButtonTheme } from '@xds/core';
-
-export const corporateButton = defineButtonTheme({
- variants: {
- 'brand-primary': {
- base: 'bg-primary text-on-primary rounded-md',
- hover: 'hover:bg-primary-dark',
- focus: 'focus:ring-2 focus:ring-primary/50',
- disabled: 'disabled:opacity-50 disabled:cursor-not-allowed',
- },
- 'brand-secondary': {
- base: 'bg-secondary text-on-secondary rounded-md border border-border',
- hover: 'hover:bg-secondary-dark',
- },
- },
-
- sizes: {
- sm: 'px-3 py-1.5 text-sm',
- md: 'px-4 py-2 text-base',
- lg: 'px-6 py-3 text-lg',
- },
-});
-```
-
-**Key point**: The Tailwind classes use XDS token names (`bg-primary`, `text-on-primary`) from the Tailwind preset, not arbitrary values.
-
-**Why this works**:
-- Familiar Tailwind syntax
-- AI can generate this confidently
-- Still uses XDS tokens (consistency)
-- Linting prevents arbitrary values
-
-### Path B with Tailwind Variants
-
-**Command**:
-```bash
-npx xds swizzle XDSButton --format=tailwind
-```
-
-**Generated file** (`components/xds/Button.tsx`):
-```tsx
-/**
- * 🎨 SWIZZLED COMPONENT: XDSButton
- *
- * Format: Tailwind Variants (familiar to most builders)
- * Tokens: XDS theme tokens (via Tailwind preset)
- *
- * RULES:
- * ✅ Use XDS token classes: bg-primary, text-on-primary, p-md
- * ❌ No arbitrary values: bg-[#ff0000], mt-[13px]
- */
-
-import { tv } from 'tailwind-variants';
-
-const button = tv({
- base: 'rounded-md cursor-pointer transition-colors',
-
- slots: {
- icon: 'w-4 h-4',
- label: 'font-medium',
- },
-
- variants: {
- variant: {
- primary: {
- base: 'bg-primary text-on-primary hover:bg-primary-dark',
- icon: 'text-on-primary',
- },
- secondary: {
- base: 'bg-secondary text-on-secondary hover:bg-secondary-dark',
- icon: 'text-on-secondary',
- },
- danger: {
- base: 'bg-danger text-on-danger hover:bg-danger-dark',
- },
- // 👇 CUSTOMIZE: Add new variants here
- },
-
- size: {
- sm: { base: 'px-sm py-xs text-sm', icon: 'w-3 h-3' },
- md: { base: 'px-md py-sm text-base', icon: 'w-4 h-4' },
- lg: { base: 'px-lg py-md text-lg', icon: 'w-5 h-5' },
- },
- },
-
- defaultVariants: {
- variant: 'primary',
- size: 'md',
- },
-});
-
-interface ButtonProps {
- variant?: 'primary' | 'secondary' | 'danger';
- size?: 'sm' | 'md' | 'lg';
- children: React.ReactNode;
- onClick?: () => void;
- // 👇 CUSTOMIZE: Add new props
-}
-
-export function Button({ variant, size, children, onClick }: ButtonProps) {
- const styles = button({ variant, size });
-
- // 👇 CUSTOMIZE: Add behavior (tracking, etc.)
- const handleClick = () => {
- onClick?.();
- };
-
- return (
- <button className={styles.base()} onClick={handleClick}>
- <span className={styles.label()}>
- {children}
- </span>
- </button>
- );
-}
-```
-
-### Format Selection
-
-| Builder knows... | Recommended format |
-|-----------------|-------------------|
-| Tailwind | `--format=tailwind` |
-| StyleX / CSS-in-JS | `--format=stylex` (default) |
-| Neither | `--format=tailwind` (more training data) |
-
-**Command with format**:
-```bash
-# Default (StyleX)
-npx xds swizzle XDSButton
-
-# Tailwind format
-npx xds swizzle XDSButton --format=tailwind
-```
-
-### Constraints Still Apply
-
-Both formats enforce XDS tokens:
-
-```tsx
-// ✅ Uses XDS token (via Tailwind preset)
-base: 'bg-primary text-on-primary p-md',
-
-// ❌ Linting error: arbitrary value not allowed
-base: 'bg-[#0066cc] text-white p-4',
-```
-
-The Tailwind preset maps XDS tokens:
-- `bg-primary` → `var(--xds-color-primary)`
-- `text-on-primary` → `var(--xds-color-on-primary)`
-- `p-md` → `var(--xds-spacing-md)`
-
-### Tradeoff: Tailwind Format
-
-| Benefit | Cost |
-|---------|------|
-| Familiar syntax, AI-friendly | Classes in DOM (less encapsulation) |
-| More training data for LLMs | Can't prevent all arbitrary values |
-| Faster onboarding | Diverges from core XDS patterns |
-| Team can maintain without learning StyleX | Harder to contribute back |
-
-**Recommendation**: Offer both formats. Let builders choose based on their team's skills. Default to Tailwind for better AI vibes.
-
----
-
-## Tradeoffs
-
-| Approach | Path A (Theme Extension) | Path B (Full Swizzle) |
-|----------|-------------------------|----------------------|
-| **Complexity** | Low | High |
-| **AI vibes** | ✅ Excellent | ⚠️ Medium |
-| **Covers use cases** | Styling only | Everything |
-| **Contribution back** | ✅ Possible | ❌ Unlikely |
-| **Maintenance** | ✅ Easy | ⚠️ Your responsibility |
-| **Learning curve** | None | StyleX required |
-
----
-
-## Decision
-
-**Implement both paths** with clear guidance on which to use when:
-
-| Builder needs... | Recommended path |
-|-----------------|------------------|
-| Different colors/spacing | Path A (customize) |
-| New button variant | Path A (customize) |
-| Custom click tracking | Path B (swizzle) |
-| Different validation logic | Path B (swizzle) |
-| Custom keyboard behavior | Path B (swizzle) |
-| Structural changes | Path B (swizzle) |
-
-**Key insight**: Most swizzles (80%?) are styling customizations. Serve those with the simple path. The 20% who need functional changes accept the complexity.
-
----
-
-## Open Questions
-
-- Should Path A generate Tailwind config instead of theme extension for Tailwind users?
-- Can we auto-detect which path a builder needs based on their prompt?
-- Should swizzled components include a "sync from upstream" command?
-- How do we version swizzled templates vs core components?
-
----
-
-## Related
-
-- `stylex-vs-tailwind.md` — Complex selectors ergonomics gap
-- `xds-architecture.md` — Swizzle API section
-- `ai-design-system-gaps.md` — Why constraints beat suggestions
-
----
-
-## Sources
-
-- [shadcn/ui Documentation](https://ui.shadcn.com/docs)
diff --git a/.context/explorations/table-api-simplification.md b/.context/explorations/table-api-simplification.md
deleted file mode 100644
index 8d542f161f..0000000000
--- a/.context/explorations/table-api-simplification.md
+++ /dev/null
@@ -1,786 +0,0 @@
-# XDSTable API Simplification
-
-Exploring a simplified table API that reduces verbosity while maintaining configurability.
-
-## Design Goals
-
-1. **Minimal required props** - just `label` + `data` for the simplest case
-2. **Single canonical form** - one pattern for columns (objects), no multiple syntaxes
-3. **Smart defaults** - infer headers, widths, cell rendering from keys
-4. **Plugins for features** - all behavior/features stay in `plugins` prop (no prop explosion)
-5. **LLM-friendly** - predictable structure, easy to document
-6. **RSC-friendly** - streaming mode with minimal config
-
-## API Examples
-
-### Simplest Table (auto-generated columns)
-
-```tsx
-<XDSTable
- label="User directory"
- data={[
- {name: 'Alice', email: '[email protected]', status: 'Active'},
- {name: 'Bob', email: '[email protected]', status: 'Pending'},
- ]}
-/>
-```
-
-- Columns auto-generated from own enumerable properties of `data[0]`
-- Headers default to capitalized keys
-- Cell rendering by value type:
- - Primitives (string, number, boolean) → render as text
- - null/undefined → render "—" or empty
- - Date → locale formatted string
- - Objects/Arrays → require explicit `cell` renderer (warn in dev)
-- Row IDs auto-detect `id` field, fallback to index
-
-### With columns and plugins (features)
-
-All table features are configured via `plugins`:
-
-```tsx
-<XDSTable
- label="User directory"
- data={users}
- columns={[
- {
- key: 'name',
- header: 'Full Name',
- width: proportional(2),
- cell: ({item}) => <XDSTableContentCell label={item.name} />,
- },
- {key: 'email', header: 'Email Address'},
- {key: 'status', width: pixel(100)},
- ]}
- plugins={{
- rowHeader: useXDSTableRowHeader({key: 'name'}),
- sortable: useXDSTableSortable({
- defaultSort: {key: 'name', direction: 'asc'},
- }),
- selection: useXDSTableSelection({
- selected: selectedIds,
- onChange: setSelectedIds,
- }),
- emptyState: useXDSTableEmptyState({content: <EmptyMessage />}),
- }}
-/>
-```
-
-## Column Definition
-
-```tsx
-interface XDSTableColumn<T> {
- // Required
- key: string; // Object key to access, also used as column ID
-
- // Optional with defaults
- header?: string; // Default: capitalize(key)
- width?: ColumnWidth; // Default: proportional(1)
- type?: 'text' | 'number' | 'status' | 'action'; // Default: 'text'
- cell?: (props: {item: T}) => ReactNode; // Default: render item[key] as text
-
- // Advanced
- align?: 'start' | 'center' | 'end';
-}
-```
-
-## Core Props
-
-| Prop | Type | Required | Description |
-| ------------------ | ----------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
-| `label` | `string` | Yes | Screen reader label for table |
-| `data` | `T[]` | No\* | Array of row objects (\*required if no children) |
-| `columns` | `Column<T>[]` | No\* | Column definitions (\*required for streaming mode, auto-generated from data[0] otherwise) |
-| `children` | `ReactNode` | No\* | Row components (\*mutually exclusive with `data`) |
-| `header` | `ReactNode` | No | Additional content in `<thead>` after column headers (e.g., filter row) |
-| `footer` | `ReactNode` | No | Content in `<tfoot>` (e.g., load more, totals) |
-| `idKey` | `keyof T` | No | Field to use as row ID (default: `'id'`, fallback: index) |
-| `density` | `XDSTableDensity` | No | Row height + padding (default: `'balanced'`) |
-| `verticalAlign` | `'start' \| 'center'` | No | Cell content alignment (default: based on density) |
-| `dividers` | `'none' \| 'rows' \| 'columns' \| 'grid'` | No | Table divider lines (default: `'rows'`) |
-| `striped` | `boolean` | No | Alternating row backgrounds (default: `false`) |
-| `highlightOnHover` | `boolean` | No | Highlight rows on hover (default: `false`) |
-| `plugins` | `XDSTablePlugins` | No | Feature plugins (see below) |
-| `xstyle` | `StyleXStyles` | No | Custom styles |
-
-**Important**: Column headers are always rendered from the `columns` prop. The `header` prop is for _additional_ content (like filter rows), not column definitions.
-
-### Header and Footer Slots
-
-The table renders:
-
-1. `<thead>`: Column headers (from `columns`) + optional `header` content
-2. `<tbody>`: Row data (from `data` or `children`)
-3. `<tfoot>`: Optional `footer` content
-
-**Smart wrapping**: If header/footer content is not an `XDSTableRow`, the table wraps it in `<tr><td colSpan="all">...</td></tr>`.
-
-```tsx
-// Simple footer - auto-wrapped in row/cell
-<XDSTable
- columns={columns}
- footer={<XDSStream endpoint="/api/users" />}
->
- {users.map(user => ...)}
-</XDSTable>
-
-// Custom footer row structure
-<XDSTable
- columns={columns}
- footer={
- <XDSTableRow>
- <XDSTableCell>Total</XDSTableCell>
- <XDSTableCell />
- <XDSTableCell>{formatCurrency(sum)}</XDSTableCell>
- </XDSTableRow>
- }
->
- {users.map(user => ...)}
-</XDSTable>
-
-// Header with filter row
-<XDSTable
- columns={columns}
- header={
- <XDSTableRow>
- {columns.map(col => (
- <XDSTableCell key={col.key}>
- <FilterInput column={col.key} />
- </XDSTableCell>
- ))}
- </XDSTableRow>
- }
->
- {users.map(user => ...)}
-</XDSTable>
-```
-
-## Appearance Props
-
-Visual styling is controlled via simple top-level props rather than a complex variant system.
-
-### Density
-
-Controls row height and padding. Vertical alignment defaults based on density but can be overridden.
-
-```tsx
-type XDSTableDensity =
- | 'compact' // single line, tight padding → default verticalAlign: 'center'
- | 'balanced' // two lines, medium padding → default verticalAlign: 'center'
- | 'spacious' // flexible height, generous padding → default verticalAlign: 'start'
- | SpacingToken // direct spacing token for custom padding
- | {
- rowHeight?: 'single' | 'double' | 'auto' | number;
- padding?: SpacingToken;
- };
-```
-
-```tsx
-// Preset (most common)
-<XDSTable density="balanced" ... />
-
-// Spacing token
-<XDSTable density={4} ... />
-
-// Full custom
-<XDSTable density={{ rowHeight: 64, padding: 3 }} verticalAlign="center" ... />
-```
-
-### Dividers, Striping, and Alignment
-
-| Prop | Type | Default | Description |
-| ------------------ | ----------------------------------------- | ---------------- | --------------------------------- |
-| `dividers` | `'none' \| 'rows' \| 'columns' \| 'grid'` | `'rows'` | Table divider lines |
-| `striped` | `boolean` | `false` | Alternating row background colors |
-| `highlightOnHover` | `boolean` | `false` | Highlight rows on mouse hover |
-| `verticalAlign` | `'start' \| 'center'` | Based on density | Cell content vertical alignment |
-
-```tsx
-<XDSTable
- label="User directory"
- data={users}
- density="compact"
- dividers="grid"
- striped
-/>
-```
-
-### Competitive Analysis
-
-| Framework | Size/Density | Borders | Striping |
-| ------------ | --------------------------------------- | -------------------------------------------------------- | ---------------- |
-| Mantine | `horizontalSpacing`, `verticalSpacing` | `withTableBorder`, `withColumnBorders`, `withRowBorders` | `striped` |
-| Radix Themes | `size` ("1" \| "2" \| "3") | — | — |
-| Ant Design | `size` ("small" \| "middle" \| "large") | `bordered` | — |
-| Material UI | `size` ("small" \| "medium") | — | — |
-| Carbon | `size` ("xs" - "xl") | — | `useZebraStyles` |
-
-Our approach: semantic `density` presets that bundle row height + padding + alignment, with escape hatches for custom values. Dividers and striping as simple boolean props.
-
-## Plugins
-
-All features are configured via the `plugins` prop. Each plugin is created with a hook:
-
-| Plugin | Hook | Description |
-| -------------------- | ------------------------------- | ------------------------------------ |
-| `rowHeader` | `useXDSTableRowHeader` | Column to use as row header for a11y |
-| `sortable` | `useXDSTableSortable` | Enable column sorting |
-| `selection` | `useXDSTableSelection` | Row selection (multi) |
-| `selection` | `useXDSTableSingleSelection` | Row selection (single) |
-| `activation` | `useXDSTableRowActivation` | Row click/activation |
-| `rowStyling` | `useXDSTableRowStyling` | Conditional row styles/props |
-| `emptyState` | `useXDSTableEmptyState` | Empty state content |
-| `virtualization` | `useXDSTableVirtualization` | Virtual scrolling |
-| `expansion` | `useXDSTableRowExpansion` | Expandable rows |
-| `expansion` | `useXDSTableTreeRows` | Tree/hierarchical rows |
-| `filtering` | `useXDSTableFiltering` | Column filtering |
-| `dragAndDropRows` | `useXDSTableDragAndDropRows` | Row reordering |
-| `dragAndDropColumns` | `useXDSTableDragAndDropColumns` | Column reordering |
-| `columnResize` | `useXDSTableColumnResize` | Resizable columns |
-| `stickyColumns` | `useXDSTableStickyColumns` | Sticky columns |
-
-### Row Styling Plugin
-
-For conditional per-row styling based on data:
-
-```tsx
-plugins={{
- rowStyling: useXDSTableRowStyling({
- getRowProps: (item) => ({
- xstyle: [
- item.status === 'error' && styles.errorRow,
- item.isArchived && styles.dimmed,
- ],
- 'data-testid': `row-${item.id}`,
- }),
- }),
-}}
-```
-
-## Migration from Current API
-
-Current:
-
-```tsx
-const dataSource = useMemo(
- () =>
- xdsTableStandardDataSource(DATA, {
- getStableUniqueID: item => item.id,
- }),
- [],
-);
-
-const rowHeader = useXDSTableRowHeader<Item, ColumnKey>({key: 'name'});
-
-<XDSTable
- columns={columns}
- dataSource={dataSource}
- label="Users"
- plugins={{rowHeader}}
-/>;
-```
-
-New:
-
-```tsx
-<XDSTable
- label="Users"
- data={DATA}
- columns={columns}
- plugins={{
- rowHeader: useXDSTableRowHeader({key: 'name'}),
- }}
-/>
-```
-
-**Changes:**
-
-- `dataSource` → `data` (raw array)
-- `label` → `label` (clearer purpose)
-- `getStableUniqueID` → auto-derived from `item.id` (or use `idKey` prop)
-- Plugins remain the same pattern
-
-## Open Questions
-
-1. Should `columns` support array-of-arrays data with numeric indices?
-2. Should there be a `caption` prop for visible table titles?
-3. How does virtualization interact with the `data` prop for lazy loading?
-
-## Recipes
-
-Common table configurations for copy-paste:
-
-### Compact Data-Dense Table
-
-```tsx
-<XDSTable
- label="Transaction log"
- data={transactions}
- density="compact"
- highlightOnHover
-/>
-```
-
-### Spreadsheet-Style
-
-```tsx
-<XDSTable
- label="Budget spreadsheet"
- data={cells}
- density="compact"
- dividers="grid"
-/>
-```
-
-### Card-Like Rows
-
-```tsx
-<XDSTable
- label="Project list"
- data={projects}
- density="spacious"
- dividers="none"
- striped
-/>
-```
-
-### Sortable with Selection
-
-```tsx
-<XDSTable
- label="User management"
- data={users}
- columns={[
- {key: 'name', header: 'Name'},
- {key: 'email', header: 'Email'},
- {key: 'role', header: 'Role'},
- ]}
- plugins={{
- rowHeader: useXDSTableRowHeader({key: 'name'}),
- sortable: useXDSTableSortable({
- defaultSort: {key: 'name', direction: 'asc'},
- }),
- selection: useXDSTableSelection({selected, onChange: setSelected}),
- }}
-/>
-```
-
-## LLM & DevX Considerations
-
-### Plugin Discoverability
-
-All plugins follow the `useXDSTable*` naming convention. The `plugins` prop is typed to show available keys:
-
-```tsx
-plugins?: {
- rowHeader?: ReturnType<typeof useXDSTableRowHeader>;
- sortable?: ReturnType<typeof useXDSTableSortable>;
- selection?: ReturnType<typeof useXDSTableSelection | typeof useXDSTableSingleSelection>;
- // ... etc
-}
-```
-
-IDE autocomplete on the `plugins` object keys reveals all available plugins.
-
-### Defaults Summary
-
-| Prop | Default |
-| ------------------ | ------------------------------------------------------- |
-| `columns` | Auto-generated from `data[0]` keys |
-| `idKey` | `'id'` field, fallback to array index |
-| `density` | `'balanced'` |
-| `verticalAlign` | `'center'` for compact/balanced, `'start'` for spacious |
-| `dividers` | `'rows'` |
-| `striped` | `false` |
-| `highlightOnHover` | `false` |
-
-## Streaming API (RSC Compatible)
-
-For server streaming and RSC compatibility, use `columns` prop (data-only) with compositional body:
-
-```tsx
-const columns = [
- {key: 'name', header: 'Name', width: proportional(2), type: 'content'},
- {key: 'email', header: 'Email'},
- {key: 'status', header: 'Status', width: pixel(100), type: 'status'},
-];
-
-<XDSTable
- label="Users"
- columns={columns} // Required upfront for streaming
- density="compact"
- dividers="grid">
- <Suspense fallback={<XDSTableLoadingRow count={10} />}>
- <UserRowsFromServer />
- </Suspense>
-</XDSTable>;
-
-// Server Component - streams rows
-async function UserRowsFromServer() {
- const users = await fetchUsers();
- return users.map(user => (
- <XDSTableRow key={user.id}>
- <XDSTableCell>{user.name}</XDSTableCell>
- <XDSTableCell>{user.email}</XDSTableCell>
- <XDSTableCell>
- <XDSBadge>{user.status}</XDSBadge>
- </XDSTableCell>
- </XDSTableRow>
- ));
-}
-```
-
-### Why Columns Upfront?
-
-Column definitions must be provided via props (not children) because:
-
-1. **No upward registration** - Context flows downward; children can't inform parent of column structure
-2. **Loading state awareness** - Skeleton rows need column widths/types from context
-3. **Single canonical form** - One pattern for columns (design goal #2)
-4. **RSC compatible** - No effects or callbacks needed for column registration
-
-**Tradeoff**: Column headers/definitions can't be streamed. This is acceptable because:
-
-- Column definitions are small/fast
-- Body cells (the bulk of data) still stream
-- Lazy cells can fetch on intersection if needed
-
-### Data vs Streaming Mode
-
-| Aspect | `data` prop | `children` (streaming) |
-| -------------------- | ---------------------------------- | --------------------------------- |
-| **Use case** | Simple tables, full plugin support | RSC, streaming, custom structure |
-| **Server streaming** | ❌ Full array needed | ✅ Row components stream |
-| **Auto-columns** | ✅ From object keys | ❌ `columns` prop required |
-| **Plugins** | ✅ Full support | ⚠️ Some have split responsibility |
-
-The `data` prop and `children` are mutually exclusive.
-
-### Compositional Components
-
-| Component | Description |
-| -------------- | ------------ |
-| `XDSTableRow` | Row wrapper |
-| `XDSTableCell` | Cell wrapper |
-
-That's it. No `XDSTableHead`, `XDSTableBody`, or `XDSTableFoot` - the table handles structure internally:
-
-- Header renders from `columns` prop
-- `children` become body rows
-- `footer` prop for footer content
-
-## Loading Patterns
-
-Use generic XDS primitives rather than table-specific loading components. This avoids component proliferation and enables reuse across the design system.
-
-### Skeleton Rows
-
-```tsx
-// Use generic XDSSkeleton in table cells
-function SkeletonRows({columns, count}) {
- return Array.from({length: count}, (_, i) => (
- <XDSTableRow key={i}>
- {columns.map(col => (
- <XDSTableCell key={col.key}>
- <XDSSkeleton width={col.type === 'status' ? 80 : undefined} />
- </XDSTableCell>
- ))}
- </XDSTableRow>
- ));
-}
-```
-
-### Infinite Scroll / Load More
-
-Use `footer` prop with generic `XDSIntersectionTrigger`:
-
-```tsx
-<XDSTable
- label="Users"
- columns={columns}
- footer={
- hasMore && (
- <XDSIntersectionTrigger onIntersect={loadMore} rootMargin="200px">
- {isLoading && <XDSTableLoadingRow />}
- </XDSIntersectionTrigger>
- )
- }>
- {users.map(user => (
- <XDSTableRow key={user.id}>...</XDSTableRow>
- ))}
-</XDSTable>
-```
-
-### Lazy Cell Data
-
-For cells that fetch data on visibility:
-
-```tsx
-<XDSTableCell>
- <XDSLazy
- fetch={() => fetchScore(user.id)}
- fallback={<XDSSkeleton width={60} />}>
- {score => <span>{score}</span>}
- </XDSLazy>
-</XDSTableCell>
-```
-
-### XDSTableLoadingRow
-
-A convenience component that renders skeleton cells matching the column structure:
-
-```tsx
-// Reads columns from context, renders appropriate skeletons
-<XDSTableLoadingRow />
-
-// Multiple rows
-<XDSTableLoadingRow count={10} />
-
-// With explicit columns (when context unavailable)
-<XDSTableLoadingRow columns={columns} count={5} />
-```
-
-Internally uses `XDSSkeleton` with column-aware widths/shapes based on column `type`.
-
-### Generic Primitives
-
-See [RSC Utilities](./rsc-utilities.md) for full documentation on:
-
-| Component | Description |
-| ------------------------ | ------------------------------------------------------- |
-| `XDSSkeleton` | Loading placeholder (shimmer animation) |
-| `XDSIntersectionTrigger` | Fires callback when element enters viewport |
-| `XDSLazy` | Lazy load wrapper - fetches data on intersection |
-| `XDSStream` | RSC streaming - fetches flight response on intersection |
-| `XDSSpinner` | Loading spinner |
-
-## RSC Streaming
-
-For React Server Component infinite scroll, use `XDSStream` after the initial rows:
-
-```tsx
-const columns = [
- {key: 'name', header: 'Name', width: proportional(2)},
- {key: 'email', header: 'Email'},
- {key: 'status', header: 'Status', width: pixel(100)},
-];
-
-async function UsersPage() {
- const {users, nextCursor, hasMore} = await fetchUsers({limit: 20});
-
- return (
- <XDSTable label="Users" columns={columns}>
- {users.map(user => (
- <XDSTableRow key={user.id}>
- <XDSTableCell>{user.name}</XDSTableCell>
- <XDSTableCell>{user.email}</XDSTableCell>
- <XDSTableCell>{user.status}</XDSTableCell>
- </XDSTableRow>
- ))}
-
- {hasMore && (
- <XDSStream
- endpoint="/api/users"
- params={{cursor: nextCursor}}
- loading={<XDSTableLoadingRow />}
- />
- )}
- </XDSTable>
- );
-}
-```
-
-The server endpoint returns rows + the next `XDSStream` trigger, creating a recursive chain for infinite scroll. See [RSC Utilities](./rsc-utilities.md) for implementation details.
-
-## Plugin Architecture
-
-Plugins work via render transforms. Each plugin can wrap or modify renders at various levels:
-
-```tsx
-type XDSTablePlugin<TItem, TColumnKey> = {
- // Table structure
- transformTable?: (render) => render;
- transformLayout?: (render) => render;
- transformColumns?: (columns) => columns;
-
- // Header
- transformHeaderSegment?: (render) => render;
- transformHeaderRow?: (render) => render;
- transformHeaderCell?: (render) => render;
-
- // Body
- transformBodyRow?: (render) => render;
- transformBodyCell?: (render) => render;
-
- // Footer
- transformFooterSegment?: (render) => render;
- transformFooterRow?: (render) => render;
- transformFooterCell?: (render) => render;
-
- // Loading state
- transformLoadingRow?: (render) => render;
- transformLoadingCell?: (render) => render;
-};
-```
-
-### How Plugins Compose
-
-Plugin hooks return plugin objects. The table composes all transforms:
-
-```tsx
-// Each hook returns a plugin object
-const sortable = useXDSTableSortable({ ... });
-// → { transformHeaderCell: (render) => renderWithSortIcon, ... }
-
-const selection = useXDSTableSelection({ ... });
-// → { transformBodyRow: (render) => renderWithCheckbox, transformColumns: (cols) => [checkboxCol, ...cols] }
-
-// Table composes them
-plugins={{ sortable, selection }}
-// → All transforms are chained together
-```
-
-### Plugins in Streaming Mode
-
-Some plugins work with children, some require `data`:
-
-| Plugin | Data Mode | Streaming Mode | Notes |
-| ---------------- | --------- | -------------- | -------------------------------------------------------- |
-| `rowHeader` | ✅ | ✅ | Via `<XDSTableRow rowHeader>` |
-| `sortable` | ✅ | ⚠️ Split | Table handles UI/indicators, caller handles row ordering |
-| `selection` | ✅ | ✅ | Via context + `<XDSTableRow selectable>` |
-| `activation` | ✅ | ✅ | Via `<XDSTableRow onActivate>` |
-| `emptyState` | ✅ | ✅ | Via conditional children |
-| `virtualization` | ✅ | ⚠️ Possible | Needs explicit `rowHeight` + `rowCount` props |
-| `expansion` | ✅ | ✅ | Via `<XDSTableRow expandable>` |
-| `rowStyling` | ✅ | ✅ | Props on `<XDSTableRow>` |
-| `dragAndDrop` | ✅ | ✅ Deferred | Rows register refs on mount |
-| `stickyColumns` | ✅ | ✅ | Via column config `{ key: 'name', sticky: true }` |
-
-### Streaming Mode Details
-
-**Sortable (split responsibility):**
-
-```tsx
-// Table provides: sort state context, column indicators, onSort callbacks
-// Caller provides: correctly ordered rows
-
-const [sort, setSort] = useState({key: 'name', direction: 'asc'});
-const sortedUsers = useMemo(
- () => [...users].sort(comparator(sort.key, sort.direction)),
- [users, sort],
-);
-
-<XDSTable
- columns={columns}
- plugins={{sortable: useXDSTableSortable({sort, onSort: setSort})}}>
- {sortedUsers.map(user => (
- <XDSTableRow key={user.id}>...</XDSTableRow>
- ))}
-</XDSTable>;
-```
-
-**Virtualization (with explicit dimensions):**
-
-```tsx
-// rowHeight and rowCount enable virtualization without full data knowledge
-<XDSTable
- columns={columns}
- rowHeight={48}
- rowCount={1000}
- plugins={{virtualization: useXDSTableVirtualization({maxHeight: 400})}}>
- {/* Only visible rows render */}
-</XDSTable>
-```
-
-**Drag and Drop (deferred registration):**
-
-```tsx
-// Rows register refs with context on mount
-// By user interaction time, all refs are available
-<XDSTable
- columns={columns}
- plugins={{dragAndDrop: useXDSTableDragAndDropRows({onReorder})}}>
- {items.map(item => (
- <XDSTableRow key={item.id} draggable>
- ...
- </XDSTableRow>
- ))}
-</XDSTable>
-```
-
-## RSC Plugin Pattern
-
-For React Server Components, plugins can be provided via a wrapper that composes context providers. This avoids upward registration and keeps plugin configuration declarative.
-
-### API
-
-```tsx
-<XDSTablePlugins
- sortable={{
- Plugin: XDSTableSortablePlugin,
- defaultSort: {key: 'name', direction: 'asc'},
- }}
- selection={{
- Plugin: XDSTableSelectionPlugin,
- selected: ids,
- onChange: setIds,
- }}>
- <XDSTable label="Users" columns={columns}>
- <UserRows /> {/* Server Component */}
- </XDSTable>
-</XDSTablePlugins>
-```
-
-### How It Works
-
-**1. XDSTablePlugins composes nested providers:**
-
-```tsx
-function XDSTablePlugins({sortable, selection, children}) {
- let result = children;
-
- if (selection) {
- const {Plugin, ...props} = selection;
- result = <Plugin {...props}>{result}</Plugin>;
- }
- if (sortable) {
- const {Plugin, ...props} = sortable;
- result = <Plugin {...props}>{result}</Plugin>;
- }
-
- return result;
-}
-```
-
-**2. Each plugin component is a client boundary:**
-
-```tsx
-'use client';
-
-function XDSTableSortablePlugin({defaultSort, onSort, children}) {
- const sortable = useXDSTableSortable({defaultSort, onSort});
- return (
- <SortableContext.Provider value={sortable}>
- {children}
- </SortableContext.Provider>
- );
-}
-```
-
-**3. Table consumes via context:**
-
-```tsx
-function XDSTable({children}) {
- const sortable = useContext(SortableContext);
- const selection = useContext(SelectionContext);
- // Apply plugin transforms...
-}
-```
-
-### Benefits
-
-- **Server-renderable config**: Plugin props are plain objects, serializable
-- **No upward registration**: Plugins known upfront, composed top-down
-- **Clean client boundaries**: Each plugin is its own `'use client'` component
-- **Composable**: Add/remove plugins declaratively
diff --git a/.context/explorations/zero-styling-architecture.md b/.context/explorations/zero-styling-architecture.md
deleted file mode 100644
index 1d412d8d02..0000000000
--- a/.context/explorations/zero-styling-architecture.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Zero-Styling Architecture
-
-*Exploration — January 2026*
-
-## Context
-
-Responding to AI + design system adherence problems identified in `ai-design-system-gaps.md`. Core insight: enforcement beats suggestion. If arbitrary values have nowhere to go, they can't exist.
-
----
-
-## Concept
-
-**Invert the usual pattern.** Instead of "styled by default, override as needed," use:
-
-1. **Zero styling on components** — Components ship with no inline styles, no utility classes, no style props
-2. **Theme file as single source of truth** — All styling controlled through centralized theme configuration
-3. **Swizzling for flexibility** — Explicit opt-out for structural and behavioral customization
-
----
-
-## Why This Works for AI
-
-| Problem | How Zero-Styling Addresses It |
-|---------|-------------------------------|
-| Arbitrary values (`mt-[13px]`) | No style props = nowhere for arbitrary values to go |
-| Drift across sessions | Theme file is the constraint; components are stateless shells |
-| Context window degradation | Theme is a single file, easy to include in context |
-| No enforcement | Compile-time enforcement — invalid tokens don't exist |
-
-**Note on documentation**: Research confirms that JSDoc/comments are not reliably read by LLMs. Type constraints reduce errors by >50% where documentation has no measurable effect. This reinforces the zero-styling approach: **constrain via types, not docs**.
-
-**Note on reactive enforcement**: Types are guardrails for iteration, not first-try guidance. Research shows LLMs get code right only 46-65% on first attempt; the value of types is enabling instant error→fix loops. This means XDS should optimize for:
-1. **Clear error messages** — Help AI understand what went wrong
-2. **Narrow valid options** — Fewer choices = faster convergence
-3. **No silent failures** — Every violation should surface immediately
-
----
-
-## Open Questions
-
-### Theme File Structure
-- Token-based (colors, spacing scales)?
-- Component-based (Button.primary.background)?
-- Both with inheritance?
-
-### Swizzle Granularity
-- Full component replacement?
-- Slot-level swizzling (e.g., just the icon area of a button)?
-
-### AI + Swizzled Components
-- When someone swizzles, they lose enforcement
-- Can swizzled components remain "theme-aware"?
-- How do we prevent AI from going off-rails in swizzled code?
-
----
-
-## Related
-- `ai-design-system-gaps.md` — Problem analysis this responds to
diff --git a/.context/proposals/layout-system.md b/.context/proposals/layout-system.md
deleted file mode 100644
index df77e8472d..0000000000
--- a/.context/proposals/layout-system.md
+++ /dev/null
@@ -1,601 +0,0 @@
-# XDS Layout System Proposal
-
-*Proposal — January 2026*
-
-## Overview
-
-A composable layout system for building consistent, structured layouts with zero styling customization. The system follows a container/content separation pattern with intelligent context-aware behavior.
-
-### Design Principles
-
-1. **Zero styling build** — No `xstyle` customization on layout components
-2. **Context-aware defaults** — Components detect their environment and self-adjust
-3. **LLM-friendly API** — Clear, discoverable props with self-documenting names
-4. **Composition over configuration** — Simple primitives that combine into complex patterns
-
----
-
-## Component Hierarchy
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ HIGHER-ORDER PATTERNS │
-│ Card, HoverCard, Popover, Modal │
-│ (Compose layouts into complete UI patterns) │
-├─────────────────────────────────────────────────────────────────┤
-│ LAYOUT STRUCTURE │
-│ XDSLayoutContainer + XDSLayout │
-│ (Container appearance + section arrangement) │
-├─────────────────────────────────────────────────────────────────┤
-│ CONTENT AREAS │
-│ XDSLayoutHeader, XDSLayoutFooter, XDSLayoutContent, │
-│ XDSLayoutPanel │
-│ (Regions that hold content) │
-├─────────────────────────────────────────────────────────────────┤
-│ LAYOUT PRIMITIVES │
-│ HStack, VStack, SplitPane, Grid, Divider │
-│ (Arrangement and spacing tools) │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Core Components
-
-### XDSLayoutContainer
-
-Outer container that sets visual appearance and padding context.
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `variant` | `'page' \| 'card' \| 'modal' \| 'section' \| 'hovercard' \| 'popover'` | Visual variant determining elevation and padding |
-| `children` | `React.Node` | Must be an `XDSLayout` component |
-
-### XDSLayout
-
-Arranges sections using named slots. Does not handle visual appearance — that's the Container's job.
-
-```
-┌─────────────────────────────────────────┐
-│ header │
-├──────┬─────────────────────────┬────────┤
-│start │ content │ end │
-├──────┴─────────────────────────┴────────┤
-│ footer │
-└─────────────────────────────────────────┘
-```
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `header` | `React.Node` | Header slot |
-| `footer` | `React.Node` | Footer slot |
-| `start` | `React.Node` | Start panel slot (left in LTR) |
-| `end` | `React.Node` | End panel slot (right in LTR) |
-| `content` | `React.Node` | Main content slot |
-| `height` | `'fill' \| 'auto'` | `fill`: layout fills container, content scrolls. `auto`: layout grows with content |
-| `isFullBleed` | `boolean` | Removes padding at layout's outer edges |
-
-### Content Areas
-
-`XDSLayoutHeader`, `XDSLayoutFooter`, `XDSLayoutContent`, `XDSLayoutPanel`
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `children` | `React.Node` | Area content |
-| `hasDivider` | `boolean` | Adds themed border (position auto-detected) |
-| `isFullBleed` | `boolean` | Removes this area's internal padding |
-| `role` | `string` | ARIA landmark role (e.g., `'banner'`, `'main'`, `'navigation'`, `'contentinfo'`) |
-
----
-
-## Basic Usage
-
-```jsx
-<XDSLayoutContainer variant="card">
- <XDSLayout
- header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
- content={<XDSLayoutContent>Body</XDSLayoutContent>}
- footer={<XDSLayoutFooter>Actions</XDSLayoutFooter>}
- />
-</XDSLayoutContainer>
-```
-
-### With Sidebar
-
-```jsx
-<XDSLayoutContainer variant="card">
- <XDSLayout
- header={<XDSLayoutHeader hasDivider>Dashboard</XDSLayoutHeader>}
- start={<XDSLayoutPanel hasDivider><XDSList items={navItems} /></XDSLayoutPanel>}
- content={<XDSLayoutContent>Main content</XDSLayoutContent>}
- />
-</XDSLayoutContainer>
-```
-
-### Full Bleed Content
-
-```jsx
-<XDSLayoutContainer variant="card">
- <XDSLayout
- header={<XDSLayoutHeader>Users</XDSLayoutHeader>}
- content={
- <XDSLayoutContent isFullBleed>
- <XDSTable ... />
- </XDSLayoutContent>
- }
- />
-</XDSLayoutContainer>
-```
-
----
-
-## Why Separate Container + Layout
-
-Separation enables **reusable layout structures** across different contexts:
-
-```jsx
-// Define layout structure once
-const NavigationLayout = ({items, content}) => (
- <XDSLayout
- start={<XDSLayoutPanel><XDSList items={items} /></XDSLayoutPanel>}
- content={<XDSLayoutContent>{content}</XDSLayoutContent>}
- />
-);
-
-// Desktop: inside a popover menu
-<XDSLayoutContainer variant="popover">
- <NavigationLayout items={navItems} content={<Details />} />
-</XDSLayoutContainer>
-
-// Mobile: full page layout
-<XDSLayoutContainer variant="page">
- <NavigationLayout items={navItems} content={<Details />} />
-</XDSLayoutContainer>
-```
-
-**Key benefit:** Author the layout once, adapt the container for responsive or contextual needs.
-
-### LLM Considerations
-
-The two-component pattern requires LLMs to remember the wrapper. Mitigations:
-
-1. **Higher-order patterns are primary** — Most code uses `XDSCard`, `XDSModal`, etc.
-2. **JSDoc on XDSLayout** — States "must be wrapped in XDSLayoutContainer"
-3. **Examples emphasize the pattern** — All raw Layout examples show the Container wrapper
-4. **TypeScript context check** — XDSLayout can warn if not inside a Container
-
----
-
-## Full Bleed Behavior
-
-`isFullBleed` exists at two levels with different scopes:
-
-| Level | Effect |
-|-------|--------|
-| `XDSLayout isFullBleed` | Layout touches container edges (outer spacing removed) |
-| `XDSLayoutContent isFullBleed` | Content area has no internal padding |
-
-These are independent — use both when needed.
-
-```
-Layout isFullBleed=false Layout isFullBleed=true
-┌────────────────────────┐ ┌────────────────────────┐
-│ ┌────────────────┐ │ │┌──────────────────────┐│
-│ │ content │ │ → ││ content ││
-│ └────────────────┘ │ │└──────────────────────┘│
-└────────────────────────┘ └────────────────────────┘
- outer padding no outer padding
-```
-
----
-
-## Padding via Variants
-
-Padding is controlled entirely through container variants. Each variant defines spacing as CSS variables.
-
-| Variant | Outer Spacing | Inner Spacing | Use Case |
-|---------|---------------|---------------|----------|
-| `page` | 16px | 16px | Full page layouts |
-| `card` | 16px | 16px | Elevated content containers |
-| `modal` | 16px | 16px | Dialog overlays |
-| `section` | 16px | 16px | Content sections within a page |
-| `hovercard` | 12px | 12px | Hover-triggered content |
-| `popover` | 12px | 12px | Click-triggered overlays |
-
-### How It Works
-
-1. `XDSLayoutContainer` sets CSS variables based on `variant`
-2. `XDSLayout` reads outer spacing variable
-3. Content areas read inner spacing variable
-4. `isFullBleed` overrides these to `0`
-
-```css
-/* card, section, page, modal */
---xds-layout-outer-spacing: 16px;
---xds-layout-inner-spacing: 16px;
-
-/* hovercard, popover */
---xds-layout-outer-spacing: 12px;
---xds-layout-inner-spacing: 12px;
-```
-
-### Theming
-
-Since spacing is controlled via CSS variables, themes can override these values. A theme with denser spacing might use:
-
-```css
-/* Dense theme overrides */
---xds-layout-outer-spacing: 12px;
---xds-layout-inner-spacing: 12px;
-```
-
-This allows the same component code to adapt to different visual densities across themes.
-
----
-
-## Auto-Adjusting Components
-
-Components inside layout areas detect context and self-adjust. No explicit props needed.
-
-| Component | Behavior |
-|-----------|----------|
-| `XDSList` | Applies spacing correction automatically |
-| `XDSScrollableArea` | Pushes scrollbar to container edge |
-| `XDSTable` | Extends edge-to-edge within container |
-
-```jsx
-// Just works — no props needed
-<XDSLayoutPanel>
- <XDSList items={navItems} />
-</XDSLayoutPanel>
-```
-
----
-
-## Dividers
-
-`hasDivider` on content areas auto-places the divider on the correct edge:
-
-| Component | Divider Position |
-|-----------|------------------|
-| Header | Bottom edge |
-| Footer | Top edge |
-| Panel (start) | End edge |
-| Panel (end) | Start edge |
-
-When `hasDivider` is false, spacing collapse is applied automatically for seamless visual flow.
-
----
-
-## Scroll Behavior
-
-| `height` | Behavior |
-|----------|----------|
-| `"fill"` (default) | Layout fills container, content scrolls internally |
-| `"auto"` | Layout grows with content, container/page scrolls |
-
----
-
-## Higher-Order Patterns
-
-Pre-composed patterns for common use cases. These are the primary API for most users.
-
-| Pattern | Use Case |
-|---------|----------|
-| `XDSCard` | Elevated content container |
-| `XDSModal` | Dialog overlay |
-| `XDSPopover` | Click-triggered overlay |
-| `XDSHoverCard` | Hover-triggered content |
-
-Each pattern internally composes `XDSLayoutContainer` + `XDSLayout`:
-
-```jsx
-// XDSCard usage (named slots)
-<XDSCard
- header={<XDSCard.Header>Title</XDSCard.Header>}
- content={<XDSCard.Content>Body</XDSCard.Content>}
- footer={<XDSCard.Footer>Actions</XDSCard.Footer>}
-/>
-
-// XDSModal usage
-<XDSModal
- isOpen={open}
- onClose={close}
- header={<XDSModal.Header>Confirm</XDSModal.Header>}
- content={<XDSModal.Content>Are you sure?</XDSModal.Content>}
- footer={<XDSModal.Footer>...</XDSModal.Footer>}
-/>
-```
-
----
-
-## Additional Components (API TBD)
-
-| Component | Description |
-|-----------|-------------|
-| `XDSSplitPane` | Resizable panels. Horizontal and vertical orientations. |
-| `XDSGrid` | Responsive grid layout. |
-| `XDSHStack` | Horizontal stack with gap. |
-| `XDSVStack` | Vertical stack with gap. |
-| `XDSDivider` | Themed divider with `isFullBleed` support. |
-
----
-
-## Component Summary
-
-| Component | Role | Key Props |
-|-----------|------|-----------|
-| `XDSLayoutContainer` | Visual appearance + padding context | `variant` |
-| `XDSLayout` | Section arrangement | `header`, `footer`, `start`, `end`, `content`, `height`, `isFullBleed` |
-| `XDSLayoutHeader` | Header area | `hasDivider`, `isFullBleed` |
-| `XDSLayoutFooter` | Footer area | `hasDivider`, `isFullBleed` |
-| `XDSLayoutContent` | Main content area | `isFullBleed` |
-| `XDSLayoutPanel` | Side panel | `hasDivider`, `isFullBleed` |
-
----
-
-## LLM Pattern Design
-
-The API is designed for LLM pattern retention and consistency:
-
-### Naming Symmetry
-
-Slot names match component names, creating strong associations:
-
-| Slot | Component |
-|------|-----------|
-| `header=` | `<XDSLayoutHeader>` |
-| `footer=` | `<XDSLayoutFooter>` |
-| `content=` | `<XDSLayoutContent>` |
-| `start=` / `end=` | `<XDSLayoutPanel>` |
-
-LLMs can infer: "the `header` slot takes the `Header` component."
-
-### Typed Slots
-
-Slot types reinforce what goes where:
-
-```typescript
-header?: React.ReactElement<XDSLayoutHeaderProps>;
-footer?: React.ReactElement<XDSLayoutFooterProps>;
-content?: React.ReactElement<XDSLayoutContentProps>;
-start?: React.ReactElement<XDSLayoutPanelProps>;
-end?: React.ReactElement<XDSLayoutPanelProps>;
-```
-
-### Canonical Examples in JSDoc
-
-Every component includes a complete example in its JSDoc:
-
-```typescript
-/**
- * Container for XDSLayout. Sets visual appearance and padding.
- *
- * @example
- * <XDSLayoutContainer variant="card">
- * <XDSLayout
- * header={<XDSLayoutHeader>Title</XDSLayoutHeader>}
- * content={<XDSLayoutContent>Body</XDSLayoutContent>}
- * />
- * </XDSLayoutContainer>
- */
-```
-
-LLMs often pull from JSDoc examples directly.
-
-### Consistent Pattern Repetition
-
-All documentation examples follow the same structure:
-1. `XDSLayoutContainer` wraps `XDSLayout`
-2. Named slots receive matching components
-3. No alternative patterns shown
-
-This repetition builds strong pattern recognition.
-
----
-
-## Open Questions
-
-### 1. Should XDSLayoutContainer have variants?
-
-**Current approach:** XDSLayoutContainer has variants (`card`, `modal`, `popover`, etc.) that set appearance and padding.
-
-**Alternative approach:** Remove variants from XDSLayoutContainer. Instead:
-- Higher-order components (XDSCard, XDSModal, XDSPopover) handle their own appearance
-- Each component is individually themable without XDSLayoutContainer growing arbitrarily
-- New containers with unique constraints (e.g., page content with max-width) don't need to be added as variants
-
-**Arguments for removing variants:**
-1. Higher-order components will exist anyway as the primary API
-2. Each container type may have unique requirements (e.g., page content needs max-width constraints for forms)
-3. Prevents XDSLayoutContainer from growing arbitrarily as new use cases emerge
-4. Theming becomes per-component rather than per-variant, giving more control
-5. Components can have domain-specific props (e.g., XDSPageContent with `maxWidth` prop)
-
-**Arguments for keeping variants:**
-1. Unified low-level API for custom use cases not covered by higher-order components
-2. Guarantees consistent styling across similar containers
-3. Enables layout reuse across contexts (same layout, different containers)
-
-**Recommendation:** Treat XDSLayoutContainer as a **primitive**:
-- Accepts `xstyle` for customization
-- No variants — visual styling moves to higher-order components
-- Only handles CSS variable propagation and flex container setup
-
-Higher-order components (XDSCard, XDSModal, etc.) configure the primitive:
-
-```jsx
-// XDSCard internally uses XDSLayoutContainer as a primitive
-function XDSCard({ children, xstyle, ...props }) {
- return (
- <XDSLayoutContainer
- xstyle={[cardStyles.base, xstyle]}
- {...props}
- >
- {children}
- </XDSLayoutContainer>
- );
-}
-
-// Usage - XDSCard handles appearance
-<XDSCard>
- <XDSLayout
- header={<XDSLayoutHeader>...</XDSLayoutHeader>}
- content={<XDSLayoutContent>...</XDSLayoutContent>}
- />
-</XDSCard>
-```
-
-**XDSLayoutContainer as primitive:**
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `xstyle` | `StyleXStyles` | Custom styles (background, shadow, radius, etc.) |
-| `paddingOuterX` | `SpacingToken` | Outer horizontal padding (left/right) |
-| `paddingOuterY` | `SpacingToken` | Outer vertical padding (top/bottom) |
-| `paddingInnerX` | `SpacingToken` | Inner horizontal padding for content areas |
-| `paddingInnerY` | `SpacingToken` | Inner vertical padding for content areas |
-| `children` | `ReactNode` | Must be an `XDSLayout` component |
-
-**What it provides:**
-- Sets CSS variables based on padding props:
- - `--layout-padding-outer-x`, `--layout-padding-outer-y`
- - `--layout-padding-inner-x`, `--layout-padding-inner-y`
-- Flex container setup for XDSLayout
-- `height: 100%` default (overridable via xstyle)
-
-**What it does NOT provide:**
-- No backgroundColor, boxShadow, borderRadius — these come from higher-order components via `xstyle`
-- No variants — each higher-order component is individually themable
-
-### 2. Page Content Layout
-
-A specific use case: page content that constrains central space to a max-width (for forms, articles, etc.).
-
-**Requirements:**
-- Content width constrained to a value like 800px
-- On smaller screens, content fills available width with minimum padding
-- Side panels (if present) remain at container edges
-
-**Challenge:** With panels, you can't simply use `max-width` on the container since panels need to be at the edges.
-
-**Solution:** Calculate padding dynamically to center content within the constraint:
-
-```css
-/* Centers content at 800px max, with minimum 16px padding */
-padding-inline: max(16px, calc((100% - 800px) / 2));
-```
-
-This approach:
-- Wide screens → padding grows to center the constrained content
-- Narrow screens → minimum padding prevents content touching edges
-- Panels stay at container edges, unaffected by content centering
-
-**Architecture: Internal StyleX utility**
-
-Content width constraints apply to a limited set of containers (page content, form modals). Rather than adding complexity to XDSLayoutContainer, create an **internal StyleX utility** that these specific components use:
-
-```tsx
-// Internal utility - not exported
-const contentWidthStyles = stylex.create({
- form: {
- '--layout-padding-inner-x': `max(${spacingTokens.space4}, calc((100% - 800px) / 2))`,
- },
- capped: {
- '--layout-padding-inner-x': `max(${spacingTokens.space4}, calc((100% - 1200px) / 2))`,
- },
- full: {
- // No override - uses standard padding
- },
-});
-```
-
-**Components that use content width:**
-
-1. **XDSPageContent** - Exposes `contentWidth` prop for page layouts
-2. **XDSModal** - May have `variant="form"` that applies the form constraint
-
-```tsx
-// XDSPageContent exposes contentWidth prop
-<XDSPageContent contentWidth="form">
- <XDSLayout ... />
-</XDSPageContent>
-
-// XDSModal might have a variant for form modals
-<XDSModal variant="form">
- <XDSLayout ... />
-</XDSModal>
-```
-
-**Why this approach:**
-
-1. **XDSLayoutContainer stays simple:** Pure primitive with token-based padding.
-
-2. **Limited scope:** Only components that need content width get the prop.
-
-3. **Internal utility:** The calc-based styles are implementation details, not public API.
-
-4. **Explicit semantics:** `XDSPageContent contentWidth="form"` clearly communicates intent.
-
-**Content width variants:**
-
-| Variant | Use Case | Width |
-|---------|----------|-------|
-| `form` | Forms, focused content | 800px |
-| `capped` | Articles, content-heavy pages | 1200px |
-| `full` | Dashboards, data tables, no constraint (default) | 100% |
-
-**LLM-friendliness:** Use-case-based naming (`form`) is more discoverable than descriptive naming (`narrow`). An LLM building a form knows immediately to use `contentWidth="form"` without having to decide if content is "narrow enough."
-
-### 3. Nested layouts
-
-How do contexts compose when layouts are nested?
-
-### 4. SplitPane/Grid
-
-Detailed API design.
-
-### 5. Animation
-
-Transition support for panels (collapse/expand)?
-
----
-
-## RTL Support
-
-The `start`/`end` naming (rather than `left`/`right`) enables automatic RTL handling via CSS logical properties:
-
-| Direction | `start` panel | `end` panel |
-|-----------|---------------|-------------|
-| LTR | Left side | Right side |
-| RTL | Right side | Left side |
-
-Implementation uses logical CSS properties (`inset-inline-start`, `padding-inline-end`, etc.) so no additional props or configuration are needed. RTL layouts work automatically when `dir="rtl"` is set on a parent element.
-
----
-
-## Accessibility
-
-Content areas support ARIA landmark roles via the `role` prop:
-
-| Component | Suggested Role | Renders As |
-|-----------|----------------|------------|
-| `XDSLayoutHeader` | `"banner"` | `<header>` or `<div role="banner">` |
-| `XDSLayoutFooter` | `"contentinfo"` | `<footer>` or `<div role="contentinfo">` |
-| `XDSLayoutContent` | `"main"` | `<main>` or `<div role="main">` |
-| `XDSLayoutPanel` | `"navigation"` / `"complementary"` | `<aside>` or `<nav>` |
-
-**Design decision:** Should content areas render semantic HTML elements by default, or require explicit `role` prop?
-
-- **Option A:** Default to semantic elements (`<header>`, `<main>`, etc.) based on component type
-- **Option B:** Default to `<div>`, require `role` prop for landmarks
-- **Option C:** Default to semantic elements, allow `as` prop to override
-
-Semantic defaults (Option A/C) provide better accessibility out-of-the-box but may cause issues with nested layouts (multiple `<main>` elements).
-
----
-
-## Related Documentation
-
-- `xds-architecture.md` — Overall XDS architecture and theming
-- `zero-styling-architecture.md` — Zero styling philosophy
diff --git a/.context/proposals/stylex-distribution.md b/.context/proposals/stylex-distribution.md
deleted file mode 100644
index 7517102e91..0000000000
--- a/.context/proposals/stylex-distribution.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# StyleX Distribution Pattern
-
-## Status
-
-**Implemented** - See `scripts/package-source.js` for tarball generation.
-
-## Context
-
-XDS is a component library that uses StyleX for styling. We needed to decide how to distribute the library to consuming applications (Next.js, Vite, etc.).
-
-The StyleX team recommended a specific pattern based on their example:
-https://github.com/facebook/stylex/tree/main/examples/example-nextjs
-
-## Proposal
-
-**Ship source code with StyleX runtime only. Consumer apps run the StyleX build plugins.**
-
-### Component Library (`@xds/core`)
-
-- Uses only `@stylexjs/stylex` as a dependency (runtime package)
-- Ships raw `.tsx` source files containing `stylex.create()` calls
-- Does NOT run `@stylexjs/babel-plugin` or `@stylexjs/postcss-plugin`
-- Essentially a "source distribution"
-
-```json
-// @xds/core/package.json
-{
- "dependencies": {
- "@stylexjs/stylex": "^0.17.0"
- },
- "exports": {
- ".": "./src/index.ts",
- "./Button": "./src/Button/index.ts"
- }
-}
-```
-
-### Consuming App (Next.js, Vite, Storybook, etc.)
-
-For Next.js:
-
-- Runs `@stylexjs/babel-plugin` to transform StyleX calls
-- Runs `@stylexjs/postcss-plugin` to extract CSS
-
-For Vite, Webpack/Rspack, and Esbuild:
-
-- Use `@stylexjs/unplugin` to generate and bundle CSS
-- Processes both its own code AND `@xds/core` imports
-- Handles all CSS extraction at build time
-
-```js
-// postcss.config.mjs in consumer app
-stylexPlugin({
- include: [
- 'src/**/*.{ts,tsx}', // App's own code
- 'node_modules/@xds/core/**/*', // XDS components
- ],
- // ...
-});
-```
-
-## Consequences
-
-### Benefits
-
-1. **No pre-compilation needed** - Library doesn't need a complex build step for styles
-2. **Consumer controls CSS output** - Apps can configure CSS layers, extraction, etc.
-3. **Tree-shaking works naturally** - Consumer's bundler handles dead code elimination
-4. **Simpler library packaging** - Just ship TypeScript source
-5. **Theme tokens resolve correctly** - CSS variables are processed in app context
-
-### Tradeoffs
-
-1. **Consumer must configure StyleX** - Apps need babel + postcss plugins set up
-2. **Include paths required** - PostCSS config must explicitly include `@xds/core` paths
-3. **Build time at consumer** - StyleX processing happens during app build, not library build
-
-## References
-
-- StyleX Next.js example: https://github.com/facebook/stylex/tree/main/examples/example-nextjs
-- StyleX Storybook example: https://github.com/facebook/stylex/tree/main/examples/example-storybook
diff --git a/.context/proposals/vibeability-test-harness.md b/.context/proposals/vibeability-test-harness.md
deleted file mode 100644
index f3dee18298..0000000000
--- a/.context/proposals/vibeability-test-harness.md
+++ /dev/null
@@ -1,368 +0,0 @@
-# Vibeability Test Harness Spec
-
-Build a test harness that measures how well LLMs can use a component system, tracks degradation over conversation length, and suggests refinements through a closed-loop analysis cycle.
-
-## Directory Structure
-
-```
-internal/vibe-tests/
-├── src/
-│ ├── interactive.ts # Sets up test iteration for Claude Code subagents
-│ ├── run-interactive.ts # Generates subagent spawn instructions
-│ ├── aggregate.ts # Aggregates results, generates reports
-│ ├── types.ts # Core type definitions
-│ └── utils.ts # Shared utilities
-├── docs/
-│ └── job-taxonomy.md # Token/time analysis documentation
-├── prompts/
-│ └── test-set.json # Prompt battery organized by category
-├── results/
-│ └── {iteration-id}/
-│ ├── manifest.json # Iteration metadata
-│ ├── tasks/ # Individual task files for subagents
-│ │ └── {promptId}.json
-│ ├── results/ # Individual result files (avoids race conditions)
-│ │ └── {promptId}.json
-│ ├── aggregate.json # Aggregated metrics
-│ └── report.html # Visual report with charts
-└── .xds-docs/ # XDS documentation (auto-injected via AGENTS.md)
- ├── AGENTS.md
- ├── principles.md
- ├── tokens.md
- └── {Component}.md
-```
-
-## Core Types
-
-```typescript
-interface Turn {
- type: 'probe' | 'filler' | 'distractor' | 'recovery';
- prompt: string;
- response: string;
- evaluation?: Evaluation;
-}
-
-type EscapeHatchType =
- | 'hallucination'
- | 'wrong_component'
- | 'redundant_css'
- | 'supplemental_css'
- | 'wrapper_div'
- | 'inline_style' // Anti-pattern: should use StyleX instead
- | 'hardcoded_color' // Anti-pattern: breaks theming
- | 'hardcoded_spacing' // Anti-pattern: breaks spacing system
- | 'hardcoded_size' // Acceptable: explicit sizes are often needed
- | 'custom_animation' // Gap: missing animation support
- | 'layout_workaround'; // Gap: missing layout primitive
-
-type EscapeHatchSeverity = 'critical' | 'acceptable';
-
-interface EscapeHatch {
- type: EscapeHatchType;
- severity: EscapeHatchSeverity;
- detail: string;
- codeSnippet: string;
- gap?: string; // What capability gap does this represent?
-}
-
-/**
- * Result quality tiers:
- * - gold: Pure XDS, no escape hatches needed
- * - green: Correct components, only acceptable escape hatches
- * - yellow: Minor issues (anti-patterns like hardcoded values)
- * - red: Critical failures (hallucinations, wrong components)
- */
-type ResultTier = 'gold' | 'green' | 'yellow' | 'red';
-
-interface Evaluation {
- success: boolean;
- tier?: ResultTier;
- componentsUsed: string[];
- componentsExpected: string[];
- escapeHatches: (string | EscapeHatch)[];
- escapeHatchCount?: number;
- failureMode: string | null;
- confusionSignals: string[];
-}
-
-/** Job breakdown for output token analysis */
-interface JobBreakdown {
- componentRouting: number; // Import statements for XDS components
- componentConfig: number; // Props and configuration on XDS components
- supplementalStyling: number; // StyleX blocks
- contentAuthoring: number; // HTML structure, JSX
- businessLogic: number; // State, handlers, logic
- boilerplate: number; // Type definitions, exports
- total: number;
-}
-
-/** Input token breakdown by doc type */
-interface InputTokenBreakdown {
- agentsMd: number; // AGENTS.md - always read
- designDocs: number; // principles.md, tokens.md
- componentDocs: number; // Component-specific docs (Button.md, etc.)
- promptOverhead: number; // Task instructions
- total: number;
-}
-
-interface TestResult {
- id: string;
- timestamp: string;
- systemVersion: string;
- model: string;
- persona: string;
- promptCategory: string;
- trajectoryDepth: number;
- prompt: string;
- response: string;
- evaluation: Evaluation;
- fullConversation: Turn[];
- contextWindowUsage: number;
- // Timing and usage metrics
- durationMs: number;
- inputTokens: number;
- outputTokens: number;
- // Optional detailed breakdowns
- jobBreakdown?: JobBreakdown;
- docsRead?: string[]; // Docs accessed during generation
-}
-
-interface Refinement {
- target: 'skill_doc' | 'component_api' | 'component_naming' | 'examples';
- component: string | null;
- suggestion: string;
- evidence: string[];
- confidence: number;
- effortEstimate: 'trivial' | 'moderate' | 'significant';
-}
-```
-
-## Quality Tiers
-
-Results are categorized into quality tiers for nuanced analysis:
-
-| Tier | Icon | Meaning | Counts as Success |
-| ------ | ---- | ---------------------------------------------------- | ----------------- |
-| Gold | 🥇 | Pure XDS, no escape hatches needed | Yes |
-| Green | 🟢 | Correct components, only acceptable escape hatches | Yes |
-| Yellow | 🟡 | Anti-patterns (hardcoded values break theming) | Yes |
-| Red | 🔴 | Critical failures (hallucinations, wrong components) | No |
-
-## Token Usage Breakdown
-
-The harness tracks token usage across two dimensions:
-
-### Input Tokens (estimated from doc reading)
-
-| Source | Description | Est. Tokens |
-| ------------------- | ------------------------------------------- | -------------- |
-| **AGENTS.md** | Component catalog and XDS guidance | ~173 |
-| **Design docs** | principles.md, tokens.md - styling patterns | ~1,200 |
-| **Component docs** | Button.md, TextInput.md, etc. | 300-2,000 each |
-| **Prompt overhead** | Task instructions and persona | ~375 |
-
-### Output Tokens (by job type)
-
-Each generated code response is analyzed by job category:
-
-| Job | Description | Typical % |
-| ------------------------ | ------------------------------------------- | --------- |
-| **Component Routing** | Import statements for XDS components | 3-10% |
-| **Component Config** | Props and attributes on XDS components | 7-30% |
-| **Supplemental Styling** | StyleX blocks for layout/spacing gaps | 10-27% |
-| **Content Authoring** | HTML structure, JSX elements, copy | 15-27% |
-| **Business Logic** | useState, handlers, API calls, conditionals | 5-51% |
-| **Boilerplate** | Type definitions, imports, exports | 5-10% |
-
-Business logic dominates integration-oriented prompts (51%), while page-setup prompts are more balanced across styling, content, and config.
-
-## Timing
-
-Timing is tracked per test and aggregated per category:
-
-- **Per test**: `durationMs` field in TestResult
-- **Inferred**: When not reported, timing is calculated from file timestamps (task creation → result write)
-- **Per category**: Average duration shown in aggregate reports
-
-## Escape Hatch Severity
-
-**Critical** (red tier - counts against success):
-
-- `hallucination` — Inventing props, components, or APIs that don't exist
-- `wrong_component` — Using a component incorrectly
-- `redundant_css` — CSS that duplicates component props
-
-**Anti-pattern** (yellow tier - noted, still success):
-
-- `inline_style` — Should use StyleX
-- `hardcoded_color` — Breaks theming
-- `hardcoded_spacing` — Breaks spacing system
-
-**Acceptable** (green tier - expected gaps):
-
-- `supplemental_css` — CSS for layout gaps
-- `wrapper_div` — Structural HTML for composition
-- `hardcoded_size` — Explicit sizes often needed
-- `custom_animation` — Missing animation support
-- `layout_workaround` — Missing layout primitive
-
-## Prompt Categories
-
-1. **feature-with-constraint**: "A banner warning trial expires in X days with upgrade button"
-2. **workflow-description**: "Checkout flow: cart → shipping → payment → confirmation"
-3. **clone-with-modification**: "Stripe's pricing table with monthly/annual toggle"
-4. **state-driven**: "Dashboard with loading → error → data states"
-5. **data-display**: "User table with sortable columns and search"
-6. **responsive-context**: "Navigation that collapses to hamburger on mobile"
-7. **integration-oriented**: "Form that validates email and posts to /api/subscribe"
-8. **page-setup**: "Landing page with hero, features, and CTA"
-
-## Test Protocols
-
-### One-shot (default)
-
-1. Read XDS docs (AGENTS.md auto-injected, component docs as needed)
-2. Generate code for prompt
-3. Self-evaluate response
-4. Write result to individual file
-
-### Degradation curve (`--degradation`)
-
-1. Probe at turn 0, evaluate
-2. Run 5 filler turns (unrelated questions)
-3. Re-probe at turn 6, evaluate
-4. Inject distractor ("now do it in Tailwind")
-5. Re-probe at turn 8, evaluate
-6. Inject recovery (re-read docs)
-7. Re-probe at turn 10, evaluate
-8. Generate line graph showing tier progression
-
-## CLI Interface
-
-```bash
-# Set up interactive test iteration
-yarn workspace @xds/vibe-tests interactive --sample 5
-
-# Set up degradation test
-yarn workspace @xds/vibe-tests interactive --sample 3 --degradation
-
-# Aggregate results after subagents complete
-yarn workspace @xds/vibe-tests aggregate --iteration abc123
-
-# Output JSON instead of console
-yarn workspace @xds/vibe-tests aggregate --iteration abc123 --json
-
-# CI mode (non-zero exit on low success rate)
-yarn workspace @xds/vibe-tests aggregate --iteration abc123 --ci
-```
-
-## Running Tests with Subagents
-
-Tests are run via Claude Code subagents spawned in parallel:
-
-1. Run `yarn workspace @xds/vibe-tests interactive --sample N`
-2. Spawn subagents with `mode: "bypassPermissions"` for each task
-3. Each subagent:
- - Reads task file from `results/{iteration}/tasks/{promptId}.json`
- - Reads XDS docs (AGENTS.md auto-injected)
- - Generates code for the prompt
- - Self-evaluates the response
- - Tracks timing (start → end)
- - Records docs read
- - Writes result to `results/{iteration}/results/{promptId}.json`
-4. Run `yarn workspace @xds/vibe-tests aggregate --iteration {id}`
-
-## Output Example
-
-### Console Output
-
-```
-📊 Vibe Test Results - Iteration 657c993f
-==================================================
-
-Overall: 100% success (2/2)
-
-🏆 Quality Tiers:
- 🥇 Gold (pure XDS): 2 (100%)
- 🟢 Green (acceptable): 0 (0%)
- 🟡 Yellow (anti-pattern): 0 (0%)
- 🔴 Red (critical): 0 (0%)
-
-⏱️ Performance:
- Total time: 33.3s (avg 16.7s per test)
-
-By Category:
- data-display 100% (1/1) [🥇1 🟢0 🟡0 🔴0] ⏱️23.3s
- integration-oriented 100% (1/1) [🥇1 🟢0 🟡0 🔴0] ⏱️10.0s
-
-📊 Token Usage Breakdown:
- ┌─────────────────────────────────────────────────┐
- │ INPUT TOKENS (estimated from doc reading) │
- ├─────────────────────────────────────────────────┤
- │ AGENTS.md: 346 tokens │
- │ Design docs: 2360 tokens │
- │ Component docs: 7033 tokens │
- │ Prompt overhead: 750 tokens │
- │ ───────────────────────────── │
- │ Input subtotal: 10489 tokens │
- ├─────────────────────────────────────────────────┤
- │ OUTPUT TOKENS (from job breakdown) │
- ├─────────────────────────────────────────────────┤
- │ Component routing: 3% (~73 tokens) │
- │ Component config: 13% (~281 tokens) │
- │ Supplemental styling: 14% (~301 tokens) │
- │ Content authoring: 45% (~943 tokens) │
- │ Business logic: 19% (~411 tokens) │
- │ Boilerplate: 5% (~103 tokens) │
- │ ───────────────────────────── │
- │ Output subtotal: 2112 tokens │
- ├─────────────────────────────────────────────────┤
- │ TOTAL: 12601 tokens │
- └─────────────────────────────────────────────────┘
-
-✓ Acceptable Escape Hatches:
- - supplemental_css: 2
-
-💡 Gap Suggestions (component/API improvements):
- 🔧 [trivial] Add prop or variant to cover: supplemental_css (seen 2x)
-```
-
-### HTML Report
-
-The HTML report includes:
-
-- Quality tier breakdown with visual bars
-- Results by category with timing
-- Token usage breakdown (input and output) - aggregate and per test
-- Degradation line graph (if degradation mode)
-- Critical issues, anti-patterns, acceptable hatches
-- Gap suggestions for component improvements
-- Individual test results with:
- - Tier icon and category
- - Prompt text
- - Escape hatches (if any)
- - Duration (e.g., 23.3s)
- - Token breakdown: Total (input/output) with hover tooltip showing full breakdown
- - Docs read badges (which .md files were accessed)
- - Expandable code view
-
-### Per-Run Token Breakdown
-
-Each individual test shows:
-
-- **Total tokens**: Sum of input + output
-- **Input/Output split**: e.g., `6245 (5189/1056)` means 5189 input, 1056 output
-- **Hover tooltip**: Full breakdown including:
- - Input: AGENTS tokens, Design doc tokens, Component doc tokens
- - Output: Routing, Config, Styling, Content, Logic, Boilerplate tokens
-- **Docs read**: Badges showing which docs were accessed (e.g., `AGENTS`, `principles`, `tokens`, `TextInput`)
-
-## Key Implementation Notes
-
-- **Individual result files**: Each subagent writes to `results/{promptId}.json` to avoid parallel write conflicts
-- **Timing inference**: When `durationMs` is 0, timing is inferred from file timestamps
-- **Doc tracking**: Subagents record which docs they read in `docsRead` array
-- **Token estimation**: Input tokens estimated from doc sizes (~4 chars per token)
-- **Job analysis**: Output tokens categorized by parsing code structure
-- **Quality tiers**: Gold/green/yellow/red for nuanced success tracking
-- **AGENTS.md**: Always used (auto-injected by Claude Code)
diff --git a/.context/proposals/xds-architecture.md b/.context/proposals/xds-architecture.md
deleted file mode 100644
index 7f4fba20ef..0000000000
--- a/.context/proposals/xds-architecture.md
+++ /dev/null
@@ -1,1280 +0,0 @@
-# XDS Architecture Proposal
-
-_Proposal — January 2026_
-
-## Builder Jobs To Be Done
-
-XDS serves developers across their workflow phases. Based on research in `frontend-developer-jtbd.md`:
-
-### Primary Jobs by Phase
-
-| Phase | Job | What Success Looks Like |
-| --------------- | ------------------------------- | -------------------------------------------------------- |
-| **Setup** | Set up project styling | Define tokens/themes in one place; immediate consistency |
-| **Setup** | Configure for my stack | Works with my build tools, framework, IDE |
-| **Build** | Construct pages from components | Compose UI quickly with typed props, autocomplete |
-| **Build** | Customize component appearance | Theme changes propagate everywhere automatically |
-| **Build** | Handle edge cases | Swizzle when needed, clear escalation path |
-| **Maintain** | Update to new versions | Clear migration path, deprecation warnings |
-| **Collaborate** | Work with AI assistants | Typed APIs, constrained options, predictable patterns |
-
-### How XDS Layers Map to Jobs
-
-| XDS Layer | Primary Jobs Served |
-| ----------------- | ---------------------------------------------------------- |
-| **Theme Layer** | Set up styling, customize appearance, maintain consistency |
-| **Component API** | Construct pages, stay consistent, work with AI |
-| **Swizzle Layer** | Handle edge cases, customize beyond theme |
-| **CLI/Tooling** | Configure for stack, adopt incrementally, update versions |
-
-### The Three Core Builder Actions
-
-| Job | What the Builder Wants | XDS Layer |
-| --------------------------------- | --------------------------------------------------------- | ----------------- |
-| **1. Set visual style** | "I want to define my project's look and feel" | **Theme Layer** |
-| **2. Override/create components** | "I want to customize beyond what's possible in the theme" | **Swizzle Layer** |
-| **3. Construct pages** | "I want to use components to build UIs" | **Component API** |
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│ JOB 3: CONSTRUCT PAGES (Component API) │
-│ │
-│ <XDSButton variant="primary" size="md" /> │
-│ <XDSStack gap="md"><XDSCard>...</XDSCard></XDSStack> │
-│ │
-│ Builder experience: │
-│ - Typed props, autocomplete-driven │
-│ - No styling decisions — just intent and structure │
-│ - AI can generate valid code with high confidence │
-├─────────────────────────────────────────────────────────────────────┤
-│ JOB 2: OVERRIDE/CREATE COMPONENTS (Swizzle Layer) │
-│ │
-│ npx xds swizzle XDSButton │
-│ → src/components/xds/Button/Button.tsx │
-│ │
-│ Builder experience: │
-│ - Full component source, yours to modify │
-│ - Access to semantic CSS variables (--xds-color-primary) │
-│ - Documented customization points for AI assistance │
-├─────────────────────────────────────────────────────────────────────┤
-│ JOB 1: SET VISUAL STYLE (Theme Layer) │
-│ │
-│ const theme = createTheme({ │
-│ tokens: { │
-│ color: { primary: ['#0066cc', '#66b3ff'] }, │
-│ spacing: { sm: '0.5rem', md: '1rem' }, │
-│ } │
-│ }) │
-│ │
-│ Builder experience: │
-│ - Define design tokens in one place │
-│ - Distributable as npm package │
-│ - Components read tokens via CSS variables │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### How the Jobs Relate
-
-| If the builder needs... | They use... | Complexity |
-| -------------------------- | ------------- | ---------- |
-| Different colors/spacing | Theme tokens | Low |
-| New button variant | Swizzle | Medium |
-| Custom component structure | Swizzle | Medium |
-| New component behavior | New component | High |
-
-**Escalation path**: Theme (tokens) → Swizzle (variants) → Custom. Each step up gives more control at the cost of more responsibility.
-
----
-
-## Context
-
-Designing the architecture for XDS based on explorations in:
-
-- `frontend-developer-jtbd.md` — Developer jobs research, workflow phases
-- `zero-styling-architecture.md` — Components with no styles, theme-driven
-- `stylex-vs-tailwind.md` — StyleX core + `@xds/variants` wrapper, token tiers, AI considerations
-- `ai-trajectory-predictions.md` — Constraints beat suggestions
-- `ai-design-system-gaps.md` — Types as enforcement
-
-### Key Requirements
-
-1. **Zero-styling**: Components ship with no inline styles
-2. **AI-friendly**: Constrained, predictable, learnable patterns for all three jobs
-3. **Open source compatible**: Users define their own themes
-4. **Multi-design-system**: Different systems have different semantic lockups
-5. **Sub-part styling**: Style internal component slots (icons, labels, etc.)
-6. **Evolvable**: Base tokens stay internal, semantic tokens exposed for swizzle
-7. **Distributable**: Themes can be packaged and shared independently
-
----
-
-## Core Architecture
-
-### Three-Layer System
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ LAYER 3: COMPONENT API (Public) │
-│ │
-│ <XDSButton variant="primary" size="md" /> │
-│ <XDSListItem variant="default" iconSlot={<Icon />} /> │
-│ │
-│ - Props define intent, not style │
-│ - Components define their own variants │
-│ - TypeScript enforces valid prop combinations │
-├─────────────────────────────────────────────────────────────────┤
-│ LAYER 2: DESIGN TOKENS (Theme Layer) │
-│ │
-│ const myTheme = createTheme({ │
-│ tokens: { │
-│ color: { primary: [...], secondary: [...] }, │
-│ spacing: { sm: '0.5rem', md: '1rem' }, │
-│ radius: { sm: '4px', md: '8px' }, │
-│ } │
-│ }) │
-│ │
-│ - Tokens only — no component-level configurations │
-│ - Components read via CSS variables │
-│ - Distributable as npm packages │
-├─────────────────────────────────────────────────────────────────┤
-│ LAYER 1: COMPONENT VARIANTS (Swizzle Layer) │
-│ │
-│ const button = createVariants({ │
-│ variants: { variant: { primary: {...}, secondary: {...} } } │
-│ }) │
-│ │
-│ - Components define their own variant → style mappings │
-│ - Uses semantic tokens (var(--xds-color-primary)) │
-│ - Swizzle to customize variants │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-**Key decision**: Theme = tokens only. Variant customization happens through swizzle, where typing is strict and self-contained.
-
----
-
-## Handling Different Semantic Lockups
-
-### The Problem
-
-Different design systems have different semantic structures:
-
-| Design System | Button Variants |
-| ------------- | --------------------------------------- |
-| System A | primary, secondary, tertiary |
-| System B | primary, secondary, danger, ghost, link |
-| System C | filled, outlined, text |
-| System D | brand, neutral, destructive, success |
-
-How does XDS support all of these with a single component library?
-
-### Solution: Swizzle for Variant Customization
-
-With token-only themes, XDS ships **default components with standard variants**. Users swizzle to customize.
-
-**XDS default Button** (what you get out of the box):
-
-```typescript
-// @xds/core/Button.tsx
-const button = createVariants({
- variants: {
- variant: {
- primary: { backgroundColor: 'var(--xds-color-primary)' },
- secondary: { backgroundColor: 'var(--xds-color-secondary)' },
- danger: { backgroundColor: 'var(--xds-color-danger)' },
- },
- size: {
- sm: { padding: 'var(--xds-spacing-sm)' },
- md: { padding: 'var(--xds-spacing-md)' },
- }
- }
-});
-
-export function Button({ variant = 'primary', size = 'md', children }) { ... }
-// Props: variant: 'primary' | 'secondary' | 'danger'
-```
-
-**System A swizzles** to get their variants:
-
-```typescript
-// src/components/xds/Button.tsx (swizzled)
-const button = createVariants({
- variants: {
- variant: {
- primary: { backgroundColor: 'var(--xds-color-primary)' },
- secondary: { backgroundColor: 'var(--xds-color-secondary)' },
- tertiary: { backgroundColor: 'transparent', border: '1px solid' },
- }
- }
-});
-
-export function Button({ variant = 'primary', children }) { ... }
-// Props: variant: 'primary' | 'secondary' | 'tertiary'
-```
-
-### Type Safety is Self-Contained
-
-Each component (swizzled or not) has strict types based on its own variant definition:
-
-```typescript
-// Type is inferred from createVariants definition
-type ButtonProps = {
- variant: 'primary' | 'secondary' | 'tertiary'; // From swizzled definition
- size?: 'sm' | 'md';
- children: React.ReactNode;
-};
-
-// ✅ Valid
-<XDSButton variant="tertiary">Click</XDSButton>
-
-// ❌ TypeScript error - 'ghost' not in this component's variants
-<XDSButton variant="ghost">Click</XDSButton>
-```
-
-### How This Simplifies Things
-
-| Concern | Token-only approach |
-| ------------------------------- | --------------------------------- |
-| **Where are variants defined?** | In the component file (one place) |
-| **Type inference** | Self-contained in component |
-| **AI context** | Component file has everything |
-| **Customization path** | Swizzle the component |
-
----
-
-## Sub-Part Styling (Slots)
-
-### The Problem
-
-Components have internal parts that need independent styling:
-
-- Button: icon, label, loading indicator
-- ListItem: leading icon, content, trailing action
-- Input: prefix, input, suffix, error message
-
-### Solution: Slots in Component Definition
-
-With token-only themes, slots are defined in the component file using Tailwind Variants (recommended) or `createVariants`.
-
-### Full Example: Button with Slots
-
-**Step 1: Theme provides tokens**
-
-```typescript
-// theme.ts
-export const theme = createTheme({
- tokens: {
- color: {
- primary: ['#0066cc', '#66b3ff'],
- onPrimary: ['#ffffff', '#000000'],
- secondary: ['#6b7280', '#9ca3af'],
- onSecondary: ['#ffffff', '#000000'],
- },
- spacing: {
- xs: '0.25rem',
- sm: '0.5rem',
- md: '1rem',
- },
- },
-});
-```
-
-**Step 2: Component defines variants and slots using tokens**
-
-```typescript
-// components/Button.tsx
-import { tv } from 'tailwind-variants';
-
-// Tailwind preset maps XDS tokens → Tailwind classes
-// bg-primary → var(--xds-color-primary)
-// px-md → var(--xds-spacing-md)
-
-const button = tv({
- slots: {
- base: 'inline-flex items-center justify-center rounded-md cursor-pointer transition-colors',
- icon: 'shrink-0',
- label: 'font-medium',
- spinner: 'animate-spin',
- },
-
- variants: {
- variant: {
- primary: {
- base: 'bg-primary text-on-primary hover:bg-primary-dark focus:ring-2 focus:ring-primary/50',
- icon: 'text-on-primary',
- },
- secondary: {
- base: 'bg-secondary text-on-secondary hover:bg-secondary-dark',
- icon: 'text-on-secondary',
- },
- ghost: {
- base: 'bg-transparent text-primary hover:bg-primary/10',
- icon: 'text-primary',
- },
- },
- size: {
- sm: {
- base: 'px-sm py-xs text-sm gap-xs',
- icon: 'w-3 h-3',
- },
- md: {
- base: 'px-md py-sm text-base gap-sm',
- icon: 'w-4 h-4',
- },
- lg: {
- base: 'px-lg py-md text-lg gap-sm',
- icon: 'w-5 h-5',
- },
- },
- },
-
- defaultVariants: {
- variant: 'primary',
- size: 'md',
- },
-});
-
-// TypeScript infers props from variant definition
-interface ButtonProps {
- variant?: 'primary' | 'secondary' | 'ghost';
- size?: 'sm' | 'md' | 'lg';
- icon?: React.ReactNode;
- isLoading?: boolean;
- children: React.ReactNode;
- onClick?: () => void;
-}
-
-export function Button({
- variant,
- size,
- icon,
- isLoading,
- children,
- onClick,
-}: ButtonProps) {
- const styles = button({ variant, size });
-
- return (
- <button className={styles.base()} onClick={onClick} disabled={isLoading}>
- {isLoading ? (
- <Spinner className={styles.spinner()} />
- ) : (
- icon && <span className={styles.icon()}>{icon}</span>
- )}
- <span className={styles.label()}>{children}</span>
- </button>
- );
-}
-```
-
-**Step 3: Use in app with theme provider**
-
-```tsx
-// App.tsx
-import {Theme} from '@xds/core';
-import {theme} from './theme';
-import {XDSButton} from './components/Button';
-import {PlusIcon} from './icons';
-
-function App() {
- return (
- <Theme theme={theme}>
- {/* Tokens flow through CSS variables */}
- <XDSButton variant="primary" size="md" icon={<PlusIcon />}>
- Add Item
- </XDSButton>
-
- <XDSButton variant="ghost" size="sm">
- Cancel
- </XDSButton>
-
- <XDSButton variant="secondary" size="lg" isLoading>
- Saving...
- </XDSButton>
- </Theme>
- );
-}
-```
-
-### How It All Connects
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ THEME (tokens only) │
-│ primary: ['#0066cc', '#66b3ff'] │
-│ ↓ │
-│ Generates CSS: --xds-color-primary: light-dark(#0066cc, ...) │
-└──────────────────────────┬──────────────────────────────────────┘
- ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ TAILWIND PRESET │
-│ Maps: bg-primary → background-color: var(--xds-color-primary) │
-└──────────────────────────┬──────────────────────────────────────┘
- ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ COMPONENT (variants + slots) │
-│ primary: { base: 'bg-primary text-on-primary' } │
-│ Button reads tokens via Tailwind classes │
-└──────────────────────────┬──────────────────────────────────────┘
- ↓
-┌─────────────────────────────────────────────────────────────────┐
-│ USAGE │
-│ <XDSButton variant="primary" icon={<Plus />}>Add</XDSButton> │
-│ Props are typed, tokens flow through, slots render correctly │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Slot Styling per Variant
-
-Slots can have different styles per variant:
-
-```typescript
-variants: {
- variant: {
- primary: {
- base: 'bg-primary text-on-primary',
- icon: 'text-on-primary', // Icon inherits primary colors
- },
- ghost: {
- base: 'bg-transparent text-primary',
- icon: 'text-primary opacity-70', // Icon is slightly muted
- },
- }
-}
-```
-
-### Using StyleX + createVariants (Alternative)
-
-For advanced users who prefer StyleX:
-
-```typescript
-import * as stylex from '@stylexjs/stylex';
-import {createVariants} from '@xds/variants';
-
-const button = createVariants({
- base: stylex.create({root: {cursor: 'pointer', borderRadius: 4}}).root,
-
- slots: {
- icon: stylex.create({root: {width: 16, height: 16}}).root,
- label: stylex.create({root: {fontWeight: 500}}).root,
- },
-
- variants: {
- variant: {
- primary: stylex.create({
- root: {
- backgroundColor: 'var(--xds-color-primary)',
- color: 'var(--xds-color-on-primary)',
- },
- }).root,
- },
- },
-});
-```
-
----
-
-## Theme Definition API
-
-> **Implementation Status**: ✅ Implemented in `/packages/core/src/theme/`
-
-### Actual Implementation
-
-XDS uses StyleX for theming, with pre-compiled theme objects:
-
-```typescript
-// /packages/core/src/theme/tokens.stylex.ts
-import * as stylex from '@stylexjs/stylex';
-
-// Define CSS variables with stylex.defineVars
-export const colorTokens = stylex.defineVars({
- accent: 'light-dark(#0064E0, #2694FE)',
- accentText: 'light-dark(#0064E0, #2694FE)',
- surface: 'light-dark(#FFFFFF, #1C1C1C)',
- textPrimary: 'light-dark(#171717, #FAFAFA)',
- hoverOverlay: 'light-dark(#0000000C, #FFFFFF0C)',
- pressedOverlay: 'light-dark(#00000019, #FFFFFF19)',
- // ... more tokens
-});
-
-export const spacingTokens = stylex.defineVars({
- space0: '0px',
- space1: '4px',
- space2: '8px',
- space3: '12px',
- space4: '16px',
- // ...
-});
-```
-
-### Theme Creation
-
-Themes override token values using `stylex.createTheme`:
-
-```typescript
-// /packages/core/src/theme/neutralTheme.stylex.ts
-import * as stylex from '@stylexjs/stylex';
-import {colorTokens} from './tokens.stylex';
-import type {Theme} from './types';
-
-const colorTheme = stylex.createTheme(colorTokens, {
- accent: 'light-dark(oklch(0.205 0 0), oklch(0.922 0 0))',
- surface: 'light-dark(oklch(1 0 0), oklch(0.145 0 0))',
- // ... override values
-});
-
-// Component-specific variant overrides
-const buttonVariants = stylex.create({
- primary: {
- color: 'light-dark(white, oklch(0.145 0 0))',
- },
- secondary: {
- borderWidth: '1px',
- borderStyle: 'solid',
- borderColor: colorTokens.divider,
- },
-});
-
-export const neutralTheme: Theme = {
- name: 'neutral',
- colorTheme,
- elevationTheme,
- spacingTheme,
- radiusTheme,
- transitionTheme,
- typographyTheme,
- components: {
- button: {variants: buttonVariants},
- },
-};
-```
-
-### Theme Type Structure
-
-```typescript
-// /packages/core/src/theme/types.ts
-export interface ComponentStyles {
- // Components register via module augmentation
- // See Button.tsx for example
-}
-
-export interface Theme {
- name: string;
- colorTheme: StyleXTheme;
- elevationTheme: StyleXTheme;
- spacingTheme?: StyleXTheme;
- radiusTheme?: StyleXTheme;
- transitionTheme?: StyleXTheme;
- typographyTheme?: StyleXTheme;
- components?: ComponentStyles; // Component-level variant overrides
-}
-```
-
-### Light/Dark Mode
-
-All color values use CSS `light-dark()` function for automatic mode switching:
-
-```css
-/* Generated CSS */
---xds-color-accent: light-dark(#0064e0, #2694fe);
---xds-color-surface: light-dark(#ffffff, #1c1c1c);
-```
-
-The Theme provider sets `color-scheme` to control which value is used:
-
-```tsx
-// Theme.tsx applies color-scheme based on mode prop
-<div
- style={{
- colorScheme:
- mode === 'dark' ? 'dark' : mode === 'light' ? 'light' : 'light dark',
- }}>
- {children}
-</div>
-```
-
-### Manual Mode Override
-
-```tsx
-// Follow system preference (default)
-<Theme theme={myTheme} mode="system">
-
-// Force dark mode
-<Theme theme={myTheme} mode="dark">
-
-// Force light mode
-<Theme theme={myTheme} mode="light">
-```
-
----
-
-## Component Implementation
-
-> **Implementation Status**: ✅ Button implemented as reference component
-
-### Actual Button Implementation
-
-Components use StyleX with theme tokens and support theme-level variant overrides:
-
-```typescript
-// /packages/core/src/Button/Button.tsx
-import * as stylex from '@stylexjs/stylex';
-import { colorTokens, spacingTokens, radiusTokens } from '../theme/tokens.stylex';
-import { ThemeContext } from '../theme/ThemeContext';
-import type { StyleXStyles } from '../theme/types';
-
-// Variant styles using tokens
-const variants = stylex.create({
- primary: {
- backgroundColor: colorTokens.accent,
- color: 'white',
- backgroundImage: {
- default: null,
- ':hover': `linear-gradient(${colorTokens.hoverOverlay}, ${colorTokens.hoverOverlay})`,
- ':active': `linear-gradient(${colorTokens.pressedOverlay}, ${colorTokens.pressedOverlay})`,
- },
- outline: {
- default: null,
- ':focus-visible': `2px solid ${colorTokens.focusOutline}`,
- },
- outlineOffset: {
- default: null,
- ':focus-visible': '3px',
- },
- },
- secondary: { /* ... */ },
- ghost: { /* ... */ },
- destructive: { /* ... */ },
-});
-
-// Derive variant type from StyleX object
-export type ButtonVariant = keyof typeof variants;
-
-// Module augmentation - register with theme types
-declare module '../theme/types' {
- interface ComponentStyles {
- button?: {
- variants?: Partial<Record<ButtonVariant, StyleXStyles>>;
- };
- }
-}
-
-// Component consumes theme variant overrides
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
- ({ variant = 'primary', children, ...props }, ref) => {
- const themeContext = useContext(ThemeContext);
- const themeVariantOverride = themeContext?.theme.components?.button?.variants?.[variant];
-
- return (
- <button
- ref={ref}
- {...stylex.props(
- styles.base,
- variants[variant],
- themeVariantOverride // Theme override applied on top
- )}
- {...props}
- >
- {children}
- </button>
- );
- }
-);
-```
-
-### Key Patterns
-
-| Pattern | Purpose |
-| ------------------------------ | --------------------------------------------------------------------- |
-| `keyof typeof variants` | Derive variant type from StyleX object |
-| `backgroundImage` for overlays | Layer hover/active colors on top of background |
-| Module augmentation | Register component variants with theme types without circular imports |
-| `ThemeContext` consumption | Apply theme-level variant overrides |
-
----
-
-## Token Categories
-
-> **Implementation Status**: ✅ Implemented in `/packages/core/src/theme/tokens.stylex.ts`
-
-| Category | Purpose | Examples |
-| ------------------ | --------------------------------------------------- | ------------------------------------------------------- |
-| `colorTokens` | All colors (semantic, text, icon, status, dividers) | `accent`, `textPrimary`, `hoverOverlay`, `negative` |
-| `spacingTokens` | Consistent spacing scale | `space1` (4px), `space2` (8px), `space4` (16px) |
-| `radiusTokens` | Border radius for different contexts | `rounded`, `container`, `element`, `content` |
-| `elevationTokens` | Box shadows | `base`, `thumb`, `dialog`, `hover`, `menu` |
-| `transitionTokens` | Animation durations | `fast` (0.15s), `normal` (0.2s) |
-| `typographyTokens` | Font families | `fontFamilyBody`, `fontFamilyCode`, `fontFamilyHeading` |
-
----
-
-## AI Compatibility Considerations
-
-### AI-Friendliness by Job
-
-| Job | AI Difficulty | Why |
-| ----------------------- | ------------- | ----------------------------------------------------------- |
-| **Construct pages** | ✅ Easy | Typed props, autocomplete, finite options |
-| **Set visual style** | ⚠️ Medium | Theme structure is learnable, but separate from components |
-| **Override components** | ⚠️ Medium | Documented patterns, semantic tokens, but unfamiliar StyleX |
-
-### Why This Architecture Is AI-Friendly
-
-| Design Decision | AI Benefit |
-| -------------------------- | ------------------------------------------------------------------------------ |
-| **Props, not classes** | `variant="primary"` is learnable; `bg-blue-500 hover:bg-blue-600` is arbitrary |
-| **TypeScript enforcement** | Invalid props fail at compile time, AI gets immediate feedback |
-| **Finite variant set** | AI learns discrete options, not infinite styling possibilities |
-| **Consistent patterns** | Same API shape across all components |
-| **No arbitrary values** | Can't generate `mt-[13px]`, only valid tokens |
-| **Re-export pattern** | Concrete types in one file, no cross-package reasoning |
-
-### The Author vs Consumer Gap
-
-The "AI gap" is primarily for **component authors**, not **component consumers**.
-
-| Role | API Surface | AI Difficulty |
-| ------------------------ | --------------------------------------------- | ----------------------------------- |
-| **Consumer** (Job 3) | `<XDSButton variant="primary" size="md">` | Trivial — typed props, autocomplete |
-| **Theme author** (Job 1) | `createTheme({ ... })` | Medium — structured, learnable |
-| **Swizzler** (Job 2) | StyleX + semantic CSS variables | Medium — documented patterns |
-| **Component author** | `createVariants({ ... stylex.create() ... })` | Higher — unfamiliar patterns |
-
-**Why this matters**: Most users are consumers (Job 3). They never touch StyleX — they just use typed props.
-
-### Theme as AI Context
-
-Themes are structured data that can be included in AI context:
-
-```typescript
-// Theme can be serialized for LLM context
-const themeContext = {
- availableVariants: {
- button: ['primary', 'secondary', 'danger'],
- input: ['default', 'error', 'success'],
- },
- availableSizes: ['sm', 'md', 'lg'],
- // ...
-};
-```
-
-This enables AI to:
-
-1. Know valid prop values without reading source
-2. Generate only theme-valid code
-3. Adapt to different themes dynamically
-
----
-
-## Tailwind Interoperability
-
-### Exporting Theme as CSS Variables
-
-```typescript
-// Auto-generated from theme
-:root {
- --xds-color-primary: #0066cc;
- --xds-color-secondary: #6b7280;
- --xds-spacing-md: 1rem;
- /* ... */
-}
-```
-
-### Tailwind Preset
-
-```css
-/* @xds/tailwind-preset */
-@import 'tailwindcss';
-@import '@xds/tokens/css';
-
-@theme {
- --color-primary: var(--xds-color-primary);
- --color-secondary: var(--xds-color-secondary);
- --spacing-md: var(--xds-spacing-md);
- /* ... */
-}
-```
-
-Now Tailwind users can use XDS tokens:
-
-```html
-<div class="bg-primary text-on-primary p-md">Tailwind with XDS tokens</div>
-```
-
-### Linting for Arbitrary Values
-
-Provide ESLint/Stylelint rules to prevent:
-
-```html
-<!-- ❌ Flagged by lint -->
-<div class="bg-[#0066cc] mt-[13px]">
- <!-- ✅ Allowed -->
- <div class="bg-primary mt-md"></div>
-</div>
-```
-
----
-
-## Swizzle API
-
-**Job 2: Override/Create Components** — When you need to customize variants or behavior.
-
-With token-only themes, swizzle is the path for **any component-level customization** beyond token changes.
-
-### When to Swizzle
-
-| Need | Solution |
-| --------------------------------- | ----------------- |
-| Different primary color | Edit theme tokens |
-| New button variant (e.g. `ghost`) | Swizzle Button |
-| Custom click tracking | Swizzle Button |
-| Different animation | Swizzle Button |
-| Structural changes | Swizzle Button |
-
-### Swizzle Command
-
-```bash
-# Default: Tailwind Variants format (recommended)
-npx xds swizzle XDSButton
-
-# StyleX format (for advanced users)
-npx xds swizzle XDSButton --format=stylex
-```
-
-### Generated Code: Tailwind Variants (Default)
-
-```typescript
-/**
- * 🎨 SWIZZLED COMPONENT: Button
- *
- * Source: @xds/[email protected]
- * Swizzled: 2026-01-09
- *
- * ⚠️ This component is now your responsibility.
- *
- * RULES:
- * ✅ Use XDS token classes: bg-primary, text-on-primary, p-md
- * ❌ No arbitrary values: bg-[#ff0000], mt-[13px]
- *
- * COMMON CUSTOMIZATIONS:
- * - Add variant: add to variants.variant below
- * - Add behavior: modify handleClick function
- * - Change structure: modify JSX return
- */
-
-import { tv } from 'tailwind-variants';
-
-const button = tv({
- slots: {
- base: 'rounded-md cursor-pointer transition-colors',
- icon: 'w-4 h-4',
- label: 'font-medium',
- },
-
- variants: {
- // 👇 CUSTOMIZE: Add or modify variants
- variant: {
- primary: {
- base: 'bg-primary text-on-primary hover:bg-primary-dark',
- icon: 'text-on-primary',
- },
- secondary: {
- base: 'bg-secondary text-on-secondary hover:bg-secondary-dark',
- icon: 'text-on-secondary',
- },
- danger: {
- base: 'bg-danger text-on-danger hover:bg-danger-dark',
- },
- },
-
- size: {
- sm: { base: 'px-sm py-xs text-sm', icon: 'w-3 h-3' },
- md: { base: 'px-md py-sm text-base', icon: 'w-4 h-4' },
- lg: { base: 'px-lg py-md text-lg', icon: 'w-5 h-5' },
- },
- },
-
- defaultVariants: {
- variant: 'primary',
- size: 'md',
- },
-});
-
-interface ButtonProps {
- variant?: 'primary' | 'secondary' | 'danger';
- size?: 'sm' | 'md' | 'lg';
- children: React.ReactNode;
- onClick?: () => void;
- // 👇 CUSTOMIZE: Add new props
-}
-
-export function Button({ variant, size, icon, children, onClick }: ButtonProps) {
- const styles = button({ variant, size });
-
- // 👇 CUSTOMIZE: Add behavior (tracking, analytics, etc.)
- const handleClick = () => {
- onClick?.();
- };
-
- return (
- <button className={styles.base()} onClick={handleClick}>
- {icon && <span className={styles.icon()}>{icon}</span>}
- <span className={styles.label()}>{children}</span>
- </button>
- );
-}
-```
-
-### Why Tailwind is the Default
-
-| Consideration | Tailwind Variants | StyleX |
-| ------------------ | --------------------- | --------------------- |
-| **AI familiarity** | ✅ High training data | ⚠️ Less common |
-| **Learning curve** | ✅ Familiar to most | ⚠️ New syntax |
-| **Encapsulation** | ⚠️ Classes in DOM | ✅ No exposed classes |
-| **Recommendation** | **Default for most** | Advanced users |
-
-### Format: StyleX (Alternative)
-
-For advanced users who want maximum encapsulation:
-
-```bash
-npx xds swizzle XDSButton --format=stylex
-```
-
-```typescript
-import * as stylex from '@stylexjs/stylex';
-import { createVariants } from '@xds/variants';
-
-const button = createVariants({
- base: stylex.create({ root: { cursor: 'pointer', borderRadius: 4 } }).root,
-
- slots: {
- icon: stylex.create({ root: { width: 16, height: 16 } }).root,
- label: stylex.create({ root: { fontWeight: 500 } }).root,
- },
-
- variants: {
- variant: {
- primary: stylex.create({
- root: {
- backgroundColor: 'var(--xds-color-primary)',
- color: 'var(--xds-color-on-primary)',
- }
- }).root,
- // 👇 CUSTOMIZE: Add variants
- }
- }
-});
-
-export function Button({ variant = 'primary', children }) {
- const styles = button({ variant });
- return (
- <button {...stylex.props(styles.base())}>
- <span {...stylex.props(styles.slots.label())}>{children}</span>
- </button>
- );
-}
-```
-
-### Token Enforcement
-
-Both formats use XDS tokens via the Tailwind preset — no arbitrary values:
-
-```tsx
-// ✅ Uses XDS token
-base: 'bg-primary text-on-primary p-md',
-
-// ❌ Linting error: arbitrary value not allowed
-base: 'bg-[#0066cc] text-white p-4',
-```
-
-### Swizzle Versioning
-
-Swizzled components are "ejected" — they don't auto-update:
-
-```
-⚠️ Swizzled component: Button
- Source version: @xds/[email protected]
- Last synced: 2026-01-15
-
- This component is now your responsibility.
- Check @xds/core changelog for updates.
-```
-
----
-
-## Distributable Themes
-
-**Job 1: Set Visual Style** — Themes can be packaged and shared independently.
-
-### Theme as npm Package
-
-With token-only themes, packages are simple:
-
-```
-@company/dark-theme/
-├── package.json
-├── theme.ts # Token definitions
-├── index.ts # Exports theme + types
-└── tokens.css # Generated CSS variables
-```
-
-```typescript
-// @company/dark-theme/theme.ts
-import {createTheme} from '@xds/core';
-
-export const darkTheme = createTheme({
- tokens: {
- color: {
- primary: ['#6366f1', '#818cf8'],
- onPrimary: ['#ffffff', '#000000'],
- background: ['#1a1a2e', '#0f0f1a'],
- onBackground: ['#e0e0e0', '#ffffff'],
- // ...
- },
- spacing: {
- sm: '0.5rem',
- md: '1rem',
- },
- },
-});
-
-export type DarkTheme = typeof darkTheme;
-```
-
-### Using a Theme Package
-
-```typescript
-// src/App.tsx
-import { Theme } from '@xds/core';
-import { darkTheme } from '@company/dark-theme';
-import { XDSButton } from '@xds/core';
-
-function App() {
- return (
- <Theme theme={darkTheme}>
- <XDSButton variant="primary">Click me</XDSButton>
- </Theme>
- );
-}
-```
-
-### Type Safety
-
-With token-only themes, type safety is straightforward:
-
-| What | Where Types Come From |
-| ---------------------- | --------------------------------------------------- |
-| **Tokens** | Theme definition (`darkTheme.tokens.color.primary`) |
-| **Component variants** | Component definition (self-contained) |
-
-Components have their own types based on their variant definitions — no cross-package type inference needed.
-
----
-
-## Open Questions
-
-### Resolved (with actual implementation)
-
-1. ~~**Light/dark mode support?**~~ → **Resolved**: CSS `light-dark()` function. Theme provider sets `color-scheme` property. Mode prop (`system`/`light`/`dark`) controls behavior.
-
-2. ~~**Component themes in theme vs component file?**~~ → **Resolved**: Hybrid approach - component variants defined in component files, themes can provide variant overrides via `components.button.variants`.
-
-3. ~~**Prop naming (intent vs variant)?**~~ → **Resolved**: Use `variant` — more corpus representation for AI.
-
-4. ~~**Type inference from StyleX objects?**~~ → **Resolved**: `keyof typeof variants` derives variant type from StyleX object. Types stay in sync automatically.
-
-5. ~~**Theme-to-component type coupling?**~~ → **Resolved**: Module augmentation - each component declares its own entry in `ComponentStyles` interface, avoiding circular imports.
-
-6. ~~**Default theme?**~~ → **Resolved**: XDS ships `defaultTheme` and `neutralTheme`. Themes are required to wrap components.
-
-7. ~~**Compile-time vs runtime themes?**~~ → **Resolved**: Compile-time via StyleX. Themes are pre-compiled `stylex.createTheme()` objects.
-
-### Unresolved Design Decisions
-
-1. **How deep should slot nesting go?**
- - `button.slots.icon.hover` or just `button.slots.icon`?
- - Risk of over-specification vs. flexibility
-
-2. **How to handle responsive tokens?**
- - `spacing: { md: { default: '1rem', '@md': '1.5rem' } }`
- - Or separate responsive layer?
-
-3. **Theme validation/linting?**
- - Warn if theme is missing required tokens?
- - Provide a `validateTheme()` function?
-
-### Swizzle Layer (Not Yet Implemented)
-
-4. **Swizzle CLI?**
- - `npx xds swizzle XDSButton` to eject component?
- - Currently, component variant overrides are theme-based, not file-based
-
-5. **Swizzle sync command?**
- - `npx xds sync XDSButton` to see upstream changes?
- - How do we help users stay up-to-date?
-
-### Future Considerations
-
-6. **Responsive variants?**
- - Should responsive breakpoints be part of variant API?
- - Or handled via StyleX media queries?
-
-7. **Tailwind preset?**
- - XDS tokens available as Tailwind utilities for hybrid projects
- - Not yet implemented
-
----
-
-## Styling Technology
-
-### Decision: StyleX + `@xds/variants` Wrapper
-
-Based on exploration in `stylex-vs-tailwind.md`, the recommended approach is:
-
-**StyleX** for the styling engine:
-
-- Compile-time CSS extraction, zero runtime
-- Full TypeScript integration
-- Scoped theming is first-class
-- No exposed CSS classes to consumers
-
-**`@xds/variants`** wrapper for ergonomics:
-
-- tw-classed-like variant API
-- Slots for sub-part styling
-- Compound variants, default variants
-- Type inference from variant definition
-
-**Tailwind preset** for ecosystem compatibility:
-
-- XDS tokens available as Tailwind utilities
-- Interop without compromising enforcement
-
-### Why Not Pure Tailwind?
-
-| Issue | Impact |
-| ------------------------------------ | ---------------------------------------------- |
-| Arbitrary values bypass constraints | AI can generate `mt-[13px]` |
-| Classes are public | Consumers can depend on implementation details |
-| Theme tokens are all public CSS vars | Can't evolve without breaking consumers |
-| Type safety is weak | No compile-time enforcement |
-
-### Component Authoring with `@xds/variants`
-
-```typescript
-import {createVariants} from '@xds/variants';
-import * as stylex from '@stylexjs/stylex';
-
-const button = createVariants({
- base: stylex.create({
- root: {cursor: 'pointer', borderRadius: 4},
- }).root,
-
- slots: {
- icon: stylex.create({root: {width: 16, height: 16}}).root,
- label: stylex.create({root: {fontWeight: 500}}).root,
- },
-
- variants: {
- variant: {
- primary: stylex.create({
- root: {backgroundColor: 'var(--xds-color-primary)'},
- }).root,
- secondary: stylex.create({
- root: {backgroundColor: 'var(--xds-color-secondary)'},
- }).root,
- },
- size: {
- sm: stylex.create({root: {padding: 4, fontSize: 14}}).root,
- md: stylex.create({root: {padding: 8, fontSize: 16}}).root,
- },
- },
-
- defaultVariants: {
- variant: 'primary',
- size: 'md',
- },
-});
-
-// TypeScript infers: { variant: 'primary' | 'secondary', size: 'sm' | 'md' }
-```
-
-This provides tw-classed ergonomics without exposed CSS classes.
-
----
-
-## Implementation Phases
-
-### Phase 1: Core Infrastructure ✅ Complete
-
-**Token System**
-
-- `stylex.defineVars` for tokens (colors, spacing, typography, radius, transitions, elevation)
-- `light-dark()` CSS function for automatic light/dark mode switching
-- Token categories: color, spacing, radius, transition, typography, elevation
-
-**Theme System**
-
-- `ThemeContext` for providing theme to component tree
-- `Theme` provider component with mode prop ('light' | 'dark' | 'system')
-- `stylex.createTheme` for theme-level token overrides
-- Component-level variant overrides via `theme.components.{component}.variants`
-- Module augmentation pattern for type-safe component styles (avoids circular imports)
-
-**Pilot Components**
-
-- Button with variants (primary, secondary, ghost, destructive)
-- Loading state with spinner animation
-- Press effect (scale 98%)
-- Theme variant consumption pattern
-
-**Infrastructure**
-
-- Storybook integration with theme switching
-- Vitest with StyleX babel plugin for testing
-- Component template (`/create-component` slash command)
-
-### Phase 2: Component Library
-
-- Additional components (XDSInput, XDSText, XDSBox, XDSStack, XDSCard, etc.)
-- Slot-level styling (icon, label, prefix, suffix)
-- Full variant/size matrix across components
-
-### Phase 3: Ecosystem
-
-- Theme gallery / community themes
-- Documentation site
-- Migration guides from other design systems
-
-### Phase 4: Advanced Features
-
-- Swizzle CLI for component customization
-- Animation tokens
-- Multi-theme composition
-- Responsive tokens
-
----
-
-## Related Explorations
-
-- `frontend-developer-jtbd.md` — Developer jobs research, workflow phases
-- `swizzle-layer-ergonomics.md` — Dual-path swizzle approach, AI-friendliness
-- `zero-styling-architecture.md` — Foundational concept
-- `stylex-vs-tailwind.md` — Styling technology choice, token tiers, `@xds/variants` wrapper approach
-- `ai-trajectory-predictions.md` — Why constraints matter long-term
-- `required-props-pattern.md` — Explicit APIs for AI
-- `distribution-methods.md` — How themes will be distributed
-- `stylex-patterns.md` — StyleX usage patterns, challenges, and workarounds (e.g., `backgroundImage` for overlay effects)
-- `component-swizzling.md` — How customized components could be distributed alongside themes
-- `component-reference.md` — Complete Button implementation as canonical component template
-
----
-
-## Sources
-
-- [Rangle.io: Token Structure](https://Rangle.io/blog/developing-your-token-structure)
-- [StyleX Theming Guide](https://stylexjs.com/docs/learn/theming/creating-themes/)
-- [Tailwind v4 Theme Docs](https://tailwindcss.com/docs/theme)
-- [UXPin: Component-Based Design](https://www.uxpin.com/studio/blog/component-based-design-complete-implementation-guide/)
diff --git a/.context/proposals/xds-selector-api.md b/.context/proposals/xds-selector-api.md
deleted file mode 100644
index 0d171c4fe2..0000000000
--- a/.context/proposals/xds-selector-api.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# XDSSelector API Proposal
-
-## Status
-
-Approved
-
-## Decision
-
-Use `items` prop with optional render function.
-
-## API
-
-### Basic
-
-```tsx
-<XDSSelector
- items={['Apple', 'Banana', 'Orange']}
- value={value}
- onChange={setValue}
-/>
-```
-
-### With Objects
-
-```tsx
-<XDSSelector
- items={[
- {value: 'apple', label: 'Apple'},
- {value: 'banana', label: 'Banana', disabled: true},
- ]}
- value={value}
- onChange={setValue}
-/>
-```
-
-### Custom Rendering
-
-```tsx
-<XDSSelector items={users} value={value} onChange={setValue}>
- {user => <XDSSelectorItem icon={user.avatar}>{user.name}</XDSSelectorItem>}
-</XDSSelector>
-```
-
-### Dividers & Groups
-
-```tsx
-<XDSSelector
- items={[
- {value: 'apple', label: 'Apple'},
- {type: 'divider'},
- {
- type: 'section',
- title: 'Citrus',
- items: [{value: 'orange', label: 'Orange'}],
- },
- ]}
-/>
-```
-
-## Types
-
-```typescript
-type XDSSelectorItem = {
- value: string;
- label?: string;
- disabled?: boolean;
- icon?: XDSIconType;
-};
-
-type XDSSelectorOption =
- | string
- | XDSSelectorItem
- | {type: 'divider'}
- | {type: 'section'; title?: string; items: XDSSelectorItem[]};
-
-interface XDSSelectorProps<T extends XDSSelectorOption> {
- // Data
- items: T[];
-
- // Value
- value?: string;
- onChange?: (value: string) => void;
-
- // Display
- placeholder?: string;
- children?: (item: Extract<T, XDSSelectorItem>) => React.ReactNode;
-
- // State
- isDisabled?: boolean;
-}
-```
-
-## Future: Async/Searchable
-
-Deferred for later. Will use `searchSource` pattern:
-
-```typescript
-interface SearchSource<T> {
- bootstrap(): Promise<T[]>;
- search(query: string): Promise<T[]>;
-}
-```
-
-## Rationale
-
-1. **No two-pass render** — data known upfront
-2. **RSC compatible** — server can return items via React Flight
-3. **Async-friendly** — `searchSource` encapsulates fetch logic
-4. **Still compositional** — render function uses JSX
-5. **LLM-friendly** — simple data structure, one component
diff --git a/.context/proposals/xds-text-heading-spec.md b/.context/proposals/xds-text-heading-spec.md
deleted file mode 100644
index 63769e0653..0000000000
--- a/.context/proposals/xds-text-heading-spec.md
+++ /dev/null
@@ -1,594 +0,0 @@
-# XDSText and XDSHeading Component Spec
-
-> **Status:** Draft
-> **Date:** 2026-01-26
-> **Context:** [typography-tokens.md](../explorations/typography-tokens.md)
-
----
-
-## Overview
-
-This spec defines the API for `XDSText` and `XDSHeading` components, informed by the typography tokens exploration and analysis of the current implementation.
-
----
-
-## Design Principles
-
-1. **Constrained escape hatches** — `xstyle` allowed for layout only (margins, flex); typography locked
-2. **Semantic-first** — Guide LLMs toward semantic types over raw sizes
-3. **Smart defaults** — Minimize required props; sensible behavior out of the box
-4. **Theme-driven** — Components pull styles from theme, not hardcoded mappings
-5. **Explicit over magic** — Prefer explicit props (e.g., `color="inherit"`) over context-based behavior
-6. **Boolean flags prefixed** — Use `is` or `has` prefix for boolean props (e.g., `hasCapsize`)
-
----
-
-## XDSHeading
-
-### API
-
-```typescript
-interface XDSHeadingProps {
- /**
- * Visual heading level (1-6). Determines styling from theme.
- * Required to ensure intentional visual hierarchy.
- */
- level: 1 | 2 | 3 | 4 | 5 | 6;
-
- /**
- * Accessibility level override. When set, the `aria-level` will differ
- * from the visual `level`. Use this when the visual hierarchy doesn't
- * match the document outline (e.g., sidebar headings, reused components).
- *
- * @default Same as `level`
- *
- * @example
- * // Visually styled as h2, but semantically h3 in document outline
- * <XDSHeading level={2} accessibilityLevel={3}>Sidebar Section</XDSHeading>
- */
- accessibilityLevel?: 1 | 2 | 3 | 4 | 5 | 6;
-
- /**
- * Visual variant. Themes define different scales for each variant.
- * @default 'default'
- */
- variant?: 'default' | 'editorial';
-
- /**
- * Text color.
- * @default 'primary'
- */
- color?: 'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit';
-
- /**
- * Display type. Headings default to block.
- * @default 'block'
- */
- display?: 'inline' | 'block';
-
- /**
- * Maximum lines before truncation. 0 = no truncation.
- * When set, shows tooltip on hover if content is truncated.
- * @default 0
- */
- maxLines?: number;
-
- /**
- * Control tooltip behavior for truncated text.
- * - `true` (default when maxLines > 0): show tooltip at default position
- * - `false`: disable tooltip
- * - Position value: show tooltip at specific position
- */
- truncateTooltip?: boolean | Position;
-
- /**
- * Enable optical alignment (textBoxTrim).
- * @default false
- */
- hasCapsize?: boolean;
-
- /**
- * Strikethrough decoration.
- * @default false
- */
- hasStrikethrough?: boolean;
-
- /**
- * Constrained styles for layout integration.
- * Allows margins, flex child props, text alignment.
- * See "Constrained xstyle" section for allowed properties.
- */
- xstyle?: StaticStyles<XDSTextXStyleAllowed>;
-
- children: React.ReactNode;
-
- 'data-testid'?: string;
- id?: string;
-}
-```
-
-### Rationale
-
-**`level` as primary prop (visual):**
-- Determines visual styling from theme
-- Required to ensure intentional hierarchy
-- TypeScript constrains to valid values (no h7)
-
-**`accessibilityLevel` for document outline:**
-- Defaults to `level` — visual and semantic match by default
-- Override when visual hierarchy differs from document outline
-- Common use cases:
- - Sidebar headings that shouldn't affect main content outline
- - Reusable card components used at different nesting depths
- - Fixed page sections where visual consistency > semantic correctness
-
-**`variant` for scale switching:**
-- `'default'` — standard XDS scale (denser)
-- `'editorial'` — larger scale for content-heavy pages
-- Extensible for future variants (e.g., `'display'`, `'marketing'`)
-
-**No separate `semanticLevel` prop:**
-- Current implementation has both `type` and `semanticLevel` which can diverge
-- New design: `level` IS the semantic level; use `variant` for visual differences
-- If truly needed (rare), can override via `aria-level` in future version
-
-### Theme Integration
-
-```typescript
-// Theme defines complete styles per level + variant
-const theme = {
- typography: {
- heading: {
- default: {
- 1: { fontSize: '1.25rem', lineHeight: '1.2', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 20px
- 2: { fontSize: '1.125rem', lineHeight: '1.33', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 18px
- 3: { fontSize: '1rem', lineHeight: '1.25', fontWeight: 700, fontFamily: 'var(--font-heading)' }, // 16px
- 4: { fontSize: '0.875rem', lineHeight: '1.43', fontWeight: 700, fontFamily: 'var(--font-heading)' }, // 14px
- 5: { fontSize: '0.875rem', lineHeight: '1.43', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 14px
- 6: { fontSize: '0.75rem', lineHeight: '1.33', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 12px
- },
- editorial: {
- 1: { fontSize: '2rem', lineHeight: '1.5', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 32px
- 2: { fontSize: '1.5rem', lineHeight: '1.33', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 24px
- 3: { fontSize: '1.25rem', lineHeight: '1.4', fontWeight: 700, fontFamily: 'var(--font-heading)' }, // 20px
- 4: { fontSize: '1rem', lineHeight: '1.5', fontWeight: 700, fontFamily: 'var(--font-heading)' }, // 16px
- 5: { fontSize: '0.875rem', lineHeight: '1.43', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 14px (fallback)
- 6: { fontSize: '0.75rem', lineHeight: '1.33', fontWeight: 600, fontFamily: 'var(--font-heading)' }, // 12px (fallback)
- },
- },
- },
-};
-```
-
-### Usage Examples
-
-```tsx
-// Standard headings
-<XDSHeading level={1}>Page Title</XDSHeading>
-<XDSHeading level={2}>Section</XDSHeading>
-<XDSHeading level={3}>Subsection</XDSHeading>
-
-// Editorial variant (larger scale)
-<XDSHeading level={1} variant="editorial">Article Title</XDSHeading>
-
-// Truncated heading with tooltip
-<XDSHeading level={2} maxLines={1}>Very Long Section Title That Might Truncate</XDSHeading>
-
-// Inherit color from parent
-<XDSHeading level={3} color="inherit">Inherits Parent Color</XDSHeading>
-```
-
----
-
-## XDSText
-
-### API
-
-```typescript
-type XDSTextType = 'body' | 'large' | 'label' | 'large-label' | 'supporting' | 'code';
-type XDSTextSize = '4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
-
-interface XDSTextProps {
- /**
- * Semantic text type. Determines size, weight, and line-height from theme.
- * Required to ensure semantic usage.
- */
- type: XDSTextType;
-
- /**
- * Explicit font size override. When set, overrides the size from `type`
- * but preserves other type properties (font-family, default color).
- *
- * ⚠️ Lint rule: Prefer using `type` alone. Use `size` only for custom
- * UI elements that need explicit size control (metrics, callouts).
- */
- size?: XDSTextSize;
-
- /**
- * Text color. Defaults vary by type:
- * - 'supporting', 'label' → 'secondary'
- * - others → 'primary'
- */
- color?: 'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit';
-
- /**
- * Font weight override.
- */
- weight?: 'normal' | 'medium' | 'semibold' | 'bold';
-
- /**
- * Display type. Text defaults to inline.
- * @default 'inline'
- */
- display?: 'inline' | 'block';
-
- /**
- * Maximum lines before truncation. 0 = no truncation.
- * Note: truncated text renders as block.
- * @default 0
- */
- maxLines?: number;
-
- /**
- * Control tooltip behavior for truncated text.
- * @default true (when maxLines > 0)
- */
- truncateTooltip?: boolean | Position;
-
- /**
- * Word break behavior for truncated text.
- * @default 'break-all' for maxLines=1, 'break-word' otherwise
- */
- wordBreak?: 'break-word' | 'break-all';
-
- /**
- * Text wrapping behavior.
- */
- textWrap?: 'wrap' | 'nowrap';
-
- /**
- * Enable optical alignment (textBoxTrim).
- * @default false
- */
- hasCapsize?: boolean;
-
- /**
- * Strikethrough decoration.
- * @default false
- */
- hasStrikethrough?: boolean;
-
- /**
- * Use tabular (monospace) numbers for alignment.
- * @default false
- */
- hasTabularNumbers?: boolean;
-
- /**
- * Constrained styles for layout integration.
- * Allows margins, flex child props, text alignment.
- * See "Constrained xstyle" section for allowed properties.
- */
- xstyle?: StaticStyles<XDSTextXStyleAllowed>;
-
- children: React.ReactNode;
-
- 'data-testid'?: string;
- id?: string;
-}
-```
-
-### Type Values
-
-| Type | Size | Weight | Line Height | Default Color | Use Case |
-|------|------|--------|-------------|---------------|----------|
-| `body` | 14px | Regular | 20px (1.43) | primary | The bulk of content |
-| `large` | 16px | Regular | 24px (1.5) | primary | Emphasized content, quotes, descriptions |
-| `label` | 14px | Bold | 20px (1.43) | primary | Form/chart/table column labels |
-| `large-label` | 16px | SemiBold | 24px (1.5) | primary | Empty state labels, prominent labels |
-| `supporting` | 12px | Regular | 16px (1.33) | secondary | Helper text, supplemental info |
-| `code` | 14px | Regular | 20px (1.43) | primary | Inline code, monospace |
-
-### Rationale
-
-**Type-based (not size-based):**
-- Semantic types guide correct usage
-- Themes control actual sizes per type
-- Weights and line-heights bundled with type
-- LLMs learn patterns from codebase examples
-- `size` prop available for overrides, with lint steering toward semantic usage
-
-**Color defaults based on type:**
-- `supporting` defaults to secondary color (helper text is de-emphasized)
-- All other types default to primary color
-- Override with `color` prop when needed
-
-### Theme Integration
-
-```typescript
-const theme = {
- typography: {
- text: {
- body: { fontSize: '0.875rem', lineHeight: '1.43', fontWeight: 400, fontFamily: 'var(--font-heading)' },
- large: { fontSize: '1rem', lineHeight: '1.5', fontWeight: 400, fontFamily: 'var(--font-heading)' },
- label: { fontSize: '0.875rem', lineHeight: '1.43', fontWeight: 700, fontFamily: 'var(--font-heading)' },
- 'large-label': { fontSize: '1rem', lineHeight: '1.5', fontWeight: 600, fontFamily: 'var(--font-heading)' },
- supporting: { fontSize: '0.75rem', lineHeight: '1.33', fontWeight: 400, fontFamily: 'var(--font-heading)' },
- code: { fontSize: '0.875rem', lineHeight: '1.43', fontWeight: 400, fontFamily: 'var(--font-code)' },
- },
- },
-};
-```
-
-### Usage Examples
-
-```tsx
-// Standard body text (type is required)
-<XDSText type="body">Body text</XDSText>
-
-// Supporting/helper text (defaults to secondary color)
-<XDSText type="supporting">Last updated 5 minutes ago</XDSText>
-
-// Labels for form fields, chart columns, table headers
-<XDSText type="label">Email address</XDSText>
-
-// Large label for empty states, prominent labels
-<XDSText type="large-label">No results found</XDSText>
-
-// Large body for quotes, descriptions
-<XDSText type="large">Important message</XDSText>
-
-// Code
-<XDSText type="code">const x = 1;</XDSText>
-
-// Truncation
-<XDSText type="body" maxLines={2}>Long text that will be clamped to two lines...</XDSText>
-
-// Inherit color (for nested text)
-<XDSText type="body" color="inherit">Inherits parent color</XDSText>
-
-// Size override for custom UI elements (lint will warn if overused)
-<XDSText type="body" size="4xl" weight="bold">
- {metricValue}
-</XDSText>
-```
-
----
-
-## Component-Specific Text Styles
-
-These styles are used internally by specific components, not exposed on XDSText:
-
-| Style | Size | Weight | Line Height | Used By |
-|-------|------|--------|-------------|---------|
-| `data-viz-large` | 32px | Medium | 36px (1.125) | XDSMetricTile |
-| `data-viz-small` | 24px | Medium | 28px (1.167) | XDSMetricTile |
-| `app-name` | 20px | Bold | 24px (1.2) | Page navigation product name |
-| `badge` | 12px | SemiBold | 16px (1.33) | XDSBadge |
-
-These are defined in `theme.components.text.componentStyles` and accessed directly by their respective components.
-
----
-
-## Size Scale
-
-When using the `size` prop to override type-based sizing:
-
-| Size | Value | Typical Usage |
-|------|-------|---------------|
-| `4xs` | 0.5rem (8px) | Citation, micro text |
-| `3xs` | 0.625rem (10px) | Micro labels |
-| `2xs` | 0.6875rem (11px) | Small micro text |
-| `xsm` | 0.75rem (12px) | Captions, badges, supporting |
-| `sm` | 0.8125rem (13px) | Secondary text |
-| `base` | 0.875rem (14px) | Body (XDS default) |
-| `lg` | 1rem (16px) | Large body, input text |
-| `xl` | 1.125rem (18px) | Large emphasis, h2 |
-| `2xl` | 1.25rem (20px) | h1, subtitle |
-| `3xl` | 1.5rem (24px) | Editorial h2, card title |
-| `4xl` | 2rem (32px) | Editorial h1, data viz |
-
-### Line Height Coupling
-
-Line height is automatically determined by size (not exposed as prop):
-
-```typescript
-const lineHeightBySize = {
- '4xs': 1.33,
- '3xs': 1.33,
- '2xs': 1.33,
- xsm: 1.33,
- sm: 1.43,
- base: 1.43,
- lg: 1.5,
- xl: 1.4,
- '2xl': 1.3,
- '3xl': 1.25,
- '4xl': 1.2,
-};
-```
-
-### Lint Rules for Size Usage
-
-```typescript
-// Lint rule: xds/prefer-semantic-type
-// Warns when `size` prop is used, suggesting to rely on `type` instead.
-// Severity: warning (not error - size is valid for custom UI elements)
-
-// Example lint output:
-// ⚠️ Line 42: Consider removing `size` prop and using semantic `type` alone.
-// The `size` prop should only be used for custom UI elements like
-// dashboard metrics or data visualizations.
-```
-
----
-
-## Truncation Behavior
-
-### Consolidated Props
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `maxLines` | `number` | `0` | 0 = no truncation |
-| `truncateTooltip` | `boolean \| Position` | `true` | Shown only when actually overflowing |
-| `wordBreak` | `'break-word' \| 'break-all'` | Smart | `break-all` for 1 line, `break-word` otherwise |
-
-### Behavior
-
-1. **maxLines=0**: No truncation, text wraps naturally
-2. **maxLines=1**: Single-line truncation with ellipsis, defaults to `break-all`
-3. **maxLines>1**: Multi-line clamp with `-webkit-line-clamp`
-4. **Tooltip**: Only shown when content actually overflows (detected via ref)
-5. **Tooltip content**: Clamped to 10 lines max to prevent huge tooltips
-6. **Truncated text always renders as block** (required for line-clamp)
-
-### Migration from Current API
-
-| Current | New |
-|---------|-----|
-| `numberOfLines={2}` | `maxLines={2}` |
-| `hasTooltipForTruncatedText={false}` | `truncateTooltip={false}` |
-| `truncatedTextTooltipPosition="above"` | `truncateTooltip="above"` |
-
----
-
-## Disabled State Handling
-
-### Open Question
-
-Current implementation uses `XDSInternalTextColorDisabledOverrideContext` to let parent components (like buttons) force disabled styling on child text.
-
-**Options:**
-
-1. **Keep context pattern** — Parent sets disabled, children inherit
-2. **Explicit prop only** — `color="disabled"` must be set explicitly
-3. **Both** — Support context but also allow explicit override
-
-**Recommendation:** Keep context for component library internals (XDSButton disabling its label), but also support explicit `color="disabled"` for standalone usage.
-
----
-
-## Constrained xstyle
-
-Both XDSText and XDSHeading support a **constrained `xstyle` prop** for layout integration. This allows spacing and flex positioning without escaping typography styles.
-
-### Allowed Properties
-
-```typescript
-xstyle?: StaticStyles<{
- // Margins (from XDSMarginXStyles)
- margin?: unknown;
- marginTop?: unknown;
- marginBottom?: unknown;
- marginStart?: unknown;
- marginEnd?: unknown;
- marginBlock?: unknown;
- marginInline?: unknown;
-
- // Width constraints (from XDSWidthXStyles)
- width?: unknown;
- minWidth?: unknown;
- maxWidth?: unknown;
-
- // Flex child properties
- alignSelf?: unknown;
- flexBasis?: unknown;
- flexGrow?: unknown;
- flexShrink?: unknown;
- flexWrap?: unknown;
-
- // Text layout (non-typography)
- overflow?: unknown;
- overflowWrap?: unknown;
- textAlign?: unknown;
- textAlignLast?: unknown;
- textOverflow?: unknown;
- verticalAlign?: unknown;
- whiteSpace?: unknown;
- wordBreak?: unknown;
-
- // Decoration (allowed since hasStrikethrough exists)
- textDecoration?: unknown;
-}>;
-```
-
-### NOT Allowed (enforced by type)
-
-- `fontSize`, `lineHeight`, `fontWeight`, `fontFamily` — use `type`/`level` props
-- `color` — use `color` prop
-- `padding` — internal to component
-- `background`, `border` — not text concerns
-
-### Rationale
-
-This matches the internal Meta implementation pattern. It allows:
-- Layout integration (margins for spacing rhythm)
-- Flex positioning (alignSelf for cross-axis control)
-- Text alignment (textAlign for content alignment)
-
-While preventing:
-- Typography escapes (can't override font-size)
-- Color escapes (must use semantic color prop)
-- Structural changes (no padding/background)
-
----
-
-## Props NOT Included
-
-| Prop | Reason |
-|------|--------|
-| `style` | Prevents escaping design system |
-| `className` | Prevents escaping design system |
-| `lineHeight` | Coupled to size/type internally |
-| `fontSize` | Use `type` or `size` prop |
-| `fontFamily` | Determined by type (body vs code vs heading) |
-
----
-
-## Migration Notes
-
-### XDSText Type Mapping
-
-| Current | New | Notes |
-|---------|-----|-------|
-| `body` | `body` | Same |
-| `large-body` | `large` | Renamed for brevity |
-| `emphasized` | `label` | Renamed to match use case (form/chart labels) |
-| `large-emphasized` | `large-label` | Renamed to match use case |
-| `supporting` | `supporting` | Same |
-| `label` | `label` | Same (if existed) |
-
-### XDSHeading Type Mapping
-
-| Current | New | Notes |
-|---------|-----|-------|
-| `header1` | `level={1}` | Semantic-first |
-| `header2` | `level={2}` | Semantic-first |
-| `header3` | `level={3}` | Semantic-first |
-| `header4` | `level={4}` | Semantic-first |
-| `display` | `level={1} variant="display"` | TBD: add display variant? |
-| `editorialHeader1` | `level={1} variant="editorial"` | Variant-based |
-| `header1_DO_NOT_USE` | Deprecated | Remove in migration |
-
----
-
-## Open Questions
-
-1. **Display variant for XDSHeading?** — Should we add `variant="display"` for hero/marketing use cases, or use XDSText with size override?
-
-2. **Nested heading context** — Current impl prevents nested headings from both having `role="heading"`. Keep this behavior?
-
-3. **`emphasized` type** — Should we keep as a type, or always use `weight` prop? Current decision: weight prop.
-
-4. **textWrap prop** — Is this needed on XDSHeading, or only XDSText?
-
----
-
-## Next Steps
-
-1. [ ] Review and finalize type values
-2. [ ] Define theme typography structure with tokens team
-3. [ ] Implement XDSHeading
-4. [ ] Implement XDSText
-5. [ ] Create migration codemod for type changes
-6. [ ] Add lint rule for `size` prop usage
diff --git a/CLAUDE.md b/CLAUDE.md
index 4fd9aba208..eca77a4dba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -48,12 +48,14 @@ Probes at turns 0, 6, 8, 10 to measure quality degradation. Results show a line
## AI Context
-For architectural context and decisions, see `.context/`:
+For architectural context, decisions, and research, see the **[GitHub Wiki](https://github.com/facebookexperimental/xds/wiki)**:
-- `.context/decisions/` — Architecture Decision Records
- - **[API Guidance](/.context/decisions/api-guidance.md)** — Component API conventions (naming, props, styling, state, async actions)
-- `.context/explorations/` — Research and brainstorms
-- `.context/proposals/` — Feature proposals
+- **Decisions** — API Conventions, Why StyleX, StyleX Distribution
+- **Architecture** — System Architecture, Component Authoring Guide
+- **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/`.
## Documentation Standard
diff --git a/internal/vibe-tests/README.md b/internal/vibe-tests/README.md
index 182274ff53..49baa3bbce 100644
--- a/internal/vibe-tests/README.md
+++ b/internal/vibe-tests/README.md
@@ -273,4 +273,4 @@ yarn workspace @xds/vibe-tests aggregate --iteration abc123 --ci
## For More Details
-See the full spec in `.context/proposals/vibeability-test-harness.md`
+See the source code and CLI help (`yarn workspace @xds/vibe-tests --help`) for the current test harness spec.
diff --git a/packages/core/src/Layout/README.md b/packages/core/src/Layout/README.md
index 1d689fe6ca..b8cd028150 100644
--- a/packages/core/src/Layout/README.md
+++ b/packages/core/src/Layout/README.md
@@ -275,4 +275,4 @@ XDSLayoutContainer sets these CSS variables that child components read:
## Related
-- See `.context/proposals/layout-system.md` for full design proposal
+- See the [System Architecture](https://github.com/facebookexperimental/xds/wiki/System-Architecture) wiki page for the broader layout philosophy