What a clean handoff spec actually contains

Most of the white-label work that goes wrong does not go wrong during the build. It goes wrong in the forty minutes it took to write the brief, and nobody finds out for three weeks.

We have taken over enough rescue projects to see the pattern. The agency sent designs, the developer said yes, and both sides discovered in week four that they had different pictures of what was being built. Neither party was careless. The brief simply did not contain the four or five things that determine whether a build lands.

Here is what we ask for, why each item exists, and what happens when it is missing.

The short version:

• A complete brief fits on one page and takes about an hour to write
• The content model predicts the schedule better than the designs do
• Unscoped integrations are where fixed-price estimates die
• Name the decision-maker before the build, not in week seven

Website design handoff: what to include beyond the artboards#

Every brief includes designs. Very few include the states between them.

A hero at 1440 tells us nothing about 1100, which is where most laptop traffic actually sits. A three-column card grid is obvious at desktop and ambiguous at tablet: does it become two columns or one, and does the card that was third become a full-width feature or just wrap? A form is designed in its empty state roughly always, and in its error state roughly never.

We do not need every breakpoint drawn. We need to know which decisions are yours and which are ours. A single line saying “cards go two-up at tablet, one-up under 640, developer’s call on the gaps” is enough, and it prevents the review round where you point at something and say that is not what we meant.

The states worth naming explicitly: hover and focus, empty, loading, error, and long content. Long content is the one that catches people. A card designed with a four-word heading will be filled by a marketing coordinator with fourteen words, and if nobody decided what happens then, the design breaks the first week it is live.

Define the content model before writing content#

This is the single biggest predictor of whether a build stays on schedule, and it is the item most often missing.

We are not asking for finished copy. We are asking what kinds of things exist on this site and what fields each one has. A case study has a client, a sector, a summary, a body, three metrics, and a hero image. A team member has a name, a role, a bio, a photo, and optionally a LinkedIn URL. A product has a spec table, and the spec table has these eight rows.

Get this wrong and the cost is not a tweak. If a case study is built with two metric fields and the client later needs three, that is a template change, a CMS change, a migration of the existing entries, and a QA pass. Get it right and adding the fifty-first case study takes a marketer fifteen minutes.

The question that surfaces most of these: what is the second one of these going to look like? Design shows the first. The model has to survive the fiftieth.

State the commercial goal of the website in one sentence#

This sounds like strategy rather than specification, and it changes technical decisions constantly.

A site whose job is inbound leads gets its budget spent on page speed, form reliability, and the path from a landing page to a submitted enquiry. A site whose job is credibility during a sales cycle, where the prospect is already in conversation and is checking whether you look real, gets it spent on proof, clarity, and the pages a buyer sends to their boss. Those are different builds, and the difference is invisible in a design file.

One sentence is enough. Buyers arrive from paid search and need to book a demo. Or, procurement teams check this site before approving a vendor. We will build differently for each, and if we have to guess we will guess the generic answer, which serves neither.

Scope every integration by name, action and access owner#

Integrations are where estimates die, and almost always for the same reason: the integration was listed but not scoped.

“Connects to the CRM” can mean a form posting to an endpoint, which is an afternoon. It can also mean field mapping to a Salesforce instance customised over nine years by someone who has left, with a required field nobody documented and an admin who answers email on Thursdays. The line in the brief is identical. The work differs by two orders of magnitude.

What we need: which system, which specific actions, who controls access, and how fast that person responds. That last one is not a joke. On a fixed-price project, a client-side admin with a two-week response time is a schedule risk we have to price for, and we would rather price it than discover it.

Name the decision-maker and the review cadence#

Every project has a person whose opinion ends the conversation. Name them in the brief.

The expensive version is the executive who was not in the kickoff, sees the build in week seven, and has entirely reasonable opinions that arrive after four other decisions have been built on top of the thing they want changed. That is not a difficult client. That is a briefing failure, and it is avoidable by asking one question at the start.

We also want to know the review cadence you can actually sustain. Not the one you would like to. If reviews realistically happen every Thursday, we will plan the build around Thursdays and nothing slips. If we assume two-day turnarounds and get five, every estimate downstream is wrong.

Decide who owns the website after launch#

Worth stating up front, because it shapes how we build rather than what we do at the end.

If your client’s marketing team will run the site, we constrain the components hard, so it is structurally difficult to produce an off-brand page. If your own developers are taking it over, we optimise for readable code and a clean repository instead, and we can follow your branching model and code standards. If it is going to a hosting provider you have not chosen yet, we avoid anything that assumes a particular stack.

These pull in different directions. Deciding at the end means retrofitting, and retrofitting is the most expensive form of the same work.

Website handoff checklist: the one-page version#

A brief that lands well contains: designs plus a note on responsive intent and states, a content model, one sentence on what the site is commercially for, integrations named with an access owner, the decision-maker and a realistic review cadence, and who owns the site afterwards.

That is a page. Maybe a page and a half. It takes about an hour to write, and in our experience it removes most of the three-week surprises that make agencies distrust outsourced development in the first place.

If it helps, ask us for the checklist version and we will send it. It is a page of questions with no branding on it, and you are welcome to use it with any developer, including one who is not us.

Frequently asked questions#

How long should a website development brief be?#

One to two pages. Shorter usually means the content model and integrations are missing. Much longer usually means design commentary is standing in for decisions. The test is whether a developer who has never met you could quote from it without a call.

Should the brief include finished copy?#

No, but it must include the content model: what types of content exist and what fields each one has. Finished copy can arrive during the build. A missing content model stalls the build in week one.

Who should write the handoff spec, the agency or the developer?#

The agency drafts it, because it holds the client context, and the developer is invited to poke holes in it before work starts. A spec nobody pushed back on has usually not been read carefully by either side.