Why design handoffs fail

The gap between a finished Figma file and working code is where product details go to die. Engineers stare at static frames and guess at behavior: What is interactive? How does this reflow on mobile? What happens when text expands? Meanwhile, designers have intent that isn't visible on the canvas—and it gets lost in Slack threads, buried in Figma comments, or never written down at all.

GitHub’s accessibility design team measured the cost of that breakdown internally. After reviewing their own audit data, they found that 48% of accessibility issues could have been prevented if design intent had been documented earlier—specifically, by integrating WCAG considerations into annotations from the start. So they built a Fix for that workflow gap, and they’ve now released it as open source under the name Annotation Toolkit.

Stamps instead of Slack threads

The Annotation Toolkit is a Figma library of annotation stamps you drop directly into your design files. Each stamp attaches a numbered label to specific UI elements, and you pair that label with a description block that explains behavior, intention, and requirements.

That small shift replaces scattered documentation with something that lives inside the source of truth. Each annotation serves three purposes at once:

  • Captures design intent that extends beyond what’s visible on the canvas.
  • Documents accessibility behaviors and edge cases—reflow, table semantics, alternative text context—at the point where they matter.
  • Gives engineers a clearly numbered reference they can walk through without hunting for context.

Nothing gets lost in translation because the translation happens upfront.

Design tools that teach accessibility

The library was created by GitHub’s accessibility team, and it shows. Each stamp ships with built-in guidance addressing nearly every design-preventable WCAG issue, including things like responsive reflow and image context. Add an image annotation and the process prompts you to record the surrounding context a developer will need to write meaningful alt text. Mark a table and you’re guided toward documenting its structure and behavior.

You're not just marking a file—you’re learning what information developers actually need to implement accessibility correctly. That means accessibility stops being a specialist topic bolted on at review time and becomes part of the standard design conversation.

Workflow before vs. after

Before the Toolkit existed, GitHub product teams made do with the usual patchwork: Figma comments that scroll away, Slack messages nobody can find later, one-off clarifications that never make it back into the design file. The result was known:

  • Engineers had no reliable way to distinguish visual decoration from intended behavior.
  • Teams lacked a common vocabulary for explaining interaction and accessibility requirements.
  • Issues that could have been caught in the design phase resurfaced as post-build QA failures instead.

Annotations change the economics of that handoff. Designers, product managers, and developers all work from the same numbered system, so requests turn up as reviewed specifics instead of guesses. Preventative QA becomes a side effect of the design phase rather than an expensive phase of development.

Annotations enable Figma to become more than just a canvas. It’s a tool for expressing a much deeper level of information.

That workflow change scales across teams that have never worked together before. A common annotation language means behavior that a designer documented once doesn't need to be rediscovered by every new engineer who touches the file.

Getting the toolkit into your Figma files

There are two ways to get started, depending on whether you prefer instant access or full documentation.

From Figma Community

  1. Open the @github profile on Figma.
  2. Locate the Annotation Toolkit and duplicate it to your drafts.
  3. Find the components in your Assets tab whenever you need them.

From the GitHub repository

  1. Visit github.com/github/annotation-toolkit.
  2. Download the exported Figma file from the repo.
  3. Open it in Figma and duplicate it into your workspace.
  4. Start pulling components from the Assets tab.

Using the toolkit is equally straightforward. Drag an annotation stamp onto the element you want to document—a profile picture gets the Image stamp, for instance—and a numbered label appears. Pair that number with a description block detailing what a developer needs to know. That's the full workflow.

The Toolkit also includes design checkpoints built into the framework: interactive checklists that keep accessibility considerations in the foreground while you work. If you want more depth, the repository documentation covers every annotation type, explains WCAG compliance requirements, and walks through common sources of handoff friction.

An open invitation to contribute

The project is actively maintained by GitHub staff and open to outside contributions. If the library doesn't cover a case you need, you're invited to add it: report bugs, request features, or propose entirely new annotation types. The maintainers are looking for real-world usage feedback to close any remaining gaps. A walkthrough video is available if you want to see the workflow in action before adopting it.

Putting intent directly in the design file doesn't replace designer-developer conversation—it makes those conversations specific enough to matter.