From approved design to an agent-ready implementation handoff

Goal

Turn reviewed design decisions into a compact package an implementation agent can use without inventing requirements. State what is approved, proposed, evidenced, and separately permissioned.

As a concrete example, imagine a small site system with two approved font roles, light and dark themes, a desktop mark, a simpler mobile fallback, and reduced-motion behavior. The handoff must preserve those decisions without turning unreviewed navigation, persistence, or viewport assumptions into requirements.

Prerequisites

Before starting, have:

• a dated decision record identifying the latest approved direction;
• the reviewed specimens or assets you are allowed to use;
• a named reviewer who can resolve contradictions;
• a repository or destination already selected by its owner; and
• explicit permission for any action beyond read-only inspection.

Do not copy private paths, credentials, employer material, confidential references, or personal strategy. Link to redistributable sources when rights permit; otherwise record only the needed decision.

1. Inventory the inputs

Create an inventory before writing code. For each item, record its name, purpose, owner, version or date, redistribution status, and current evidence.

For the example, the inventory includes the identity decision record, approved static specimens, motion trials, font roles, header dimensions, and unresolved behavior. It should not include raw source prompts. Summarize their useful workflow principles instead.

Use the downloadable design handoff checklist to keep the inventory consistent.

2. Label every statement

Track decision status separately from verification status. A requirement can be confirmed but untested, or proposed but already tested in a prototype:

Record approval and test evidence separately. Example specimen dimensions might be confirmed while navigation behavior, theme persistence, accessibility conformance, and all-viewport behavior remain proposed or pending. Do not promote one kind of evidence into another.

A motion trial may be confirmed and tested only on a light background while dark mode, production integration, and broader browser coverage remain pending. Reduced motion should show the finished static state without requiring the animation.

3. Define implementation permission gates

Separate permissions so a request cannot silently expand:

1. Inspect: read approved inputs and report gaps. No modifications.
2. Prepare locally: create or update handoff files and assets in the named workspace only.
3. Implement: change the named website surfaces after the scope and acceptance checks are approved.
4. Verify: run the agreed local checks. In this workflow, treat installing tools, starting network-visible services, or using external systems as separate permission gates unless the task already includes them.
5. Publish or deliver: commit, push, open or merge a pull request, upload files, or create public downloads only when separately authorized.
6. Clean up: delete branches, worktrees, generated data, or artifacts only after exact targets are confirmed.

An approval of the visual direction authorizes none of gates 3–6 by itself.

4. Assemble the output package

Keep the core small enough to review:

• README.md: purpose, scope, prerequisites, permissions, and known gaps;
• decisions.md: confirmed, proposed, inferred, and tested statements with dates;
• tokens.md or a machine-readable equivalent: typography, neutral color roles, spacing, dimensions, and motion values that are actually approved;
• assets/: authorized static light/dark variants and documented fallbacks;
• surfaces-and-states.md: desktop/mobile, light/dark, hover, focus, loading, error, empty, and reduced-motion expectations as applicable;
• acceptance.md: observable checks and evidence required; and
• manifest.json: filenames, versions, checksums where useful, status, and source rights.

Optional modules may cover animation prototypes, CMS models, collection features, deployment, or an offline bundle. Include them only when needed; otherwise mark them “not applicable” with a reason. A manifest entry does not mean an offline pack or public download exists.

5. Run acceptance checks

Before handing off, verify that the package:

• assigns each typography role unambiguously and records license status;
• maps each approved visual treatment to the correct surface;
• uses the approved mobile fallback until small-size legibility is validated;
• distinguishes initial theme, theme switching, and persistence as separate behaviors;
• matches confirmed specimen dimensions without claiming working navigation;
• motion plays once, settles, and becomes static under reduced motion; and
• every unsupported behavior is labeled pending rather than silently invented.

Record the environment, date, commands or review method, result, and any check that could not run. A screenshot can prove appearance, not hidden interaction or persistence.

Recovery and handoff

If inputs conflict, stop implementation, preserve the current work, and ask the decision owner to resolve the conflict. If a check fails, revert only the files changed within the authorized scope or restore the recorded pre-change versions; do not use broad destructive cleanup. If required evidence is missing, deliver a gap report and a proposed next test instead of declaring completion.

The final handoff report should list created artifacts, verification results, unresolved decisions, permissions not exercised, and the next approval needed. Describe the package accurately: an agent-ready design handoff, not evidence that the implementation or release is complete.