Creating Guidance Pages gives your system the structure it needs to be usable across teams. These pages explain what patterns and tokens are, how to use them, and how to apply them consistently and accessibly. Use this tactic whenever you launch or update a pattern or token, especially ones with complex behaviour or accessibility needs.
Creating Guidance Pages
How to
-
Cover the basics
Explain what it is, when to use it, and the outcome it supports. Keep it short and clear.
-
Show visuals and anatomy
Add diagrams or screenshots with labels for key parts, variants, and states. Use Creating Specs to validate technical details if needed.
-
Document behaviour and interaction states
Outline how the component responds to hover, focus, active, disabled, or transitions. Reference the Interaction States tactic to capture patterns consistently.
-
Add accessibility guidance
Include ARIA roles, focus order, screen reader expectations, and error handling. Tie back to your Accessibility Review findings.
-
Provide content guidance
Show wording examples for labels, errors, and instructions. Align with Tone of Voice and Content Strategy so docs reflect system values.
-
Include examples and links
Show best practices and common mistakes. Link to design files, code implementations, and tokens. Use Versioning to ensure links stay current.
-
Test and refine
Run Guidance Clarity Tests to check pages are skimmable, consistent, and easy for new teams to follow.
Draft faster: Generate first drafts from specs—anatomy, props, accessibility lists. AI handles about 80% of technical documentation. You add "when to use" guidance, rationale, and context that needs product knowledge.