Level up design-to-code collaboration with GitHub’s open source Annotation Toolkit
Andrea Griffiths·2025-11-19·via The latest on enterprise software - The GitHub Blog
If you’ve ever been handed a design file and thought, “Wait—what exactly is this supposed to do?” you’re not alone.
The handoff between designers and developers is one of the most common points where product workflows break down. You are looking at components and trying to figure out what’s interactive, what’s responsive, what happens when text gets bigger. The designer is trying to express something that isn’t directly stated on the canvas. Somewhere in that gap, accessibility considerations get missed. Knowledge walks out the door in lost Slack threads. Then it all comes back later as a bug that could have been prevented if messages weren’t missed or if expectations had been clearer upfront.
GitHub’s accessibility design team ran into this exact problem internally. They looked at their own accessibility audit data and realized something striking: nearly half of accessibility audit issues (48%) could have been prevented if design intent had been better documented upfront by integrating WCAG (Web Content Accessibility Guidelines) considerations directly into annotations. So they built something to fix it. And now they’ve open sourced it.
It’s called the Annotation Toolkit, and it’s a Figma library designed to make the handoff easier. The framework brings structure, clarity, and accessibility-first practices into every design-to-code interaction.
At its core, the Annotation Toolkit is a Figma library of stamps (annotations) that you can drop into your designs. Each annotation lets you:
Express design intent beyond what’s visually on the canvas.
Document accessibility behaviors like responsive reflow or table handling.
Guide engineers clearly by linking numbered stamps to descriptions.
Instead of documenting all this in Figma comments (which get lost), Slack threads (which disappear), or scattered one-off clarifications (which nobody can remember later), the annotations live right inside your design file. They’re numbered, they’re portable, and they stay with your work.
Think of it like embedding clarity directly into the handoff.
Why it matters: Accessibility by default
The toolkit was built by GitHub’s accessibility design team specifically so that accessibility considerations aren’t something you bolt on at the end. They’re baked into the design workflow from the start.
Each annotation comes with built-in guidance. Want to mark a table? The toolkit addresses nearly every design-preventable accessibility issue under WCAG guidelines, including things like reflow behavior. Adding an image? It prompts you to document the context so developers can write proper alt text. The toolkit doesn’t just let you document accessibility—it teaches you as you go.
That’s not a small thing. It means developers stop guessing. It means accessibility isn’t a specialist concern anymore, but is part of the conversation from day one.
Real-world application: From pain points to productivity
Before this toolkit, GitHub teams relied on a patchwork of Figma comments, Slack threads, and one-off clarifications. This patched approach resulted in knowledge gaps and repeated accessibility oversights.
But now, annotations provide:
Clarity at scale: engineers no longer guess at intended behaviors. Consistency across teams: designers, product managers (PM), and developers all share a common language.
Preventative QA: many issues are resolved at the design stage instead of post-build.
Annotations enable Figma to become more than just a canvas. It’s a tool for expressing a much deeper level of information.
You’ve got two paths here, so pick whichever feels easier:
Option 1: From Figma Community (fastest)
Head to the @github profile on Figma (figma.com/@github).
Find the Annotation Toolkit and click the link to duplicate it.
It goes straight to your drafts.
Access the components anytime from your Assets tab.
Option 2: From GitHub (if you want all the docs at once)
Visit github.com/github/annotation-toolkit.
Download the exported Figma file from the repo.
Open it in Figma and duplicate it to your workspace.
Same deal—find components in your Assets tab.
Once you’ve got the toolkit, adding your first annotation is straightforward. Open any design file, drag an annotation stamp into it (say, the Image annotation on a profile picture), and you’ll see a numbered label appear. Pair that number with a description block and write what you need. That’s it. You’ve just documented something that would normally disappear into a Slack thread.
The toolkit comes with design checkpoints, which are basically interactive checklists that keep accessibility top of mind as you work. If you want to go deeper, everything is documented. The repo has tutorials for every annotation type, deep dives on WCAG compliance, and guidance on avoiding common handoff friction. Check it out and contribute back if you find gaps.
The bigger picture
The Annotation Toolkit is a shift in how we think about collaboration. By embedding intent, accessibility, and clarity directly into Figma, GitHub is giving the developer-designer partnership a new foundation.
It’s not about replacing conversations. It’s about making them more meaningful. When intent is clear, work flows faster, and the end result is better for everyone.
The toolkit is actively maintained by GitHub staff and open to contributions. If you spot something that could be better, head over to github.com/github/annotation-toolkit and open an issue. Report bugs, suggest features, or contribute new annotation types. The team is actively looking for feedback on how you’re using it and what’s missing.
Andrea is a Senior Developer Advocate at GitHub with over a decade of experience in developer tools. She combines technical depth with a mission to make advanced technologies more accessible. After transitioning from Army service and construction management to software development, she brings a unique perspective to bridging complex engineering concepts with practical implementation. She lives in Florida with her Welsh partner, two sons, and two dogs, where she continues to drive innovation and support open source through GitHub's global initiatives. Find her online @acolombiadev.
Related posts
Explore more from GitHub
Docs
Everything you need to master GitHub, all in one place.
Catch up on the GitHub podcast, a show dedicated to the topics, trends, stories and culture in and around the open source developer community on GitHub.
