Proposal: Using descriptions, notes and annotations in Figma

Within Figma, there are three primary ways to add descriptive, helper content for components and design assets:

Method	Description	+ Pros	– Cons
Layer	Text layers within the design document	• High visibility • Helpful at the point of design • Anyone with view access can see	• Not searchable or dynamic • Not seen at the point of use • No programmatic relationship to a component
Comment	Comments are added and viewed when in the comment mode	• Threaded, can be resolved, dynamic • Helpful at the point of review • Anyone with view access (while authenticated), and higher can participate — does not require a paid Figma license	• No visibility unless in comment mode • Resolved comments are only visible if a user’s settings allow them to be • Tied to where the comment is placed on the page, not programmatically connected to any part of a design
Component description	Descriptions can be added to each component within the properties panel	• Searchable • Always connected to a component • Visible on instances • Relatively visible • Helpful at the point of use	• Not a lot of space • Visible only to editors

Proposal

Standardize what kind of content and fidelity we want to leverage within each of the three methods outlined above. I'm proposing the following:

Layer

• Audience: designers and users of the design file
• Use text layers for headings to categorize variants and instances

Comment

• Audience: everyone
• Use comments to engage with others in a conversation about the design. These conversations can be resolved and will persist as part of the history of the design file.
• Use comments for annotations on instances, where descriptions are not possible
• Use comments when the intended audience may not have edit permissions, since component descriptions are limited to editors at the point of use. This would be beneficial for developer handoff, similar to how we use Sketch Measure today.

Component description

• Audience: designers who are referencing or using final components in new designs
• Use descriptions to identify the purpose and intended use of the component
• Consider using keywords in the description as meta for search. e.g., “Keywords: wrench, tool, admin” used for a wrench icon that is used to represent admin in the product.
• Consider mentioning where the component is used in the product, or for what purpose
• Include usage notes, like max-width, that are applicable at the point of use
• Keep descriptions short, when possible

Examples

Layer	Comment	Component description

/cc @tauriedavis @pedroms @andyvolpe @lvanc