Figma Accessibility Annotations: Spec for Developers

WHY IT EXISTS: Visual design doesn't communicate everything. A developer can't know the intended heading structure (H1, H2, H3), ARIA roles, or screen reader focus order just by looking at a static mockup. Accessibility annotations were created to bridge this gap, embedding non-visual requirements directly into the design file to prevent ambiguity during handoff.

THE MENTAL MODEL: Think of accessibility annotations as a "spec layer" on top of your visual design. Just as you spec colors and fonts, you spec accessibility properties. This layer acts as a contract between designer and developer, ensuring the user experience is equivalent for users of assistive technologies. It moves accessibility from an afterthought in a separate ticket to an integral part of the design artifact.

HOW IT WORKS: While you can use simple text notes, robust systems use dedicated Figma plugins or component libraries. These tools provide a structured way to add a11y information. Typically, a plugin will create a dedicated, non-rendering layer group within your frame. This group contains objects or text nodes that specify properties like heading levels, ARIA landmarks (main, navigation), alt text, and logical focus order. The annotations are often named systematically so they can be easily parsed by developers.

WHEN TO USE IT: Use accessibility annotations for any component or screen that will be handed off for development. It's especially critical for complex interfaces with non-obvious reading orders, custom interactive components that need specific ARIA roles, and any design where the visual hierarchy differs from the semantic document structure. It's a key part of a mature design-to-development workflow.

WHEN NOT TO USE IT: Avoid annotating standard, native HTML elements that have built-in accessibility, unless you are overriding their default behavior. For example, you don't need to specify that a <button> is a button. Over-annotating creates noise and can lead developers to ignore the truly important custom specs. Annotations are also not a substitute for using semantic layer names and a logical layer order in Figma, which provide their own implicit accessibility cues.

ONE CANONICAL EXAMPLE: eBay's open-source "Include" plugin for Figma formalizes this process. When a designer annotates a frame, the plugin creates a new layer group named [Frame Name] | Accessibility Layer. Within this group, it generates specific sub-layers for Landmarks Layer and Headings Layer. This creates a predictable, machine-readable structure that developers can reference to understand exactly which parts of the design correspond to nav elements, main content, or H1/H2/H3 tags, removing guesswork from the implementation.