# Airframe

> Airframe is a CSS-first structural UI system: layout primitives (`af-stack`, `af-inline`, `af-grid`), a full token layer (`--af-*`), and production-ready accessible CSS patterns. One CSS import, zero runtime JavaScript, works with any framework. Use it as the design system, or wrap a kit around it. As much or as little as you need.

When generating or reviewing Airframe markup:
- Prefer semantic HTML and structural primitives over utility soup
- All classes start with `af-`; modifiers use `af-is-*`; BEM parts use `af-card__title`
- Theme via CSS variables (`--af-base-primary`, etc.); no rebuild required for day-to-day branding. Force light or dark with `data-theme` (`light` / `dark` only). High contrast stays on `prefers-contrast`.
- Use Airframe as the design system (`af-*` in templates), or wrap a kit. Wrappers (e.g. `<UiButton>`) render `af-*`. Do not ship a parallel palette or layout grammar. Alias existing `--color-*` into `--af-*` once.
- Use as much or as little as you need: tokens only, structure only, pattern classes, or kit wrappers. That is adoption depth, not construction.
- Construction model: Structure → Patterns → Blocks → Blueprints. Structure arranges. Patterns are pieces. Blocks are sections. Blueprints are complete interfaces. Structure has primitives (how children relate) and shells (how the viewport is divided). A block is a section guide; a blueprint is a screen guide. Start from https://airframeui.com/blocks or https://airframeui.com/blueprints when one is close, then edit. They are not gospel. Copy-ready starting points: https://airframeui.com/llms-blocks.txt
- Optional: [Airframe → Figma](https://airframeui.com/figma) for theming, Theme Studio, and `af theme export` — most projects only need CSS variable overrides
- Prefer `@airframeui/mcp` for pattern/token lookups (same version as core). Default snippet: `npx -y @airframeui/mcp@0.5.0` in `.cursor/mcp.json` or `.mcp.json`. MCP is optional — fallback: catalog → examples → dist/patterns/<id>.css, plus `@airframeui/core/breaking`. Loop: `search_patterns` → `get_pattern` → `get_example` → `validate_markup`. Do not dump catalogs. Pattern pages: https://airframeui.com/docs/patterns/{catalogId}. https://airframeui.com/docs/mcp
- Bootstrap agents with `npx af init --agents` (writes AIRFRAME.md; will not replace a product AGENTS.md)
- Use the minimum number of classes — components have sensible defaults
- Follow accessibility contracts (native controls, labels, focus-visible)

Package resources (after `npm install @airframeui/core`):
- `@airframeui/core/rules` — authoritative AIRFRAME_RULES.md
- `@airframeui/core/catalog` — pattern catalog JSON (regenerated on core build from all pattern CSS)
- `@airframeui/core/classes` — class reference JSON
- `@airframeui/core/examples` — structured code examples
- `@airframeui/core/breaking` — version-to-version import/catalog renames
- `@airframeui/core/ai` — AI tooling integration guide
- `@airframeui/tokens/catalog.json` — every `--af-*` token with descriptions and default colours per mode

Theme / agent tooling:
- `@airframeui/theme/rules` — theme generation and lint (only when mapping foreign tokens)
- Project bootstrap: `npx af init --agents`
- Airframe → Figma: https://airframeui.com/figma
- Theme Studio: https://airframeui.com/theme-studio

The pattern catalog (`@airframeui/core/catalog`) regenerates on core build from `src/patterns/*.css` plus `catalog.enrichment.json`.

For the shortest useful context, start with **AI Rules** or **Getting Started** below.

## Documentation Sets

- [Abridged documentation](https://airframeui.com/llms-small.txt): a compact version of the documentation for Airframe, with non-essential content removed
- [Complete documentation](https://airframeui.com/llms-full.txt): the full documentation for Airframe
- [Getting Started](https://airframeui.com/_llms-txt/getting-started.txt): Install, usage, tokens, theming, structure, framework setup, and using Airframe as the system or wrapping a kit. Construction is Structure → Patterns → Blocks → Blueprints (blocks and blueprints are optional links). Best first read for coding agents.
- [Why Airframe](https://airframeui.com/_llms-txt/why-airframe.txt): Why a CSS grammar outlives engines. Comparison with Tailwind and Bootstrap, adoption depth, and roadmap.
- [AI Rules](https://airframeui.com/_llms-txt/ai-rules.txt): Authoritative rules for generating Airframe markup, plus the MCP loop.
- [Structure](https://airframeui.com/_llms-txt/structure.txt): Primitives, shells, grid, and responsive suffixes.
- [Patterns](https://airframeui.com/_llms-txt/patterns.txt): UI patterns: buttons, forms, cards, overlays, badges, and more.
- [Accessibility](https://airframeui.com/_llms-txt/accessibility.txt): WCAG guidance, forms, keyboard/focus, contrast, and pattern contracts.

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [@airframeui/core on npm](https://www.npmjs.com/package/@airframeui/core): Install the package to load ./rules, ./catalog, ./classes, ./examples, and ./ai locally in a project
- [@airframeui/tokens on npm](https://www.npmjs.com/package/@airframeui/tokens): Token CSS, JSON, and catalog.json (descriptions and default colours per mode). Core depends on this package.
- [@airframeui/theme on npm](https://www.npmjs.com/package/@airframeui/theme): Token pipeline: read --af-* from CSS (theme.files in airframe.config.js), lint, and export DTCG JSON (af theme export into theme.outputDir, default .airframeui). Figma is the usual destination for that export. Product page: /figma. Foreign-file import (af theme generate) is best-effort and usually incomplete. Most apps override CSS variables. Same version as @airframeui/core. Docs: /docs/advanced/theme
- [@airframeui/mcp on npm](https://www.npmjs.com/package/@airframeui/mcp): MCP server: install -D @airframeui/mcp (same version as core) or npx. On-demand pattern search, markup validation, token lookup, and theme mapping. Docs: /docs/mcp
- [@airframeui/build on npm](https://www.npmjs.com/package/@airframeui/build): Dev dependency for custom breakpoint CSS (media queries cannot read CSS variables), @af bp() / @af-apply, af theme, and af init --agents. PostCSS config is a single plugin (@airframeui/build/postcss); it inlines @import so you do not install postcss-import. Default responsive utilities already ship in @airframeui/core. Docs: /docs/advanced/build
- [@airframeui/eslint-plugin on npm](https://www.npmjs.com/package/@airframeui/eslint-plugin): Dev dependency. Flat config: import airframe from @airframeui/eslint-plugin and use airframe.configs["flat/recommended"] for JSX, plus airframe.configs["flat/angular"] for Angular 20+ templates with @angular-eslint/template-parser. Same version as @airframeui/core. Catalog snapshot from classes.json and catalog.json; installed core/tokens catalogs win when present. Docs: /docs/eslint-plugin
- [Structure (classes)](https://airframeui.com/structure): Visual index of structure primitives and shells: stack, inline, grid, app, cover, body. Live previews. Docs pages linked from each card.
- [Blocks (page sections)](https://airframeui.com/llms-blocks.txt): Section guides made from patterns. Start from hero, pricing, toolbar, FAQ, and more, then edit the markup and layout. A block is a section; a blueprint is a screen. Neither is gospel. Gallery: /blocks.
- [Blueprints (complete screens)](https://airframeui.com/blueprints): Complete screen guides built from patterns and blocks. Landing, auth, dashboard, inbox, board, chat and settings. Start from one, then change it. Not a rigid app template.
- [Airframe → Figma](https://airframeui.com/figma): Shared brand colours between the live app and Figma. Prefer the Airframe plugin (af figma export → Apply) or Theme Studio / af theme export four-file pack. Git stays the source of truth.
- [Theme Studio](https://airframeui.com/theme-studio): Playground for Airframe → Figma: pick colours, preview patterns, copy CSS into the project, download a Figma pack. Product page: /figma. CLI: /docs/advanced/theme.
- [Airframe on GitHub](https://github.com/airframeui/airframeui): Source monorepo. Issues and pull requests welcome. Security reports: team@airframeui.com (see SECURITY.md).