Canopy Writing Principles — Best Practices

This skill provides guidance on tone of voice and content writing for applications built with Canopy.

Apply this skill when writing any UI text: headings, body copy, labels, error messages, or button text.

---

Brand Personality

Write in a way that reflects three core traits:

• Bright — bring intelligence and energy; demonstrate expertise in accessible language.
• Calm — keep it simple, concise, and confident; let the facts speak.
• Real — be down to earth, warm, and transparent; write like you speak.

---

Content Principles

1. Lead with the benefit — tell users what's in it for them early on.
2. Understand your audience — explain acronyms, avoid jargon, write at reading age 9.
3. Active, not passive — "The system updated your address" not "Your address has been updated".
4. Draw pictures with words — prefer concrete objects over abstract ideas.
5. Structure your thoughts — order messages logically before you write.
6. Edit and simplify — cut unnecessary words; avoid long sentences.
7. Use "you" — prefer "you" over "we" to involve the reader.
8. Write like you speak — use contractions ("You're" not "You are"), avoid clichés.

---

Practical Rules

Headings and Titles

• Set expectations — titles should describe what the content contains and how it helps.
• Keep titles short and actionable: "How do I update my address online".

Button Text

• Use descriptive verbs: Accept, Create, Delete, Save, Update.
• Avoid vague terms: Yes, No, OK, Click here.

Link Text

• Use words that describe the destination or action: "Update my address", "View my policy documents".
• Never write "click here" or "find out more" as link text.

Error Messages

• Be specific about what went wrong and what the user needs to do to fix it.
• Use active, direct language without blame.

Paragraphs and Body Copy

• Keep each paragraph short and to the point.
• Break content into bite-sized chunks; users scan rather than read.
• Use subheadings, bullet points, and whitespace to aid scanning.

---

Dos and Don'ts

Do

1. Do focus on the customer's goal before writing.
2. Do use words that customers themselves would use.
3. Do use active, confident language: "you should", "we recommend".
4. Do keep body text scannable with short paragraphs and subheadings.

Don't

1. Don't use internal jargon or technical acronyms without explanation.
2. Don't use passive voice when active is possible.
3. Don't use vague button or link labels ("Click here", "Find out more").
4. Don't write long paragraphs that are difficult to scan.