Working with AI

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.

Tell your AI to install the CLI and set itself up:

text
Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.

That's it. The init --features agents command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, astryx upgrade --from <old version> reports a stale block and adding --apply refreshes it.

By default this creates AGENTS.md (the tool-agnostic standard most agents read). To target a specific tool's file instead:

bash
npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
npx @astryxdesign/cli init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)
npx @astryxdesign/cli init --features agents --agent all       # every agent file present, else AGENTS.md and .claude/CLAUDE.md

The generated context teaches your AI a 3-step workflow before writing any UI code:

1. astryx build "<idea>": get the page template to start from (always one: the closest match, or the app shell), two other templates, and the blocks and components for the parts it lacks
2. astryx template <name> <path>: scaffold that template into the project, keep its frame and spacing, and replace its content
3. astryx component <Name>: read props and examples for every component used

It also includes rules that prevent common mistakes (start every page from a template, no raw divs, no style={{}}, use tokens not magic values), a CLI quick reference, and package-labeled integration guidance when a configured manifest declares agentDocs. After setup, you shouldn't need to manually correct your AI on these conventions; the agent docs handle it at the system level.

Cursor reads project rules from .cursor/rules/. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as .cursor/rules/astryx.mdc; an absolute path is refused.

bash
npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc

Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as alwaysApply: true) stays.

Paste this into your AI before writing any component code. If your AI can't answer these questions, it'll know to install the agent docs first.

text
Before writing any Astryx code, check your knowledge:
​
1. What is the correct import path for Button?
2. How do you make a Dialog non-dismissible?
3. What prop does Selector use for its items?
​
If you don't know all three, run `npx @astryxdesign/cli init --features agents` to generate agent docs, then read the generated file.

AI agents frequently invoke the CLI with incorrect paths (e.g. node_modules/@astryxdesign/cli/bin/docs.mjs instead of astryx.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.

json
"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}

With this alias, agents run npm run astryx -- component --list instead of guessing the binary path. The -- separator is standard npm convention for passing flags to scripts.

bash
npm run astryx -- component --list
npm run astryx -- component Dialog --dense
npm run astryx -- docs styling --full --detail brief
npm run astryx -- docs tokens --dense

For a shorter read, add --detail brief (one line per section) or --detail compact. --dense swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.

bash
astryx docs styling --full --detail brief
astryx component Dialog --detail compact
astryx docs principles --dense

Astryx 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 Astryx 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.

json
{
  "mcpServers": {
    "astryx": {
      "type": "url",
      "url": "https://astryx.atmeta.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.