Page History
...
| Do | Don’t | Article setting(s) |
|---|---|---|
Use headerStyle="h1" only for the top-level page title; use h2+ for sections. | Make multiple unrelated headings h1. | headerStyle |
| Keep titles short and localize them. | Ship English-only strings or paragraphs as titles. | textTranslations |
| Left-align section headings for scanability. | Center-align long, multi-line section headers. | textAlign |
| Constrain width to keep lines readable. | Let headings span edge-to-edge with unreadable long lines. | width |
| Add space with a single padding utility. | Chain multiple padding utilities in the paddingClass value. | paddingClass |
| Use a tooltip to clarify a term; add a small delay. | Put critical instructions only in a tooltip. | showTooltip, tooltipTextTranslations, tooltipDelay |
| Ensure sufficient contrast for readability. | Pick text colors with poor contrast on the background. | textColor |
| Show/hide based on explicit rules. | Leave irrelevant titles visible at all times. | displayConditions |
| Initialize dynamic text on mount; clean up on unmount. | Start listeners and never dispose them. | ON_INIT, ON_DESTROY |
| Gate by role when needed. | Expose sensitive titles to all users. | visibilityPolicySetId |
Accessibility
...
- Provide localized, descriptive headings via
textTranslations. - Use semantic hierarchy via
headerStyleand readable alignment withtextAlign. - Ensure legibility through adequate contrast using
textColor. - Avoid tooltip-only information; if used, localize and delay slightly with
tooltipTextTranslationsandtooltipDelay. - Expose deterministic automation hooks for testing via
dataTestIdandid. - Avoid color-only emphasis: pair
textColorchoices with semantic levels inheaderStyle. - Keep headings readable by constraining
width; add spacing withpaddingClassto separate from neighboring content. - Reduce cognitive load by hiding irrelevant headings using
visibilityPolicySetIdanddisplayConditions.
