Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Create user-experience-guidelines.md (#39894) 

* Create user-experience-guidelines.md

* Beefing up user-experience guidlines

adding media folder, and 6 new docs to create the user experience folder in our docs repo.

* UX guidelines to pass linting

* Update task-list-and-inbox.md

* Update task-list-and-inbox.md

* moving images to developer.woo.com
This commit is contained in:
Brent MacKinnon 2023-10-23 17:59:56 -03:00 committed by GitHub
parent 791af33e95
commit 72b228fc7c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 189 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/user-experience/accessibility.md Normal file
View File

@ -0,0 +1,7 @@
# User Experience Guidelines: Accessibility
## Accessibility
Your extensions must meet the [Web Content Accessibility Guidelines](https://www.google.com/url?q=https://www.w3.org/WAI/standards-guidelines/wcag/&sa=D&source=editors&ust=1692895324247620&usg=AOvVaw3zuZP9mII_1wB0hF2DHvqz) (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](https://www.google.com/url?q=https://make.wordpress.org/accessibility/handbook/best-practices/quick-start-guide/&sa=D&source=editors&ust=1692895324247995&usg=AOvVaw1FOL7wC9TwyiIxLUiQZ34k).

34
docs/user-experience/best-practices.md Normal file
View File

@ -0,0 +1,34 @@
# User Experience Guidelines: Best Practices
## Best practices
**Plugin name should simply state the feature of the plugin and not use an existing core feature or extension in its’ title**. The plugin name should appear at all times in the UI as a functional and original name. e.g “Appointments” instead of “VendorXYZ Bookings Plugin for WooCommerce.”
**Avoid creating new UI**. Before considering a new UI, review the WordPress interface to see if a component can be repurposed. Follow existing UI navigation patterns so merchants have context on where they are when navigating to a new experience.
**Be considerate of mobile for the merchant (and shopper-facing if applicable) experience**. Stores operate 24/7. Merchants shouldn’t be limited to checking their store on a desktop. Extensions need to be built responsively so they work on all device sizes.
**It’s all about the merchant**. Don’t distract with unrelated content. Keep the product experience front and center to help the user achieve the tasks they purchased your product for.
**Present a review request at the right time**. Presenting users with a request for review is a great way to get feedback on your extension. Think about best placement and timing to show these prompts.
Here are some best practices:
- Avoid showing the user a review request upon first launching the extension. Once the user has had a chance to set up, connect, and use the plugin they’ll have a better idea of how to rate it.
- Try to present the review request at a time that’s least disruptive, such as after successful completion of a task or event.
**Don’t alter the core interface**. Don’t express your brand by changing the shape of containers in the Woo admin.
**Focus on the experience**. After the customer installs your product, the experience should be the primary focus. Keep things simple and guide the user to successful setup. Do not convolute the experience or distract the user with branding, self promotion, large banners, or anything obtrusive.
**Keep copy short and simple**. Limit instructions within the interface to 120-140 characters. Anything longer should be placed in the product documentation.
**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](https://www.google.com/url?q=https://woocommerce.com/document/grammar-punctuation-style-guide/&sa=D&source=editors&ust=1692895324244468&usg=AOvVaw2FWh4SUBI0dLsCqUZtXGFt).

13
docs/user-experience/colors.md Normal file
View File

@ -0,0 +1,13 @@
# User Experience Guidelines: Colors
## Colors
When creating extensions for the WordPress wp-admin, use the core colors, respect the user’s WordPress admin color scheme selection, and ensure your designs pass AA level guidelines.
When using components with text, such as buttons, cards, or navigation, the background-to-text contrast ratio should be at least 4.5:1 to be [WCAG AA compliant](https://www.google.com/url?q=https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html&sa=D&source=editors&ust=1692895324245359&usg=AOvVaw04OufEgaTguaV-k6wMtlMU). Be sure to [test your color contrast ratios](https://www.google.com/url?q=https://webaim.org/resources/contrastchecker/&sa=D&source=editors&ust=1692895324245608&usg=AOvVaw1aGcU7vUM05t3bxPA2qrIX) to abide by WCAG standards.
- [Accessibility handbook on uses of color and contrast](https://www.google.com/url?q=https://make.wordpress.org/accessibility/handbook/current-projects/use-of-color/&sa=D&source=editors&ust=1692895324245960&usg=AOvVaw3DDtjcP5MkNoQgX3VgPKXr)
- [Color contrast ratio checker](https://www.google.com/url?q=http://webaim.org/resources/contrastchecker/&sa=D&source=editors&ust=1692895324246320&usg=AOvVaw1RTR_DT4liFu_SiBOF8RxK)
- [More resources regarding accessibility and color testing](https://www.google.com/url?q=http://webaim.org/resources/contrastchecker/&sa=D&source=editors&ust=1692895324246679&usg=AOvVaw316-gDJXDzTH8gOjibWeRm)
For WooCommerce-specific color use, review our [Style Guide](https://www.google.com/url?q=https://woocommerce.com/brand-and-logo-guidelines/&sa=D&source=editors&ust=1692895324247100&usg=AOvVaw2cgvb_mHoClPzhtW57QooS).

33
docs/user-experience/notices.md Normal file
View File

@ -0,0 +1,33 @@
# User Experience Guidelines: Notices
## Notices
Use notices primarily to provide user feedback in response to an action. Avoid using notices to communicate offers or announcements. Don’t apply brand colors, fonts, or illustrations to your notices.
If a post-activation notice is required, keep it within the WordPress plugin area—do not display it on the dashboard, or any other parts of the platform.
Use the standard WordPress notice format and WooCommerce admin notices API.
### Language
Providing timely feedback like success and error messages is essential for ensuring that the user understands whether changes have been made.
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
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 close to the inputs where data needs to be revised.
![visualization of four different notice designs next to one another](https://woocommerce.files.wordpress.com/2023/10/notices1.png)
**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.
### Examples
![an example of an informational message as a notice](https://woocommerce.files.wordpress.com/2023/10/informational-notice.png)

27
docs/user-experience/onboarding.md Normal file
View File

@ -0,0 +1,27 @@
# User Experience Guidelines: Onboarding
## Onboarding
The first experience your users have with your extension is crucial. A user activating your extension for the first time provides an opportunity to onboard new and reorient returning users the right way. Is it clear to the user how to get started? Keep in mind that the more difficult the setup, the more likely a user will abandon the product altogether so keep it simple and direct.
**Use primary buttons as calls to action and keep secondary information deprioritized for clarity**. Guide merchants towards successful setup with a clear next step and/or step-by-step process with progress indicator if the extension isn’t configured or if setup is not complete.
**If necessary, provide a dismissible notification in the plugin area**. Add a notification to communicate next steps if setup or connection is required to successfully enable the plugin.
- Use the standard WordPress notice format and WooCommerce admin notices API.
- Notices should be dismissible. Users should always have a clear way to close the notice.
- Keep the post-activation notice with the WordPress plugin area in context of the plugin listing—do not display it on the dashboard, or any other parts of the platform.
- Don’t display more than one notice.
- Try to keep the notice copy between 125 to 200 characters.
If no action is required for setup it’s best to rely on other onboarding aids such as the Task List (link to component) and Inbox (link to component) to help users discover features and use your plugin.
**Get to the point and keep it instructional**. This is not a time to promote your brand or pitch the product. The user has bought your product and is ready to use it. Keep the information instructional and precise and avoid the use of branded colors, fonts, and illustrations in empty states and other onboarding aids. Help users with context on next steps.
**Show helpful empty states**. Rely on the existing plugin UI, if any, to guide users towards successful setup and use of the plugin. Avoid onboarding emails, push notifications, and welcome tours.
**Plugins should not redirect on activation from WordPress plugins area**. This can break bulk activation of plugins. Following the [dotorg plugin guideline 11](https://www.google.com/url?q=https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/%2311-plugins-should-not-hijack-the-admin-dashboard&sa=D&source=editors&ust=1693330746653223&usg=AOvVaw3YwkUVGDikvvG4jHmZ4Yej), the extension shouldn’t hijack the dashboard or hide functionality of core or other extensions.
**Avoid dead end links and pages**. There should always be a way forward or back.
**Error Handling and Messaging**. If users encounter an error during setup, provide a clear and useful notification with clear and easily understood information on what went wrong and how to fix it.

48
docs/user-experience/task-list-and-inbox.md Normal file
View File

@ -0,0 +1,48 @@
# User Experience Guidelines: Task list and Inbox
## Task List & Inbox
Plugins should choose between implementing a Task or Inbox note based on the following guidelines. Avoid implementing both Task and Inbox note for the same message, which adds clutter and reduces the impact of the message.
Use the Task List and Inbox sparingly. Messages should be clear, concise, and maintain a consistent tone. Follow the [Grammar, Punctuation, and Capitalization guide](https://www.google.com/url?q=https://woocommerce.com/document/grammar-punctuation-style-guide/&sa=D&source=editors&ust=1693330746656102&usg=AOvVaw3bYX5mFADFqIMpsW8-owen).
### Task List
![an example of a task in the task list](https://woocommerce.files.wordpress.com/2023/10/task-list1.png)
Anything that **requires** action should go in the task list.
- *What appears in the Things to Do Task List:*
- Tasks that will enable, connect, or configure an extension.
- Tasks that are critical to the business, such as capturing payment or responding to disputes.
- *What doesn’t appear in the Things to do Task List:*
- Any critical update that would impact or prevent the functioning of the store should appear as a top level notice using the standard WordPress component.
- Informational notices such as feature announcements or tips for using the plugin should appear in the Inbox as they are not critical and do not require action.
- Notifications from user activity should result in regular feedback notices (success, info, error, warning).
Examples:
![three tasks in the task list under the heading "Things to do next" with the option to expand at the bottom to "show 3 more tasks" ](https://woocommerce.files.wordpress.com/2023/10/task-list-example.png)
### Inbox
The Inbox provides informational, useful, and supplemental content to the user, while important notices and setup tasks have their separate and relevant locations.
![an example of an inbox notification](https://woocommerce.files.wordpress.com/2023/10/inbox1.png)
- *What appears in the Inbox*:
- Informational notices such as non-critical reminders.
- Requests for plugin reviews and feedback.
- Tips for using the plugin and introducing features.
- Insights such as inspirational messages or milestones.
- *What doesn’t appear in the Inbox*:
- Notices that require action, extension setup tasks, or regular feedback notices.
Examples:
![an example of two inbox notifications listed under the "Inbox" section of the admin](https://woocommerce.files.wordpress.com/2023/10/inbox-examples.png)

27
docs/user-experience/user-experience-guidelines.md Normal file
View File

@ -0,0 +1,27 @@
# User Experience Guidelines
This guide covers general guidelines, and best practices to follow in order to ensure your product experience aligns with WooCommerce for ease of use, seamless integration, and strong adoption.
We strongly recommend you review the current [WooCommerce setup experience](https://www.google.com/url?q=https://woocommerce.com/documentation/plugins/woocommerce/getting-started/&sa=D&source=editors&ust=1692895324238396&usg=AOvVaw2TmgGeQmH4N_DZY6QS9Bve) to get familiar with the user experience and taxonomy.
We also recommend you review the [WordPress core guidelines](https://www.google.com/url?q=https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/&sa=D&source=editors&ust=1692895324239052&usg=AOvVaw1E61gu1LlpT1F6yqYdMrcl) to ensure your product isn’t breaking any rules, and review [this helpful resource](https://www.google.com/url?q=https://woocommerce.com/document/grammar-punctuation-style-guide/&sa=D&source=editors&ust=1692895324239337&usg=AOvVaw0tMP_9YsdpSjtiAOQSw_D-) on content style.
## General
Use existing WordPress/WooCommerce UI, built in components (text fields, checkboxes, etc) and existing menu structures.
Plugins which draw on WordPress’ core design aesthetic will benefit from future updates to this design as WordPress continues to evolve. If you need to make an exception for your product, be prepared to provide a valid use case.
- [WordPress Components library](https://www.google.com/url?q=https://wordpress.github.io/gutenberg/?path%3D/story/docs-introduction--page&sa=D&source=editors&ust=1692895324240206&usg=AOvVaw12wUm2BSmyxcEjcAQxlwaU)
- [Figma for WordPress](https://www.google.com/url?q=https://make.wordpress.org/design/2018/11/19/figma-for-wordpress/&sa=D&source=editors&ust=1692895324240568&usg=AOvVaw1iTxXh4YpA9AZlAACquK3g) | ([WordPress Design Library Figma](https://www.google.com/url?q=https://www.figma.com/file/e4tLacmlPuZV47l7901FEs/WordPress-Design-Library?type%3Ddesign%26node-id%3D7-42%26t%3Dm8IgUWrqfZX0GNCh-0&sa=D&source=editors&ust=1692895324240869&usg=AOvVaw0N2Y5nktcq9dypK8N68nMD))
- [WooCommerce Component Library](https://www.google.com/url?q=https://woocommerce.github.io/woocommerce-admin/%23/&sa=D&source=editors&ust=1692895324241224&usg=AOvVaw0rXxnruNoF8alalpaev9yD)
## Explore User Experience Guidlines
- [Best Practices](/docs/user-experience/best-practices.md)
- [Colors](/docs/user-experience/colors.md)
- [Accessibility](/docs/user-experience/accessibility.md)
- [Onboarding](/docs/user-experience/onboarding.md)
- [Notices](/docs/user-experience/notices.md)
- [Task list & Inbox](/docs/user-experience/task-list-and-inbox.md)