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.mdindex 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 Creationdiff --git a/.context/README.md b/.context/README.mddeleted file mode 100644index 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 documentationdiff --git a/.context/decisions/api-guidance.md b/.context/decisions/api-guidance.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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 comparisondiff --git a/.context/explorations/animation-system.md b/.context/explorations/animation-system.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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 objectdiff --git a/.context/explorations/component-swizzling.md b/.context/explorations/component-swizzling.mddeleted file mode 100644index 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 componentdiff --git a/.context/explorations/distribution-methods.md b/.context/explorations/distribution-methods.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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 defaultsdiff --git a/.context/explorations/rsc-utilities.md b/.context/explorations/rsc-utilities.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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 declarativelydiff --git a/.context/explorations/zero-styling-architecture.md b/.context/explorations/zero-styling-architecture.mddeleted file mode 100644index 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 todiff --git a/.context/proposals/layout-system.md b/.context/proposals/layout-system.mddeleted file mode 100644index 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 philosophydiff --git a/.context/proposals/stylex-distribution.md b/.context/proposals/stylex-distribution.mddeleted file mode 100644index 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-storybookdiff --git a/.context/proposals/vibeability-test-harness.md b/.context/proposals/vibeability-test-harness.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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 componentdiff --git a/.context/proposals/xds-text-heading-spec.md b/.context/proposals/xds-text-heading-spec.mddeleted file mode 100644index 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 usagediff --git a/CLAUDE.md b/CLAUDE.mdindex 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 Standarddiff --git a/internal/vibe-tests/README.md b/internal/vibe-tests/README.mdindex 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.mdindex 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