Figma Docs widget

The Grails Docs widget puts a component’s Grails documentation on the Figma canvas. You insert it next to the component, and anyone who opens the file can read it there, without leaving Figma.

Before you start

• The file has to be linked to Grails. Open the Grails plugin in the file at least once (version 1.8.2 or later): that links the file to its Grails project, and the widget reads that link. If the file is not linked yet, the widget tells you so.
• You need your Grails plugin token to choose a component and to refresh. Find it in Grails → Team Settings → Integrations → Plugin Token. Each person uses their own; it is saved only on your device.

Show a component’s documentation

1. In Figma, insert the Grails Docs widget on the page where the component lives.
2. Click Choose a component. The first time, paste your plugin token.
3. The widget lists the components on the page. You can pick any one that Grails holds, documented or not; the ones Grails does not hold yet are listed too, greyed out, until you sync them with the plugin.
4. The documentation appears on the canvas, each block drawn as on the component’s page in Grails: its category (Usage, Dev Specs, Brand…), Do and Don’t with their thumbs, checklists with their boxes, guidelines, specs and tables.

At the top, the widget shows the component’s sync state (Synced, Changed in Figma, Removed from Figma) and a line with when its documentation was last updated and by whom: Last update: Oct 21, 2026 · By Ana. A component with no documentation yet says so under its name.

Structured data for agents

Under the documentation, the Structured data in Grails panel shows what Grails holds about the component beyond what the canvas draws, organized so a person or an AI agent reading the canvas knows what exists and how to query it:

• Component key (or Node id when Grails has no key recorded for the component yet): the reference identifier. The component key is the same across files.
• Dates line: shows when the component was synced, when it last changed, and when its documentation was last edited (Synced <date> · component changed <date> · docs edited <date>). If the component changed after its documentation was last edited, an amber warning states: “The component changed after the documentation was last edited.”
• Measured in Figma: counts what was captured from the design file:
  • Properties: component property count.
  • Anatomy: detected structural elements.
  • Variants: variant count.
  • Tokens: bound design tokens.
  • Styles: every style applied to the component (text, color, effect and grid).
  • Uses: components this component contains.
  • Used by: components that consume this component.
• Declared in Grails: counts what team members added in Grails:
  • Documentation: total count of documentation blocks. Blocks that are not documentation for a person (agent instructions and the child and parent component lists) are neither shown on the canvas nor counted.
  • Patterns: patterns that include this component.
  • Relations: declared semantic relationships.
• Query it: lists the exact commands to fetch full details:
  • MCP: getEntities({ ids: ["<key>"] }), then call getComponentSpec, getEntityGraph, or getEntityDocumentation with the resulting canonical ID.
  • REST: GET https://api.grails.design/v1/components/<canonicalId>/spec.

When a figure is missing, the panel says so instead of showing a zero: not captured yet on Properties, Anatomy and Variants until a spec has been captured for the component, and none recorded on Tokens, Styles, Uses, Used by, Patterns and Relations when Grails has recorded none. That means none were recorded, not that none exist.

Note

Because Figma AI agents see the canvas as an image rather than text layers, this panel displays the reference keys and query commands directly in the visual layout so an agent can copy them and call the tools.

The widget’s menu

Select the widget to see its menu:

Action	What it does
Refresh	Brings the latest documentation from Grails.
Change component	Lets you pick another component on the page.
Open in Grails	Opens the component’s page in Grails Docs.
Text size	Draws everything at 1x, 2x or 3x. It is saved in the file, so everyone sees the same size.
Forget my token	Removes your token from this device.

Who sees it

What the widget shows is saved in the file, so everyone who opens the file sees it, including people who have no access to Grails. Refreshing it needs a token from an admin or editor of the Grails team.

What it does not show yet

The widget does not show images yet. Images, files, embedded Figma frames and examples appear as a line that names them; open the component in Grails to see them.