Add best practices to all customer account components (#3490)

### Background

Part of shop/issues-checkout#8472
Part of shop/issues-checkout#8578
Part of shop/issues-checkout#8511
Part of shop/issues-checkout#8508
Part of shop/issues-checkout#8507
Part of shop/issues-checkout#8509
Part of shop/issues-checkout#8510
Part of shop/issues-checkout#8512
Related to Shopify/shopify-dev#63804

This PR improves the documentation for Customer Account UI Extension components by enhancing best practices sections with more detailed, actionable guidance.

### Solution

Updated the best practices sections for multiple components to provide clearer, more specific guidance for developers. The changes include:

- **Avatar**: Improved readability with better formatting and more concise language
- **ButtonGroup**: Added a new best practices section with guidelines for grouping actions
- **CustomerAccountAction**: Expanded guidance on information collection and form design
- **ImageGroup**: Added recommendations for accessibility and visual spacing
- **Menu**: Restructured content with clearer headings and more detailed organization principles
- **Page**: Reorganized with clear subsections for headings, subheadings, and page-level actions
- **Section**: Added a new best practices section with guidance on headings and actions

These improvements make the documentation more actionable and help developers create more consistent, user-friendly interfaces.

### 🎩

See Shopify/shopify-dev#63804 for details

### Checklist

- [x] I have 🎩'd these changes
- [ ] I have updated relevant documentation

Author: lsit

packages/ui-extensions/docs/surfaces/customer-account/screenshots/avatar-best-practices.png

@@ -41,25 +41,30 @@ const data: ReferenceEntityTemplateSchema = {
     {
       type: 'Generic',
       anchorLink: 'best-practices',
-      title: 'Best Practices',
+      title: 'Best practices',
       sectionContent: `
-  - By default, if a user does not provide their first or last name, the avatar component will display a placeholder icon. However, if at least one of the names is provided, the avatar will be replaced with one or two initials representing the user.
-  - There are 5 sizes for the avatar component:
-    * small-200 (21x21 px): Use when showing avatars in tables / lists where space is limited.
-    * small (26x26 px): Use when you want to conserve space but want a larger size than small-200.
-    * base (32x32 px): Use by default.
-    * large (39×39 px): Use when the avatar is a focal point, such as a customer details card.
-    * large-200 (47x47 px): Use when placing more emphasis on the avatar.
+Use these best practices to deliver a clear and accessible experience in your extensions.
 
-  - Provide alt text for avatars to assist customers using assistive technologies.
+### Show initials by default
 
-  **Dos**
-  - When using multiple avatars on the same page, maintain a consistent style and size to create a unified visual pattern for users.
+When no first or last name is provided, display the placeholder icon. If either name exists, show one or two initials.
 
-  **Don'ts**
-  - Don't use different size avatars on the same page.
+### Choose an appropriate size
 
-  ![An example showing dos and don'ts of the Avatar component](/assets/templated-apis-screenshots/customer-account-ui-extensions/2025-10/avatar-best-practices.png)
+Select a size based on context: 
+- small‑200 (21×21) for tight tables or lists
+- small (26×26) when slightly larger is needed
+- base (32×32) as the default
+- large (39×39) when the avatar is a focal point (for example, a customer card)
+- large‑200 (47×47) when extra emphasis is required
+
+### Provide descriptive alt text
+
+Write alt text that meaningfully describes the avatar so assistive technologies can convey the same context.
+
+### Keep sizes consistent on a page
+
+Use the same style and size for multiple avatars in one view to create a unified visual pattern and avoid mixing sizes.
   `,
     },
   ],

packages/ui-extensions/docs/surfaces/customer-account/screenshots/menu-dont-do.png

@@ -38,6 +38,36 @@ When used within a [Section](/docs/api/customer-account-ui-extensions/polaris-we
       ],
     },
   },
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+Use these best practices to deliver a clear and accessible experience in your extensions.
+
+### Prioritize and group related actions
+
+Cluster actions by purpose and place the most important or common action first to set a clear default.
+
+### Use a single primary action
+
+Reserve the primary style for one action only. Keep all other actions secondary to reinforce hierarchy.
+
+### Reduce clutter in secondary options
+
+Limit the number of secondary actions and collapse extras into menus or overflow to keep the interface clean.
+
+### Write short, scannable labels
+
+Use verbs and nouns in sentence cases. For example, “Edit address”. Keep styling consistent across actions.
+
+### Support accessibility and responsiveness
+
+Provide an accessible label for the group and ensure the layout adapts well across screen sizes.
+`,
+    },
+  ],
   related: [],
 };
 

packages/ui-extensions/docs/surfaces/customer-account/screenshots/menu-labels.png

@@ -46,11 +46,29 @@ const data: ReferenceEntityTemplateSchema = {
     {
       type: 'Generic',
       anchorLink: 'best-practices',
-      title: 'Best Practices',
+      title: 'Best practices',
       sectionContent: `
-- Use CustomerAccountAction to shift focus toward information and functionality needed to confirm or complete an order action.
-- If the order action experience you’re building requires complex forms or large amounts of information, consider building a full-page extension instead.
-- See Polaris for more best practices and content guidelines for designing [Modals](https://polaris.shopify.com/components/overlays/modal#best-practices).
+Use these best practices to deliver a clear and accessible experience in your extensions.
+
+### Highlight the key decision
+
+Use the component to present the essential details and actions needed to confirm or complete an order task.
+
+### Collect only what’s necessary
+
+Request the minimum information required to finish the customer’s job so the flow stays quick and friction‑free.
+
+### Keep forms simple and predictable
+
+Use clear labels, intuitive actions, and concise copy so customers know what’s required and what happens next.
+
+### Choose a full‑page extension for complex flows
+
+If the task spans multiple steps or needs a lot of input, switch to a full‑page extension instead of a modal.
+
+### Refer to Polaris guidance
+
+Refer to Polaris for additional best practices and content guidelines when designing [modals](https://polaris-react.shopify.com/components/deprecated/modal#best-practices).
 `,
     },
   ],

packages/ui-extensions/src/surfaces/customer-account/components/Avatar/Avatar.doc.ts

@@ -35,9 +35,21 @@ const data: ReferenceEntityTemplateSchema = {
     {
       type: 'Generic',
       anchorLink: 'best-practices',
-      title: 'Best Practices',
+      title: 'Best practices',
       sectionContent: `
-- Optimize image file sizes and consider lazy loading for performance.
+Use these best practices to deliver a clear and accessible experience in your extensions.
+
+### Write concise alt text for each image
+
+Describe what’s important about each image so all users can understand the content.
+
+### Optimize performance
+
+Compress images and use modern formats; consider lazy loading to reduce initial load times.
+
+### Preserve visual breathing room
+
+Maintain consistent spacing around the group so images don’t feel crowded or overwhelming.
 `,
     },
   ],

packages/ui-extensions/src/surfaces/customer-account/components/ButtonGroup/ButtonGroup.doc.ts

@@ -41,24 +41,29 @@ const data: ReferenceEntityTemplateSchema = {
     {
       type: 'Generic',
       anchorLink: 'best-practices',
-      title: 'Best Practices',
+      title: 'Best practices',
       sectionContent: `
-### Consolidate actions into one menu
+Use these best practices to deliver a clear and accessible experience in your extensions.
 
-- Use the menu component in the upper-right corner of full-page extensions, to be consistent with the **Order status** page.
-- Use menus to consolidate page-level actions, instead of adding multiple buttons around the page.
+### Place menus consistently
 
-![The “Don’t do” example shows 3 separate action buttons on a subscription page. The “Do” example shows the same 3 actions consolidated into one menu.](/assets/templated-apis-screenshots/customer-account-ui-extensions/2025-10/menu-dont-do.png)
+Position menus in the upper‑right of full‑page extensions to match account pages like order status.
 
-### Content guidelines
+### Group page‑level actions
 
-When writing button labels:
-- Aim for 2 words (verb and noun).
-- Lead with a strong verb that encourages action.
-- Avoid unnecessary words and articles such as “the,” “an,” or “a.”
-- Use sentence case.
+Keep related actions in a single menu rather than scattering buttons across the page.
 
-![A button that follows the content guidelines says “Skip order”. A button that does not meet the content guidelines says “Skip this order”.](/assets/templated-apis-screenshots/customer-account-ui-extensions/2025-10/menu-labels.png)
+### Limit items to what’s relevant
+
+Include only actions that matter for the current page to reduce decision fatigue.
+
+### Order by frequency and risk
+
+List the most common or least risky actions at the top so they’re easy to reach.
+
+### Write concise, action‑first labels
+
+Use short labels (ideally two words) that start with a verb, use sentence case, avoid filler articles, and clearly state the outcome.
 `,
     },
   ],

packages/ui-extensions/src/surfaces/customer-account/components/CustomerAccountAction/CustomerAccountAction.doc.ts

@@ -58,21 +58,21 @@ const data: ReferenceEntityTemplateSchema = {
     {
       type: 'Generic',
       anchorLink: 'best-practices',
-      title: 'Best Practices',
+      title: 'Best practices',
       sectionContent: `
-**Heading**
-- Set clear expectations about the purpose and main topic of the page.
-- Aim for 1-3 words.
-- Use sentence case.
+Use these best practices to deliver a clear and accessible experience in your extensions.
 
-**Subheading**
-- Use to provide additional context or information that enhances the customer’s understanding of the page.
-- Use subheadings sparingly and only when they add useful information that is distinct from the heading.
+### Write clear, focused headings
 
-**Buttons**
-- Use for page-level actions only.
-- If there is a single primary action for the page, display it as a primary button. Display all other page-level actions as secondary buttons.
-- See [UX guidelines](/docs/apps/customer-accounts/order-action-menu-extensions/ux-guidelines) to learn more about the button logic for order actions.
+State the main purpose of the page in a few words and use sentence case for readability.
+
+### Use subheadings only when they add value
+
+Add a subheading when it provides helpful context that’s different from the heading. Keep it brief and use sparingly to avoid clutter.
+
+### Add page‑level actions thoughtfully
+
+Include buttons in the header only for actions that affect the entire page or flow. Make the main action a primary button, keep lesser actions secondary, limit the total number, and follow established UX patterns—especially for order actions.
 `,
     },
   ],

packages/ui-extensions/src/surfaces/customer-account/components/ImageGroup/ImageGroup.doc.ts

@@ -20,6 +20,34 @@ const data: ReferenceEntityTemplateSchema = {
       anchorLink: 'considerations',
       sectionContent: `- When adding headings inside sections they automatically use a specific style, which helps keep the content organized and clear.`,
     },
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+Use these best practices to deliver a clear and accessible experience in your extensions.
+
+### Describe each section with a clear heading
+
+Use concise, sentence‑case headings that reflect the section’s purpose.
+
+### Provide an accessible name when no heading exists
+
+If a visual heading isn’t present, set an accessibilityLabel so assistive technologies can identify the section.
+
+### Align actions to the section’s content
+
+Only include primary and secondary actions that relate directly to what’s in the section.
+
+### Limit and prioritize actions
+
+Keep the number of actions small to reduce noise and emphasize what matters most.
+
+### Keep layout and styling consistent
+
+Maintain consistent spacing, typography, and alignment between sections for a coherent experience.
+`,
+    },
   ],
   definitions: [
     {