Good documentation helps people and agents choose the right assets in their work, but writing documentation for a whole library can take lots of time and effort.
The Figma agent can help speed up the process by creating documentation for the components, styles, and variables in your library file. You can use it to draft documentation on the canvas, refine the suggestions, and add descriptions to each asset.
What's the difference between adding documentation to the canvas and adding descriptions to components, styles, and variables?
Each serves a different use case, and we recommend having both:
- Documentation on the canvas helps people explore your design system through visual examples, usage guidelines, and design specs.
- Descriptions give agents structured context about individual assets, helping them choose which components, styles, and variables to use in a design.
Draft documentation on the canvas
Ask the agent to document assets in the file so other people can get up to speed quickly when viewing the library. The agent has a built-in skill for creating documentation, so you don’t need to specify every detail of how it should lay everything out on the canvas.
Try prompts like:
- Create documentation for all the components on this page. Include design specs, variants, properties, and nested instances.
- Create a table of all color variables in this document. Include a 32 × 32 px swatch filled with each color, its name, hex value, and intended use.
- Document the button component set for a designer learning about its different states. Include usage guidelines.
Tip: If you find yourself customizing the documentation on the canvas and want to reuse your approach for other libraries, consider asking the agent to create a custom documentation skill that captures your requirements. When prompting, you can also attach existing documentation frames if you want it copy pre-existing conventions.
Review and refine the outputs
Review the draft to make sure it explains when and why to use each asset. An agent may identify what a component looks like without understanding its intended purpose. Clear guidance helps distinguish similar components, such as primary and destructive buttons, or cards intended for lists and modals.
For each component, check that the documentation covers:
- Its purpose and intended use case
- When to use it instead of a similar component
- Its available variants and states, such as hover, focus, error, and disabled
- Any accessibility requirements, such as minimum color contrast or expected keyboard interactions
For styles, explain when to apply them—for example, “Use for body text on light backgrounds only.” For variables, explain values whose purpose may not be obvious, such as the semantic color role of color/surface/danger or the intent behind a spacing value.
Add descriptions to components and variables
To give agents explicit context about each asset, make sure its description field is filled out.
A description provides documentation for an asset as plain text. These descriptions appear in search results, helping people and agents find the right resource.
Once you’ve reviewed the documentation on the canvas, ask the agent to update each component’s description to match. You can add descriptions to components, styles, and variables directly in Figma.
Try a prompt like: "Use the documentation on the canvas to update each component, style, and variable description. Add related keywords so people can more easily find this asset when searching."
How do I teach the agent how to read between the lines and follow established patterns or avoid anti-patterns?
Use examples to show how components work together in a complete design, and guidelines files to explain the decisions behind those designs: which patterns to choose, what to avoid, and when exceptions apply. Keep guidance about individual assets in their descriptions, and use guidelines files for conventions that apply across your library.
Learn more about using guidelines and examples in your libraries.