---
title: "Typed spec, not free HTML"
url: /patterns/typed-spec
description: "Restructure the task so the error cannot happen."
---

## §0 · statement

# Typed spec, not free HTML

Restructure the task so the error cannot happen.

## §1 · why

### Why it works

An agent writing free HTML can invent a colour, a spacing value or a component. An agent filling a typed spec can only choose from what the type allows. A script composes the page from vetted parts and returns a verdict. The agent selects and fills; scripts build and judge.

## §2 · example

### Copy this

```ts
type PageSpec = {
  template: "account-overview" | "payment-form";
  sections: Array<
    | { part: "BalanceCard"; accountId: string }
    | { part: "TransactionList"; accountId: string; limit: 10 | 25 }
    | { part: "Alert"; status: "danger" | "warning" | "success"; textId: string }
  >;
};
// The agent returns a PageSpec. compose(spec) builds the page and returns a verdict.
```

## §3 · breaks

### Where it breaks

A new screen needs a new part. Without a proposal path the agent is stuck or goes back to free HTML.

## §4 · cases

Used in: [Case 5](/cases/agent-first-foundation).
