Field note

What spec-driven development means for a frontend

Spec-driven development means the written spec is the source of truth, and code, tests and coding agents all trace back to it. For a frontend, that spec has to cover what most backend specs skip: every state a screen can be in, what each user can perceive and operate, and what the browser stores and sends.

Tacet Works · 22 November 2026

The short answer

Spec-driven development (SDD) is a way of building software where a written, versioned spec comes first and everything else follows from it. For a frontend, the spec describes behaviour from the user’s side of the screen: states, interactions, accessibility, performance and data handling. Each rule in it is written so a test can check it.

The idea is not new. Requirements documents, behaviour-driven development and contract-first APIs all share it. What changed is that coding agents made it necessary. An agent given a vague ticket produces plausible code. An agent given a precise spec produces code that can be checked. The spec is what turns agent speed into something you can trust.

Most writing about SDD comes from tool makers and focuses on the backend or on the workflow commands. This note is about what changes when the thing being specified is an interface people use.

Why frontends are harder to specify

A frontend has more states than it has screens. A single checkout page can be loading, empty, partially filled, invalid, submitting, failed, timed out or offline, on a phone or a desktop, with a mouse, a keyboard or a screen reader. Most of those states are never designed. They are discovered in production.

Backend specs usually describe inputs and outputs. Frontend specs have to describe perception: what the user sees, when, in what order, and what they can do next. That is why “the form validates input” is not a frontend requirement. It does not say what the user sees, where focus goes, what happens to their entries, or how a screen reader announces the error.

Frontends also run on the user’s device, which adds two concerns a backend spec rarely carries:

  • Privacy. The browser can store data and send requests to third parties. A spec that does not list every storage key and every outgoing request leaves room for leaks.
  • Performance. The user’s phone, not a server you control, does the work. A spec without a performance budget cannot be held to one.

What goes in a frontend spec

A frontend spec lists the feature’s user stories, every state of the interface, acceptance criteria for each state, the data collected and why, and the rules inherited from the product’s constitution. We write it in four connected documents, described in full in the spec pack.

Section What it answers Why a frontend needs it
User stories Who is this for and what do they want to do? Keeps scope tied to people, not components
States What can the screen be showing at any moment? Most defects live in undesigned states
Acceptance criteria How do we know each state behaves correctly? Turns intent into tests
Data map What is collected, why, and where does it go? Makes privacy reviewable
Inherited rules Which accessibility, performance and security rules apply? Stops one feature lowering the bar
Out of scope What will we not build? Stops scope from growing unpriced

The states list is the section we write first. Once every state is named, the acceptance criteria almost write themselves, and gaps show up before any design or code exists.

Criteria from the user’s side of the screen

Frontend acceptance criteria describe what a person observes and can do, never which function runs. We write them in Given/When/Then, one behaviour each, so every criterion becomes one clear test. Accessibility, privacy and performance rules are written as criteria too, so they are tested like any other behaviour.

Feature: Spending limit before first payment

  Scenario: New member opens checkout
    Given a verified member with no spending limit set
    When they open checkout for the first time
    Then the spending-limit step is shown before payment methods
    And they can choose a daily, weekly or monthly limit
    And skipping requires an explicit "no limit" choice, which is logged

  Scenario: Keyboard user
    Given a member using only a keyboard
    When they reach the spending-limit step
    Then every option can be chosen with arrow keys and confirmed with Enter
    And focus is visible on the selected option

Criteria written this way have a useful side effect: a product owner can read them. The spec becomes a document both sides of the engagement can check, not an engineering artefact only engineers understand. We cover the details in acceptance criteria for frontends.

From criteria to tests, gates and reports

A frontend spec is only worth writing if it is enforced. In our process, each criterion becomes an automated test that cites its ID. The tests run on every change, alongside security, privacy, accessibility and performance gates. At release, a trace report lists every criterion with its test and result.

The chain has three links:

  1. Tests. End-to-end behaviour runs in Playwright against a real browser. Logic runs in Vitest. Accessibility checks run with axe inside the browser tests.
  2. Gates. No change merges until every relevant test passes, along with checks on dependencies, secrets, headers, storage, third-party requests and the performance budget. See quality gates.
  3. Reports. The trace report joins the spec’s criteria and the test results, so anyone can see what was delivered without reading code.

Break any link and the spec decays into documentation nobody trusts. Keep all three and the spec stays true for as long as the product runs.

Where coding agents fit

Coding agents fit in the build step, working from one task at a time. Each task links to the criteria it must satisfy and the plan it must follow. The agent proposes a change, the gates check it, and a senior engineer reviews it against the same criteria. The spec constrains the agent, and the review catches what tests cannot.

This is the practical case for SDD in 2026. Agents can write a lot of frontend code quickly. Without a spec, nobody can say whether that code is right, only whether it looks right. With one, every agent-written change has a definition of done that was agreed before it was written. More on this in agent-assisted delivery.

What changes for the people involved

For a founder, SDD changes what you buy. You see the scope as plain sentences before you commit to a build, you can price changes against a known baseline, and you can check each milestone against a report rather than a demo. For engineers, it changes when the hard questions get asked: before the code, not during review.

Without a spec With a spec
Scope lives in tickets and chat threads Scope lives in one versioned document
States are discovered in production States are listed before design
“Done” is a judgement call “Done” is every criterion passing
Privacy is a policy page Privacy is a test that fails the build
Agent output is hard to verify Agent output is checked against agreed criteria
Change requests are argued Change requests are written as deltas and priced

Common objections

The objections we hear most are about speed, flexibility and design. Each has a fair point behind it, and each is answered by keeping the spec small and changeable rather than by skipping it.

“Writing specs slows us down.” It moves time earlier. The questions a spec asks, such as what happens on error or what the empty state shows, get asked anyway. Without a spec they are asked during code review or by users. A spec asks them when changing the answer costs a sentence, not a refactor.

“Our product changes too fast for a spec.” A spec that cannot change is a problem. A spec that changes through small, reviewed deltas is the opposite. Fast-moving products benefit most, because every change is written against a known baseline and priced before work starts.

“Design already defines the frontend.” Design defines how screens look in the states someone drew. A spec defines how the interface behaves in every state, including the ones nobody drew, and what it stores, sends and announces. The two work together: designs show the intended experience, and criteria make it testable.

“Agents can write the spec too.” Agents can help draft one. They cannot decide what the product should do, which trade-offs are acceptable, or what the client agreed to. Those decisions are the spec’s real content, and they stay with people.

What it costs

SDD moves effort earlier. Writing a frontend spec for a feature takes real time, and the first spec on a product takes the longest because the constitution is written with it. In return, less time goes to rework, late surprises and arguments about whether something was in scope. We think that trade is worth making on any product that must hold up to scrutiny.

It is not the right fit for everything. A throwaway prototype does not need a constitution. A one-day experiment does not need a trace report. We use SDD where the frontend has to be correct, private and maintainable, which is most products that real users depend on.

How to start

Start small. Pick one feature, list every state it can be in, and write one Given/When/Then criterion per state. Then name a test after each criterion. That alone shows most teams where their gaps are. Our feature spec template has the sections in the order we fill them, and a Spec Sprint does the whole exercise with you in one to two weeks.

Start with a Spec Sprint

One to two weeks to a versioned spec you own, whoever builds it.

Start a Spec Sprint