Foundations

Our voice reflects our values, while the tone adapts to the situation and ensures we convey the right message. When in doubt, always choose accessibility.

    How our voice sounds

  • We're inclusive, relatable, and joyful without being overly bubbly.
  • We prioritize openness, accessibility, and conciseness.
  • We focus on the benefit—how we improve users' lives through what we build.
  • We sound human, innovative, and confident.
  • We know our audience and speak from a place of expertise, but never as a know-it-all.
Build trust by being clear and confident: “Turn on cookies in your browser.”
Don't be boastful or condescending: “Looks like you don't like our cookies.”

    Finding the right tone

  • Focus on the users. Think about what they need and the challenges they face.
  • Be mindful of everything happening on the current, preceding, and following screens.
  • Look through Dovetail and reports to pick the best words.
  • Write as if you're talking directly to someone, keeping Appfire's values in mind.
  • Be helpful. Explain why certain options aren't available or what to do instead.
  • Avoid stating the obvious about how to use the interface.
A helpful message says why an interface element is not clickable: “There are no tasks to be exported yet.”
Don't explain the obvious, like “click the link below” or “click Save to save your changes.”

    Use plain language

  • Keep the writing jargon-free, clear, and concise. People scan, not read.
  • Make active voice your default choice to improve readability.
  • Use passive voice only when justified, such as to avoid blaming users for errors.
  • Stick to a simple tense and construction. Say, “You worked on more projects this year,” instead of “We noticed you were working on more projects this year.”
  • Remove redundancies and lengthy introductions (“In today's world...”, “We'd like to invite you to try a new feature our team has been working on...”).
Active “This field requires mapping” is more direct, while passive “Tasks couldn't be added” helps maintain a neutral tone.
Passive “Mapping is required for this field” is less user-friendly, while active “You couldn't add tasks” blames the user.

    Straight to the point

  • Reserve the word please for requests that require extra effort. Overuse of please seems insincere and reduces our credibility.
  • Avoid “Are you sure...?” which can create self-doubt and lower trust in the product.
  • Don't start with “Do you want to…?” either. It's redundant.
“Delete this task?” is unambiguous, succinct, and precise.
“Are you sure you want to delete this task?” adds complexity.

    Include everyone

  • When referring to a person of unknown gender, use they instead of he or she.
  • Minimize acronyms. If you need them, define them first.
  • Avoid idioms and slang to make sure everyone understands your message.
  • Use emojis sparingly. They add noise and have different meanings in some countries.

    Create descriptive links

  • Keep your links concise but descriptive enough to know where they lead to.
  • Encourage users to click by saying “Learn more about pricing” instead of a generic “Learn more.” People using screen readers will benefit as well.
Link naturally within your text:
“Visit the MDN guidelines for guidance on accessible hyperlinks.”
Don't create links such as “click here,” “here,” or “link” as they are not screen-reader friendly.

    Be mindful of placeholders

  • Placeholders are temporary text often used in forms, input fields, and dropdown menus.
  • Placeholders can be helpful at times but reduce form and input field accessibility.
  • For forms and input fields, always use labels and don't include placeholders by default.
    Exception: we don't need labels for search fields.
  • If a placeholder can add value to a specific context, ensure it doesn't repeat the label and is applied consistently across the form or screen.
  • For select dropdown menus, use placeholders by default (Select team, Select city, etc.).
  • Skip articles (a, an, the) for those short prompts to improve scanning.
An example of an empty input field.

Do

People are more likely to notice and fill out empty input fields.

An example of an input field with a placeholder that repeats the label.

Don't

Placeholders that repeat labels can be overlooked and don't add value.

    Bold and italics

  • You can use bold or italics to highlight a word or two.
  • Avoid overuse, as nothing will stand out then.
  • Don't create blocks of italics. They're hard to scan, especially for people with dyslexia.
  • Screen readers skip bold or italics. Make sure everyone is aware of critical details.
Share your feedback on the #design-systems channel in Slack.