Components description edits

jffortier · web-flow · commit f7129d8c708d · 2025-05-16T16:33:09.000-04:00
diff --git a/packages/ui-extensions/src/docs/shared/components/Abbreviation.ts b/packages/ui-extensions/src/docs/shared/components/Abbreviation.ts
@@ -2,7 +2,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Abbreviation',
-  description: 'A text that represents an abbreviation or acronym.',
+  description:
+    'Displays abbreviated text or acronyms, revealing their full meaning or additional context through a tooltip on hover or focus. Use to clarify shortened terms, initialisms, or technical language without interrupting the reading flow.',
   category: 'Polaris web components',
   subCategory: 'Titles and text',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/Banner.ts b/packages/ui-extensions/src/docs/shared/components/Banner.ts
@@ -3,7 +3,7 @@ import {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Banner',
   description:
-    'Use `s-banner` to communicate important status updates or indicate that there are important actions that users must take. \n\n You can use banners both as a standalone component on a page or inside of a `s-section`.',
+    'Highlights important information or required actions prominently within the interface. Use to communicate statuses, provide feedback, or draw attention to critical updates.',
   category: 'Polaris web components',
   subCategory: 'Feedback',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/Box.ts b/packages/ui-extensions/src/docs/shared/components/Box.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Box',
   description:
-    'The `s-box` component is an escape hatch for building custom user interfaces. You should only use `s-box` when you cannot build what you need with the existing components.',
+    'A generic container that provides a flexible alternative for custom designs not achievable with existing components. Use it to apply styling such as backgrounds, padding, or borders, or to nest and group other components. The contents of Box always maintain their natural size, making it especially useful within layout components that would otherwise stretch their children.',
   category: 'Polaris web components',
   subCategory: 'Structure',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/Button.ts b/packages/ui-extensions/src/docs/shared/components/Button.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Button',
   description:
-    'Use `s-button` when you want to provide users the ability to perform specific actions, submitting forms, or opening dialogs.',
+    'Triggers actions or events, such as submitting forms, opening dialogs, or navigating to other pages. Use Button to let users perform specific tasks or initiate interactions throughout the interface. Buttons can also function as links, guiding users to internal or external destinations.',
   category: 'Polaris web components',
   subCategory: 'Actions',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/ClipboardItem.ts b/packages/ui-extensions/src/docs/shared/components/ClipboardItem.ts
@@ -2,13 +2,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'ClipboardItem',
-  description: `
-  This component is used alongside a \`Button\` or \`Link\` component to facilitate writing to the user's clipboard.
-
-  ClipboardItem's \`--auto\` command is \`--copy\`, which copies the content of the text prop to the clipboard.
-
-  \`ClipboardItem\` is a non-rendering component.
-`,
+  description:
+    'Enables copying text to the user’s clipboard. Use alongside Button or Link components to let users easily copy content. `<s-clipboard-item>` doesn’t render visually.',
   category: 'Polaris web components',
   subCategory: 'utilities',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/DropZone.ts b/packages/ui-extensions/src/docs/shared/components/DropZone.ts
@@ -2,11 +2,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'DropZone',
-  description: `
-    \`s-drop-zone\` allows file uploads through drag-and-drop functionality into a designated area on a page, or by activating a button. At present, \`s-drop-zone\` does not offer image upload preview capabilities. The use of object URLs directly in an image component is not possible due to the extension and host operating on separate domains.
-
-    Any element focused within the \`s-drop-zone\` component, including child elements such as the 'Add file' button, will initiate the file selector when the Enter or Spacebar key is pressed.
-    `,
+  description:
+    'Lets users upload files through drag-and-drop functionality into a designated area on a page, or by activating a button.',
   category: 'Polaris web components',
   subCategory: 'Forms',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/Form.ts b/packages/ui-extensions/src/docs/shared/components/Form.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Form',
   description:
-    'The form component should be used to wrap one or more form controls. This component provides an "implicit submit" behavior, where customers can submit the form from any input by pressing "Enter" on their keyboards. This behavior is widely expected, and should be respected as often as possible.\n\nUnlike an HTML `form` element, this component does not support configuring the descendant fields to be submitted via HTTP automatically. Instead, you must provide an `onSubmit` callback that will perform the necessary HTTP requests in JavaScript.',
+    'Wraps one or more form controls and enables implicit submission, letting users submit the form from any input by pressing “Enter.” Unlike the HTML form element, this component doesn’t automatically submit data via HTTP. You must register a `submit` event to handle form submission in JavaScript.',
   category: 'Polaris web components',
   subCategory: 'Forms',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/Heading.ts b/packages/ui-extensions/src/docs/shared/components/Heading.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Heading',
   description:
-    'The `s-heading` component renders hierarchical titles similar to HTML’s `h1-h6` elements. Heading levels are automatically determined by parent `s-section` nesting depth starting from `h2`. Always prefer using the `heading` property on `s-section` and `s-banner` components before constructing custom layout with `s-heading`.',
+    'Renders hierarchical titles to communicate the structure and organization of page content. Heading levels adjust automatically based on nesting within parent Section components, ensuring a meaningful and accessible page outline.',
   category: 'Polaris web components',
   subCategory: 'Titles and text',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/Icon.ts b/packages/ui-extensions/src/docs/shared/components/Icon.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Icon',
   description:
-    'Icons are pictograms or graphic symbols. They can act as wayfinding tools or as a means of communicating functionality.',
+    'Renders a graphic symbol to visually communicate core parts of the product and available actions. Icons can act as wayfinding tools to help users quickly understand their location within the interface and common interaction patterns.',
   category: 'Polaris web components',
   subCategory: 'Media',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/Image.ts b/packages/ui-extensions/src/docs/shared/components/Image.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Image',
   description:
-    'Use `s-image` when you want to display an image. \n\n When using images or illustrations in your app, ensure that they add clarity and clearly direct users to the next step. Make sure to use high-resolution images to ensure a professional, high-quality experience.',
+    'Embeds an image within the interface and controls its presentation. Use to visually illustrate concepts, showcase products, or support user tasks and interactions.',
   category: 'Polaris web components',
   subCategory: 'Media',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/Link.ts b/packages/ui-extensions/src/docs/shared/components/Link.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Link',
   description:
-    '`s-link` is an interactive component that directs users to a specified URL. It even supports custom protocols.',
+    'Makes text interactive, allowing users to navigate to other pages or perform specific actions. Supports standard URLs, custom protocols, and navigation within Shopify or app pages.',
   category: 'Polaris web components',
   subCategory: 'Actions',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/ListItem.ts b/packages/ui-extensions/src/docs/shared/components/ListItem.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'ListItem',
   description:
-    'Use `s-list-item` as children of the `s-unordered-list` or `s-ordered-list` component.',
+    'Represents a single item within an unordered or ordered list. Use only as a child of `s-unordered-list` or `s-ordered-list` components.',
   category: 'Polaris web components',
   subCategory: 'Structure',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/OrderedList.ts b/packages/ui-extensions/src/docs/shared/components/OrderedList.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'OrderedList',
   description:
-    '`s-ordered-list` displays a set of related text-only content beginning with a number.',
+    'Displays a numbered list of related items in a specific sequence. Use to present step-by-step instructions, ranked items, or procedures where order matters.',
   category: 'Polaris web components',
   subCategory: 'Structure',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/Paragraph.ts b/packages/ui-extensions/src/docs/shared/components/Paragraph.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Paragraph',
   description:
-    'Use `s-paragraph` to display a block of text similar to the `<p>` tag in HTML.',
+    'Displays a block of text, and can contain inline elements such as buttons, links, or emphasized text. Use to present standalone blocks of content, as opposed to inline text.',
   category: 'Polaris web components',
   subCategory: 'Titles and text',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/PaymentIcon.ts b/packages/ui-extensions/src/docs/shared/components/PaymentIcon.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'PaymentIcon',
   description:
-    'Payment icons can be used for displaying payment-related information or features such as a user’s saved or available payment methods.',
+    'Displays icons representing payment methods. Use to visually communicate available or saved payment options clearly',
   category: 'Polaris web components',
   subCategory: 'Media',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/Progress.ts b/packages/ui-extensions/src/docs/shared/components/Progress.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Progress',
   description:
-    'Progress displays a progress bar in determinate or indeterminate state.',
+    'Displays an indicator showing the completion status of a task. Use to visually communicate progress in either determinate (known percentage) or indeterminate (unknown duration) states.',
   category: 'Polaris web components',
   subCategory: 'Feedback',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/QRCode.ts b/packages/ui-extensions/src/docs/shared/components/QRCode.ts
@@ -2,7 +2,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'QRCode',
-  description: 'Used to quickly access scannable data.',
+  description:
+    'Displays a scannable QR code representing data such as URLs or text. Use to let users quickly access information by scanning with a smartphone or other device.',
   category: 'Polaris web components',
   subCategory: 'Other',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/Spinner.ts b/packages/ui-extensions/src/docs/shared/components/Spinner.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Spinner',
   description:
-    'Use `s-spinner` to let users know that content is being loaded. For loading states on buttons, use the `loading` property on the `s-button` component instead.',
+    'Displays an animated indicator showing users that content or actions are loading. Use to communicate ongoing processes, such as fetching data from a server. For loading states on buttons, use the “loading” property on the Button component instead.',
   category: 'Polaris web components',
   subCategory: 'Feedback',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/Stack.ts b/packages/ui-extensions/src/docs/shared/components/Stack.ts
@@ -2,11 +2,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Stack',
-  description: `
-    \`s-stack\` structures layout elements along the [block or inline axes](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_display/Block_and_inline_layout_in_normal_flow) of the page. It is useful for organizing buttons, creating layouts that adjust to screen size, and controlling spacing between elements.
-    It’s important to note that Stack does not include any padding by default. If you need padding around your stacked elements, use \`base\` to apply the default padding.
-    When using \`s-stack\`, use smaller gaps between small elements and larger gaps between big ones. Maintain a consistent spacing in stacks across all pages of your app.
-  `,
+  description:
+    'Organizes elements horizontally or vertically along the block or inline axis. Use to structure layouts, group related components, or control spacing between elements.',
   category: 'Polaris web components',
   subCategory: 'Structure',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/Text.ts b/packages/ui-extensions/src/docs/shared/components/Text.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Text',
   description:
-    'The `s-text` component is used for inline text styling, similar to HTML `span` elements, not for paragraph-level content. Use it to apply different visual tones and text styles to specific words or phrases within a `s-paragraph`, such as a `strong` type or `critical` tone.',
+    'Displays inline text with specific visual styles or tones. Use to emphasize or differentiate words or phrases within a Paragraph or other block-level components.',
   category: 'Polaris web components',
   subCategory: 'Titles and text',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/TextField.ts b/packages/ui-extensions/src/docs/shared/components/TextField.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'TextField',
   description:
-    'Use a text field to allow users to enter or edit text. Text fields provide a single-line input area for collecting string values from users.',
+    'Lets users enter or edit text within a single-line input. Use to collect short, free-form information from users.',
   category: 'Polaris web components',
   subCategory: 'Forms',
   related: [],
diff --git a/packages/ui-extensions/src/docs/shared/components/Time.ts b/packages/ui-extensions/src/docs/shared/components/Time.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Time',
   description:
-    'Represents a specific period in time. It may include the datetime attribute to translate dates into machine-readable format.',
+    'Represents a specific point or duration in time. Use to display dates, times, or durations clearly and consistently. May include a machine-readable `datetime` attribute for improved accessibility and functionality.',
   category: 'Polaris web components',
   subCategory: 'Titles and text',
   related: [
diff --git a/packages/ui-extensions/src/docs/shared/components/UnorderedList.ts b/packages/ui-extensions/src/docs/shared/components/UnorderedList.ts
@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'UnorderedList',
   description:
-    '`s-unordered-list` displays a set of related text-only content beginning with a bullet.',
+    'Displays a bulleted list of related items. Use to present collections of items or options where the sequence isn’t critical.',
   category: 'Polaris web components',
   subCategory: 'Structure',
   related: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/Heading/shared.ts b/packages/ui-extensions/src/surfaces/admin/components/Heading/shared.ts
@@ -17,7 +17,7 @@ const shared = {
       type: 'Generic' as const,
       anchorLink: 'considerations',
       sectionContent: `- The level of the heading is automatically determined by how deeply it's nested inside other components, starting from h2.
-- Default to using the \`heading\` property in \`s-section\`. The \`s-heading\` component should only be used if you need to implement a custom layout for your heading in the UI.`,
+- Default to using the \`heading\` property in components that support it (e.g. Section and Banner). The \`s-heading\` component should only be used if you need to implement a custom layout for your heading in the UI.`,
     },
     {
       title: 'Best practices',
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Heading/Heading.doc.ts b/packages/ui-extensions/src/surfaces/checkout/components/Heading/Heading.doc.ts
@@ -28,13 +28,29 @@ const data: ReferenceEntityTemplateSchema = {
   },
   subSections: [
     {
+      title: 'Useful for',
+      type: 'Generic',
+      anchorLink: 'useful-for',
+      sectionContent: `- Creating titles and subtitles for your content that are consistent across your app.
+- Helping users with visual impairments navigate through content effectively using assistive technologies like screen readers.`,
+    },
+    {
+      title: 'Considerations',
+      type: 'Generic',
+      anchorLink: 'considerations',
+      sectionContent: `- The level of the heading is automatically determined by how deeply it's nested inside other components, starting from h2.
+- Default to using the \`heading\` property in components that support it (e.g. Section and Banner). The \`s-heading\` component should only be used if you need to implement a custom layout for your heading in the UI.`,
+    },
+    {
+      title: 'Best practices',
       type: 'Generic',
       anchorLink: 'best-practices',
-      title: 'Best Practices',
       sectionContent: `
-        - Add a heading at the top of each section that clearly describe what’s below.
-        - Use the heading to highlight the most important concepts or pieces of information that customers need to know.
-      `,
+- Use short headings to make your content scannable.
+- Use plain and clear terms.
+- Don't use jargon or technical language.
+- Don't use different terms to describe the same thing.
+- Don't duplicate content.`,
     },
   ],
 };
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Image/Image.doc.ts b/packages/ui-extensions/src/surfaces/checkout/components/Image/Image.doc.ts
@@ -26,6 +26,17 @@ const data: ReferenceEntityTemplateSchema = {
       ],
     },
   },
