User experience guidelines for extensions

When creating a high-quality extension, it’s not just important to offer great functionality and fail-proof code — it’s also critical to make sure people get the best experience when using it.

Onboarding ↑ Back to top

WooCommerce Subscriptions onboarding banner

The first experience your users have with your extension is crucial. When your extension is activated for the first time, make sure the user is presented with clear next steps.

A common solution for this is presenting a notice message after the user activates the extension and providing set-up instructions for.

For integrations with external or third-party services, we recommend an admin notice, linking to the specific service integration screen within WooCommerce.

We recommend a notice with this text format, as it’s consistent and clear for the user.

Discovery ↑ Back to top

All extensions should be hooked into the WordPress and WooCommerce UI. Add options to existing areas within WooCommerce where users will already be going to perform a certain task:

  • Additional product features or options: in the Product metabox.
  • Options for Orders, Coupons, or Reviews: in the Orders, Coupons, or Reviews screens, respectively.
  • Settings for your extensions: as a new tab or within an existing tab under WooCommerce > Settings as a subtab under the appropriate category.. For integrations, settings should go under WooCommerce > Settings > Integrations. (More info on Adding a Section to a Settings Tab and how to implement the WC_Integration class.)

Whenever possible, avoid creating entirely new screens or new experiences. Similarly, since extensions are specific to WooCommerce, avoid adding settings or menu items outside of WooCommerce, such as in the WP Admin > Settings screen.

To create a cohesive experience, application data should be loaded via API instead of an iframe. Feedback

Feedback ↑ Back to top

Providing timely feedback like success and error messages is essential for ensuring that the user understands whether or not changes have been made.

Language ↑ Back to top

Use a short but meaningful messages that communicate what is happening. Make sure the message provides instructions on what the user needs to do to continue. Proper punctuation should be used if the message contains multiple sentences. Avoid abbreviations.

Design ↑ Back to top

The placement of the feedback is vital to make sure the user notices it. For example, when validation messages are needed to prompt the user to enter data, get the user’s attention by displaying a message at the top of screen and close to the inputs where data needs to be revised.

You can use iconography and color to create highlight and give a particular tone to feedback. Keep in mind that the color and iconography can be perceived differently by people from different cultures, so it’s key that the copy on the feedback is enough for the user to understand what is being communicated.

Types of feedback ↑ Back to top

Success message: When the user performs an action that is executed successfully.

Error Message: When the user performs an action that could not be completed. (This can include validation messages.) When requiring the user to input data, make sure you verify whether each field meets the requirements, such as format, ranges, and if the field is required. Provide validation messages that are adjacent to each field so that the user can act on each in context. Avoid technical jargon.

Warning Message: When the user performs an action that may have completed successfully, but the user should review it and proceed with caution.

Informational Message: When it’s necessary to provide information before the user executes any action on the screen. Examples can be limitations within a time period, or when a global setting limits the actions on the current screen.

Accessibility ↑ Back to top

Make sure your extensions meets the Web Content Accessibility Guidelines (also known as WCAG). Meeting 100% conformance with WCAG 2.0 is hard work, but make sure your extensions meet at the AA level of conformance at minimum.

For more information on accessibility check out the the WordPress accessibility quick start guide.

Tone ↑ Back to top

Providing a consistent tone is crucial to communicating with a user. Make sure you consistently use the same communication style and terminology across the extension, and avoid abbreviations and acronyms.

In extensions, always:

  • Use sentence case for descriptions, feedback, and headlines. Avoid all-caps text.
  • Use standard punctuation and avoid excessive exclamation marks.
  • Use American English.

For more, read our Grammar, Punctuation, and Capitalization guide.

Colors ↑ Back to top

When creating extensions for the WordPress wp-admin, use the core colors and make sure your designs pass AA level guidelines.

For WooCommerce-specific color use, review our Style Guide.

Testing ↑ Back to top

Before launching your extension, make sure users can perform all the functionality provided. This can be achieved running user tests.

To run an effective user test, list out as many scenarios your extension supports. An example of a scenario is: “I am a store owner who wants to create a customizable product including letting customers add custom text and select from 5 different color options for the custom text.” Give this scenario to your testers and watch them try and perform the task using your extension. (In this case, it would be using your extension on the front end of a site.)

There are different ways to do quick user testing:

  • Ask friends and family to participate in your test sessions.
  • Use online services that allow you to expose your extension to new users. We recommend
  • Ask other WooCommerce enthusiasts in the WooCommerce Community Slack for feedback.

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top