Design Spec

A design spec is a concise markdown document structured into seven non-negotiable sections that together replace wireframes as the main handoff artifact. It lives in the repo next to the code and gets treated like production material instead of disposable design fluff. The format exists because vague intent produces vague AI output at high speed. Clear specs act as both blueprint and test plan.

It is not a loose collection of notes in Notion. It is not annotated Figma frames with extra comments. Plenty of teams still confuse specs with the old handoff docs that lived separately from code. Those went stale instantly. A real design spec is the single source that engineers reference during implementation, QA uses for tests, and AI tools consume directly.

The most common mistake is filling it with product jargon and component names instead of user actions. Bad specs say use the modal. Good specs say the user confirms the save and receives an undoable toast. The difference shows up immediately when you paste the spec into Cursor and watch what comes back.

Concrete example. The save-to-collection spec clocks in at roughly 40 lines. Its edge cases section lists five real failure modes including network error, free-tier limit hit, and already-saved state. Success criteria demand specific numbers like 30 percent of weekly active users saving at least one item per month. Claude Code built a working version from it in a single pass. The QA lead wrote E2E tests straight from the evals section. Zero screenshots were required.

Another instance comes from a 2026 productivity tool team. Their design spec for an improved command palette ran 520 lines. It defined exact keyboard behavior, empty states, and aria-live announcements. The spec routed to v0 for initial UI, Bolt for prototype logic, and the design system docs for token validation. One artifact drove every role and every tool.

Use a design spec whenever you are building standard product surfaces that should feel consistent with your system. It earns its keep on forms, lists, detail views, and anything where behavior matters more than novel layout. The upfront writing catches 80 percent of misunderstandings before the first line of code.

Skip the full spec format for tiny bug fixes or brand-driven hero modules where mood matters more than measurable criteria. In those cases a lighter document or visual exploration comes first. The tradeoff is that writing boring, precise prose feels tedious until you see how much faster the team moves afterward.

Design specs force scope discipline through the out list. They force measurable thinking through success criteria. They force clarity through the accessibility and copy section that demands every string and every aria label.

Portfolios built on strong specs stand out in 2026. Hiring managers at serious companies read the intent paragraph and edge case list before they look at the shipped screenshot. It shows how the candidate thinks, not just how they decorate.

The fastest teams review specs in the same pull request as the code. Changes are tracked, dated, and credited. Try achieving that level of accountability with a Figma comment thread.

Write the spec first. Treat it as the job. Everything else becomes execution.

A great design spec turns opinion into contract and ambiguity into shipping velocity.