Components

The Components section is your comprehensive library of all design system components synced from Figma. It lets you explore component sets, inspect individual variants, view property definitions, understand which tokens are bound to each component, and monitor structural health over time.

Layout

The layout is divided into a groups panel on the left and a main content area on the right. On a wide screen the panel floats over the edge of the page as a card or is docked to the side, as chosen in User Settings → Appearance → Side panels.

• Head — Over the list, the section’s name, how many components it shows, and the Design / Code switch. See Design and Code.
• Search — A field pinned at the top of the groups panel. Filter components by name, their group included, in real time.
• View Toggles — In the bar at the foot of the list, List and Grid switch between a List (table) view and a Grid (card) view. Only in Components: Assets is always a grid, and its bar has Grid size instead.
• Filters — Four buttons pinned above the tree of groups, each showing its name and what is picked:
  • Status — All, Synced, Outdated, Deleted in Figma, Schema Upgrade Required or Action Required.
  • Variants — All, With variants or Without variants.
  • Documentation — All, Documented or Not documented. A component is documented when it has at least one documentation block.
  • CHI — All, Poor, Monitor or Good. Good includes Optimal. A component’s level is the one its CHI shows, in the list and in its panel. A component with no CHI (a dash in the list) shows only under All.
• Components and Assets — Two sections of the top bar’s Design System menu. Assets lists only the components marked as exportable assets, which you can download. On a phone, choose it from the sections menu.
• Source — In the bar at the foot of the list, one picker chooses which Figma file, or which type of file, the list shows. The picker appears only when the project’s components come from more than one Figma file. Its menu has All sources, then the files grouped under Libraries and Snowflakes (and Other files for a file whose type is not known yet), each with how many components it holds. When a group has more than one file, the menu also offers All libraries / All snowflakes. The button says what is picked, for example “Design System · Library”.

The search and the filters narrow both the list in the centre and the tree of groups in the sidebar, and they work inside the source picked. While a search is typed, every folder of the tree opens so no match is hidden. When nothing matches, the sidebar and the centre both say so, and both offer Clear search and filters.

Design and Code

The switch in the head, over the list, picks where the components come from:

• Design: the components synced from Figma. Everything else on this page is about them.
• Code: the components your component library’s repository uploaded with grails-cli sync, by name, with the file each one is declared in and its CHI. The left panel groups them by folder. A component the repository no longer declares is not listed.

Click a component on the Code side to open its panel: its file, its repository and the commit it was read at, with a link to the file; its props, with their type and default; its CHI and the five measures behind it; and its stories. Design Coverage shows a dash when the component has no stories, because there is nothing to measure it from.

The Code side is read-only: a repository’s components change in the repository. It has no filters, no grid and no Assets; those are about the Figma component.

• Several repositories: the head names the one you are looking at, and its menu lists the others.
• A link keeps the side. The address carries it (?view=code), so a link someone shares opens Code if that is what they were looking at.

When the Code side has nothing to show, it gives the same explanation as Tokens: what Code is and the three steps to turn it on.

Where a component lives

The Lives in column, and the badges of a card in the grid, show two icons: a palette for Figma and code tags for your code. An icon is lit when the component is there and grey when it is not, and hovering it says which. A component you matched with its code (see Pending matches below) has both lit. It is one row, also when it is in more than one Figma file, and then the row says how many (2 files). The Code side has the same column, with the Figma icon lit for a code component that is also in Figma. The Design and Code switch at the top wears the same two icons.

Pending matches

Grails looks for components that are the same one kept in two places: a Figma component and a component in your code with the same name, or the same component key in two Figma files. It does not join them on its own. When it finds some, admins and editors see a callout over the list, N possible matches to review, and Review opens a panel with each pair.

Each pair says why it was proposed (Match by Name, or Match by Key for the same component key in two Figma files; hover it for the sentence) and is one card with both sides, joined by a link icon. Each side starts with the icon of where it comes from (a palette for Figma, code tags for your code) and its name; under the name, where it lives (the Figma file; the repository, and the file below), its props and its CHI. Click a side to open it before deciding. The decisions are at the foot of the card:

• Match joins them: from then on Grails treats them as one component, and its panel has a Figma and Code switch at the top, to see either side without leaving it. You can undo it later (see Unmatch).
• Not the same dismisses the pair, and Grails will not propose it again.

Both ask for confirmation first. If two components cannot be joined, for example because both already have a component from the same repository, the pair stays in the list with the reason.

Unmatch

A match can be undone. The Pending matches panel has two tabs: To review, with the pairs above, and Matched, with what has been matched, newest first, whether a person matched it or Grails did on its own. Each card says who matched it (you, a teammate, or Grails automatically) and when, and admins and editors see Unmatch at its foot. A matched component’s panel has the same action in the ⋯ menu beside its Figma and Code switch.

