No Preview

Sorry, but you either have no stories or none are selected somehow.

If the problem persists, check the browser console, or the terminal you've run Storybook from.

The component failed to render properly, likely due to a configuration issue in Storybook. Here are some common causes and how you can address them:

  1. Missing Context/Providers: You can use decorators to supply specific contexts or providers, which are sometimes necessary for components to render correctly. For detailed instructions on using decorators, please visit the Decorators documentation.
  2. Misconfigured Webpack or Vite: Verify that Storybook picks up all necessary settings for loaders, plugins, and other relevant parameters. You can find step-by-step guides for configuring Webpack or Vite with Storybook.
  3. Missing Environment Variables: Your Storybook may require specific environment variables to function as intended. You can set up custom environment variables as outlined in the Environment Variables documentation.

DIY UX writing in 8 steps

Follow these steps to write clear, useful UI copy.

For best practices in writing for specific components, such as alerts, errors, or confirmation dialogs, check out our .

1. Consider the big picture

Before you start writing, consider the full context:

  • Where will learners be in their journey when they see this message?
  • What is the learner's goal and how will this message help them achieve it?
  • What is our business goal and how will this message help achieve it?
  • What questions might learners have that we should answer?
  • Make a list of all the information this message will need to address.

2. Say it out loud, then write it down

Once you know what information you need to include, say it out loud as if you're explaining the situation to one of our learners. Speak directly to the learner, using "you." After you've said it out loud, write it down. This is your first draft and will help ensure your writing is natural and conversational.

3. Cut any unnecessary words

Cut any words that aren't necessary for learners to understand the message. Remove words that are repetitive or redundant. Once you've cut things down, you can always add words back in to make the message sound friendlier or more encouraging if it feels too robotic.

4. Use consistent language

Make sure the words you're using match the words we use to talk about the same things elsewhere in the product. This also goes for keeping language consistent between the headings, body copy, and button copy within a single component. Switching terms can be an unnecessary source of confusion for learners.

5. Ensure language includes everyone

Use inclusive language that makes all learners feel welcome. Avoid idioms, slang, humor, and jargon to appeal to a global audience. Write for all devices and ensure every element has text for screen readers to speak.

6. Do a readability check

Paste your writing into Hemingway App to check for readability.

  • Aim for a 7th-grade reading level or below
  • Simplify any sentences that are "hard to read" or "very hard to read"

7. Do a style check

Check your writing against our brand voice guidelines. Refer to the UX Writing space for the password and more writing tools. Here are some notes to keep in mind:

  • Use sentence case for headings and button copy.
  • Always use oxford commas.
  • Put spaces around your em dashes ( — ).
  • Use exclamation points sparingly, default to periods.
  • Use periods at the end of complete sentences.

8. Have someone else read your work

When you're done, show the copy to someone else. It's best if it's someone that's not familiar with the project you're working on. They should be able to easily understand the information you listed out in step 1.

When you're done, your copy should:

  • Meet both user needs and business objectives.
  • Sound natural and conversational.
  • Be concise.
  • Use consistent language.
  • Be accessible and inclusive.
  • Be easy to read and understand.
  • Be on-brand.
  • Clearly get the intended message across.

Need help along the way? Reach out to Emily Lee in #ux-writing on Slack for quick questions or create a UX writing request for larger projects.