Follow these practices to build templates that are easy to read, maintain, and use.
Clarity first
Messages should communicate clearly and concisely.
Good: Clear hierarchy and scannable — use a header for the main title, sections for content, context for metadata, actions for buttons.
Bad: Long paragraphs without structure. Prefer short blocks and lists over walls of text.
Visual hierarchy
Use block types to create structure:
- Header — Main title or status
- Section — Primary content
- Context — Metadata, timestamps, authors
- Actions — Buttons for user actions
- Divider — Optional visual break between sections
Put the most important information at the top. Use headers and sections to separate ideas.
Placeholder and data practices
- Use descriptive placeholder names:
{{user.email}} not {{e}}
- Pre-format dates and numbers in your data when possible
- Keep sample data in sync with entity definitions if you use entities
- Test with realistic data (empty, one item, many items) for directives and table blocks
Interactive elements
- Use clear, action-oriented button labels (“Approve”, “View Details”) not vague text (“Click here”)
- Use Primary (green) for the main action, Danger (red) for destructive actions, Default (gray) for secondary
- Ensure each button has a unique action ID
Next steps
