We Need a Spec Format for Design, QA, and Documentation

Pierre-Clément Kerneis — Sat, 24 May 2025 11:58:52 +0000

Tired of losing track of what your app is supposed to do? Here's how I ended up building a spec format that drives mockups, tests, and docs — all from a single source of truth.

🤯 The Problem: Lost in Translation

I've been working as a developer on a web application that's been around for over a decade.

It went from waterfall to Agile.

It went from Jira to GitLab.

Most of the people who worked on the application at the beginning are long gone.

Somewhere along the way, we lost something: a clear, centralized, and accessible description of what the app is supposed to do.

As new features come in and behavior changes, we're left with thousands of tickets that contradict each other.

Requirements are buried in meeting notes or lost in informal conversations.

And my team and I spend hours retro-engineering behaviors that should be obvious.

🧠 The Realization: We Need Executable UI Specs

It hit me: even though we have version control, CI/CD, test pipelines, an agile board, and even well-maintained user documentation — we still don't have a living spec.

In the backend world, spec-driven development is already a thing.

We have tools like OpenAPI (which we eventually started using) that let teams define what an API should do — then auto-generate documentation, mocks, tests, and client code from that spec.

But on the frontend, I couldn’t find anything that comes close.

Every team cobbles together their own partial solutions:

Design handoffs in Figma
User flows described as Cucumber tests
UI component libraries with Storybook
Docs scattered across Google Docs or markdown files
Product specs buried in Jira

And everything drifts apart — constantly.

We need a frontend equivalent of OpenAPI: something UI-focused, developer-friendly, and test-aware.

📋 What I Wanted

Here's my wishlist. I wanted something that:

Was easy to write, easy to read — Markdown, YAML, whatever
Described screens and interactions clearly
Could turn into automated tests without tons of glue code
Could generate useful, visual documentation for product owners, QA, and new developers
Stayed in sync with the code

🛠️ Building Spequoia

That’s why I started building Spequoia — a human-readable specification format that can power mockups, tests, and documentation from a single source.

At its core, it’s just a YAML document where you can:

Describe UI screens
Describe features using Markdown
Define interaction flows for each feature
Generate animated wireframe mockups
Run automated acceptance and regression tests
Produce interactive documentation and tutorials

It also comes with a static website generator to bundle everything together — no complex frameworks, no IDE plugins.

You just write specs and share the output with design, dev, and QA.

From the very same document, you can:

🎞️ Animate UI mockups

✅ Generate interactive tutorials from E2E test runs

🌐 Pack everything into a static website

🚧 What's Next

Spequoia is still early. At the time of writing, it's just a proof-of-concept — but the foundations are there.

And I'd love your feedback, your ideas, or your help shaping it.

👉 Explore the repo

🧪 Try the interactive demo

Have you built something similar?

Ever fought against the chaos of missing specs?

I'd love to hear your thoughts — drop a comment!

DEV Community: Pierre-Clément Kerneis