Handoff
Fixing a Design Handoff That Kept Breaking Down
Design work published where engineering already works, so it stops drifting out of sync after the handoff meeting.
Repository structure
Components, patterns, and guidelines committed and versioned alongside the codebase, instead of living in a disconnected design file.
Published reference
The documentation surface on GitHub Pages, browsable and linkable the same way engineers already reference API docs.
Branch review
A proposed pattern change moving through the same branch-and-review workflow engineers use for code, instead of a separate design review process on its own timeline.
Citable in a PR
A pull request referencing the design documentation directly, closing the gap between a design decision and its reflection in what actually ships.
Challenge
Handoff ended right where engineering's real work began. After the meeting, the Figma file became a historical record. It drifted from what shipped, and nothing forced anyone to update it. The table component was the worst case: the Figma version and the shipped version had been different for months before anyone noticed.
Process
I put design commits through the same versioning, branching, and review flow as code, published to GitHub Pages so engineers could find them in the tools they already use. At first the review step slowed design down more than it helped, until we let small changes skip it.
Research
It took me a while to stop blaming discipline. Design and engineering tools just spoke different languages and lived in different places, so the lag was guaranteed however careful anyone was.
Design
A component is "done" when it's committed with documentation that describes how to use it, in the place engineers actually go to check. Not when a Figma frame looks approved.
Outcome
Questions that used to mean pinging me got answered by the documentation itself, and design and engineering could work on the same branch instead of finding problems after the build. I haven't counted the pings. It felt like most of them went away.