What can be documented

Documentation in Grails does not hang off a place: it hangs off a thing. A block always belongs to a concrete entity, and that is what makes a component’s documentation show up next to the component, survive a rename, and disappear if the component is deleted.

The eight

Entity	Where it comes from	Documented from
Component	synced from Figma, code, or both	its page in Docs
Token	synced from Figma	its page in Docs
Style	synced from Figma	its page in Docs
Token collection	synced from Figma, code, or both	its page in Docs (which also shows its tokens)
Screen	synced from Figma	the screen panel
Flow	you create it in Grails	the flow panel
Project	exists as long as the team does	Docs
Page	you write it	Docs → Pages

The split that matters: synced and your own

The first five come from a source (Figma or repository code), and that decides their lifetime. They appear when someone syncs and disappear when they leave the source. A component and a token collection can each come from Figma, from code (uploaded with grails-cli sync), or live in both when matched. Its documentation belongs to the component canon: if a component is deleted, what you wrote about it goes to the trash — and if it comes back, it comes back with its documentation, not blank. A component gets it back when it is synced again from the same source. In a copy of the file it is another component, and starts with no documentation.

The last three exist because someone decided they should. A flow, the project and a page do not depend on any sync, so their documentation cannot be orphaned.

Why not everything accepts everything

The Props block only exists on a component, and that is not an arbitrary restriction: it does not store the list of properties, it reads them from the component’s spec. On a token there would be no spec to read from, so the menu does not even offer it.

It is the only case today. The other eleven shapes live on any of the eight entities.

A token collection’s page: its tokens, by role

The page of a token collection shows the tokens it holds, grouped by what each one is for, above its documentation. You do not write that part: it is read from the collection every time, so it is never out of date.

Each group is a role, drawn the way its role calls for:

Role	What you see
Color	a swatch and its hex, over a checkerboard when it has some transparency; it can also be seen as a grid of swatches
Font family	”Aa Bb Cc” in that family, and its name
Font size, Font weight, Line height, Letter spacing	a sample of text with that size, weight, line height or tracking
Paragraph spacing	two lines of text that far apart
Corner radius	a box with that radius
Spacing	a bar as wide as the value
Size	a square of that size
Stroke width	a line that thick
Opacity	the colour at that transparency
Effect, Motion, Text, Boolean	the value, with a bar for a duration and an on or off for a boolean
Unknown Role	the value and its type, for the tokens Grails could not place

In the table, a token with a value per mode (Light and Dark, say) has a column for each one, the default mode first. A token that points at another token shows the value it ends up at and the name of the token it points at.

How a token gets its role. Grails reads, in this order: whether it is a colour or a boolean; the scopes you set in Figma’s variables panel; the words in the token’s name, in English and in Spanish (Font size/md, espaciado/4); and the words in its collection’s name. The first one that says it decides. A token that nothing places goes to Unknown Role, at the end of the list.

Set the scopes in Figma

A token left on “All scopes” has nothing to read but its name. Giving a spacing token the Gap scope, or a radius the Corner radius scope, places it for sure, whatever it is called.

Very large values are drawn at a limit so one outlier does not push the group off the page, and the number is always printed in full beside the picture.

Export → Markdown writes the same groups, as a table per role, before your documentation.

A collection that lives in code is read the same way: one entry in the Docs panel, a Design / Code switch in its header when it lives in both, and the same groups by role over the tokens your repository holds, with one column per mode in the order the repository gives them. Roles are placed with the same signals, except that a code token has no Figma scopes, so its type, its name and its collection’s name decide. A collection that lives only in code can be read but not edited for now. A collection that lives in code has the detail.

After the tokens come your documentation blocks, as on any other page.

What is documented and what is synced are not the same

A component brings its name, variants, props and thumbnail from Figma. None of that is documentation — it is the spec, and it updates on its own.

Documentation is what a person knows and the Figma file does not say: why this component exists, when not to use it, what broke the last time someone used it wrong. That is the part that cannot be synced, and the only one that is lost if nobody writes it.

⇢ Documentation blocks — the twelve shapes your writing can take, and how to pick between them.