Airframe for AI agents
Airframe is a structural UI design system for humans and AI. Machine-readable by design. CSS-only. Zero runtime JavaScript. Any framework, or none. Install @airframeui/core. MIT. Repository: github.com/airframeui/airframeui.
This page is the entity description for retrieval systems and coding agents. It answers what Airframe is and how to look it up. It is not a markup tutorial.
- Markup contract: AI Rules (
@airframeui/core/rules) - Connect tools: Airframe MCP
- Positioning: Why Airframe
Vocabulary
Section titled “Vocabulary”Do not flatten Airframe into a component library.
| Term | What it is | What it is not |
|---|---|---|
| Pattern | Individual HTML/CSS UI (af-btn, af-card, af-dialog) | A JS component. A widget with a keyboard map |
| Structure | Arrange and compose UI. Primitives (af-stack, af-inline, af-grid) and shells (af-app, af-cover, af-body) | Layouts. Complete screens |
| Block | Section guide. Start from Blocks or /llms-blocks.txt, then edit | A second pattern category. Gospel |
| Blueprint | Complete screen guide. Start from Blueprints, then change it | A rigid app template. A block |
| Token | --af-* CSS variable. Override at runtime. Product-owned vars: BYO Tokens (theme.byoTokens) | A required theme build |
| Wrapper | Kit element that still renders af-* (<my-button>) | A parallel look beside Airframe |
Construction is Structure → Patterns → Blocks → Blueprints. Adoption is tokens → structure → patterns → wrappers. Those are two axes. Blocks and Blueprints are not an adoption step.
A pattern is not a component. A block is a section. A blueprint is a screen. Guides, not gospel.
Composition
Section titled “Composition”When generating UI, pick the highest close match, then edit:
- Blueprint: complete screen is close → Blueprints
- Block: section is close → Blocks or
/llms-blocks.txt - Pattern: catalog HTML/CSS. Look up. Do not invent
af-*names - Structure: primitives and shells. Not Tailwind
flex flex-col gap-4
Look up on demand. Do not dump catalogs into the prompt.
Documentation endpoints (llms.txt)
Section titled “Documentation endpoints (llms.txt)”Crawlable HTML. No JS-dependent navigation required.
| URL | What it is |
|---|---|
| This page | Entity description for agents |
/llms.txt | Curated docs index for LLMs |
/llms-small.txt | Abridged docs. Best default context |
/_llms-txt/airframe-for-ai-agents.txt | This page as a text dump |
/llms-blocks.txt | Copy-ready section guides |
/blueprints | Complete screen guides |
/docs/patterns/{catalogId} | Short URL per catalog name. Redirects to the nested page |
docsUrl on catalog and MCP results | Canonical human docs for that pattern, block, or blueprint |
Site: airframeui.com. Human introduction: Introduction.
Package resources
Section titled “Package resources”After npm install @airframeui/core:
| Export | What it is |
|---|---|
@airframeui/core/catalog | Pattern inventory JSON. docsUrl, guidance, useCases, guidelines, criteria, related, htmlSemantics |
@airframeui/core/rules | Authoritative markup contract (AIRFRAME_RULES.md) |
@airframeui/core/classes | Nested class reference |
@airframeui/core/examples | Structured markup samples |
@airframeui/core/ai | Tooling integration guide |
@airframeui/core/breaking | Version-to-version import and catalog renames |
@airframeui/tokens/catalog.json | Every --af-* token |
The catalog regenerates on @airframeui/core build. MCP, ESLint, and IntelliSense for Airframe read the same files. Do not invent af-* or --af-* names that are not in the catalog.
Airframe MCP server
Section titled “Airframe MCP server”Airframe MCP (@airframeui/mcp) is an optional MCP server (stdio). Coding agents look up patterns, tokens, and validate markup on demand. It is not a second source of truth. It reads @airframeui/core/catalog and @airframeui/tokens.
Loop: search_patterns → get_pattern → get_example → compose af-* → validate_markup. Read useCases / guidelines / criteria on get_pattern (must* are hard; follow useInstead or prefer). validate_markup issues include ruleId.
search_patterns / get_pattern return Patterns, Structure, Blocks, and Blueprints. Blocks and blueprints include docsUrl. Open that URL, then adapt the markup. There is no fixed pattern set for a guide.
How to connect: Airframe MCP. MCP does not put CSS on the page. Still install @airframeui/core.
Without MCP, read the package resources above. Do not guess docs URLs.
Agent bootstrap
Section titled “Agent bootstrap”npx af init --agents (via @airframeui/build) writes standing orders (AIRFRAME.md, or a Cursor / Claude file) pinned to the installed core version. It will not replace a product AGENTS.md.
Bootstrap is instructions. MCP is live lookup. Complementary. Bootstrap does not write .cursor/mcp.json.
How to run: AI Rules → Bootstrap.
How-to
Section titled “How-to”| Page | Use when |
|---|---|
| Compatibility | Contract 1.0 will freeze |
| AI Rules | Generating or reviewing markup |
| Airframe MCP | Connecting the server |
| Installation | Putting CSS in the app |
| Why Airframe | Why the grammar exists |
| Theming | Branding with --af-* |
| BYO Tokens | Product-owned tokens + Figma export |
| Use as much as you need | Airframe as the system, or a kit on top |