Writing

Figma's Specs editor works when treated as an executable contract

Figma's latest Specs editor proposes a single Markdown source of truth for human designers and AI agents. In enterprise platform work, agents fail when context is scattered across comments, tickets, and tribal knowledge. One versionable document fixes that. It is inspectable, and it narrows the gap between design intent and generated code. That is the strongest version of the case for it.

The case for a single Markdown source of truth

The argument in favour is straightforward. A Markdown file can live in the same repository as the code it describes. It can be reviewed, diffed, and versioned. Unlike a Figma canvas or a design system microsite, it does not require a separate tool to inspect. For agent-driven UI work, that proximity matters. The agent can read the spec alongside the component source, the tokens, and the existing lint rules. When context is scattered, agents guess. When it is local and explicit, they guess less.

The case against narrative specifications

The case against Specs is just as simple. A Markdown file is easy to write and easier to ignore. Real design constraints live in tokens, components, and code, not prose. If a spec says "use 8px spacing" but the codebase contains 12px margins, the spec is wrong or the code is wrong, and no amount of reading resolves that. If Specs stays narrative, teams might mistake documentation for enforcement. A document that nobody is required to follow becomes a record of intentions, not a source of truth.

There is also a risk that a tool-specific spec becomes another silo. Figma already stores components, variables, and prototypes in its own format. If Specs lives only inside Figma and is not wired into existing pipelines, it can drift from the actual implementation. The spec may describe what the team wanted at some point, while the deployed interface moves on. That is not a failure of Markdown; it is a failure of integration.

Treat specs as a contract, not a guide

My take is simple: treat Specs as a contract, not a guide. I would parse the Markdown into machine-readable assertions such as JSON Schema, policy rules, or lint checks, so agent output is validated against the spec rather than eyeballed. The document stays human-friendly; enforcement lives in CI. If an agent generates a button that violates a spacing rule, the check fails. If a generated screen misses a required accessibility attribute, the check fails. The spec becomes something the pipeline honours, not something the team hopes the agent read.

This approach keeps the human-readable document but moves the point of enforcement. The Markdown is still where people argue about intent, trade-offs, and edge cases. The assertions are what machines execute. That division of labour is useful because prose is good for context and terrible for validation. JSON Schema and policy rules are the opposite. You want both, but you should not confuse one for the other.

TechCrunch's summary of Figma's Specs is a useful reference for the feature itself. What matters more is how teams choose to use it. Teams that treat specs as executable contracts will see fewer production UI defects than teams that treat them as documentation. Within two quarters, the difference will be measurable. That is not because agents become perfect. It is because a check that runs on every change catches drift before it reaches production.

The most realistic failure mode is a well-written Markdown file that everyone likes and nobody consults. The most realistic success mode is a short spec, paired with a few enforceable rules, that makes the agent's output easier to review and safer to merge. The gap between those two outcomes is not the quality of the prose. It is whether the spec made its way into the pipeline.

Originally covered at techcrunch.com ↗