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!
Top comments (0)