Add guidelines files to a design library

Guidelines help the Figma agent create designs that better reflect your design system. These files help you capture information the agent can’t infer from library assets alone, such as how to follow established patterns and avoid anti-patterns.

You can add guidelines to published design libraries. When someone asks the agent to create a design using a library, the library’s guidelines files are automatically provided to the agent in the background. This additional guidance can help it produce results that align more closely with your system.

What to include in guidelines

The purpose of guidelines files is to give the agent additional information about the library it can’t already find on the canvas or from reading documentation. For best results, we recommended files like:

• overview.md
• guidelines.md
• components.md
• examples.md
• anti-patterns.md
• best-practices.md

For best results, we recommend aiming for three to eight focused files with a combined size under 100 KB. Choose a structure that keeps related rules together without repeating the same guidance across files; repeated information can increase processing time and AI credit use.

Here are a few ideas for what to include in your guidelines:

Focus on where people struggle

Prioritize common mistakes, anti-patterns, and decisions that people or agents find difficult when using your design library. Consider these questions:

• What mistakes does your team make most often?
• What do you most want the agent to get right?
• Where do people have trouble deciding which component, variant, or pattern to use?

When creating the files, use scenario-based dos and don'ts for decisions that are ambiguous or easy to get wrong. For each scenario, include:

• A description of the scenario
• An example of what to do
• An example of what not to do
• The reasoning behind the recommendation

Give the agent a clear recommendation instead of only describing the available options. Call out behavior the agent should never use when the rule has no exceptions. If exceptions exist, describe them so the guidance does not conflict.

Use the agent’s previous outputs to identify gaps

You may need to document conventions that are obvious to experienced designers but the agent cannot infer.

For example: the order in which a screen should be composed, how to distinguish components with duplicate or similar names, which variables, styles, or tokens are required, and which rules apply across pages or platforms.

Fill documentation gaps

There may be situations where the documentation in your Figma library isn’t as strong as what’s available in your codebase. In that case, use guidelines to bring the existing rules into your library to improve the agent’s output.

Start with rules that have the greatest effect on how your designs look and behave. Colors, spacing, and corner radius are a good place to begin and can significantly improve the agent's output.

• Colors: List the color variables the agent should use, explain their semantic roles, and identify combinations or raw values it should avoid.
• Spacing: Describe your spacing scale and how spacing should be applied within components, between elements, and across common layouts.
• Corner radius: List the radius variables in your system and explain which components or surfaces should use each value.

Add guidelines to a design library

Guidelines files are specific to the library they’re attached to. You can add Markdown (.md), plain-text (.txt), or JSON (.json) files.

To add guidelines to a library:

1. Open the Figma Design file that contains the library. You must have edit access to the file.
2. Open the file menu, then click Library > Manage guidelines....
3. Click Upload, then select one or more .md, .txt, or .json files from your computer. The combined size of all guidelines files in a library can’t exceed 200 KB.
4. Click Apply changes.

When complete, the agent can start using the new guidelines when working with this library.

Update or remove guidelines

To manage guidelines already attached to a library:

1. Open the Figma Design file that contains the library.
2. Open the file menu, then click Library > Manage guidelines....
3. Open the options menu next to the guidelines file you want to manage.
4. Choose an action:
   • Rename: Change the file's name.
   • Replace: Upload a new file to replace the existing one.
   • Delete: Remove the file from the library.
5. Click Apply changes.

After the changes are applied, the agent uses the updated guidelines. It can no longer use instructions from a removed file as guidelines for that library.

Frequently asked questions