SpecFlow

Documenting a Design System Without Writing the Docs

Design Systems Tooling · Ongoing · Design Systems Lead & AI Tooling

Design SystemsAI ToolingFigmaDesignOpsClaude

Published while still building.

The wins below are real and shipped. The measurement chapter is not done yet — and I'm leaving that gap visible on purpose, because pretending I'd already proven the thing would be the least interesting version of this story.

The Problem

Component documentation in a design system is slow, manual, and quietly inconsistent.

The failure mode isn't just speed. It's that a component gets documented as one instance — the version that happened to be on the artboard — instead of its full range of behavior. The variants, the breakpoints, the responsive rules, the edge cases all live in the designer's head and never make it into the spec. A reader downstream treats that single snapshot as the whole truth.

So the real cost is fidelity, not minutes. A spec that's fast to write but only captures one state isn't saving anyone time — it's deferring the confusion to whoever reads it next.

I wanted to attack both: make specs faster to produce and force them to capture the component's actual flexibility.

Note on honesty

I haven't yet measured the "before" — how long a spec takes by hand, or what percentage of existing specs miss breakpoints. That baseline is the first item in the next-steps chapter below. Right now this problem statement is qualitative and observed, not quantified.

What I Built

SpecFlow is a Claude skill that turns a Figma component into a structured spec. The interesting part isn't "AI writes docs" — it's the set of opinions baked into how it reads the design before it writes anything.

SpecFlow workflow: Figma → SpecFlow analysis → structured output

It discovers the full component before documenting it.

The skill maps a component's flexibility — variants, states, responsive behavior — before it writes a single line. It treats "document one instance as the whole story" as the primary bug to avoid.

It narrates its discovery like a designer on day one.

Instead of silently scanning and presenting a finished spec, it walks through what it found and assigns confidence levels. A reviewer can see where to look, rather than being handed a clean-looking doc that hides its own uncertainty.

It looks for "dev ready" as the source of truth.

Frames marked dev-ready are treated as authoritative; unmarked, in-progress content is deprioritized. This keeps the spec anchored to what the team has actually committed to, not to whatever happened to be on the canvas.

It treats breakpoints as required, not optional.

A spec that doesn't describe how the component behaves across breakpoints is incomplete by definition. The skill won't call a spec done without it.

It infers character limits from layout.

If the layout implies a constraint, the skill estimates it instead of bouncing the question back to the designer.

What's actually shipped

Two real component specs produced end to end.
A Paper mockup of the workflow.
A documented path into Supernova (our CMS): paste vs. URL embed vs. manual blocks, including the full block inventory.

This is early. It's two specs and a workflow, not a rollout. But the opinions above are load-bearing and they're working.

The Reframe: Maybe the Doc Shouldn't Exist

The more I built, the more the project stopped being "auto-generate the documentation" and started being a harder question: should the static doc exist at all?

I've started building interactive prototypes that replace the doc rather than describe it — the component, live, with its real behavior, instead of a written description of that behavior. Two are built and the conversations around them are underway.

This is the part I'm most interested in and the part I'm least sure about. It's a genuine fork: SpecFlow could be a faster way to write specs, or it could be the argument for writing far fewer of them. I don't know yet which is right. That's fine — I'd rather hold the open question than resolve it prematurely.

What I Haven't Done Yet

The measurement chapter

Everything above is craft and judgment. None of it is measured. I've validated SpecFlow by reading its output and by reactions in meetings — not by a test that could prove it's better than the hand-written version. That's the next chapter, and it's the one that would turn this from "I built a thing I believe in" into "I built a thing and here's the evidence."

Establish the baseline.

Time to author a spec by hand vs. with SpecFlow. Breakpoint / responsive coverage in existing hand-written specs (what % actually document it). Variant coverage — how often a spec captures one instance vs. the full set.

Define a rubric, not a vibe.

Score specs on explicit axes: Completeness (variants, states, breakpoints, tokens all present), Accuracy (does the spec match the dev-ready Figma source), Usability (can a downstream reader act on it without asking follow-ups).

Run a with-vs-without comparison.

Same component, spec'd by hand and by SpecFlow, scored blind on the rubric. Small N to start. The point is isolating whether the skill's opinions actually move the score, versus the output just looking tidier.

Test the reframe separately.

For the prototype-replaces-doc thesis, the measure is different: can a reader get what they need from the live prototype without the written spec at all? That's a comprehension test, not a coverage rubric.

Where This Stands

Chapter	Status
Problem (qualitative)	Observed, not yet quantified
What I built	Shipped — 2 specs, workflow, Supernova path
The reframe	In progress — 2 prototypes, conversations live
Baseline measurement	Not started
Rubric + comparison	Designed here, not yet run

The honest summary: I have a strong opinionated tool and a sharper-than-expected thesis, and I have not yet earned the right to put a number on either. The next update to this page should have a baseline in it.

This page is intentionally living. Last updated June 2026.