Skip to content
Airframe

AI and Human Engineering

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”

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”

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”

For AI

Section titled “For AI”
  • Follow the 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”
  • 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”

AI generates (minimal classes; cards already stack):

<div class="af-card">
  <h2 class="af-card__title">
    Dashboard
  </h2>
  <div class="af-card__body">
    <p>
      Welcome back!
    </p>
    <div class="af-inline af-gap-sm">
      <button type="button" class="af-btn">
        Get Started
      </button>
      <button type="button" class="af-btn af-is-outline">
        Learn More
      </button>
    </div>
  </div>
</div>

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”

Utility-first markup is easy for models to spit out and hard for people to own:

<!-- Hard to read -->
<div class="flex flex-col gap-4 p-6 bg-white rounded-lg border border-gray-200 shadow-sm">
  <h2 class="text-xl font-semibold mb-2">
    Title
  </h2>
  <p class="text-gray-600">
    Content
  </p>
</div>

Airframe stays readable:

<!-- Easy to read -->
<div class="af-card">
  <h2 class="af-card__title">
    Title
  </h2>
  <div class="af-card__body">
    <p>
      Content
    </p>
  </div>
</div>

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”