Patterns

A pattern describes how something is put together from your components: an empty state, a step that asks for a PIN, the home of an account. It is written so that a person can read it and an AI agent can follow it.

Open Patterns from the Knowledge menu in the top bar, next to Docs.

The overview and the left panel

The overview shows every pattern as a card: its kind, whether it is a draft or published, the problem it solves, a small picture of its shape, the documentation it carries, who wrote it and when it last changed. Drafts come first.

The left panel starts with Overview, then lists the patterns, drafts first and then published. Search by name or by the problem a pattern solves, and filter by Status and Author. The + next to the search starts a new pattern (admins and editors).

A pattern is built by composition

A pattern is made of sections. A section describes one use: what it is for, how many it takes (exactly one, optional, one or more…), the components or other patterns it accepts, an optional content guide, and its rules. A section can hold parts, smaller sections inside it, such as a card’s preview and its empty state.

Its kind follows from how it is built, and changes as it grows:

Kind	Built from	Drawn as
Section	one section	a single card
Screen	several sections in one screen	one column with the sections from top to bottom
Flow	several screens	the screens side by side, in order, with an arrow between each

A component a section accepts is shown as it is in documentation: click it to open the component. It can come with the values its properties must take there, such as variant: primary.

Rules say what holds, each with its strength: must, should or may. A rule applies to one section, to a whole screen, or to the whole pattern.

The Overview panel on the right lists the pattern’s parts by aspect — its intent, its screens and sections, its rules by strength, its documentation — and takes you to each one.

Edit a pattern

Admins and editors edit a pattern on its own page, like documentation in Docs:

1. Click Edit in the bar at the bottom.
2. Change the name, what it solves, when to use it and when not, and its sections. Add a section turns a section pattern into a screen; Add a screen turns it into a flow. Each section has its own controls to move it, remove it, add a component or pattern, add a rule or add a part.
3. Click Save. Grails checks the pattern and, if something is missing (a section with nothing it accepts, a blank name…), lists every problem at once. When it is saved, the page goes back to reading.

Done leaves the editor; if something is unsaved, it asks whether to save or discard it.

While editing, the settings button next to a component a section accepts marks it as the default in that section (one per section) and narrows the values of its props there, from the props its spec declares (variant: primary). Each Avoid when situation can name the pattern to use instead, and a section’s content guide can take a maximum length.

If someone else changed the pattern since you opened it — another person, or an AI agent through the API — Save says so and saves nothing, so their changes are never overwritten. Reload the page to see them, then edit again. Publishing works the same way: Publish and Unpublish change only the status.

To start a new one, click + in the left panel. A new pattern is one section; it gets its address when you first save it.

Its documentation

Under its sections, a pattern has its own documentation, written with the same blocks as Docs — text, titles, tables, guidelines, checklists, images… — and the same categories (Usage, Content Guidelines, Accessibility…). It is edited with the pattern: click Edit, use Add block in the bar at the bottom, and Save writes the pattern and its documentation together. The categories it uses appear on its card in the overview and in the Overview panel.

Publish

A new pattern is a draft. Click Publish in its head to publish it, and Unpublish to take it back to draft. Viewers can read patterns but not edit or publish them.

Export and delete

Export in the bar at the bottom offers two options:

• Markdown downloads the pattern as a .md file with its intent, sections, rules and documentation, formatted for a pull request, wiki or AI agent.
• Copy as Markdown copies that same text to the clipboard.

Admins and editors delete a pattern from More → Delete pattern. A dialog asks to confirm (Delete “Pattern Name”?). If other patterns use it, Grails names them before you confirm: they will show it as a pattern that no longer exists until someone removes it from them. A deleted pattern cannot be recovered.

The Updated date of a pattern changes whenever you save edits to its composition or to its documentation blocks.

Team activity

In the team activity panel, every pattern event appears when someone creates, edits, publishes, unpublishes or deletes a pattern. The entry names the pattern and links to its page when the row is about a single pattern of the current project. Grouped entries (such as created 3 patterns) and events from other projects show the names without a link. The deleted the pattern X entry has no link either. Earlier entries of a pattern that was later deleted keep their link, and following it lands on a not found page. When a pattern is created or updated by an AI agent through the API, the second line marks it with Through the API.

The Graph tab

Graph shows the pattern one step around: the components and patterns it uses, and the patterns that use it. A component is drawn as a rounded box and a pattern as a diamond; click a pattern to open it.

A component’s own Graph in Docs shows the other side: the patterns that use it, and the patterns that contain those, drawn as diamonds. A draft says so under its name. The Patterns chip at the top of that graph shows or hides them.

Find and mention a pattern

Search finds patterns: press ⌘K and type its name. Drafts appear too, marked Draft. In any documentation, type @ and pick a pattern to mention it; the mention is a link to the pattern’s page. While you are editing, it opens in a new tab, so nothing you have not saved is lost.

When a pattern needs a look

A pattern names your components, and your design system keeps changing. When a component it names was deleted, or no longer has a property or a value the pattern asks for, the pattern shows a warning at the top that says what changed and where. The pattern itself does not change on its own: you decide what to do.

Patterns and AI agents

Patterns are also written and read through the API and MCP, by AI agents with an API key that has the write:patterns permission. An agent writes the same composition you see here.