Update titles and descriptions for code examples

Author: timtrevor-shopify

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

@@ -37,8 +37,10 @@ const data: AdminReferenceEntityTemplateSchema = {
     examples: [
       {
         image: 'button-default.png',
+        description:
+          'Group related buttons together with a primary action and secondary options. This example shows a button group with a save button and a cancel button using the slot layout.',
         codeblock: {
-          title: 'Default',
+          title: 'Group a primary and secondary action',
           tabs: [
             {
               code: './examples/default.html',
@@ -55,9 +57,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Action buttons for selected items with destructive option.',
+          'Present multiple secondary actions for operating on selected items. This example shows archive, export, and delete buttons grouped together for bulk operations.',
         codeblock: {
-          title: 'Bulk action buttons',
+          title: 'Add bulk action buttons',
           tabs: [
             {
               code: './examples/bulk-actions-in-data-tables.html',
@@ -71,9 +73,10 @@ const data: AdminReferenceEntityTemplateSchema = {
         },
       },
       {
-        description: 'Icon-labeled buttons for common actions.',
+        description:
+          'Add icons to grouped buttons to help merchants quickly identify each action. This example shows duplicate, archive, and delete buttons with icons.',
         codeblock: {
-          title: 'Buttons with icons',
+          title: 'Add icons to grouped buttons',
           tabs: [
             {
               code: './examples/toolbar-buttons-with-icons.html',
@@ -88,9 +91,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Tightly grouped buttons for view switching and filter options.',
+          'Remove the gap between buttons to create a segmented control for toggling between views or options. This example shows day, week, and month buttons joined together with no spacing.',
         codeblock: {
-          title: 'Segmented appearance',
+          title: 'Create a segmented button group',
           tabs: [
             {
               code: './examples/segmented-appearance.html',
@@ -105,9 +108,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Confirmation dialog style with cancel option and destructive action.',
+          'Pair a cancel button with a critical action for destructive confirmation flows. This example shows a cancel and delete button grouped together for a confirmation dialog.',
         codeblock: {
-          title: 'Destructive actions pattern',
+          title: 'Confirm a destructive action',
           tabs: [
             {
               code: './examples/destructive-actions-pattern.html',

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

@@ -41,8 +41,10 @@ const data: AdminReferenceEntityTemplateSchema = {
     examples: [
       {
         image: 'clickable-default.png',
+        description:
+          "Build custom interactive elements with flexible styling that Button or Link don't support. This example shows two clickable elements with different background and border styles.",
         codeblock: {
-          title: 'Default',
+          title: 'Create a custom interactive element',
           tabs: [
             {
               code: './examples/default.html',
@@ -57,9 +59,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          "Demonstrates the clickable component's ability to function as a link, opening the specified URL in a new browser tab when clicked.",
+          'Set href to make a clickable element navigate like a link. This example shows a clickable that opens a URL in a new browser tab.',
         codeblock: {
-          title: 'Link Mode',
+          title: 'Navigate to a URL',
           tabs: [
             {
               code: './examples/link-mode.html',
@@ -74,9 +76,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          "A disabled submit button that can be used within a form, showing the component's form integration capabilities and disabled state.",
+          'Use a clickable as a form submit button with a disabled state to prevent premature submission. This example shows a disabled submit-type clickable with border and padding.',
         codeblock: {
-          title: 'Form Submit Button',
+          title: 'Create a form submit button',
           tabs: [
             {
               code: './examples/form-submit-button.html',
@@ -91,9 +93,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Illustrates how the clickable component can be integrated into a section layout to provide an interactive action button.',
+          'Embed a clickable element within a content section to provide an interactive action alongside text. This example shows a styled clickable button inside a box with a heading and description.',
         codeblock: {
-          title: 'Section with Clickable Action',
+          title: 'Add a clickable action to a section',
           tabs: [
             {
               code: './examples/section-with-clickable-action.html',
@@ -108,9 +110,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          "Demonstrates the use of an accessibility label to provide context for screen readers, enhancing the component's usability for users with assistive technologies.",
+          'Add an accessibility label to provide screen readers with more context than the visible text alone. This example shows a clickable delete button with a descriptive label for assistive technologies.',
         codeblock: {
-          title: 'Accessibility with ARIA Attributes',
+          title: 'Add an accessibility label',
           tabs: [
             {
               code: './examples/accessibility-with-aria-attributes.html',
@@ -125,9 +127,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Shows a disabled link with an accessibility label, explaining the unavailability of a feature to users of assistive technologies.',
+          'Disable a clickable link while providing an accessibility label that explains why the feature is unavailable. This example shows a disabled navigation element with a descriptive label for screen readers.',
         codeblock: {
-          title: 'Disabled Link with ARIA',
+          title: 'Describe a disabled link with an accessibility label',
           tabs: [
             {
               code: './examples/disabled-link-with-aria.html',

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

@@ -41,10 +41,11 @@ const data: AdminReferenceEntityTemplateSchema = {
     description: 'Component examples',
     examples: [
       {
-        description: 'Default clickable chip.',
+        description:
+          'Create an interactive chip that merchants can click to trigger an action. This example a clickable chip with default styling.',
         image: 'clickable-chip-default.png',
         codeblock: {
-          title: 'Default',
+          title: 'Add a clickable chip with default styling',
           tabs: [
             {
               code: './examples/default.html',
@@ -59,9 +60,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Demonstrates a simple clickable chip with a base color and interactive functionality.',
+          'Use the `color` property to visually distinguish chips by importance or category. This example shows three chips with base, subdued, and strong color variants.',
         codeblock: {
-          title: 'Basic Usage',
+          title: 'Apply color variants to chips',
           tabs: [
             {
               code: './examples/basic-usage.html',
@@ -76,9 +77,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Showcases a strong-colored clickable chip with a check circle icon and a removable state.',
+          'Add an icon and a remove button so merchants can see status at a glance and dismiss the chip. This example shows a removable chip with a check circle icon in the graphic slot.',
         codeblock: {
-          title: 'With Icon and Remove Button',
+          title: 'Add an icon and a remove button to a chip',
           tabs: [
             {
               code: './examples/with-icon-and-remove-button.html',
@@ -93,9 +94,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Demonstrates a subdued clickable chip configured as a link with a product icon.',
+          'Set `href` to make a chip link to another page when clicked. This example shows a subdued chip with a product icon that acts as a link.',
         codeblock: {
-          title: 'As a Link',
+          title: 'Use a chip as a link',
           tabs: [
             {
               code: './examples/as-a-link.html',
@@ -110,9 +111,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Illustrates a clickable chip in a disabled state, preventing interaction while displaying an inactive status.',
+          'Disable a chip to prevent interaction while keeping it visible. This example shows a disabled chip with an accessibility label explaining the inactive state.',
         codeblock: {
-          title: 'Disabled State',
+          title: 'Disable a clickable chip',
           tabs: [
             {
               code: './examples/disabled-state.html',

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

@@ -46,8 +46,10 @@ const data: AdminReferenceEntityTemplateSchema = {
     examples: [
       {
         image: 'link-default.png',
+        description:
+          'Add an inline link to let merchants navigate to another page. This example shows a basic text link with an `href` property.',
         codeblock: {
-          title: 'Default',
+          title: 'Add a basic link',
           tabs: [
             {
               code: './examples/default.html',
@@ -62,9 +64,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Links automatically inherit the tone from their surrounding paragraph context.',
+          'Embed links within paragraph text so merchants can navigate to related content inline. This example shows two links inside a paragraph that inherit the surrounding text tone.',
         codeblock: {
-          title: 'Basic Links in Paragraph',
+          title: 'Embed links in paragraph text',
           tabs: [
             {
               code: './examples/basic-links-in-paragraph.html',
@@ -79,9 +81,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Demonstrates how links can be integrated within banner components to highlight important information and provide direct action paths.',
+          'Place links inside banners to provide direct actions alongside important notifications. This example shows a link inside an info banner prompting merchants to create a campaign.',
         codeblock: {
-          title: 'Links in Banner',
+          title: 'Add links inside a banner',
           tabs: [
             {
               code: './examples/links-in-banner.html',
@@ -96,9 +98,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Illustrates using links within a box container to provide contextual navigation and additional information in a visually contained area.',
+          'Place links inside a box container to provide navigation within a visually distinct content area. This example shows two links inside a bordered box with background and padding.',
         codeblock: {
-          title: 'Links in Box Container',
+          title: 'Add links inside a box container',
           tabs: [
             {
               code: './examples/links-in-box-container.html',
@@ -113,9 +115,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Demonstrates how to create links that trigger file downloads, useful for exporting data or providing downloadable resources.',
+          'Use the download attribute to trigger a file download when the link is clicked. This example shows a link that downloads a CSV file for customer data export.',
         codeblock: {
-          title: 'Download Links',
+          title: 'Trigger a file download',
           tabs: [
             {
               code: './examples/download-links.html',
@@ -130,9 +132,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Illustrates linking to external resources with different targets, showing how to open links in new tabs and provide navigation to external documentation.',
+          'Open external URLs in a new tab so merchants stay on the current page. This example shows two links with `target="_blank"` pointing to external documentation.',
         codeblock: {
-          title: 'External Links',
+          title: 'Open external links in a new tab',
           tabs: [
             {
               code: './examples/external-links.html',
@@ -147,9 +149,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Shows how to use the `lang` attribute to specify the language of a link, supporting internationalization and proper screen reader pronunciation.',
+          'Set the `lang` attribute so screen readers pronounce the link text correctly. This example shows a French-language link with the `lang` attribute set.',
         codeblock: {
-          title: 'Links with Language Attribute',
+          title: 'Set the language for a link',
           tabs: [
             {
               code: './examples/links-with-language-attribute.html',
@@ -164,9 +166,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Demonstrates how links can have different visual tones, including default, neutral, and critical, allowing for varied contextual styling.',
+          'Configure links to inherit the tone of their parent paragraph to match the surrounding context. This example shows links inside paragraphs with six different tones.',
         codeblock: {
-          title: 'Links with Different Tones',
+          title: 'Match link tone to surrounding context',
           tabs: [
             {
               code: './examples/links-with-different-tones.html',

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

@@ -44,8 +44,10 @@ const data: AdminReferenceEntityTemplateSchema = {
     description: 'Component examples',
     examples: [
       {
+        description:
+          'Add a dropdown menu of actions triggered by a button. This example shows a menu with three icon buttons including a critical delete action.',
         codeblock: {
-          title: 'Default',
+          title: 'Add a basic actions menu',
           tabs: [
             {
               code: './examples/default.html',
@@ -68,9 +70,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Shows how to organize menu items into logical sections with headings, helping to group related actions and improve menu readability.',
+          'Organize menu items into labeled groups so merchants can quickly find related actions. This example shows two sections with headings separating product actions from export options.',
         codeblock: {
-          title: 'Menu with Sections',
+          title: 'Organize items into sections',
           tabs: [
             {
               code: './examples/menu-with-sections.html',
@@ -89,9 +91,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          "Demonstrates a menu with a mix of link-based buttons, standard buttons, and a disabled button, showcasing the menu's flexibility in handling different interaction states.",
+          'Mix link-based, standard, and disabled buttons in a single menu. This example shows a menu with a link that opens in a new tab, a disabled action, and a download link.',
         codeblock: {
-          title: 'Menu with Links and Disabled Items',
+          title: 'Add links and disabled items to a menu',
           tabs: [
             {
               code: './examples/menu-with-links-and-disabled-items.html',
@@ -110,9 +112,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          "Presents a comprehensive menu showing how to create sections with different action groups and include a critical action at the menu's root level.",
+          'Combine sections with root-level items to separate grouped actions from standalone ones like a destructive action. This example shows two sections for customer management alongside a root-level delete button.',
         codeblock: {
-          title: 'Actions menu with sections',
+          title: 'Mix sections with root-level actions',
           tabs: [
             {
               code: './examples/customer-actions-menu.html',
@@ -131,9 +133,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Illustrates a complex menu with nested sections, demonstrating how to organize multiple related actions with icons.',
+          'Build a settings-style menu with multiple sections and a standalone action at the bottom. This example shows account and store settings sections with a root-level sign-out link.',
         codeblock: {
-          title: 'Menu with nested sections',
+          title: 'Build a settings menu with sections',
           tabs: [
             {
               code: './examples/settings-menu.html',
@@ -152,9 +154,9 @@ const data: AdminReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Use an icon-only button as the menu trigger for a compact "more actions" pattern commonly used in toolbars and table rows.',
+          'Use an icon-only button as the menu trigger for a compact "more actions" pattern. This example shows a three-dot icon button that opens a menu with common product actions.',
         codeblock: {
-          title: 'Icon-only trigger',
+          title: 'Trigger a menu from an icon-only button',
           tabs: [
             {
               code: './examples/icon-only-trigger.html',