Merge pull request #3644 from Shopify/improve-admin-component-docs

Improve admin component documentation for common usage patterns

Author: davejcameron

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

@@ -10,7 +10,8 @@ const data: AdminReferenceEntityTemplateSchema = {
       title: 'Best practices',
       type: 'Generic' as const,
       anchorLink: 'best-practices',
-      sectionContent: `- Work independently from each other
+      sectionContent: `- Use ChoiceList when rendering multiple checkboxes to provide a consistent and accessible selection interface
+- 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.)`,

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

@@ -5,6 +5,14 @@ import gridItemSharedContent from '../../../../docs/shared/components/GridItem';
 const data: AdminReferenceEntityTemplateSchema = {
   ...sharedContent,
   subSections: [
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Always configure layout properties when using Grid. At minimum, set gridTemplateColumns to define your column structure (e.g., repeat(12, 1fr) for a 12-column grid)
+- Use gap to add spacing between grid items rather than adding margins to individual items
+- Combine gridTemplateColumns with gridColumn on GridItem components to control how items span across columns`,
+    },
     {
       title: 'Useful for',
       type: 'Generic' as const,

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

@@ -6,6 +6,14 @@ const data: AdminReferenceEntityTemplateSchema = {
   thumbnail:
     '/assets/templated-apis-screenshots/admin/components/searchfield.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- The SearchField automatically includes a clear button when text is entered, so you should not create your own clear button`,
+    },
+  ],
   definitions: [
     {
       title: 'SearchField',

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

@@ -17,7 +17,8 @@ const data: AdminReferenceEntityTemplateSchema = {
       title: 'Best practices',
       type: 'Generic' as const,
       anchorLink: 'best-practices',
-      sectionContent: `- Use plain and clear terms.
+      sectionContent: `- Text elements display inline and will flow on the same line when placed next to each other. To stack multiple text elements vertically, wrap them in a Stack container or use multiple \`s-paragraph\` components.
+- 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.`,