Working with AI

How to set up AI coding tools to generate correct component code.

Overview

The design system is built to be AI-friendly: consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props.The CLI includes a built-in agent docs system that generates context files for your AI tool of choice. One command sets up everything your AI needs to write correct component code.

Quick Start

Tell your AI to install the CLI and set itself up:
Paste this into your AI
text
Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your XDS context. Read the generated file.
That's it. The agent-docs command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.If you prefer to target a specific file format:
Manual options
bash
npx astryx agent-docs --agent claude    # CLAUDE.md
npx astryx agent-docs --agent cursor    # .cursorrules
npx astryx agent-docs --agent codex     # AGENTS.md (Copilot, Codex, etc.)

What Gets Generated

The generated context teaches your AI a 3-step workflow before writing any UI code:
  1. npx astryx template --list: find a related page pattern to use as reference
  2. npx astryx template <name> --skeleton: study the layout structure
  3. npx astryx component <Name>: read props and examples for every component used
It also includes rules that prevent common mistakes (no raw divs, no style={{}}, use tokens not magic values) and a CLI quick reference. After setup, you shouldn't need to manually correct your AI on these conventions; the agent docs handle it at the system level.

Cursor Setup

Cursor project rules aren't always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.
Install as a Cursor user rule
bash
mkdir -p ~/.cursor/rules
npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc

Checking Your Setup

Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can't answer them, it'll know to install the agent docs first.
Paste this into your AI
text
Before writing any XDS code, check your knowledge:
​
1. What is the correct import path for Button?
2. How do you make an Dialog non-dismissible?
3. What prop does Selector use for its items?
​
If you don't know all three, run `npx astryx init --features agents` to generate agent docs, then read the generated file.

The npx astryx Pattern

AI agents frequently invoke the CLI with incorrect paths (e.g. node_modules/@astryxdesign/cli/bin/docs.mjs instead of xds.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.
package.json
json
"scripts": {
  "xds": "node node_modules/@astryxdesign/cli/bin/xds.mjs"
}
With this alias, agents use npx astryx component --list instead of guessing the binary path. The -- separator is standard npm convention for passing flags to scripts.
Reliable CLI invocation
bash
npx astryx component --list
npx astryx component Dialog --dense
npx astryx docs styling --dense
npx astryx docs tokens --dense

The --dense Flag

Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.
Dense output for pasting into AI conversations
bash
npx astryx component Dialog --dense
npx astryx docs styling --dense
npx astryx docs tokens --dense

MCP Server

XDS ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the XDS design system directly, searching for components, reading full documentation, and pulling code examples on demand.The MCP server exposes two tools: search(query) for discovering components, doc topics, and templates; and get(name) for retrieving full documentation with props, usage, and examples.Add the server to your MCP config file. This works with any MCP-compatible tool: Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.
MCP config (same for all tools)
json
{
  "mcpServers": {
    "xds": {
      "type": "url",
      "url": "https://astryx.meta.com/mcp"
    }
  }
}
Once connected, your AI tool can search for components by natural language (e.g. "dropdown menu", "success message") and retrieve full documentation without any manual CLI invocation. The server uses the same keyword index from component docs, so search quality improves automatically as component documentation is updated.