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, present the user with clear next steps.

A common solution for this is a notice message after activating the extension and providing setup instructions.

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 go 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 ↑ Back to top

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

Language ↑ Back to top

Use short but meaningful messages that communicate what is happening. Ensure that 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 feedback is vital so 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 feedback is sufficient 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 actions on the current screen.

Accessibility ↑ Back to top

Your extensions must meet the Web Content Accessibility Guidelines (WCAG). Meeting 100% conformance with WCAG 2.0 is hard work; meet the AA level of conformance at a minimum.

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

Tone ↑ Back to top

Maintain a consistent tone when communicating with a user. Maintain the same communication style and terminology across an extension, and avoid abbreviations and acronyms.

In extensions:

  • Use sentences 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 ensure your designs pass AA level guidelines.

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

Testing ↑ Back to top

Users must be able to perform all actions of the functionality provided. This can be achieved by running user tests.

To run an effective user test, list as many scenarios your extension supports. An example of a scenario: “I am a store owner who wants to create a customizable product that includes letting customers add custom text and select from 5 different color options for the custom text.” Give this scenario to testers, and watch them attempt/perform the task with your extension.

Different ways to do quick user testing:

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

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

Back to the top