Specs Before Screens: What Figma Specs Changes About Agency Handoff

Every agency designer knows this moment. You hand over a beautiful Figma file, the client's developers start building, and two weeks later a question arrives that the file can't answer: "What happens if the user has no saved cards?" The answer was in your head, or in a call, or in a comment buried on frame 47. It was never in the handoff.

At Config India in October, Figma launched Specs: Markdown documents that live on the canvas next to designs, code layers and FigJam boards. Both Figma's own agent and third-party agents read them before generating work. Most coverage frames this as an AI feature. I think the bigger change is for handoff. The written spec is now a first-class design deliverable, sitting in the same place as the screens.

What Figma Specs is, and why it matters beyond AI

According to coverage from Tenet and Design Compass, Specs are Markdown files attached to a Figma file. They sit alongside the frames they describe, and agents treat them as instructions before producing anything. AI Weekly described them as a rulebook for agents.

That framing is accurate, but it undersells something. For years, specs lived somewhere else: a Notion page, a Confluence space, a PDF attached to an email. The further the spec sat from the design, the faster the two drifted apart. Putting the words next to the pictures removes the most common excuse for not reading them.

The handoff problem agencies keep running into

Agency handoff has a specific shape. We design, we explain, and then we leave. Sometimes the client's in-house team builds it. Sometimes an outsourced dev team we've never met builds it. Either way, the people who knew why decisions were made are no longer in the room.

What usually survives handoff is the redline: spacing, sizes, colors. What usually gets lost is the reason. A developer sees a 24px gap and copies it. They don't know it exists so the Arabic label has room to grow. So when they reuse the component elsewhere, they shrink it, and the Arabic version breaks.

Redlines without reasons produce faithful copies of the happy path and improvised guesses everywhere else.

Anatomy of a client-ready spec

Here's what I put in a spec for each feature or flow. It's deliberately short. A spec nobody reads is worse than none, because it creates false confidence.

1. Purpose

Two or three sentences: what problem this flow solves, for whom, and what success looks like. This is the part agents and developers both use to make judgment calls when the spec doesn't cover something.

2. Flows

The steps, in order, with links to the frames. Include the entry points. "Users arrive here from the cart, from a push notification, or from a saved link" changes how a screen should behave.

3. States

This is where most handoffs fail. List every state, including the ones you didn't draw:

• Empty, loading, partial, error, success
• First use vs. returning user
• Offline or slow connection
• Permission denied, session expired
• Very long content and missing content

If a state isn't drawn, write one line about what should happen. That line saves a round trip.

4. Content rules

Character limits, truncation behavior, tone, and which strings are final versus placeholder. Mark placeholders clearly. Developers ship placeholder copy more often than anyone admits.

5. Bilingual and RTL behavior

For our Arabic/English products, this section is non-negotiable:

• What mirrors and what doesn't (media controls, charts, some icons)
• Which numerals each language uses
• How mixed-direction strings, like an English product name in an Arabic sentence, should render
• Text expansion: Arabic and English rarely take the same space, so note which containers must grow
• Date, currency and phone formats per locale

I've written more about this in DESIGN.md Has No Sense of Direction. The same gap shows up in specs: if nobody writes the direction rules down, an agent will default to left-to-right.

6. Acceptance criteria

A short checklist a developer or QA can tick off. "The order summary shows the correct total in both languages with no wrapping at 320px" is testable. "Looks good on mobile" is not.

Writing for two readers at once

A spec on the canvas now has two audiences: a developer who skims, and an agent that reads every word and takes it literally. Some habits work for both:

• Be explicit about scope. "This spec covers checkout only. It does not cover the cart." Agents will otherwise apply rules too broadly.
• Use the same names as the components. If the component is OrderSummary, don't call it "the receipt box" in the spec. See my post on naming.
• Prefer lists to paragraphs. Developers scan them. Agents parse them more reliably.
• Write "must" and "should" deliberately. "Must" is a rule. "Should" is a preference. Agents take the difference seriously, and so do good developers.
• State the "don'ts." "Don't use a bottom sheet for payment methods" prevents an agent from cheerfully suggesting one.

Keeping specs alive after handoff

A spec written at handoff is accurate for about one sprint. After that, the product changes and the spec doesn't. For an agency, this is the hard part, because we're often not around to update it.

Before handoff, agree on three things with the client:

1. An owner. One named person on the client side who approves changes to the spec. Usually a product manager or lead designer.
2. A review rhythm. At the end of each sprint, someone checks whether shipped behavior still matches the spec, and updates whichever one is wrong.
3. A rule for conflicts. When the spec and the build disagree, which one wins until someone decides? Write it down.

If the client wants us to stay involved, a light monthly spec review is an easy retainer to justify. It's cheaper than redesigning a drifted product a year later.

[Waleed: add a short example of a handoff question a spec would have prevented on a recent Breem project, anonymized if needed.]

A starter spec template

# Feature: Checkout — payment step
Owner: [client PM] · Last reviewed: [date]

## Purpose
Let returning users pay in two taps; let new users add a card without leaving checkout.

## Scope
Covers: payment method selection, add card, pay.
Does not cover: cart, delivery address.

## Flows
1. From cart → payment step (frame: Checkout/Payment)
2. From "pay again" notification → payment step with last method selected

## States
- No saved methods → show add-card form directly
- Card declined → inline error, keep form values
- Session expired → return to cart with message

## Content rules
- Button: "Pay [amount]" / "ادفع [amount]" — max 24 characters
- Error copy is final; helper text is placeholder

## Bilingual / RTL
- Layout mirrors; card number field stays LTR
- Amount uses Money component; digits per locale

## Acceptance criteria
- [ ] Works at 320px in both languages without wrapping
- [ ] All states above reachable and tested

Closing thoughts

Figma Specs won't fix handoff by itself. A badly written spec on the canvas is still a badly written spec. But it removes the distance between what we draw and what we mean, and it gives agencies a place to leave their reasoning behind when they step away. For the next project, I'm treating the spec as a deliverable with the same weight as the screens. If you're building the components the spec refers to, my Arabic RTL app design checklist covers the layout side.

Sources: Figma Specs and code layers for AI agents (Tenet), Figma brings code and planning documents to the canvas (Design Compass), Figma unveils Specs Markdown rulebook to steer AI agents (AI Weekly).

FAQs