Merge pull request #3594 from Shopify/dc-add-more-docs

Add Best practices to more Polaris docs

Author: davejcameron

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

@@ -5,6 +5,35 @@ const data: AdminReferenceEntityTemplateSchema = {
   ...sharedContent,
   thumbnail: '/assets/templated-apis-screenshots/admin/components/avatar.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Identifying individuals or businesses
+- Representing merchants, customers, or other entities visually
+- Seeing visual indicators of people or businesses in lists, tables, or cards`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- \`small-200\`: use in tightly condensed layouts
+- \`small\`: use when the base size is too big for the layout, or when the avatar has less importance
+- \`base\`: use as the default size
+- \`large\`: use when an avatar is a focal point, such as on a single customer card
+- \`large-200\`: use when extra emphasis is required`,
+    },
+    {
+      title: 'Content guidelines',
+      type: 'Generic' as const,
+      anchorLink: 'content-guidelines',
+      sectionContent: `For avatars, we recommend using a format that describes what will show in the image:
+- alt="Person's name" if avatar represents a person
+- alt="Business's name" if avatar represents a business
+- alt="" if the name appears next to the avatar as text`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Badge/Badge.doc.ts

@@ -5,6 +5,38 @@ const data: AdminReferenceEntityTemplateSchema = {
   ...sharedContent,
   thumbnail: '/assets/templated-apis-screenshots/admin/components/badge.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Communicating the state of an object
+- Identifying objects that need attention or action
+- Quickly scanning complex lists to find specific object states`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- \`base\`: use in tables where many badges are displayed
+- \`large\`: use when badge needs to stand out prominently
+- Text truncates automatically, keep labels short to avoid truncation
+- Badges are static indicators, not interactive or dismissible
+- Use \`critical\` or \`warning\` tones for errors needing immediate attention
+- Use consistent styles and icons for common statuses
+- When using badges in line items, integrate them with the full content group rather than attaching only to the header
+- Don't use badges for merchant-created information. Instead, use a Chip or ClickableChip`,
+    },
+    {
+      title: 'Content guidelines',
+      type: 'Generic' as const,
+      anchorLink: 'content-guidelines',
+      sectionContent: `Badge labels should:
+- Use 1-2 words maximum: \`Fulfilled\`, \`Partially refunded\`
+- Always use past tense: \`Refunded\` not \`Refund\`
+`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Banner/Banner.doc.ts

@@ -6,6 +6,16 @@ const data: AdminReferenceEntityTemplateSchema = {
   thumbnail: '/assets/templated-apis-screenshots/admin/components/banner.png',
   isVisualComponent: true,
   subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Showing important information or changes
+- Prompting merchants to take a specific action
+- Displaying warnings, errors, or critical information
+- Communicating persistent conditions that need attention
+`,
+    },
     {
       title: 'Outside of a section',
       type: 'Generic' as const,
@@ -28,6 +38,16 @@ const data: AdminReferenceEntityTemplateSchema = {
 - Info, Warning and Critical banners should contain a call to action and clear next steps. Users should know what to do after seeing the banner.
 - Avoid banners that can't be dismissed unless the user is required to take action.`,
     },
+    {
+      title: 'Content guidelines',
+      type: 'Generic' as const,
+      anchorLink: 'content-guidelines',
+      sectionContent: `- Keep titles concise and clear
+- Limit body content to 1-2 sentences where possible
+- Use action-led buttons with strong verbs (e.g., "Activate Apple Pay" not "Try Apple Pay")
+- Avoid unnecessary words and articles in button text
+- For warning and critical banners, explain how to resolve the issue`,
+    },
   ],
   definitions: [
     {

packages/ui-extensions/src/surfaces/admin/components/Box/Box.doc.ts

@@ -11,8 +11,15 @@ const data: AdminReferenceEntityTemplateSchema = {
       type: 'Generic' as const,
       anchorLink: 'useful-for',
       sectionContent: `- Creating custom designs when you can't build what you need with the existing components.
-  - Setting up specific stylings such as background colors, paddings, and borders.
-  - Nesting with other components.`,
+- Setting up specific stylings such as background colors, paddings, and borders.
+- Nesting with other components.`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Use for structural layouts with consistent spacing patterns
+- Avoid adding too many borders that may visually fragment the interface`,
     },
   ],
   definitions: [

packages/ui-extensions/src/surfaces/admin/components/Button/Button.doc.ts

@@ -5,6 +5,37 @@ const data: AdminReferenceEntityTemplateSchema = {
   ...sharedContent,
   thumbnail: '/assets/templated-apis-screenshots/admin/components/button.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Taking primary actions like saving or creating resources
+- Taking secondary actions like canceling forms or filtering results
+- Triggering destructive operations like deletion or disconnection
+- Accessing supplementary actions via tertiary buttons`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Be clearly and accurately labeled with strong, actionable verbs
+- Use established button tones appropriately (e.g., critical tone only for actions that are difficult to undo)
+- Prioritize the most important actions to avoid confusion
+- Be positioned in consistent locations in the interface
+- Use buttons for actions and links for navigation`,
+    },
+    {
+      title: 'Content guidelines',
+      type: 'Generic' as const,
+      anchorLink: 'content-guidelines',
+      sectionContent: `- Use simple, concise verbs (e.g., "Save", "Edit", "Add tags")
+- Write in sentence case
+- Avoid unnecessary words and articles (e.g., "a", "an", "the")
+- Don't use punctuation
+- For icon-only buttons, use \`accessibilityLabel\` to describe the action`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

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

@@ -6,6 +6,23 @@ const data: AdminReferenceEntityTemplateSchema = {
   thumbnail:
     '/assets/templated-apis-screenshots/admin/components/buttongroup.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Accessing related actions in a consistent layout
+- Making secondary actions visible alongside primary actions`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Group together related calls to action
+- Avoid too many actions that may cause uncertainty
+- Consider how buttons will work on small screens`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Checkbox/Checkbox.doc.ts

@@ -5,6 +5,25 @@ const data: AdminReferenceEntityTemplateSchema = {
   ...sharedContent,
   thumbnail: '/assets/templated-apis-screenshots/admin/components/checkbox.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Work independently from each other
+- Be framed positively (e.g., "Publish store" not "Hide store")
+- Always have a label when used to activate or deactivate a setting
+- Be listed in a logical order (alphabetical, numerical, time-based, etc.)`,
+    },
+    {
+      title: 'Content guidelines',
+      type: 'Generic' as const,
+      anchorLink: 'content-guidelines',
+      sectionContent: `- Start each option with a capital letter
+- Don't use commas or semicolons at the end of each line
+- Use first person when asking merchants to agree to terms (e.g., "I agree to the Terms of Service")`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Chip/Chip.doc.ts

@@ -5,6 +5,38 @@ const data: AdminReferenceEntityTemplateSchema = {
   ...sharedContent,
   thumbnail: '/assets/templated-apis-screenshots/admin/components/chip.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Labeling, organizing, and categorizing objects
+- Highlighting content attributes
+- Enhancing discoverability by identifying items with similar properties`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- \`subdued\`: use for secondary or less important information
+- \`base\`: use as default color
+- \`strong\`: use for important or verified status
+- Text truncates automatically, keep labels short to avoid truncation
+- Chips are static indicators, not interactive or dismissible. For interactive chips, use ClickableChip
+- Add icons to \`graphic\` slot to provide visual context
+- Display chips near the content they classify`,
+    },
+    {
+      title: 'Content guidelines',
+      type: 'Generic' as const,
+      anchorLink: 'content-guidelines',
+      sectionContent: `Chip labels should:
+- Be short and concise to avoid truncation
+- Use \`accessibilityLabel\` to describe purpose for screen readers
+- Common status labels: \`Active\`, \`Draft\`, \`Published\`, \`Verified\`
+- Common category labels: \`Product type\`, \`Collection\`, \`Tag name\``,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/ChoiceList/ChoiceList.doc.ts

@@ -7,6 +7,25 @@ const data: AdminReferenceEntityTemplateSchema = {
   thumbnail:
     '/assets/templated-apis-screenshots/admin/components/choicelist.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Include a title that tells merchants what to do or explains the available options
+- Label options clearly based on what the option will do
+- Avoid mutually exclusive options when allowing multiple selection`,
+    },
+    {
+      title: 'Content guidelines',
+      type: 'Generic' as const,
+      anchorLink: 'content-guidelines',
+      sectionContent: `- Write titles and choices in sentence case
+- End titles with a colon if they introduce the list
+- Start each choice with a capital letter
+- Don't use commas or semicolons at the end of lines`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/ClickableChip/ClickableChip.doc.ts

@@ -6,6 +6,26 @@ const data: AdminReferenceEntityTemplateSchema = {
   thumbnail:
     '/assets/templated-apis-screenshots/admin/components/clickable-chip.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Creating interactive filters or tags that can be clicked or removed
+- Navigating to related content when configured as a link
+- Allowing merchants to dismiss or remove applied filters or selections`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Use for interactive chips that merchants can click or dismiss
+- Use Chip component instead for static, non-interactive indicators
+- Keep labels short to avoid truncation
+- Use color variants to indicate importance (subdued, base, strong)
+- Add icons to provide visual context`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',