Patternfly Logo

Writing for all audiences

UX copy should be accessible by everyone, so consider all users’ abilities (physical, cognitive, and more) when you write. Refer to the Web Content Accessibility Guidelines (WCAG) for accessibility compliance information.

Here are a few best practices for making your UX copy more accessible:

  • Avoid directional language, like “Use the button to the left." It doesn't account for users with different screen layouts (desktop vs. mobile) or users working with screen readers.
  • Use proper heading levels (H1, H2) to articulate the page content’s organization.
  • Do not identify items by color, like “Click the blue button.”
  • Use plain language and short sentences.
  • Use common contractions (for example, "it’s” and "you’re") in areas that sound most natural to you. Contractions are great for maintaining a casual voice and tone and for making your UX copy more accessible. UX copy should make a product interaction feel, look, and sound more human. Contractions help you get there.
  • Be clear and concise.

Use the following guidelines when writing text that is only visible to a screen reader, like an aria-label that describes an icon button:

  • Avoid redundancy. Screen readers will announce the name of the component or element as well as associated property and state when the HTML is defined correctly.
  • Make sure labels for elements like buttons or links make sense when pulled out of the context. Use descriptive hyperlinks instead of raw links or vague linked text, like “Click here.”
  • When you define an aria-label for an element that also has associated visible text in the UI, ensure the aria-label begins with the same text that appears in the UI to avoid confusion with screen reader users who have vision.
  • Avoid unnecessary capitalization.
  • Avoid leet speak that uses numbers or special characters in place of letters (like "a11y" for accessibility).

Localize your content to align with different regional and cultural expectations and keep your source content (copy and code) as clear and consistent as possible. Source content created with these goals in mind yields better translations, improves product quality, lowers costs, and increases reuse.

Keep these additional guidelines in mind when writing for global users:

  • Avoid idioms like “cross your fingers.” They don’t make sense in all languages.
  • Avoid vague terms like “stuff” or “kind of.” They can be translated incorrectly.
  • Use humor sparingly. It generally doesn’t translate well.
  • Avoid culture-specific or location-specific references and examples. They won’t resonate with all users.
  • Avoid adding words to an image. They make translation harder.
  • Translated text can be a drastically different length than the text you originally provide. Ensure the text you use can be 50% shorter or 50% longer with no negative impact on design.

View source on GitHub