Template design best practices

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

​

Information density

Balance completeness with readability. Show key info at a glance; use buttons or modals for extra detail when needed. Avoid overloading a single message with too many fields or buttons (for example, present one primary action and a few secondary choices).

​

Placeholder and data practices

• Use descriptive placeholder names: {{user.email}} not {{e}}
• Pre-format dates and numbers in your data when possible
• For templates built around the same service object, define a reusable entity and preserve the source field paths to reduce per-template mapping work
• Keep sample data aligned with the incoming object shape, including optional and nested fields
• 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

​

Accessibility and mobile

Use descriptive image alt text and meaningful link labels. Do not rely on red/green color or emoji alone to communicate status: include words such as Approved or Failed. Keep essential information in text. Check the message on a narrow screen. Wide tables, long labels, and dense cards are harder to scan; show a summary and link to the complete record. Avoid a carousel when users need to compare every item at once.

​

Notification hygiene

Reserve user mentions for information that needs that person’s attention. Batch routine updates into a digest and make failure/approval messages distinct. A message should tell the reader what happened, why it matters, and what to do next.

​

Before activating a version

Preview normal, empty, missing, and long inputs. Test each conditional branch, resolve all unexpected placeholder text, and verify button destinations in a test channel. Review the limits, especially expanded block count and interactive metadata.

​

Next steps