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

spec-first-nextjs is a Figma-to-Next.js workflow where every component starts as a human-approved contract and CI fails on visual drift. A spec moves through draft, approved, implemented, and revising states in tool-readable YAML frontmatter; six CLI tools scaffold, capture, fetch from Figma, sync tokens, pixel-diff, and verify; and Storybook runs an axe-core accessibility audit per story. A reusable AGENTS.md means AI coding agents inherit the whole workflow on first read - the same honesty a visual-testing SaaS sells, with zero external services.

// 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-first · CI-gated on drift

  1. Figma

    Design source and variables

  2. Spec contract

    Draft spec in tool-readable YAML frontmatter

  3. Human approvalcontrol point

    The contract is approved before code exists

  4. Code

    Implement against the approved spec

  5. Pixel diff

    Compare shipped render to the Figma frame

  6. CI gate

    Merges fail on visual drift

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