Docs

Most documentation in Grails hangs off something synced from Figma: a component, a token collection, a text style. That covers “how do I use this button” well, and covers nothing else. A design system also needs the writing that belongs to no single component — voice and tone, how to name things, when to break a rule, what your accessibility floor is.

The Docs section is where that writing lives. A page is documentation you create and own: it does not appear because a sync found it, and it does not disappear when someone deletes a component in Figma.

Overview

The section is split by where the documentation comes from, not by what kind of thing it describes:

• Library — documentation attached to entities synced from Figma: components, tokens and styles. The list tells you which ones are documented and which are not, and clicking a row opens that entity’s documentation panel so you can write there.
• Pages — documentation you write here. This is what the section adds.

The split exists because the two halves have different lifetimes. A component’s documentation appears and disappears with the sync; a page exists because someone decided it should, and only stops existing when someone decides otherwise.

Above them sits the toolbar, with the section title and — if your role allows it — the New page button.

Note

Before anyone has written a page, the Pages half shows a short empty state explaining what pages are for. Library always has content: it lists every synced entity, documented or not, because knowing what is missing is half of what it is for.

Pages

How pages are grouped

Pages are grouped by their path — a label like Brand or Foundations that several pages can share. Groups appear as headings, in alphabetical order, and pages with no path are collected first under Ungrouped.

A path is not a folder, and the difference is worth knowing because it explains what you cannot do:

• There is no folder to create, rename or delete. Groups exist only because pages point at them, so a group with no pages simply stops appearing.
• A page’s group never affects its link. A page’s address comes from its title when you create it and then stays put, independently of any group it is in — which is what will let a later version move pages around without breaking anything you have shared.

What each row shows

• Icon — the emoji you picked for the page, or a generic document icon if you have not picked one.
• Title — the page’s name.
• Summary — the short line you wrote under the title, if any. It is shown here so the list is useful without opening anything.

Creating a page

Press New page and give it a title. The title becomes the page’s address, so Voice and Tone becomes a page at /docs/voice-and-tone, and Grails opens it for you straight away.

Two things happen automatically and are worth knowing about:

• Two pages can share a title. The second one gets a slightly different address; neither creation fails and you are not asked to pick another name.
• Renaming later keeps the original address. This is deliberate: a link you shared in Slack three months ago keeps opening the right page after someone tidies up its title.

Writing a page

Opening a page shows its own editor, with the page’s identity at the top and its content below.

The page header

• Icon — click it to pick an emoji. It is what makes a page findable in a long list at a glance.
• Title — click and type. It saves by itself, shortly after you stop typing.
• Summary — one line describing the page, shown in the section list beside the title.

The header saves on its own as you edit it. The content below does not — see the next section.

The content

Below the header is the same block editor used for component documentation, so everything you already know about writing documentation in Grails applies here: section titles, prose, tables, specs, guidelines, use cases, checklists, props, images, files, and mentions of other entities.

Three shapes are worth knowing apart before you start a long page, because they look interchangeable and are not:

• Title breaks the page into sections. It is a heading with a level you choose, and it carries no body — the prose that follows goes in a Text block below it.
• Table lays values out in rows and columns: breakpoints and their sizes, a support matrix. You edit it in place, dragging column widths that then stay where you put them.
• Specs defines. Each row names something and says what it is — the shape you want for a glossary, a set of parts, or the states of a component.

Full guidance on choosing between them, and on what each editor offers, is in Documentation blocks.

Caution

The blocks are saved when you press Save, not as you type. Adding, rewriting, reordering and removing blocks are all changes you commit at once — and if you try to leave with unsaved work, Grails asks before discarding it.

Navigating away with an in-app link or the browser’s back button is the one case that does not ask. Save before you leave the page.

Mentioning things, and being mentioned

Inside a page you can mention any component, token or style, and the mention resolves to that entity’s current name — so a rename in Figma updates your page by itself, rather than leaving the old name written down.

Clicking a mention opens that entity’s panel on top of the page, so you can check something without losing your place.

Available actions

Action	Roles	What happens
Read pages	Admin, Editor, Viewer	Anyone on the team can read every page in the project
Create a page	Admin, Editor	The page is created and opened for editing
Rename a page	Admin, Editor	The title changes; the page’s link stays the same
Edit the summary or icon	Admin, Editor	Saved automatically, shortly after you stop typing
Write and save blocks	Admin, Editor	Saved together when you press Save

Not available yet

Moving a page between groups, and deleting a page, cannot be done from the interface yet. Both work underneath — a page’s group is stored and honoured, and pages can be removed — but neither has a control in this release, so a page you create stays where it is until a later version adds them.

Deleting a page

Danger

When deleting arrives, it will not be undoable. A page and everything written in it are removed permanently.

This is different from deleting a component. A component’s documentation is kept and comes back if that component is ever re-synced from Figma — because a sync can bring the component back. Nothing can bring a page back, so there is nothing for a restore to hook onto.

Permission notes

A viewer can read every page in the project and cannot change anything: no New page button, no editable title, summary or icon, and no way to add or edit blocks.

Editors and admins have identical permissions over pages. There is no per-page permission — a page is readable and writable by exactly the people who can read and write the project it belongs to.