An open source design system that's fully customizable and agent ready
TypeScript
docs: make AGENTS the canonical agent guide (#6098)
Cindy Zhang87970aa764de
diff --git a/AGENTS.md b/AGENTS.mdindex 193ee5970a..03968429b2 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -54,3 +54,148 @@ Run `pnpm check:knowledge` after editing knowledge records or templates. Amaterial template-shape change requires a schema-version bump and migration ofactive records; changing template guidance alone does not rewrite acceptedhistory.++## Custom Commands++### `/vibe-test [count]` - Run vibeability tests++Tests how well AGENTS.md helps LLMs generate correct Astryx component code.++**Usage:**++```+/vibe-test 5 # Run 5 stratified sample tests (one-shot)+/vibe-test # Run all 21 tests (one-shot)+/vibe-test 5 --degradation # Run 5 tests with degradation curve (10-turn)+```++**How to execute:**++1. Run `pnpm -F @astryxdesign/vibe-tests interactive --sample <count>` to set up iteration+2. Spawn parallel subagents (one per test prompt) to:+ - Read the task file from `results/<iteration>/tasks/{promptId}.json`+ - Generate code for the prompt using Astryx components (AGENTS.md auto-injected)+ - Self-evaluate for success/escape hatches+ - Write `.tsx` result to `results/<iteration>/results/{promptId}.tsx`+ - Write `.json` metadata to `results/<iteration>/results/{promptId}.json`+3. Trigger `gh workflow run vibe-screenshots.yml` to build previews and capture screenshots+4. Run `pnpm -F @astryxdesign/vibe-tests aggregate --iteration <id>` to see results++**Degradation mode (--degradation):**+Tests context retention across 10-turn conversations with filler, distractor, and recovery turns.+Probes at turns 0, 6, 8, 10 to measure quality degradation. Results show a line graph of each test's progression.++**Result format:**++```json+{+ "id": "<iter>-<promptId>",+ "timestamp": "...",+ "model": "claude-code-interactive",+ "persona": "naive",+ "promptCategory": "...",+ "trajectoryDepth": 0,+ "prompt": "...",+ "response": "<code>",+ "evaluation": {"success": true, "componentsUsed": [...], "escapeHatches": [...]}+}+```++Runners may also write an optional `<promptId>.provenance.json` sidecar beside the result metadata. The versioned, executor-neutral contract and fallback behavior are documented in `internal/vibe-tests/docs/execution-provenance.md`.++## AI Context++For architectural context, decisions, and research, see the **[GitHub Wiki](https://github.com/facebook/astryx/wiki)**:++- **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 `{Name}.doc.mjs` file in each component directory under `packages/core/src/` (e.g. `Button/Button.doc.mjs`). These are plain JS files with JSDoc type annotations exporting a `ComponentDoc` object (typed via `@astryxdesign/cli/authoring`).++## Documentation Standard++Documentation lives in two places:++1. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`+2. **Component Docs** — `{Name}.doc.mjs` files in each component directory (props, features, examples)++**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.++**Audience**: every `.doc.mjs`, and everything under `packages/cli/assets/docs/`, is written for people **building with** Astryx — not for people building Astryx. Rubrics, readiness gates, audit checklists and lab→core criteria belong in the wiki. [`packages/cli/assets/docs/README.md`](packages/cli/assets/docs/README.md) has the test and the page each kind of material goes to.++## Quick Reference++- **Package manager**: pnpm 11, pinned by the `packageManager` field (see+ CONTRIBUTING.md for install options — Corepack is one of several, and Node+ 25+ no longer bundles it)+- **Testing**: Vitest (colocated tests)+- **Components**: `packages/core/`+- **Storybook**: `apps/storybook/`++## JSDoc Conventions++- **`@example` code fences must use plain ` ``` `, not ` ```tsx `.**+ Storybook's autodocs parser doesn't handle language-tagged fences in JSDoc correctly — the code block won't render as a proper code block. Always use untagged fences in `@example` blocks.++<!-- STYLEX-CAPS:START -->++[StyleX v0.17.5 CSS Support]|Use CSS-native solutions. Don't build JS workarounds for supported features.+|AT-RULES: @media, @supports, @container (+named), @starting-style, @scope — YES+|AT-RULES: @layer, @property (explicit) — NO (compiles but invalid CSS output)+|PSEUDO-CLS: :hover, :focus, :focus-visible, :focus-within, :active, :disabled — YES+|PSEUDO-CLS: :first-child, :last-child, :nth-child(), :where(), :is(), :has(), :not() — YES+|PSEUDO-CLS: :placeholder-shown, :checked, :empty, :modal, :user-valid, :user-invalid — YES+|PSEUDO-EL: ::before, ::after, ::placeholder, ::selection, ::backdrop, ::marker, ::view-transition-_ — YES+|COMPOUND: ::backdrop+condition, RTL :is([dir="rtl"] _), nested @media+pseudo — YES+|VALUES: var(), calc(), clamp(), light-dark(), color-mix(), container-type/name — YES+|ANIM: transition (shorthand+individual), transitionBehavior:allow-discrete, animation, stylex.keyframes — YES+|WHEN: stylex.when.ancestor(':hover'/':focus-within'/':active'/':disabled') — YES+|WHEN: stylex.when.descendant(':hover'), siblingBefore(':checked'), siblingAfter(':checked'), anySibling(':hover') — YES+|WHEN: stylex.when.ancestor('[data-attr]') — NO (pseudo selectors only, must start with ":")+|NESTING: CSS nesting with & — NO (use stylex.when.ancestor/descendant/sibling for parent-child state)+|API: stylex.firstThatWorks() for CSS fallbacks (e.g. display: grid with flex fallback) — YES+|API: stylex.positionTry() for anchor positioning @position-try — YES+|API: stylex.types.color/length/etc for typed CSS variables in defineVars — YES+|API: stylex.defineConsts() for compile-time constants — YES+|DYNAMIC: Functions in stylex.create for runtime values — YES+|VARS: stylex.defineVars, stylex.createTheme (require .stylex.ts files) — YES+|LAYOUT: grid, flex+gap, aspect-ratio, overscrollBehavior, scrollbar-gutter/width — YES+|PATTERN: dialog entry animation -> @starting-style (not useState+rAF)+|PATTERN: parent hover child style -> stylex.when.ancestor(':hover', marker) (not CSS nesting). Use stylex.defineMarker() in a .stylex.ts file for scoped markers. Ancestor element MUST have marker.marker in its stylex.props() call. NEVER use stylex.defaultMarker() for form controls (CheckboxInput, RadioList, Switch) — it leaks hover/focus-within from outer containers like Popovers. Always use a component-scoped defineMarker() instead.+|PATTERN: hover on touch -> @media (hover: hover) guard+|PATTERN: zebra striping -> :nth-child(even) (not index%2 JS)+|PATTERN: container responsive -> @container (not ResizeObserver)+|PATTERN: CSS fallback values -> stylex.firstThatWorks() (not manual fallback)+|PATTERN: dynamic/runtime values -> stylex.create({ s: (val) => ({ prop: val }) }) (not inline styles)+|PATTERN: conditional styles -> stylex.props(condition && styles.x) (not className toggling)+|PATTERN: link elements -> useLinkComponent() (not hardcoded <a>). Consumers swap via LinkProvider for framework routers (Next.js, React Router)+|VERIFY: node internal/stylex-capabilities/scan.mjs++<!-- STYLEX-CAPS:END -->++<!-- ASTRYX-CLI:START -->++Astryx CLI|Run from repo root. Load agent docs before any component work.+ASTRYX="node packages/cli/clients/cli/bin/astryx.mjs"+BOOTSTRAP (run every branch, <500ms):+$ASTRYX help # discover all commands and options+$ASTRYX docs # list available doc topics+$ASTRYX docs principles --dense # design rules, anti-patterns, xstyle, tokens+$ASTRYX docs tokens --dense # spacing, color, radius, typography, shadow+$ASTRYX docs theme --dense # theme provider, light/dark, overrides+$ASTRYX component --list # all components grouped by category+$ASTRYX template --list # available page templates+ON DEMAND:+$ASTRYX component <Name> --dense # props, variants, usage, anatomy for one component+$ASTRYX template <name> # emit full page source+$ASTRYX template <name> --skeleton # layout skeleton with spatial annotations+$ASTRYX swizzle <Name> # eject component source for deep customization+$ASTRYX upgrade --apply # run version migration codemods+OPTIONS: --detail compact|brief less output | --dense token-efficient | --zh Chinese+RULE: always run bootstrap on each branch — docs reflect the branch's actual API+RULE: always run $ASTRYX component <Name> --dense before modifying a component+RULE: after @astryxdesign/core bump, always run $ASTRYX upgrade --apply++<!-- ASTRYX-CLI:END -->diff --git a/CLAUDE.md b/CLAUDE.mdindex e98e33c8d7..65bc7681b0 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,148 +1,5 @@-# Astryx+# Claude Code guidance-A design system for building internal tools and products.+Read and follow [`AGENTS.md`](AGENTS.md). It is the canonical repository instruction surface.-## Custom Commands--### `/vibe-test [count]` - Run vibeability tests--Tests how well AGENTS.md helps LLMs generate correct Astryx component code.--**Usage:**--```-/vibe-test 5 # Run 5 stratified sample tests (one-shot)-/vibe-test # Run all 21 tests (one-shot)-/vibe-test 5 --degradation # Run 5 tests with degradation curve (10-turn)-```--**How to execute:**--1. Run `pnpm -F @astryxdesign/vibe-tests interactive --sample <count>` to set up iteration-2. Spawn parallel subagents (one per test prompt) to:- - Read the task file from `results/<iteration>/tasks/{promptId}.json`- - Generate code for the prompt using Astryx components (AGENTS.md auto-injected)- - Self-evaluate for success/escape hatches- - Write `.tsx` result to `results/<iteration>/results/{promptId}.tsx`- - Write `.json` metadata to `results/<iteration>/results/{promptId}.json`-3. Trigger `gh workflow run vibe-screenshots.yml` to build previews and capture screenshots-4. Run `pnpm -F @astryxdesign/vibe-tests aggregate --iteration <id>` to see results--**Degradation mode (--degradation):**-Tests context retention across 10-turn conversations with filler, distractor, and recovery turns.-Probes at turns 0, 6, 8, 10 to measure quality degradation. Results show a line graph of each test's progression.--**Result format:**--```json-{- "id": "<iter>-<promptId>",- "timestamp": "...",- "model": "claude-code-interactive",- "persona": "naive",- "promptCategory": "...",- "trajectoryDepth": 0,- "prompt": "...",- "response": "<code>",- "evaluation": {"success": true, "componentsUsed": [...], "escapeHatches": [...]}-}-```--Runners may also write an optional `<promptId>.provenance.json` sidecar beside the result metadata. The versioned, executor-neutral contract and fallback behavior are documented in `internal/vibe-tests/docs/execution-provenance.md`.--## AI Context--For architectural context, decisions, and research, see the **[GitHub Wiki](https://github.com/facebook/astryx/wiki)**:--- **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 `{Name}.doc.mjs` file in each component directory under `packages/core/src/` (e.g. `Button/Button.doc.mjs`). These are plain JS files with JSDoc type annotations exporting a `ComponentDoc` object (typed via `@astryxdesign/cli/authoring`).--## Documentation Standard--Documentation lives in two places:--1. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`-2. **Component Docs** — `{Name}.doc.mjs` files in each component directory (props, features, examples)--**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.--**Audience**: every `.doc.mjs`, and everything under `packages/cli/assets/docs/`, is written for people **building with** Astryx — not for people building Astryx. Rubrics, readiness gates, audit checklists and lab→core criteria belong in the wiki. [`packages/cli/assets/docs/README.md`](packages/cli/assets/docs/README.md) has the test and the page each kind of material goes to.--## Quick Reference--- **Package manager**: pnpm 11, pinned by the `packageManager` field (see- CONTRIBUTING.md for install options — Corepack is one of several, and Node- 25+ no longer bundles it)-- **Testing**: Vitest (colocated tests)-- **Components**: `packages/core/`-- **Storybook**: `apps/storybook/`--## JSDoc Conventions--- **`@example` code fences must use plain ` ``` `, not ` ```tsx `.**- Storybook's autodocs parser doesn't handle language-tagged fences in JSDoc correctly — the code block won't render as a proper code block. Always use untagged fences in `@example` blocks.--<!-- STYLEX-CAPS:START -->--[StyleX v0.17.5 CSS Support]|Use CSS-native solutions. Don't build JS workarounds for supported features.-|AT-RULES: @media, @supports, @container (+named), @starting-style, @scope — YES-|AT-RULES: @layer, @property (explicit) — NO (compiles but invalid CSS output)-|PSEUDO-CLS: :hover, :focus, :focus-visible, :focus-within, :active, :disabled — YES-|PSEUDO-CLS: :first-child, :last-child, :nth-child(), :where(), :is(), :has(), :not() — YES-|PSEUDO-CLS: :placeholder-shown, :checked, :empty, :modal, :user-valid, :user-invalid — YES-|PSEUDO-EL: ::before, ::after, ::placeholder, ::selection, ::backdrop, ::marker, ::view-transition-_ — YES-|COMPOUND: ::backdrop+condition, RTL :is([dir="rtl"] _), nested @media+pseudo — YES-|VALUES: var(), calc(), clamp(), light-dark(), color-mix(), container-type/name — YES-|ANIM: transition (shorthand+individual), transitionBehavior:allow-discrete, animation, stylex.keyframes — YES-|WHEN: stylex.when.ancestor(':hover'/':focus-within'/':active'/':disabled') — YES-|WHEN: stylex.when.descendant(':hover'), siblingBefore(':checked'), siblingAfter(':checked'), anySibling(':hover') — YES-|WHEN: stylex.when.ancestor('[data-attr]') — NO (pseudo selectors only, must start with ":")-|NESTING: CSS nesting with & — NO (use stylex.when.ancestor/descendant/sibling for parent-child state)-|API: stylex.firstThatWorks() for CSS fallbacks (e.g. display: grid with flex fallback) — YES-|API: stylex.positionTry() for anchor positioning @position-try — YES-|API: stylex.types.color/length/etc for typed CSS variables in defineVars — YES-|API: stylex.defineConsts() for compile-time constants — YES-|DYNAMIC: Functions in stylex.create for runtime values — YES-|VARS: stylex.defineVars, stylex.createTheme (require .stylex.ts files) — YES-|LAYOUT: grid, flex+gap, aspect-ratio, overscrollBehavior, scrollbar-gutter/width — YES-|PATTERN: dialog entry animation -> @starting-style (not useState+rAF)-|PATTERN: parent hover child style -> stylex.when.ancestor(':hover', marker) (not CSS nesting). Use stylex.defineMarker() in a .stylex.ts file for scoped markers. Ancestor element MUST have marker.marker in its stylex.props() call. NEVER use stylex.defaultMarker() for form controls (CheckboxInput, RadioList, Switch) — it leaks hover/focus-within from outer containers like Popovers. Always use a component-scoped defineMarker() instead.-|PATTERN: hover on touch -> @media (hover: hover) guard-|PATTERN: zebra striping -> :nth-child(even) (not index%2 JS)-|PATTERN: container responsive -> @container (not ResizeObserver)-|PATTERN: CSS fallback values -> stylex.firstThatWorks() (not manual fallback)-|PATTERN: dynamic/runtime values -> stylex.create({ s: (val) => ({ prop: val }) }) (not inline styles)-|PATTERN: conditional styles -> stylex.props(condition && styles.x) (not className toggling)-|PATTERN: link elements -> useLinkComponent() (not hardcoded <a>). Consumers swap via LinkProvider for framework routers (Next.js, React Router)-|VERIFY: node internal/stylex-capabilities/scan.mjs--<!-- STYLEX-CAPS:END -->--<!-- ASTRYX-CLI:START -->--Astryx CLI|Run from repo root. Load agent docs before any component work.-ASTRYX="node packages/cli/clients/cli/bin/astryx.mjs"-BOOTSTRAP (run every branch, <500ms):-$ASTRYX help # discover all commands and options-$ASTRYX docs # list available doc topics-$ASTRYX docs principles --dense # design rules, anti-patterns, xstyle, tokens-$ASTRYX docs tokens --dense # spacing, color, radius, typography, shadow-$ASTRYX docs theme --dense # theme provider, light/dark, overrides-$ASTRYX component --list # all components grouped by category-$ASTRYX template --list # available page templates-ON DEMAND:-$ASTRYX component <Name> --dense # props, variants, usage, anatomy for one component-$ASTRYX template <name> # emit full page source-$ASTRYX template <name> --skeleton # layout skeleton with spatial annotations-$ASTRYX swizzle <Name> # eject component source for deep customization-$ASTRYX upgrade --apply # run version migration codemods-OPTIONS: --detail compact|brief less output | --dense token-efficient | --zh Chinese-RULE: always run bootstrap on each branch — docs reflect the branch's actual API-RULE: always run $ASTRYX component <Name> --dense before modifying a component-RULE: after @astryxdesign/core bump, always run $ASTRYX upgrade --apply--<!-- ASTRYX-CLI:END -->+Also read the nearest nested `AGENTS.md` for any path you modify. Do not duplicate shared guidance in this file.