audit tooling
I turned design handoffs from a trust fall into a checklist.
Forge reads a design handoff, grades it against our system, and hands back the fix. It's the front door to spec-driven development, where every surface is built by an AI swarm against specs and gates, not loose prompts.
- Design System Lead & Sole Forge Maintainer
- React, Vite, FastAPI, Shield (@ch/ui), Claude Design
- Design systems, Tooling, Internal products
- Accessibility, Fidelity, Developer experience
The frustration
Every handoff was a trust fall.
We design in Claude Design using a Shield design-synced design system, then build with the Shield package. But between those two things there's a divergence: Claude Design recreates our components in monolithic JSX files, not in the composable primitives Shield actually ships. Nobody could see how far the output had drifted from the system, or translate it into something a swarm could read.
The insight
The handoff already knew what each component was supposed to be.
Our Claude Design exports weren't just pictures. Every element carried a data-design-symbol. If the handoff already knew what each component was supposed to be, I could compare it to the real Shield catalog and grade fidelity automatically. That one detail became the seed for Forge.
The tool
Canvas on the left, verdict cards on the right.
Forge takes a real Claude Design handoff, renders it live, and grades every component against Shield, with a verdict for each: reuse this Shield component, needs work, or genuinely new. It generates a fix prompt that you hand straight back to Claude to bring the screen in line. The output of an audit is a next step, not a to-do list.
The layer
Design fidelity as an enforced spec dimension.
Forge is the design-side front door to the SDD layer, the scaffold every engagement inherits, where the AI swarm builds against specs and gates instead of loose prompts. A forged surface doesn't stay a picture: it lands as a runnable @ch/ui prototype plus a design.yaml whose mapping table is the machine-readable contract.
From there the layer runs it: design-sync checks the mappings, the swarm builds the surface into its domain-scoped feature directory, and visual-fidelity verifies the build actually composes what the design promised. Shield is the linchpin, the one vocabulary spoken at every stage and the registry every gate validates against, so design and build can't disagree about what "correct" means.
The SDD layer
From design to a conformant PR, gated at every step.
Forge is the front door to spec-driven development. A forged surface becomes a machine-readable contract, and Shield is the shared vocabulary every gate validates against.
The screens
Shield & Forge
The problem
We design in Claude Design and build on Shield, our design system. But somewhere between the two, things quietly slipped. Every handoff was a trust fall, and nobody could actually see how close a build was to the system.
The first version
Handoff rendered live on the left. On the right, a card for every component with a verdict (reuse this Shield component, needs work, or genuinely new) and a path to green so progress felt tangible.
Handling real exports
Real exports are messy: multiple views bundled together, shared dependencies, whole apps that need to actually boot. Fixing import-maps and scoping each view to its own files was the unglamorous work that made Forge trustworthy instead of a demo.
The review experience
A 40-item audit is only useful if you can move through it. Every card is navigable: click one and Forge reveals the right view and isolates that component on the canvas. Guideline violations grouped by rule with counts and how-to-fixes.
Fix prompts
An audit that only lists problems creates work. Forge generates a fix prompt, a structured brief complete with reviewer notes and specific guideline violations, that you hand straight back to Claude to bring the screen in line.
A team object
Audits became living and shared. Once you share one, the state persists for everyone, anyone can edit, and an avatar shows who touched it last. Small touches that turned Forge from a solo tool into something a reviewer and builder could stand around together.
Closing the loop
A finished audit now opens a branch and PR straight from Forge, and Linear integration means an audit doesn’t just describe the work, it starts it. From handoff to ticket to code, one flow.
What I took away
Forge started as a designer’s frustration and turned into a full-stack product I shipped and maintained alone: frontend, backend, database, security, the whole thing. The biggest lesson wasn’t technical: it was that the unglamorous work is the work. The insight (design handoffs are inspectable) took an afternoon; making it trustworthy (booting real exports, failing closed, dogfooding end to end) took the rest. That’s the part that decides whether a tool gets used or gets bookmarked.
I also came away convinced that the best design-systems work happens between the tools, not inside any one of them. Forge lives in the seam between Claude Design and Shield, and its whole value is making that seam visible. As a designer, being able to build in that gap myself, instead of writing a spec and hoping, changed what kinds of problems I could take on.