Skip to content
← all systems

spec-first-nextjs

Figma to Next.js where every component starts as a human-approved contract - and CI fails on visual drift.

pixel-diff CI gate · zero SaaS

role
Architect and sole engineer
stack
Next.js 16 · Storybook 10 · Playwright · pixelmatch · Tailwind v4
status
oss

// 01 - PROBLEM

Design-vs-shipped drift is invisible until a designer complains. Existing visual-testing SaaS solves it for a fee; this workflow gives solo devs and small teams the same honesty with zero external services.

// 02 - APPROACH

  • Spec lifecycle: draft, approved, implemented, revising - YAML frontmatter makes the state machine tool-readable.
  • Six CLI tools: scaffold, capture, fetch from Figma, sync tokens, pixel-diff, verify.
  • Storybook with an axe-core a11y audit per story and embedded Figma frames.
  • A reusable AGENTS.md so AI coding agents inherit the whole workflow on first read.

// 03 - ARCHITECTURE

Spec before code, human before merge
The contract is approved before implementation exists, and the verify gate refuses code that drifts from it - honesty enforced by CI, not by review vigilance.

// 04 - PRODUCTION-GRADE

  • One-line CI gate fails merges on drift
  • Accessibility audit per story via axe-core
  • Figma Variables to Tailwind v4 token sync

// 05 - ARTIFACTS