Making design context a first-class citizen

Annotations have always lived in a strange place for designers. Adding the final measurements, callouts and extra context to a Figma file can make the difference between a smooth handoff and a confused development cycle — yet the manual effort is real. Those non-visual requirements are also scattered: some live in the design file, others in a product requirements doc. Dev Mode's annotations feature is an attempt to bring that context together in a single spec that is purpose-built for both the people who create designs and the people who turn them into code.

Three core problems shaped the scope of the work: annotations take time to produce, they go stale quickly as designs evolve, and they add visual clutter to already busy files.

Different roles, different needs

Designers and developers use annotations for different reasons. For designers, annotations are the place to express qualities that can't be represented in the pixels themselves — accessibility properties, detailed interactive behavior, or the rationale behind a particular choice. For developers, the challenge is often one of curation: design files contain so much information that knowing what to focus on for a specific engineering task can be difficult. The goal was one shared space where a designer curates a spec for developers, calls out details or areas of confusion, and stays in sync with the engineering view while doing so.

This led to a deliberate decision: annotations live inside Dev Mode, not on the Figma canvas. A designer annotating there sees exactly what a developer will see, and can share a link to the spec when done. The intent is not to isolate developers once design work wraps up, but to keep the broader team engaged in the product process.

Annotations that keep up with the design

Traditional annotations are static. A designer marks a design "ready for dev," and everything freezes. But with the always-on, work-in-progress nature of modern product development, designers iterate while developers need a reliable way to track changes. The key conceptual leap was connecting annotations to design properties rather than treating them as free-floating text. When the underlying design changes, annotations tied to those properties update automatically, so developers can trust that what they see reflects the latest state.

The same principle applies to measurements. If a dimension line is bound to actual design values, redrawing is unnecessary when the design inevitably shifts. And because annotations can reference real variables and components from a design system, designers can rely on the spec staying aligned with the codebase over time.

Positioning without the canvas shuffle

Historically, one of the most tedious annotation tasks is the constant rearrangement of frames to carve out space for comments on the canvas. The team explored whether annotations could be visible enough to developers without consuming design canvas real estate at all. The promising direction was automated positioning and display, a significant departure from how files get annotated today — but a more scalable one if the logic could handle the many interactions at play: zooming, panning, scaling, minimizing, selecting, and hovering.

Early prototypes pushed annotations outside the top-level frame being annotated. Beta feedback revealed that with nested frames, this pushed context too far away. Two adjustments addressed the issue:

  • A maximum distance cap for how far an annotation can drift from what it describes
  • Annotations that bump into the window edge and stay visible during panning

The team also experimented with hiding annotations until a frame is clicked. It felt logical in theory, but testing showed important notes could be missed unless a user actively selected a frame. The more intuitive interaction proved to be annotations that automatically expand based on zoom level and position. Iterating on different zoom parameters through a temporary UI slider helped dial in the behavior and overall feel of the system.

Because almost every team approached annotations differently — some treating them as trackable tasks linked to management tools — the design employs an extensibility-first approach via the plugin API, allowing teams to build custom workflows around the feature.

One step in a longer handoff conversation

Annotations in Dev Mode are positioned as a response to widespread user feedback, making the spec the home for design intent and developer context in one place. The feature addresses real friction in handoff, but it isn't treated as the complete answer to designer-developer communication — just one part of the process that felt worth simplifying as Dev Mode continues to evolve.