AI Rules: Authoritative rules and patterns for generating Airframe markup with AI.
# AI Rules
> Authoritative rules for generating Airframe markup with AI coding agents
The authoritative rules ship with `@airframeui/core` as **`@airframeui/core/rules`** (`AIRFRAME_RULES.md`). This page is the docs summary agents and humans should follow when generating markup. ## For LLMs and coding agents [Section titled “For LLMs and coding agents”](#for-llms-and-coding-agents) Prefer these entry points over scraping the whole site: * [`/llms.txt`](/llms.txt) — curated index of documentation sets and package resources * [`/llms-small.txt`](/llms-small.txt) — abridged docs (best default context) * [`/_llms-txt/ai-rules.txt`](/_llms-txt/ai-rules.txt) — this page + AI engineering notes * [`/_llms-txt/getting-started.txt`](/_llms-txt/getting-started.txt) — install, usage, tokens, layouts After `npm install @airframeui/core`, load in-project resources: ``` // JSON (safe to import in Node / bundlers) import catalog from '@airframeui/core/catalog'; // component metadata import classes from '@airframeui/core/classes'; // class reference import examples from '@airframeui/core/examples'; // code examples // Markdown — resolve the package export and read as text (do not assume a JS default export) // @airframeui/core/rules → AIRFRAME_RULES.md // @airframeui/core/ai → AI_INTEGRATION.md ``` ## Non-negotiable rules [Section titled “Non-negotiable rules”](#non-negotiable-rules) * **Semantic HTML first** — ``, ``, ``, real headings * **Token-first theming** — prefer `--af-color-*` / other `--af-*` tokens; do not invent unknown token names * **Readable DOM** — avoid utility soup; prefer patterns + layout recipes * **`af-` prefix** — only use known Airframe classes (see `@airframeui/core/classes`) * **Minimal classes** — components include sensible defaults; don’t restate them * **Modifiers** — variants/state use `af-is-*` (e.g. `af-btn af-is-primary`, `af-btn af-is-outline`) * **Responsive** — breakpoint suffixes use `@` in HTML: `af-grid-2@md`, `af-stack@lg` * **Framework attrs** — `class` in HTML/Vue/Angular/Astro; `className` in React ## Theme generation for agents [Section titled “Theme generation for agents”](#theme-generation-for-agents) Runtime CSS variable overrides are the default. When mapping an existing design system into Airframe tokens: * **[Theme Studio](/theme-studio)** — upload Tokens Studio / DTCG / CSS / Figma Variables and export `theme.css` * **CLI** — `npx af theme generate --from ./tokens.json -o theme.css` (via `@airframeui/build`) * **MCP** — `@airframeui/mcp` tools: `generate_theme`, `map_tokens`, `lint_theme`, `validate_theme` * **Rules** — `@airframeui/theme/rules` and `@airframeui/theme/mapping` after `npm install @airframeui/theme` See [Theming](/docs/theming) and [Build Tool](/docs/advanced/build#af-theme-theme-generation). ## AI predictable patterns [Section titled “AI predictable patterns”](#ai-predictable-patterns) Canonical patterns (aligned with `AIRFRAME_RULES.md`): ### Card (minimal — default stacking) [Section titled “Card (minimal — default stacking)”](#card-minimal--default-stacking) Cards already `display: flex; flex-direction: column` with a default gap (`--af-space-4`). Do not add redundant stack/gap. ``` ``` ### Simple grid (equal columns) [Section titled “Simple grid (equal columns)”](#simple-grid-equal-columns) `af-grid-*` includes grid display. Default gap is `--af-space-3` (same as `af-gap-md`). ``` ``` ### 12-column grid (asymmetric layouts) [Section titled “12-column grid (asymmetric layouts)”](#12-column-grid-asymmetric-layouts) ``` ``` **Note:** `af-grid:has(> [class*='af-col-span'])` switches to 12 columns. Default gap is `--af-space-3` (`af-gap-md`). Override with `af-gap-sm` / `af-gap-lg` when needed. ### Stack + inline (header pattern) [Section titled “Stack + inline (header pattern)”](#stack--inline-header-pattern) ``` ``` ### Semantic typography first [Section titled “Semantic typography first”](#semantic-typography-first) ``` Title Body text
Visually H1, semantically H2 Caption
Title ``` ## Related tooling [Section titled “Related tooling”](#related-tooling) * [VS Code Extension](/docs/vscode-extension) — IntelliSense for tokens and classes * [ESLint plugin](/docs/eslint-plugin) — catch Tailwind/Bootstrap leftovers and prefer layout recipes * [AI and Human Engineering](/docs/ai-and-human-engineering) — why the structural contract exists
# AI and Human Engineering
> How Airframe provides a structural language for AI-generated and human-maintained UI
**Airframe** is a structural UI system for humans and AI. Think of it like an aircraft airframe: it defines the shape and strength of the system. You bring the engine, whether that is React, Vue, Angular, AI-generated code, or whatever comes next. Building UI is easy. Keeping intent intact is hard. That is the gap between AI-generated code and human-maintained systems, and between prototype and production. **Frameworks are engines. Airframe is the structure.** ## The problem [Section titled “The problem”](#the-problem) AI can write UI quickly, but only if it has: * Predictable patterns * Clear constraints * Structural rules to follow Humans keep that code alive, and they need: * Readable markup * Consistent meaning * Room to refactor without breaking things ## The solution: a structural contract [Section titled “The solution: a structural contract”](#the-solution-a-structural-contract) Airframe is that shared contract. It gives AI and humans the same language for layout and components. 1. **Structural primitives.** `af-stack`, `af-inline`, and `af-grid` describe layout intent, not one-off styling tricks. 2. **Readable output.** Semantic markup people can review and change without decoding a wall of utilities. 3. **Safe constraints.** Tokens and cascade layers keep theming and overrides predictable. 4. **Clear rules.** `@airframeui/core` ships the contract in `AIRFRAME_RULES.md`. Frameworks can change. The structure stays. ## How it works [Section titled “How it works”](#how-it-works) ### For AI [Section titled “For AI”](#for-ai) * Follow the [AI Rules](/docs/ai-rules) (`@airframeui/core/rules`) * Prefer semantic HTML with `af-*` classes * Use layout primitives (`af-stack`, `af-inline`, `af-grid`) and patterns (`af-card`, `af-btn`) * Theme with CSS variables (`--af-*`). Do not invent unknown token names. ### For humans [Section titled “For humans”](#for-humans) * Review a DOM you can actually read * Override tokens in CSS (no build step for simple themes) * Extend with cascade layers * Use the same patterns the AI was given ## Real-world example [Section titled “Real-world example”](#real-world-example) **AI generates** (minimal classes; cards already stack): ``` Dashboard Welcome back!
Get Started Learn More
``` **Humans review:** * Clear component structure (`af-card`) * Layout intent where it matters (`af-inline` for actions) * Predictable spacing (`af-gap-sm`) * Named parts (`af-card__title`, `af-card__body`) Both sides get something useful. AI has rules it can follow. Humans get markup that still makes sense next month. The same contract holds across frameworks. ## Why this matters [Section titled “Why this matters”](#why-this-matters) Utility-first markup is easy for models to spit out and hard for people to own: ``` ``` Airframe stays readable: ``` ``` AI can generate either. Humans can maintain the second. Airframe is the structural language that makes AI output something people can keep shipping. ## Next steps [Section titled “Next steps”](#next-steps) * [AI Rules](/docs/ai-rules): generation rules, patterns, theme and MCP entry points * [Patterns](/docs/patterns/button): structural UI patterns * [Tokens](/docs/tokens) and [Theming](/docs/theming): design language and Theme Studio * [VS Code Extension](/docs/vscode-extension): IntelliSense for `af-*` and `--af-*` while you edit