Documentation
Every component in Grails can have extended usage documentation authored in Markdown. This documentation is intended for the entire product team — designers, engineers, and product managers — to understand how and when to use each component correctly.
Opening the Documentation Drawer
From any component in the library, click the Book icon (📖) in the top-right area of the Component Details Panel. This opens a secondary Documentation Drawer, stacked on top of the component drawer.
The Book icon is only visible when the component has documentation attached. If no documentation exists, the icon is hidden.
What Documentation Contains
Documentation is a free-form Markdown body. Teams typically use it to communicate:
- Usage guidelines — When should and shouldn’t this component be used?
- Composition rules — How does this component work alongside others?
- Content guidelines — Rules for labels, lengths, or copy tone.
- Accessibility notes — ARIA roles, keyboard behavior, contrast requirements.
- Designer notes — Intent from the originating designer explaining key decisions.
- Code references — Links to the corresponding implementation in the codebase.
How Documentation is Authored
Documentation is written in your Figma file using the component’s native description field, or directly within Grails.
Grails syncs the Markdown content as part of the component spec during each Push or Pull sync, keeping the documentation co-located with the component’s source of truth in Figma.
Permission Notes
| Action | Roles | Notes |
|---|---|---|
| Read Documentation | Admin, Editor, Viewer | All roles can open and read the documentation drawer. |
| Edit Documentation | Admin, Editor | Only Admins and Editors can update the documentation content. |