Polaris code example updates for Action components

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

@@ -33,19 +33,16 @@ const data: AdminReferenceEntityTemplateSchema = {
     },
   ],
   defaultExample: {
-    image: 'button-default.png',
+    image: 'buttongroup-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.',
     codeblock: {
-      title: 'Code',
+      title: 'Group a primary and secondary action',
       tabs: [
         {
           code: './examples/default.html',
-          language: 'html',
-          layout: 'inline',
-        },
-        {
-          code: './examples/default.jsx',
-          language: 'preview-jsx',
-          layout: 'inline',
+          language: 'preview',
+          title: '',
         },
       ],
     },
@@ -54,111 +51,60 @@ const data: AdminReferenceEntityTemplateSchema = {
     description: 'Component examples',
     exampleGroups: [
       {
-        title: 'Basic usage',
+        title: '',
         examples: [
           {
             description:
-              'Standard button group with cancel and primary action for form workflows.',
+              'Present multiple secondary actions for operating on selected items. This example shows archive, export, and delete buttons grouped together for bulk operations.',
             codeblock: {
-              title: 'Basic usage',
-              tabs: [
-                {
-                  code: './examples/basic-usage.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/basic-usage.jsx',
-                  language: 'preview-jsx',
-                },
-              ],
-            },
-          },
-          {
-            description:
-              'Action buttons for selected items with destructive option.',
-            codeblock: {
-              title: 'Bulk action buttons',
+              title: 'Add bulk action buttons',
               tabs: [
                 {
                   code: './examples/bulk-actions-in-data-tables.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/bulk-actions-in-data-tables.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },
           },
           {
             description:
-              'Typical form completion actions with clear visual hierarchy.',
+              'Add icons to grouped buttons to help merchants identify each action. This example shows duplicate, archive, and delete buttons with icons.',
             codeblock: {
-              title: 'Form action buttons',
-              tabs: [
-                {
-                  code: './examples/form-action-buttons.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/form-action-buttons.jsx',
-                  language: 'preview-jsx',
-                },
-              ],
-            },
-          },
-          {
-            description: 'Icon-labeled buttons for common actions.',
-            codeblock: {
-              title: 'Buttons with icons',
+              title: 'Add icons to grouped buttons',
               tabs: [
                 {
                   code: './examples/toolbar-buttons-with-icons.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/toolbar-buttons-with-icons.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },
           },
           {
             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',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/segmented-appearance.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },
           },
           {
             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',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/destructive-actions-pattern.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },

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

@@ -38,16 +38,15 @@ const data: AdminReferenceEntityTemplateSchema = {
   ],
   defaultExample: {
     image: 'clickable-default.png',
+    description:
+      "Build custom interactive elements with flexible styling that [button](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/actions/button) or [link](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/actions/link) don't support. This example shows two clickable elements with different background and border styles.",
     codeblock: {
-      title: 'Code',
+      title: 'Create a custom interactive element',
       tabs: [
         {
           code: './examples/default.html',
-          language: 'html',
-        },
-        {
-          code: './examples/default.jsx',
-          language: 'preview-jsx',
+          language: 'preview',
+          title: '',
         },
       ],
     },
@@ -56,112 +55,74 @@ const data: AdminReferenceEntityTemplateSchema = {
     description: 'Component examples',
     exampleGroups: [
       {
-        title: 'Basic usage',
+        title: '',
         examples: [
           {
             description:
-              'A simple clickable button with a base border and padding, demonstrating the default button behavior of the clickable component.',
+              'Set the `href` property to make a clickable element navigate like a link. This example shows a clickable component that opens a URL in a new browser tab.',
             codeblock: {
-              title: 'Basic Button Usage',
-              tabs: [
-                {
-                  code: './examples/basic-button-usage.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/basic-button-usage.jsx',
-                  language: 'preview-jsx',
-                },
-              ],
-            },
-          },
-          {
-            description:
-              "Demonstrates the clickable component's ability to function as a link, opening the specified URL in a new browser tab when clicked.",
-            codeblock: {
-              title: 'Link Mode',
+              title: 'Navigate to a URL',
               tabs: [
                 {
                   code: './examples/link-mode.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/link-mode.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },
           },
           {
             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 component as a form submit button with a disabled state to prevent premature submission. This example shows a disabled submit-type clickable component with a border and padding.',
             codeblock: {
-              title: 'Form Submit Button',
+              title: 'Create a form submit button',
               tabs: [
                 {
                   code: './examples/form-submit-button.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/form-submit-button.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },
           },
           {
             description:
-              'Illustrates how the clickable component can be integrated into a section layout to provide an interactive action button.',
+              'Add a clickable button alongside descriptive content in a section. 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',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/section-with-clickable-action.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },
           },
           {
             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',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/accessibility-with-aria-attributes.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },
           },
           {
             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',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/disabled-link-with-aria.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
+                  title: '',
                 },
               ],
             },