AI & LLMs

Aether UI is designed to be the most LLM-friendly design system in the ecosystem. Every component ships with machine-readable AI metadata, the registry exposes a llms.txt index, and an MCP server lets agents browse and install components directly from Cursor, Claude Desktop, or any MCP-compatible tool. The system also ships 33 AI-native components — streaming text, chat bubbles, prompt inputs, conversation threads, and full chat layouts — all SDK-agnostic and installable via the same CLI.

llms.txt

The registry publishes a llms.txt file at the root of the public registry following the llms.txt convention. It lists every component with its intent, install command, and composition hints — optimised to fit inside an LLM context window.

Paste this URL into any agent context or system prompt:

URL

https://aether-ui.dev/llms.txt

The file is regenerated on every pnpm --filter @aetherstack/scripts build-registry run and committed alongside the per-item JSON files. The CI stale-artefact check will fail a PR if it becomes out of sync.

AI Metadata on Registry Items

Every public registry item ships an ai block alongside the standard registry fields. The schema is:

registry item — ai block

{
  "ai": {
    "intent": "Short machine-readable purpose summary (one sentence)",
    "prompts": [
      "natural-language prompts that should produce this item"
    ],
    "composition": ["other-item", "also-this-one"],
    "slots": ["children", "actions", "footer"]
  }
}

intent — injected into llms.txt and MCP tool responses so agents understand what the component does without reading its source.

prompts — example natural-language inputs that aether-ui generate and the MCP compose_block tool use to match a description to the right component.

composition — sibling components frequently used together. Agents use this to build coherent groups.

slots — named insertion points an LLM can target when generating usage code (e.g. children, actions, header).

Required for all public registry items

The CI validate-registry job rejects any public item that ships without an ai block. Add one before opening a PR that introduces a new component.

MCP Server

@aetherstack/mcp-server is a Model Context Protocol server that exposes the Aether UI registry to LLM agents. Connect it to Cursor, Claude Desktop, or any MCP-compatible tool via the stdio transport.

Connect to Cursor

Add the following entry to your .cursor/mcp.json(or Cursor's global MCP settings):

.cursor/mcp.json

{
  "mcpServers": {
    "aether-ui": {
      "command": "npx",
      "args": ["-y", "@aetherstack/mcp-server"]
    }
  }
}

Connect to Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aether-ui": {
      "command": "npx",
      "args": ["-y", "@aetherstack/mcp-server"]
    }
  }
}

Use a local registry

Override the bundled registry with a local file or a custom URL via environment variables:

.cursor/mcp.json

{
  "mcpServers": {
    "aether-ui": {
      "command": "npx",
      "args": ["-y", "@aetherstack/mcp-server"],
      "env": {
        "AETHER_REGISTRY_FILE": "/path/to/your/registry.json"
      }
    }
  }
}

Available tools

list_componentsList all components, patterns, and blocks in the registry.

param	type	description
type	"all" \| "primitives" \| "patterns" \| "blocks"	Filter by category (default: all)
query	string?	Optional keyword filter on name, title, or intent

get_componentGet full details about a specific component.

param	type	description
name	string	Registry name, e.g. "button" or "dashboard-shell"

install_componentGet the install command for one or more components.

param	type	description
names	string[]	One or more registry names to install

compose_blockGiven a natural-language UI goal, suggest which components to install and how to compose them.

param	type	description
description	string	e.g. "a SaaS dashboard with a sidebar and KPI cards"

Prompt-Driven CLI

aether-ui generate resolves a natural-language description into a sequence of add calls and writes a starter file into your project. No LLM or API key required — resolution is keyword-based and fully deterministic.

terminal

# Scaffold a SaaS dashboard
aether-ui generate "build me a SaaS dashboard"

# Scaffold a login page
aether-ui generate "login page"

# Scaffold a settings form
aether-ui generate "settings page"

# Scaffold a full-page chat interface
aether-ui generate "make me a chat interface"

# Scaffold an AI assistant panel
aether-ui generate "add an AI assistant panel"

# Scaffold an agent task view
aether-ui generate "agent task view"

# Preview without writing files
aether-ui generate "data table with users" --dry-run

The command fetches the registry, resolves matching components, installs each one via the standard add flow, and writes a starter page.tsx file that imports and composes them.

Canonical recipes

The following prompts resolve deterministically to a complete set of components:

Prompt	Components installed
build me a SaaS dashboard	dashboard-shell, metric-card, table, table-toolbar, page-header, empty-state, loading-state, error-state, nav
make me a chat interface	ai-chat-layout, ai-chat-sidebar, ai-conversation-thread, ai-prompt-input, ai-streaming-text, ai-thinking-indicator, ai-conversation-starter
add an AI assistant panel	ai-assistant-panel, ai-conversation-thread, ai-prompt-input
agent task view	ai-agent-workspace, ai-tool-call-sequence, ai-tool-call-card, ai-response-card
prompt builder	ai-prompt-builder, ai-prompt-library, ai-model-selector
login page	login-block
sign up page	signup-block
settings page	section-header, form-field, input, textarea, switch, button
data table	table-toolbar, table, badge, button, empty-state, loading-state
marketing landing page	marketing-navbar, landing-hero, features-section, testimonials-section, pricing-section, cta-section, footer-section

Using Aether UI in Agent Prompts

When writing a system prompt for an agent that generates Aether UI code, include the following snippet to give it the context it needs:

system prompt snippet

You are building a product with Aether UI, a premium open-code design system for React and Next.js.

Registry: https://registry.aether-ui.dev
llms.txt: https://aether-ui.dev/llms.txt
Docs: https://aether-ui.dev

Key facts:
- Install components with: aether-ui add <name>
- 51 UI primitives + 14 AI-native primitives, 29 patterns + 10 AI patterns, 25 blocks + 9 AI blocks
- AI-native components use prefix "ai-" (e.g. ai-chat-layout, ai-prompt-input, ai-streaming-text)
- AI components accept string and AsyncIterable<string>; wire your own AI SDK
- Components live in components/ui/, patterns in components/patterns/, blocks in components/blocks/
- AI components live in components/ui/ai/, components/patterns/ai/, components/blocks/ai/
- Import from @/components/ui/<name>, @/components/patterns/<name>, @/components/blocks/<name>
- Use tailwind classes; design tokens are CSS custom properties (--color-primary, --radius, etc.)
- Always compose from existing Aether UI components rather than building from scratch

Environment Variables

Variable	Default	Description
AETHER_REGISTRY_URL	bundled	Remote registry URL to fetch from (overrides bundled registry.json)
AETHER_REGISTRY_FILE	bundled	Local path to a registry.json file (overrides bundled and URL)