+  subSections: [
+    {
+      title: 'Best practices',
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      sectionContent: `
+- Use high-resolution images to ensure a professional and high-quality experience.
+- Use optimized images so your app loads as fast as possible.
+- Use images intentionally, these should add clarity and lead users to the next step.`,
+    },
+  ],
 };
 
 export default data;
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Stack/Stack.doc.ts b/packages/ui-extensions/src/surfaces/checkout/components/Stack/Stack.doc.ts
@@ -28,11 +28,28 @@ const data: ReferenceEntityTemplateSchema = {
   },
   subSections: [
     {
+      title: 'Useful for',
+      type: 'Generic',
+      anchorLink: 'useful-for',
+      sectionContent: `
+- Placing items in rows or columns when sections don't work for your layout.
+- Controlling the spacing between elements.`,
+    },
+    {
+      title: 'Considerations',
+      type: 'Generic',
+      anchorLink: 'considerations',
+      sectionContent: `
+- Stack doesn't add any padding by default. If you want padding around your stacked elements, use \`base\` to apply the default padding.
+- When spacing becomes limited, Stack will always wrap children to a new line.`,
+    },
+    {
+      title: 'Best practices',
       type: 'Generic',
       anchorLink: 'best-practices',
-      title: 'Best Practices',
-      sectionContent:
-        '- Use Stack when you need to arrange elements vertically or horizontally with consistent spacing.\n\n- Stack is particularly useful for forms, lists, and any content that needs to flow vertically or horizontally.\n\n- Consider using Stack when you need to maintain consistent rhythm between elements in a single direction.',
+      sectionContent: `
+- Use smaller gaps between small elements and larger gaps between big ones.
+- Maintain consistent spacing in stacks across all pages of your app.`,
     },
   ],
 };
diff --git a/packages/ui-extensions/src/surfaces/checkout/components/Text/Text.doc.ts b/packages/ui-extensions/src/surfaces/checkout/components/Text/Text.doc.ts
