[App home] Match UX changes for templates - one column.

packages/ui-extensions/docs/surfaces/admin/build-docs.mjs

@@ -237,6 +237,14 @@ const templates = {
     wrapperElement: 's-box',
     wrapperAttributes: 'padding="base", inlineSize="100%"',
   }),
+  templatePattern: createTemplate({
+    layoutStyles:
+      'width: 100%; transform: scale(1.0); transform-origin: top left;',
+  }),
+  compositionPattern: createTemplate({
+    layoutStyles:
+      'display: grid; align-items: center; justify-items: stretch; gap: 0.5rem; padding: 1rem;',
+  }),
   example: createTemplate({
     layoutStyles: 'display: grid; place-items: center; gap: 0.5rem;',
     wrapperElement: 's-box',

packages/ui-extensions/src/surfaces/admin/components/patterns/accountConnection.ab.doc.ts

@@ -1,6 +1,6 @@
-import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {AdminReferenceEntityTemplateSchema} from '../../docs-types';
 
-const data: ReferenceEntityTemplateSchema = {
+const data: AdminReferenceEntityTemplateSchema = {
   name: 'Account connection',
   isOneColumnLayout: false,
   overviewPreviewDescription:
@@ -15,9 +15,22 @@ const data: ReferenceEntityTemplateSchema = {
   subCategory: 'Compositions',
   thumbnail:
     '/assets/templated-apis-screenshots/admin/patterns/accountConnection.png',
+  usedComponents: [
+    'Button',
+    'Grid',
+    'GridItem',
+    'Heading',
+    'Section',
+    'Stack',
+    'Text',
+  ],
+  recommendedApis: ['Modal API', 'Toast API'],
+  recommendedTemplates: ['Settings'],
   defaultExample: {
+    description:
+      'Merchants need to connect or disconnect external services (e.g. marketing platforms, sales channels) from your app. This pattern displays account connection layout with a connect button and terms. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) aligns account information and button, the [section](/docs/api/app-home/polaris-web-components/layout-and-structure/section) provides padding, and the terms text below describes the connection agreement.',
     codeblock: {
-      title: 'Account connection',
+      title: 'Display connection status with connect button and terms',
       tabs: [
         {
           title: 'html',
@@ -28,19 +41,64 @@ const data: ReferenceEntityTemplateSchema = {
           title: 'jsx',
           code: 'examples/accountConnection.jsx',
           language: 'preview-jsx',
+          layout: 'compositionPattern',
         },
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the account connection pattern with additional functionality:
 
-  related: [
-    {
-      name: 'Built for Shopify',
-      subtitle: 'Requirements',
-      url: '/docs/apps/launch/built-for-shopify/requirements',
-      type: 'component',
-    },
-  ],
+- [Modal API](#example-confirm-disconnect-with-modal): Confirm account disconnection before removing an integration.
+- [Toast API](#example-show-connection-feedback-with-toast): Show feedback when connection status changes.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use the [Modal API](/docs/api/app-home/apis/modal-api) to confirm account disconnection before removing the integration.',
+            codeblock: {
+              title: 'Confirm disconnect with Modal',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/accountConnection-modal.jsx',
+                  language: 'preview-jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/accountConnection-modal.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+          {
+            description:
+              'Use the [Toast API](/docs/api/app-home/apis/toast) to show feedback when an account is connected or disconnected.',
+            codeblock: {
+              title: 'Show connection feedback with Toast',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/accountConnection-toast.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/accountConnection-toast.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/admin/components/patterns/appCard.ab.doc.ts

@@ -1,6 +1,6 @@
-import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {AdminReferenceEntityTemplateSchema} from '../../docs-types';
 
-const data: ReferenceEntityTemplateSchema = {
+const data: AdminReferenceEntityTemplateSchema = {
   name: 'App card',
   isOneColumnLayout: false,
   overviewPreviewDescription:
@@ -13,9 +13,23 @@ const data: ReferenceEntityTemplateSchema = {
   category: 'Patterns',
   subCategory: 'Compositions',
   thumbnail: '/assets/templated-apis-screenshots/admin/patterns/appCard.png',
+  usedComponents: [
+    'Box',
+    'Button',
+    'Clickable',
+    'Grid',
+    'Heading',
+    'Paragraph',
+    'Stack',
+    'Thumbnail',
+  ],
+  recommendedApis: ['Navigation API'],
+  recommendedTemplates: ['Homepage'],
   defaultExample: {
+    description:
+      "Merchants can discover and install complementary apps that extend your app's functionality. This pattern displays a tappable app card with thumbnail and content layout. The [clickable](/docs/api/app-home/polaris-web-components/actions/clickable) component wraps the card, the [thumbnail](/docs/api/app-home/polaris-web-components/images/thumbnail) shows the app icon, and the [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) aligns the content.",
     codeblock: {
-      title: 'App card',
+      title: 'Display a tappable app card with thumbnail and content',
       tabs: [
         {
           title: 'html',
@@ -26,19 +40,43 @@ const data: ReferenceEntityTemplateSchema = {
           title: 'jsx',
           code: 'examples/appCard.jsx',
           language: 'preview-jsx',
+          layout: 'compositionPattern',
         },
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the app card with additional functionality:
 
-  related: [
-    {
-      name: 'Built for Shopify',
-      subtitle: 'Requirements',
-      url: '/docs/apps/launch/built-for-shopify/requirements',
-      type: 'component',
-    },
-  ],
+- [Navigation API](#example-navigate-to-app-store): Provide a link a recommended app when merchants click the card or its install button.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use `href` attributes to navigate merchants to the App Store when they click the card or install button.',
+            codeblock: {
+              title: 'Navigate to App Store',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/appCard-nav.jsx',
+                  language: 'preview-jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/appCard-nav.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/admin/components/patterns/calloutCard.ab.doc.ts

@@ -1,6 +1,6 @@
-import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {AdminReferenceEntityTemplateSchema} from '../../docs-types';
 
-const data: ReferenceEntityTemplateSchema = {
+const data: AdminReferenceEntityTemplateSchema = {
   name: 'Callout card',
   isOneColumnLayout: false,
   overviewPreviewDescription:
@@ -14,9 +14,23 @@ const data: ReferenceEntityTemplateSchema = {
   subCategory: 'Compositions',
   thumbnail:
     '/assets/templated-apis-screenshots/admin/patterns/calloutCard.png',
+  usedComponents: [
+    'Box',
+    'Button',
+    'Grid',
+    'Heading',
+    'Image',
+    'Paragraph',
+    'Section',
+    'Stack',
+  ],
+  recommendedApis: ['Navigation API', 'Toast API'],
+  recommendedTemplates: ['Homepage'],
   defaultExample: {
+    description:
+      'Merchants can take action on new features or opportunities you highlight. This pattern presents a callout card that stacks content on smaller screens with a prominent illustration and call-to-action. The [grid](/docs/api/app-home/polaris-web-components/layout-and-structure/grid) uses responsive column templates. The illustration and button draw attention to important actions or promotions.',
     codeblock: {
-      title: 'Callout card',
+      title: 'Display a callout card with illustration and call-to-action',
       tabs: [
         {
           title: 'html',
@@ -27,19 +41,64 @@ const data: ReferenceEntityTemplateSchema = {
           title: 'jsx',
           code: 'examples/calloutCard.jsx',
           language: 'preview-jsx',
+          layout: 'compositionPattern',
         },
       ],
     },
   },
+  examples: {
+    description: `The examples below show how you can extend the callout card with additional functionality:
 
-  related: [
-    {
-      name: 'Built for Shopify',
-      subtitle: 'Requirements',
-      url: '/docs/apps/launch/built-for-shopify/requirements',
-      type: 'component',
-    },
-  ],
+- [Navigation API](#example-navigate-to-feature-pages): Add links to the pattern for CTA navigation.
+- [Toast API](#example-show-dismiss-feedback-with-toast): Dismiss feedback.`,
+    exampleGroups: [
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Use `href` attributes on buttons to navigate merchants to feature pages when they click CTA buttons.',
+            codeblock: {
+              title: 'Navigate to feature pages',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/calloutCard-nav.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/calloutCard-nav.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+          {
+            description:
+              'Use the [Toast API](/docs/api/app-home/apis/toast) to show feedback when the callout card is dismissed.',
+            codeblock: {
+              title: 'Show dismiss feedback with Toast',
+              tabs: [
+                {
+                  title: 'jsx',
+                  code: 'examples/calloutCard-toast.jsx',
+                  language: 'jsx',
+                  layout: 'compositionPattern',
+                },
+                {
+                  title: 'html',
+                  code: 'examples/calloutCard-toast.html',
+                  language: 'html',
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  },
 };
 
 export default data;