Figma Comments: Annotate Designs for Better Handoff
Figma comments are the inline documentation for your designs, bridging the gap between a static screen and its intended behavior. Use them to clarify interactions and edge cases directly on the canvas. The footgun is assuming the design speaks for itself.
Why it exists
A static design file is inherently ambiguous. It shows a developer what to build, but not how it should behave, why a decision was made, or what happens in edge cases. This ambiguity forces developers to make assumptions, which leads to implementation errors, bugs, and time-consuming rework.
The mental model
Treat Figma comments as the inline documentation for your design. They are the bridge between a visual mockup and its functional requirements, providing the context a developer needs to build the feature correctly the first time. It's the design equivalent of leaving helpful code comments for the next engineer.
How it works
Designers place comments directly on specific elements within the Figma file to provide context or ask questions. These annotations can tag specific developers, link to external resources like a Jira ticket, or explain a complex behavior. Developers get notified and can view, reply to, and resolve comments within the design file, creating a single, contextual source of truth for design-related communication and decisions.
When to use it
Use comments to document anything a developer cannot infer from the pixels alone. This includes specifying animation timings and easing curves, defining all states of a component (default, hover, active, disabled, error), explaining complex user flows, calling out accessibility requirements like tab order, or noting which API endpoint a component should call. They are essential for clarifying non-obvious functionality.
When not to use it
Avoid using comments for long-form project documentation that belongs in a wiki or project management tool; comments are for contextual, element-level clarification. During handoff, don't use them for general feedback. Once a decision is finalized in a comment thread, update the design itself to reflect that decision. The comment thread is a record of the conversation, not the final specification.
One canonical example
A designer is handing off a login form. The static design shows two input fields and a 'Login' button. The designer adds a comment to the password field: '@dev-lead This field needs to show a password strength indicator as the user types, per the rules in JIRA-123.' Another comment on the 'Login' button says: 'Button is disabled until both fields are valid. On click, show a loading spinner and disable the button until the API responds.' This prevents the developer from having to guess these critical behaviors.
Interview question
Which scenario represents an inappropriate use of Figma comments according to the card?
- a.Providing a detailed overview of the entire project's technical architecture.Correct
- b.Clarifying the loading state and error messages for a data-driven section.
- c.Documenting the specific API endpoint a component should call.
- d.Explaining the tab order and accessibility requirements for a complex form.
Why? this is the answer
The card explicitly states to "Avoid using comments for long-form project documentation that belongs in a wiki or project management tool," making a detailed overview of technical architecture an inappropriate use. The other options are all examples of valid, element-level clarifications that comments are designed for.
Just read this? Test yourself on what you have been reading.
Read the original → depalma.io
- #figma
- #handoff
- #ui design
- #collaboration
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on figma — each one lists the topics its interview covers.
See open roles