Readable DOM

Markup that reads like English. Classes that tell a story. Code that both humans and AI can understand and maintain.

The Problem: Utility Soup

Traditional utility-first frameworks create markup that's hard to read, maintain, and understand. Every element becomes a wall of classes.

Utility Soup (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 text-gray-900">
    Payment Settings
  </h2>
  <p class="text-gray-600 mb-4">
    Manage your payment methods.
  </p>
  <div class="flex flex-wrap items-center gap-2">
    <button class="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700">
      Save
    </button>
    <button class="px-4 py-2 bg-gray-200 text-gray-800 rounded hover:bg-gray-300">
      Cancel
    </button>
  </div>
</div>

Readable DOM (Clear Intent)

<div class="af-card af-stack af-gap-lg">
  <h2 class="af-card__title">
    Payment Settings
  </h2>
  <p class="af-card__body">
    Manage your payment methods.
  </p>
  <div class="af-inline-md">
    <button class="af-btn">
      Save
    </button>
    <button class="af-btn af-is-secondary">
      Cancel
    </button>
  </div>
</div>

The Solution: Readable Patterns

Airframe uses noun-based components, verb/adjective helpers, and layout recipes that read like English.

Noun-Based Components

Components are things: af-card, af-btn, af-alert. Clear, semantic, predictable. 

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

Layout Recipes

Layouts are actions: af-stack (vertical), af-inline (horizontal), af-grid (grid). 

<div class="af-stack af-gap-lg">
  <div>
    Item 1
  </div>
  <div>
    Item 2
  </div>
</div>

Clear Modifiers

Variants use af-is-*: af-is-secondary, af-is-outline. 

<button class="af-btn af-is-outline">
  Save
</button>
<a href="/home" class="af-btn af-is-secondary">
  Secondary
</a>

Responsive Suffixes

Breakpoints use @xs, @sm, @md, @lg, @xl, @2xl suffixes. Readable and consistent. 

<div class="af-col-span-8@lg">
  Main content
</div>

Real-World Examples

See how readable DOM makes complex layouts easy to understand and maintain.

Dashboard Layout

A responsive dashboard with sidebar and main content

Readable DOM

<div class="af-container">
  <div class="af-grid">
    <aside class="af-col-span-3@lg">
      <nav class="af-stack af-gap-sm">
        <a href="#">
          Dashboard
        </a>
        <a href="#">
          Settings
        </a>
      </nav>
    </aside>
    <main class="af-col-span-9@lg">
      <div class="af-stack af-gap-lg">
        <h1>
          Welcome
        </h1>
        <p>
          Content here
        </p>
      </div>
    </main>
  </div>
</div>

Live Preview

Welcome

Content here

Responsive Card Grid

Cards that adapt from 1 column to 3 columns

Readable DOM

<div class="af-grid-1 af-grid-2@md af-grid-3@lg af-gap-lg">
  <div class="af-card">
    <h3 class="af-card__title">
      Card 1
    </h3>
    <p class="af-card__body">
      Content
    </p>
  </div>
  <div class="af-card">
    <h3 class="af-card__title">
      Card 2
    </h3>
    <p class="af-card__body">
      Content
    </p>
  </div>
  <div class="af-card">
    <h3 class="af-card__title">
      Card 3
    </h3>
    <p class="af-card__body">
      Content
    </p>
  </div>
</div>

Live Preview

Card 1

Content

Card 2

Content

Card 3

Content

Form Layout

Clean, accessible form patterns

Readable DOM

<form class="af-stack af-gap-lg">
  <div class="af-field">
    <label class="af-field__label">
      Email
    </label>
    <input type="email" class="af-input">
    <p class="af-field__help">
      We'll never share your email.
    </p>
  </div>
  <div class="af-inline-md">
    <button type="submit" class="af-btn">
      Submit
    </button>
    <button type="button" class="af-btn">
      Cancel
    </button>
  </div>
</form>

Live Preview

We'll never share your email.

Why Readable DOM Matters

Readable DOM isn't just nice to have—it's essential for maintainable code in the age of AI-assisted development.

For Humans

Reviews move faster. Onboarding is clearer. Maintenance stays predictable. The DOM reads like intent.

For AI

Predictable patterns. Consistent conventions. Clear intent. AI can generate and maintain code people can trust.

AI and Human Engineering

Readable DOM is the shared contract between AI output and human systems. One markup, two audiences.

Start Building with Readable DOM

Experience the difference. Write markup that reads like English. Build systems that both humans and AI can maintain.

Get Started View Layouts