A SPEC.md is the document that translates an approved mockup into something buildable: routing architecture, a real data model written as actual type definitions, a separate storage schema, explicit business-logic rules, an integrations/stack section, per-screen UX detail, and a running Architecture Decision Record. Write it after the mockup is approved, not before — the spec formalizes what the mockup discovered, it doesn't dictate to it. The three prior documents each answer a different question and the spec answers the last one: the brief says why and for whom, the brandbook says what it looks like, the mockup says how it's assembled and flows, and the spec says how it is actually built. Keep it independently readable — don't restate the brief's business case or the brandbook's palette. And keep an append-only ADR log so that six months later, the answer to "why is it built this way?" is written down instead of lost.
The four-document map
| Document | Question it answers | Never duplicate here |
|---|---|---|
| Brief | Why, for whom, business case, scope | Data models, routing |
| Brandbook | Visual identity | Business logic |
| Mockup | What it looks like assembled, how it flows | Persistence details |
| Spec | How it's built: data, logic, architecture | The business case, the palette |
If the spec restates the brief, it will drift out of sync with the brief; if the brief restates the spec, the same. Link between documents instead of copying. Each one should survive being read alone.
Why after the mockup, and not before
The intuitive order is spec-then-mockup: design the architecture, then draw the screens. Reverse it. A spec written before the mockup encodes assumptions the mockup hasn't tested yet, and the most expensive assumptions are the structural ones. [Verified] In real project history, the structural shape of the data model changed during mockup review — the app turned out to need a shared/household account with multiple members rather than one-user-one-account, and that surfaced only when a human walked through populated screens. Had the spec been written first, it would have specified the wrong model, the mockup would have been built to match the wrong spec, and the correction would have cost far more. Writing the spec after means it records a decision that has already been pressure-tested against real-looking screens.
The rule: the mockup discovers structure; the spec formalizes it.
The sections a good SPEC.md needs
Skeleton first, so you know the shape before the detail:
# SPEC.md — [project name] (v1.0, YYYY-MM-DD)
1. Overview — one paragraph: what this builds, links to brief/brandbook/mockup
2. Routing / navigation architecture
3. Data model — real type definitions (the in-memory / UI shape)
4. Storage schema — how it persists (may differ from the data model)
5. Business logic rules — rules NOT visible on any screen
6. Integrations & stack
7. Per-screen UX detail — states, interactions, data read/written per screen
8. ADR log — numbered, append-only decision record
Now each section.
1. Overview
One paragraph. What the thing is, and links to the other three documents. Do not re-argue the business case — that's the brief's job. This section exists so a new engineer knows in thirty seconds what they're reading and where the other three documents are.
2. Routing / navigation architecture
Name the navigation model and how screens stack. This should map directly onto the approved mockup: the mockup's tabs become the tab navigator, the mockup's overlays become the modal/stack layer. State explicitly which state is global (shared across tabs) versus local to a screen — this is where the mockup's "two tabs both read this" discoveries get written down.
3. Data model (real type definitions, not prose)
Write the model as actual type or interface definitions. Prose descriptions of data ("a listing has a title and some photos") are ambiguous; types are not. For the classifieds portal, after the mockup's shared-account discovery: