Accessibility Annotations in Figma: Your Annotations Aren't Reaching Developers

You've spent an hour in Figma documenting the accessibility requirements for a component. You've specified the ARIA role, labeled the properties, clarified the keyboard behavior. You hand it off to the dev team. Three weeks later the component ships and the keyboard navigation is missing. You check the code. Your annotations are never mentioned in the PR.

This isn't because developers don't care. It's because your annotations are probably not reaching them.

The problem isn't what you're writing. It's where you're writing it, who can see it, and how explicit you need to be about things that feel obvious when you're looking at the design.

Why annotations fail to reach developers

The first barrier is permissions. Figma's Dev Mode shows the properties your developers actually need to read. But annotations are hidden in the Design tab, behind a toggle most developers never click. If your team isn't toggling "Show annotations," a developer could read your spec every day and still never see anything you wrote.

The second barrier is visibility. You've put accessibility annotations on the component in your library. But the developer is looking at a variant. They're on a specific instance of that component, maybe three levels deep in a page frame. Your annotation lives on the main component. It's not visible in the variant branch. This is especially true for complex components with many variants. The annotation exists, but it's not where the developer is reading.

The third barrier is language. You've written an annotation because you understand what accessible keyboard behavior means. A developer might not. If your annotation says "keyboard-trap: false," they may not know whether that's something to implement or something to avoid. If you write "focus order," are you describing what should happen, or describing what's already visible in the design.

The fourth barrier is scale. You have six button variants. You've written an accessibility annotation once on the primary button. The outline button and ghost button are variants. Do the same rules apply? A developer might assume they do. They might also assume they don't. Without explicit confirmation, they're guessing.

The core issue is not annotation as a concept. It's that annotations live in a space that developers have to deliberately choose to look at, that visibility doesn't cascade to variants, and that implicit knowledge ("this is obvious from the design") doesn't carry forward the way explicit spec language does.

What developers actually need versus what designers typically annotate

Designers usually annotate based on what they're thinking about while designing. That's the interaction model. How focus moves. What semantic meaning the component has. Designers think about the difference between a button and a link because the difference affects interaction design. The code implications feel secondary.

Developers need to know the same things, but they need them in a different order. They need to know what HTML element to use. That drives everything downstream. Once they know "use button for actions and link for navigation," the ARIA roles follow naturally. Once they know focus should trap in a dialog, they know to implement a focus trap. But they need that decision first, and they need it to be explicit.

Most designer annotations are descriptive. "This is a dialog." "Focus traps here." Developers need prescriptive language. "Implement a focus trap. Tab should loop inside the dialog. Escape closes it." One is naming what's true. The other is specifying what to build.

Designers also annotate what's visible. "This button has a focus state." Developers need to know both the visible state and the mechanics. "This button has a focus state. The focus indicator is 2px, 2px offset. Screen readers announce the button label as '

Close,' not 'X.'" The visible state plus the label plus the mechanics make the spec complete.

Another gap: designers think about the happy path. "When the user selects an option, the dialog closes." Developers think about states. "What if JavaScript fails? What if the user hits Escape before the selection completes? What if they select something, then hit Escape, then open the dialog again?" Accessibility annotations that don't address state changes or failure modes are incomplete from a developer's perspective.

When to annotate and when it's theatre

Not every component needs an accessibility annotation. Some decisions are better left to development standard library conventions. Some patterns are obvious enough in the visual design that annotating them adds noise.

Annotate when the visual design and the accessible implementation would diverge without guidance. A visually hidden skip link. A search input with a visually separate submit button that should be a single form semantically. A button that looks like a text link. A heading that's visually styled identically to body text. These require annotation because the code choice isn't obvious from the visual design.

Don't annotate when the visual and semantic models are the same. A standard primary button. A labeled text input. A navigation link. These don't need annotation because developers already know that a button is a button and a link is a link.

The annotation burden grows in two places where it's not necessary. First, when you're being comprehensive for completeness's sake. "Every button is a button, every input is an input, role: none on decorative elements." That's just noise. Second, when you're annotating the design consequences of decisions that are already clear. You've made a heading large and bold to establish hierarchy. You don't need to annotate "heading level 2." The visual treatment makes it obvious.

The expensive annotations are the ones that address decisions that would otherwise be invisible or ambiguous. A visually complex component with multiple nested interactive regions. The decision about when focus should trap. The handling of disabled states. The keyboard shortcut a component responds to. These are the annotations that actually move the needle.

How to write annotations that stick

Specificity is the first principle. Don't write "accessible dialog." Write "dialog with focus trap. Focus loops on Tab inside the dialog. Escape closes dialog. Outside click does not close." A developer should never finish reading your annotation and still have a question about what to implement.

Explicitness is the second principle. Assume the developer doesn't already know what you know. If you're specifying focus behavior, name each interactive element. "Tab moves focus from Name input to Email input to Submit button. Shift+Tab reverses the order. Focus cannot escape the form while it's open." Not "trap focus." Trap focus is the consequence of what you just described. The description is what they need to build.

Consistency is the third principle. Use the same term for the same thing every time. If you call something "close button" in one annotation, don't call it "dismiss button" elsewhere. Developers will wonder if they're the same thing. Pick a term and stick to it across the entire component system.

Format matters more than you'd think. A wall of text is harder to reference than a structured annotation. Try this pattern:

"Role: dialog

Label: Modal title

Behavior: Focus traps on Tab inside. Escape closes. Outside click does not close.

Label visibility: Title is visible and serves as dialog label."

Each line is one decision. A developer can skim and find what they're looking for.

One more thing about annotations: they can clarify without prescribing. "This needs a focus indicator" is a constraint. "This needs a focus indicator visible on keyboard navigation" is the actual constraint. The first forces a specific visual approach. The second lets developers implement it however is standard for your codebase. The more you constrain, the harder the work. Annotate constraints, not implementation.

The annotation checklist

Before you consider a component annotated, ask yourself these questions:

Is every interactive element named consistently across all variants? You've named a button the same way in five different components. A developer should be able to search for that name and find all uses.

Have I specified any behavior that differs between variants? If all buttons behave the same way, you don't need per-variant annotations. If the outline button disables differently from the primary button, every variant needs explicit annotation.

Does the annotation address what a developer would need to know about keyboard navigation, ARIA roles, or visual state that isn't obvious from the design? If you can look at the design and know exactly what to code, the annotation is optional.

Is my language prescriptive, not descriptive? "Focus traps" is descriptive. "Tab loops inside the dialog without escaping to the background" is prescriptive.

Have I made the annotation visible in Dev Mode? You can't control whether developers look at annotations, but you can ensure they're visible where developers are looking. If your annotation exists in the Design tab and never appears in Dev Mode, it won't reach them.

Have I addressed state changes, not just the default state? The button when focused, when hovered, when disabled, when active, when loading. If you've only annotated the default state, the annotation is incomplete.

Am I annotating decisions that would otherwise be ambiguous or invisible? Or am I documenting the obvious? If it's obvious, skip it. Noise is friction.

The real constraint

The constraint is shared context. The moment you hand off a design, you lose the ability to clarify in conversation. Everything your developer needs to know lives in what you wrote. That's why specificity matters so much. That's why consistency matters. That's why a developer should never finish reading an annotation and wonder what the next step is.

The weird part is most teams already know this about other kinds of spec work. They understand that interaction documentation needs to be explicit and consistent. They understand that visual specs need to be precise. But when it comes to accessibility annotations, there's this assumption that it's either obvious or someone will ask. It's usually neither. A developer sees an accessible pattern in production and wonders how it was ever supposed to work that way, checks the spec, and finds nothing there.

Start treating accessibility annotations like the spec that they are. Make them visible, make them specific, make them address the decisions that wouldn't be obvious from the design alone. That's the work that reaches developers.