Guidelines

Content

Words are interface elements. Every word must earn its place, serving user understanding rather than filling space.

Philosophy

The Subtractive Triad applies to content as much as design. Remove words that don't serve comprehension. What remains should be clear, helpful, and human.

"Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines." — Strunk & White, The Elements of Style

Voice Principles

Canon's voice is calm, direct, and respectful of the user's intelligence.

Clear over clever

Clarity always wins. Puns, jargon, and marketing speak create friction. Say what you mean in the simplest terms possible.

Brief over verbose

Respect user attention. Cut filler words, redundant phrases, and obvious statements. Every word should carry weight.

Helpful over positive

Forced positivity feels hollow. Instead of "Great job!", provide useful information: "Saved" or "3 items updated."

Human over corporate

Write like you speak. Avoid passive voice, formal jargon, and phrases that no human would actually say aloud.

Voice Examples

Compare approaches to find the Canon voice.

Avoid

The system has encountered an error processing your request.

Prefer

Something went wrong. Please try again.

Speak like a human, not a machine

Avoid

Click here to learn more about our amazing features!

Prefer

Learn about features

Be direct, avoid marketing speak

Avoid

Are you absolutely sure you want to delete this?

Prefer

Delete this item? This cannot be undone.

State consequences clearly without drama

Avoid

Oops! Something went wrong :(

Prefer

Something went wrong. Try refreshing the page.

Be helpful without being cute

Tone by Context

Voice stays consistent; tone adapts to situation.

ContextToneExampleAvoid
Success statesConfident, minimalSaved.Awesome! Your changes have been successfully saved!
Error statesClear, helpfulInvalid email format. Check and try again.Oops! That email doesn't look right :(
Empty statesEncouraging, actionableNo projects yet. Create your first project.Nothing to see here!
ConfirmationsDirect, consequence-focusedDelete project? This removes all files.Are you really sure you want to delete this?

Error Messages

Error messages are where content quality matters most. Users are already frustrated—don't make it worse with vague or unhelpful text.

error-messages.html 
<!-- Vague: tells user nothing useful -->
"token attr-name">class="token tag"><p "token attr-name">class="error">An error occurred."token attr-name">class="token tag"></p>

<!-- Clear: explains problem and solution -->
"token attr-name">class="token tag"><p "token attr-name">class="error">
  Email address is required. Please enter your email to continue.
"token attr-name">class="token tag"></p>

<!-- Even better: specific and actionable -->
"token attr-name">class="token tag"><p "token attr-name">class="error">
  We couldn't find an account with that email.
  "token attr-name">class="token tag"><a "token attr-name">href="/signup">Create an account"token attr-name">class="token tag"></a> or
  "token attr-name">class="token tag"><a "token attr-name">href="/forgot-password">reset your password"token attr-name">class="token tag"></a>.
"token attr-name">class="token tag"></p>

Error Message Checklist

  • States what went wrong (briefly)
  • Explains why (if helpful)
  • Provides a path forward
  • Avoids technical jargon
  • Doesn't blame the user

UI Text Patterns

Common UI text elements and their Canon-compliant patterns.

Buttons

Primary actions
Use verbs: "Save", "Create", "Send"
Destructive actions
State consequence: "Delete project"
Navigation
Use destination: "Settings", "Dashboard"

Labels

Form fields
Noun phrases: "Email address", "Password"
Toggles
State what's enabled: "Email notifications"
Checkboxes
Full statements: "Remember my login"

Headings

Page titles
Simple nouns: "Settings", "Projects"
Section headers
Descriptive: "Account preferences"
Empty states
State + action: "No results. Try different filters."

Feedback

Success
Brief confirmation: "Saved", "Sent"
Progress
Action + status: "Uploading...", "Saving..."
Loading
What's happening: "Loading projects"

Documentation

Code documentation follows the same principles: clear, brief, and useful.

documentation.js 
/**
 * Button
 *
 * Primary action trigger. Use sparingly—each screen
 * should have one clear primary action.
 *
 * @example
 * <Button variant="primary">Submit</Button>
 *
 * @see https://createsomething.ltd/canon/components/button
 */

Documentation Guidelines

  • Start with what, not how
  • Include practical examples
  • Link to related resources
  • Update when behavior changes
  • Delete when no longer accurate

Capitalization

Consistent capitalization creates visual calm.

Sentence case

Use for most UI text

  • Page titles: "Account settings"
  • Button labels: "Create project"
  • Error messages: "Email is required"

Title case

Use sparingly

  • Product names: "Canon Design System"
  • Feature names: "Quick Start"
  • Marketing headlines only

All caps

Use rarely

  • Eyebrow labels: "GUIDELINES"
  • Abbreviations: "API", "URL"
  • Never for emphasis