Step-by-Step Study Material

Step 1: Understanding the Core Problem

Why This Exists

Imagine you have a company with a specific visual identity — specific fonts, colors, layouts, and tone. You want AI agents to build pages that look like your company made them, not generic AI output.

Two scenarios exist:

The Key Insight

When an agent works inside a codebase, it learns by seeing real examples alongside the rules. Outside the codebase, it only gets words — and words alone are interpreted differently by every model.

Example of the problem with words alone:

Instruction: "Keep the layout clean"

Model A interprets: Minimal whitespace, dense information
Model B interprets: Large padding, few elements per row
Model C interprets: Single column, no sidebars

All three followed the rule. None produced the same result.

---

Step 2: The Solution — A Three-Part System

Vercel solved this with three interconnected layers. Think of them as three different jobs:

┌─────────────────────────────────────────────────────┐
│  Layer 1: design.md        → Teaches JUDGMENT        │
│  Layer 2: Public Stylesheet → Enforces MECHANICS     │
│  Layer 3: Evaluation Loop  → Measures IMPROVEMENT   │
└─────────────────────────────────────────────────────┘

Layer 1: design.md — The Judgment File

This is a single public file any agent can load from a URL. It teaches agents:

• How to frame the reader's job (What did this person come here to do?)
• How to structure evidence (What information matters most?)
• How to choose a composition (How should the page be laid out?)
• Brand rules (logo usage, wordmark rules, etc.)
• Anti-patterns to avoid — named patterns the agent should recognize and reject

Why naming anti-patterns matters:

Without a name:  "Don't make it look generic"  ← vague, ignored
With a name:     "Avoid the SaaS Dashboard Pattern: 
                  equal-weight cards, no hierarchy, 
                  no clear primary action"       ← specific, actionable

Giving bad patterns names lets agents recognize and avoid them reliably.

---

Layer 2: Public Stylesheet — The Mechanics Enforcer

The problem it solves:

Agents kept inventing their own typography, spacing, and layout — even when told not to.

The solution:

Take those decisions away from the model entirely by providing a pre-built stylesheet with documented class names.

<!-- Agent writes this (using documented class names) -->
<div class="stat-strip">
  <span class="stat-value">$2.4M</span>
  <span class="stat-label">Annual Savings</span>
</div>

<!-- Browser loads the stylesheet from a public URL -->
<!-- Agent never reads the CSS — it just uses the class names -->

Why this is clever:

• The agent only needs to know class names, not CSS rules
• The stylesheet loads in the browser — it never enters the model's context window
• This saves context space for more design guidance
• Visual consistency is guaranteed, not hoped for

---

Layer 3: Evaluation Loop — The Improvement Engine

This is how you know whether your guidance is actually working.

The basic cycle:

Generate page → Review output → Encode correction → Rerun → Measure change
     ↑                                                              │
     └──────────────────────────────────────────────────────────────┘

How Vercel structured their evals:

They wrote 7 fixed scenarios based on real use cases:

1. Usage and performance report
2. Renewal proposal
3. Benchmark report
4. Interactive planning page
5. Build-versus-buy brief
6. Security governance brief
7. Presentation deck

Each scenario has:

• A frozen prompt (never changes)
• Mock inputs (same fake data every time)
• Fixed render settings (same viewport)

Only design.md changes between runs. This means any difference in output is caused only by the guidance.

---

Step 3: How Corrections Become Rules

This is the most important operational concept. Every rule earns its place through evidence.

The Correction Routing System

When a reviewer finds a problem, the fix goes to the narrowest place that can enforce it:

Type of Problem          →  Where the Fix Goes
─────────────────────────────────────────────────────
Judgment / composition   →  design.md (prose rules)
Reusable visual pattern  →  Stylesheet (CSS class)
Mechanical / checkable   →  Deterministic code check
Agent behavior issue     →  The agent's configuration
Model-specific failure   →  Wait; don't generalize yet

Real Example: The Table Width Problem

What happened:

A commercial terms table came back squeezed to the same width as the prose, even though the page had room for the table to be twice as wide.

What they did:

1. Checked previous outputs — found the same failure everywhere
2. Added a rule to design.md: "Evidence tables should use the full width available"
3. Added a deterministic code check: automatically catches this layout failure in future runs

Result: Later runs produced correct full-width tables consistently.

Key principle:

❌ Don't fix the generated page by hand
✅ Fix the guidance so the next first attempt is better

---

Step 4: Measuring Whether It Works

After 200+ runs, Vercel ran a controlled test:

Important Caveats to Understand

This result comes with honest limitations — understanding them makes you a better practitioner:

1. Checks only catch known failures — you can't measure what you haven't named yet
2. Six pages is a tiny sample — not statistically conclusive
3. Every page still had at least one blocking failure — the system improves, it doesn't perfect

The real value: Once you name a failure and encode it, that failure tends to stay gone.

---

Step 5: Keeping the System Current

A guidance file that never updates becomes stale. Here's how to maintain it:

Real usage → Collect feedback → Group repeated complaints → 
Propose changes → Human review → Route fix to right layer → 
Measure whether complaint frequency drops

Signal sources:

• Slack threads with the design agent
• GitHub pull request comments
• Figma comments
• New page type requests → become new eval scenarios

The health metric:

After encoding a fix, count how often that complaint appears in similar work over time. If the count drops → fix worked. If it doesn't drop → something is wrong with the fix.

---

Step 6: Build Your Own — Practical Application

Here is the process condensed into actionable steps:

Step 6.1 — Pick One Repeated Artifact

Choose something with a real reader and real inputs. Write a short rubric before generating anything:

• Did the supplied facts survive?
• Is the reader's decision clear?
• Was the correction you keep making by hand resolved?

Step 6.2 — Save the Baseline First

Generate once without any new guidance. Save everything:

• Prompt
• Inputs
• Model configuration
• Screenshot

You cannot measure improvement without a before.

Step 6.3 — Rewrite Your Last 10 Corrections as Observable Rules

❌ Vague:      "Make the table feel less cramped"
✅ Observable: "Let evidence tables use the full available width"

Only observable rules can be checked. Structure your file with sections:

• Scope
• Reader and task
• Observable decisions
• Available primitives

Step 6.4 — Constrain Repeatable Mechanics

If agents keep inventing their own spacing or typography, publish a stylesheet. Put judgment in prose, put mechanics in CSS.

Step 6.5 — Run One Matched Comparison

Generate the page again with identical inputs but with your file loaded. Score both against your rubric without knowing which is which (blind review).

Step 6.6 — Encode the Correction

Ask these questions about every correction:

1. What did the user have to repeat or steer manually?
2. Is a rule missing or unclear?
3. Can the stylesheet express this correction?
4. Is the failure mechanical enough to check in code?
5. Does this correction generalize beyond this one output?

Update the guidance. Run the comparison again. Measure whether first attempts improved.

---

Summary: The Mental Model

PROBLEM:  Words alone are interpreted differently by every model
SOLUTION: Words + Constrained Mechanics + Measured Feedback

design.md        = Teaches WHY and WHAT (judgment)
Stylesheet       = Enforces HOW (mechanics, no invention allowed)
Eval Loop        = Proves WHETHER it worked (evidence-based improvement)

Core principle:  Name failures → Encode fixes → Measure recurrence
                 Fix the guidance, not the output

The system works because it treats AI design guidance the same way good software treats bugs: reproduce it, name it, fix it at the source, verify the fix holds.