Add richer descriptions to variable collections, groups, and modes
Figma currently allows us to add a description and scope to an individual variable. However, the description field is a relatively limited text input, and documentation cannot be added to the broader structures that give variables their meaning.
Proposed Description Levels
It would be helpful to support descriptions at multiple levels of the variable system:
-
Variable collections: Explain the collection’s purpose, intended use, architecture, and relationship to other collections.
-
Variable groups: Document how a specific category of variables should be applied and distinguish it from related groups.
-
Modes: Explain the context represented by each mode, when it should be applied, and any important differences or limitations.
-
Individual variables: Retain variable-specific guidance, but provide a more capable description experience comparable to component documentation.
Ideally, these descriptions would support multiline content, links, and basic formatting instead of being limited to a simple text field. They should also be visible where people browse, apply, inspect, or consume published variables, including in Dev Mode and library workflows.
Considerations for Description Hierarchy
One important consideration is how hierarchical descriptions should interact with descriptions already added to individual variables. A collection, group, or mode description should provide shared context without overwriting or duplicating the variable-level description. For example, Figma could display the relevant collection, group, and mode guidance as separate contextual sections alongside the individual variable’s own documentation.
This would make complex variable systems significantly easier to understand without forcing design-system teams to repeat the same guidance across many variable rows or maintain critical usage instructions somewhere outside Figma.
Open Questions for the Community
How should these description levels be presented without creating too much visual noise? Should descriptions be inherited, shown as separate contextual information, or selectively surfaced when browsing and applying variables? I’d be interested to hear how other teams would expect collection, group, mode, and individual-variable documentation to work together.
Other Related Community Posts
These listed discussions make strong and valuable points about adding descriptions beyond individual variables, particularly at the variable collection and variable group levels. I especially appreciate that they identify the burden of repeating similar guidance across many variables. Their suggestions establish a solid foundation for improving variable documentation in Figma.
My request is related, but it is not quite the same. The earlier discussions primarily propose adding description fields to collections and groups. My proposal expands that idea into a broader documentation hierarchy that also includes modes and richer, component-like documentation for individual variables.
It also considers how descriptions at each level should work together, how existing variable-level descriptions should be preserved, and how documentation could be surfaced without creating duplication or visual noise when variables are browsed, applied, inspected, or accessed through libraries and Dev Mode.
Credit to the contributors for clearly identifying the core need! My proposal builds on their ideas while addressing a broader and more interconnected use case.