Unmatching asks for confirmation first. The two become separate components again, each with its own documentation. Anything that changed after the match stays where it is now, and the notice says how many things did. Grails will not propose the pair again.

Some matches cannot be undone, and their card says why instead of offering the button:

• a match made before Grails kept a record of matches;
• a match whose component was matched with something else since: undo that later match first.

Browsing Components

Components can be browsed in two distinct modes:

List View

A structured table ideal for scanning large libraries quickly.

• Components are grouped by their Figma file path.
• Each row shows the variant count and current sync status.
• A Snowflake chip beside a component’s name marks a component that lives in a Figma file that is not a library. A library component has no chip.
• Open in Figma, the icon button on a row, opens the component in its Figma file. It is shown only when Grails knows the real key of that file. Grails learns it in one of two ways: Figma gives it to the plugin (development builds and private organization plugins), or a person links the file from the Grails plugin in Figma, with its Link this file step. Until then the row has no button.

Grid View

A visual card layout ideal for spotting components by thumbnail.

• Displays realistic rendered thumbnails pulled directly from Figma.
• Status badges and variant counts are visible at a glance.
• A Snowflake chip among a card’s badges marks a component that lives in a Figma file that is not a library.

Assets

Assets is always a grid. Grid size, in the bar at the foot of the list, makes its cards Large (the default), Medium or Small, and this browser remembers the size you pick.

Downloading Assets

In Assets, you can download what you see, straight from Figma with your team’s Figma token (set by a team admin in Team Settings). Every download asks you for the format first: SVG or PDF, PNG at 1x, 2x, 3x or 4x, or JPG at 1x or 2x.

• One asset — click the download button at the top right of its card.
• A whole group — click ZIP in the group’s header, beside Remove group from Assets. You get one ZIP with the group’s assets as the grid shows them: the search and the filters narrow what goes in. A ZIP holds up to 500 assets.
• If Figma cannot render some assets of a group, the ZIP still arrives, with a missing.txt file that names them and says why.
• Grails asks Figma for each asset by the key of its Figma file. A file synced with the Community plugin needs its link pasted once in Link this file, in the Grails plugin; until then its assets do not download, and the message says so. In a ZIP they are listed in missing.txt.
• If the team has no Figma token, or Figma’s rate limit was reached, the download does not start and a message says what to do. Figma limits how often a token can export: a token from a Dev or Full seat allows a few exports a minute, one from a View or Collab seat only a few a month.

What’s Inside Each Component

Every component in Grails exposes four key areas of information, each with its own dedicated page in this section:

Section	What you’ll find
Component Details Panel	Overview with health score, relations and patterns, tokens
Documentation	Rich-text usage guidelines authored in Figma or Grails
Component Health Index	Structural quality score with sub-metric breakdown

Available Actions

Action	Roles	Description
Switch View Modes	Admin, Editor, Viewer	Toggle between List and Grid using the List and Grid buttons in the bar at the foot of the list (Components view).
Change the Grid Size	Admin, Editor, Viewer	In Assets, use Grid size in the bar at the foot of the list: Large, Medium or Small. This browser remembers it.
Search Components	Admin, Editor, Viewer	Filter the list or grid, and the tree of groups, by component name or group.
Filter Components	Admin, Editor, Viewer	Narrow the list or grid, and the tree of groups, by Status, Variants, Documentation or CHI. When nothing matches, Clear search and filters removes them.
Switch between Components and Assets	Admin, Editor, Viewer	Open the Design System menu in the top bar and choose Components or Assets. On a phone, they are in the sections menu.
Download Assets	Admin, Editor, Viewer	In Assets, download one asset from its card, or a whole group as a ZIP from its header, in the format you pick. It needs the team’s Figma token.
Choose a Source	Admin, Editor, Viewer	Use Source, in the bar at the foot of the list, to list the components of one Figma file, or of all the libraries or all the snowflakes when that group has more than one file. It appears only when the project’s components come from more than one Figma file.
Inspect Details	Admin, Editor, Viewer	Click a component to open the details panel.
Open in Figma	Admin, Editor, Viewer	Click the icon button on a row, or Open in Figma in the details panel, to open the component in its Figma file. It is shown only when Grails knows the real key of that file.
View Documentation	Admin, Editor, Viewer	Click the Book icon in the drawer to open usage guidelines.

Permission Notes

All roles (Admin, Editor, Viewer) can browse the component library. Only Editors and Admins can push or pull updates via the Figma Plugin — but the results are always visible to Viewers here.