@shopify/ui-extensions 2026.1.2 → 2026.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2026.1.2",
+  "version": "2026.1.3",
   "scripts": {
     "docs:admin": "node ./docs/surfaces/admin/build-docs.mjs",
     "docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",

package/src/docs/shared/component-definitions.ts

@@ -32,6 +32,13 @@ interface ComponentDoc {
   extraExamples?: ReferenceEntityTemplateSchema['examples'];
 }
 
+function toPascalCase(name: string) {
+  return name
+    .split(' ')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
 function buildDefinitions({
   name,
   description,
@@ -41,13 +48,15 @@ function buildDefinitions({
   description?: string;
   definitions: DefinitionsConfiguration;
 }) {
+  const typeName = toPascalCase(name);
+
   return [
     ...(description
       ? [
           {
             title: `${name}`,
             description,
-            type: `${name}ElementProps`,
+            type: `${typeName}ElementProps`,
           },
         ]
       : []),
@@ -57,7 +66,7 @@ function buildDefinitions({
           {
             title: 'Properties',
             description: '',
-            type: `${name}ElementProps`,
+            type: `${typeName}ElementProps`,
           },
         ]
       : []),
@@ -67,7 +76,7 @@ function buildDefinitions({
           {
             title: 'Events',
             description: `Learn more about [registering events](${CHECKOUT_PATH}#event-handling).`,
-            type: `${name}ElementEvents`,
+            type: `${typeName}ElementEvents`,
           },
         ]
       : []),
@@ -77,7 +86,7 @@ function buildDefinitions({
           {
             title: 'Slots',
             description: `Learn more about [component slots](${CHECKOUT_PATH}#slots).`,
-            type: `${name}ElementSlots`,
+            type: `${typeName}ElementSlots`,
           },
         ]
       : []),
@@ -87,7 +96,7 @@ function buildDefinitions({
           {
             title: 'Methods',
             description: `Learn more about [component methods](${CHECKOUT_PATH}#methods).`,
-            type: `${name}ElementMethods`,
+            type: `${typeName}ElementMethods`,
           },
         ]
       : []),
@@ -114,6 +123,7 @@ export function createComponentDoc({
   const kebabCasedName = name
     .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
     .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/\s+/g, '-')
     .toLowerCase();
 
   return {

package/src/docs/shared/components/Abbreviation.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Abbreviation',
   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',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

package/src/docs/shared/components/Announcement.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Announcement',
   description:
     'The Announcement component provides a less disruptive alternative to auto-open modals for capturing user attention. It provides a standardized way to engage users without being too intrusive.',
-  category: 'Polaris web components',
-  subCategory: 'Feedback',
+  category: 'Web components',
+  subCategory: 'Feedback and status indicators',
   related: [],
 };
 

package/src/docs/shared/components/Avatar.ts

@@ -3,8 +3,9 @@ import {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Avatar',
   description:
-    'Show a user’s profile image or initials in a compact, visual element.',
-  category: 'Polaris web components',
+    "The avatar component displays profile images or initials for users, customers, and businesses in a compact visual format. Use avatar to represent people or entities throughout the interface, with automatic fallback to initials when images aren't available." +
+    '\n\nAvatars support multiple sizes for different contexts and provide consistent color assignment for initials based on the name provided. For product or content preview images, use [thumbnail](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/thumbnail). For full-size images, use [image](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/image).',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };

package/src/docs/shared/components/Badge.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Badge',
   description:
-    'Inform users about the status of an object or indicate that an action has been completed.',
-  category: 'Polaris web components',
+    'The badge component displays status information or indicates completed actions through compact visual indicators. Use badge to communicate object states, order statuses, or system-generated classifications that help users quickly understand item conditions.' +
+    '\n\nBadges support multiple tones and sizes, with optional icons to reinforce status meaning and improve scannability in lists and tables. For user-created labels, categories, or tags, use [chip](/docs/api/{API_NAME}/{API_VERSION}/web-components/typography-and-content/chip) instead.',
+  category: 'Web components',
   subCategory: 'Feedback and status indicators',
   related: [],
 };

package/src/docs/shared/components/Banner.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Banner',
   description:
-    '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',
+    'The banner component highlights important information or required actions prominently within the interface. Use banner to communicate statuses, provide feedback, draw attention to critical updates, or guide users toward necessary actions.' +
+    '\n\nBanners support multiple tones to convey urgency levels, optional actions for next steps, and can be positioned contextually within sections or page-wide at the top. For inline status indicators on individual items, use [badge](/docs/api/{API_NAME}/{API_VERSION}/web-components/feedback-and-status-indicators/badge).',
+  category: 'Web components',
   subCategory: 'Feedback and status indicators',
   related: [],
 };

package/src/docs/shared/components/Box.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Box',
   description:
-    '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',
+    "The box component provides a generic, flexible container for custom designs and layouts. Use box to apply styling like backgrounds, padding, borders, or border radius when existing components don't meet your needs, or to nest and group other components." +
+    '\n\nBox contents maintain their natural size, making it especially useful within layout components that would otherwise stretch their children. For structured layouts, use [stack](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/stack) or [grid](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/grid).',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/Button.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Button',
   description:
-    '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',
+    'The button component triggers actions or events, such as submitting forms, opening dialogs, or navigating to other pages. Use buttons to let users perform specific tasks or initiate interactions throughout the interface.' +
+    '\n\nButtons support various visual styles, tones, and interaction patterns to communicate intent and hierarchy. They can also function as links, guiding users to internal or external destinations. For navigation-focused interactions within text, use [link](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/link). For grouping multiple related buttons, use [button group](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button-group).',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };

package/src/docs/shared/components/ButtonGroup.ts

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ButtonGroup',
-  description: 'Displays multiple buttons in a layout.',
-  category: 'Polaris web components',
+  name: 'Button group',
+  description:
+    'The button group component displays multiple related buttons in a structured layout. Use button group to organize action buttons together, creating clear visual hierarchies and helping users understand available options.' +
+    '\n\nButton groups support various layouts including segmented appearances for tightly related options like view switching or filter controls. For individual actions, use [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button).',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };

package/src/docs/shared/components/Checkbox.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Checkbox',
   description:
-    'Give users a clear way to make selections, such as agreeing to terms or choosing multiple items from a list.',
-  category: 'Polaris web components',
+    'The checkbox component provides a clear way for users to make selections, such as agreeing to terms, enabling settings, or choosing multiple items from a list. Use checkbox to create binary on/off controls or multi-select interfaces where users can select any combination of options.' +
+    '\n\nCheckboxes support labels, help text, error states, and an indeterminate state for "select all" functionality when working with grouped selections. For settings that take effect immediately, use [switch](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/switch) instead.',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Chip.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Chip',
   description:
-    'Represents a set of user-supplied keywords that help label, organize, and categorize objects. Used to categorize or highlight content attributes. They are often displayed near the content they classify, enhancing discoverability by allowing users to identify items with similar properties.',
-  category: 'Polaris web components',
+    'The chip component displays static labels, categories, or attributes that help classify and organize content. Use chip to show product tags, categories, or metadata near the items they describe, helping users identify items with similar properties.' +
+    '\n\nChips support multiple visual variants for different levels of emphasis and can include icons to provide additional visual context. For system-generated status indicators, use [badge](/docs/api/{API_NAME}/{API_VERSION}/web-components/feedback-and-status-indicators/badge). For interactive or removable chips, use [clickable chip](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/clickable-chip).',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/docs/shared/components/Choice.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Choice',
   description:
-    'Create options that let users select one or multiple items from a list of choices.',
-  category: 'Polaris web components',
+    'The choice component creates individual selectable options within a choice list. Use choice to define each option that merchants can select, supporting both single selection (radio buttons) and multiple selection (checkboxes) modes.' +
+    '\n\nChoice components support labels, help text, and custom content through slots, providing flexible option presentation within choice lists.',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/ChoiceList.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ChoiceList',
+  name: 'Choice list',
   description:
-    'Present multiple options to users, allowing either single selections with radio buttons or multiple selections with checkboxes.',
-  category: 'Polaris web components',
+    'The choice list component presents multiple options for single or multiple selections. Use it when merchants need to choose from a defined set of options, such as filtering results or collecting preferences.' +
+    '\n\nThe component supports both single selection (radio button behavior) and multiple selection (checkbox behavior) modes. It includes configurable labels, help text, and validation. For compact dropdown selection with four or more options, use [select](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/select).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Clickable.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Clickable',
   description:
-    'A generic interactive container component that provides a flexible alternative for custom interactive elements not achievable with existing components like Button or Link. Use it to apply specific styling such as backgrounds, padding, or borders.',
-  category: 'Polaris web components',
+    'The clickable component wraps content to make it interactive and clickable. Use it when you need more styling control than [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) or [link](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/link) provide, such as custom backgrounds, padding, or borders around your clickable content.' +
+    '\n\nClickable supports button, link, and submit modes with built-in accessibility properties for keyboard navigation and screen reader support.',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };

package/src/docs/shared/components/ClickableChip.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ClickableChip',
+  name: 'Clickable chip',
   description:
-    'Interactive button used to categorize or highlight content attributes. They are often displayed near the content they classify, enhancing discoverability by allowing users to identify items with similar properties.',
-  category: 'Polaris web components',
+    'The clickable chip component displays interactive labels or categories that users can click or remove. Use clickable chip to show filter tags, selected options, or merchant-created labels that users need to interact with or dismiss.' +
+    '\n\nClickable chips support multiple visual variants, optional icons, and can function as both clickable buttons and removable tags for flexible interaction patterns. For non-interactive labels, use [chip](/docs/api/{API_NAME}/{API_VERSION}/web-components/typography-and-content/chip).',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };

package/src/docs/shared/components/ClipboardItem.ts

@@ -1,11 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ClipboardItem',
+  name: 'Clipboard item',
   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',
+  category: 'Web components',
+  subCategory: 'Actions',
   related: [],
 };
 

package/src/docs/shared/components/ColorField.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ColorField',
+  name: 'Color field',
   description:
-    'Allow users to select a color with a color picker or as a text input.',
-  category: 'Polaris web components',
+    'The color field component allows users to select colors through an integrated color picker or direct text input. Use color field for theme colors, brand colors, or any color selection to provide both visual and text-based color input methods.' +
+    '\n\nColor fields support hex color codes, color preview swatches, and validation to ensure users select or enter valid color values. For a standalone visual color palette interface without text input, use [color picker](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/color-picker).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/ColorPicker.ts

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ColorPicker',
-  description: 'Allow users to select a color from a color palette.',
-  category: 'Polaris web components',
+  name: 'Color picker',
+  description:
+    'The color picker component allows users to select colors from a visual color palette interface. Use color picker to provide an intuitive, visual way for users to choose colors for themes, branding, or design customization.' +
+    '\n\nColor pickers support multiple color formats, predefined color swatches, and interactive selection to make color choice easy and accurate. For combined visual and text-based color input with validation, use [color field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/color-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/ConsentCheckbox.ts

@@ -1,10 +1,10 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ConsentCheckbox',
+  name: 'Consent checkbox',
   description:
     'Use buyer consent checkboxes for collecting the buyer’s approval for a given policy.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/ConsentPhoneField.ts

@@ -1,10 +1,10 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ConsentPhoneField',
+  name: 'Consent phone field',
   description:
     'Display a phone field for customers to sign up for text message marketing, noting that the phone field value will be automatically saved during checkout.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/DateField.ts

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'DateField',
-  description: 'Allow users to select a specific date with a date picker.',
-  category: 'Polaris web components',
+  name: 'Date field',
+  description:
+    'The date field component captures date input with a consistent interface for date selection and proper validation. Use it to collect date information in forms, scheduling interfaces, or data entry workflows.' +
+    '\n\nThe component supports manual text entry. For visual calendar-based selection, consider using [date picker](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/date-picker).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/DatePicker.ts

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'DatePicker',
-  description: 'Allow users to select a specific date or date range.',
-  category: 'Polaris web components',
+  name: 'Date picker',
+  description:
+    'The date picker component allows merchants to select dates using a calendar interface. Use it when merchants benefit from seeing dates in context of the full month, such as selecting dates relative to today or needing weekday context.' +
+    '\n\nThe component supports single dates, multiple dates, and date ranges. For text date entry, use [date field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/date-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Details.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Details',
   description:
     'Creates a collapsible content area that can be expanded or collapsed by users. Use with Summary to provide expandable sections for additional information or settings.',
-  category: 'Polaris web components',
-  subCategory: 'Interactive',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

package/src/docs/shared/components/Divider.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Divider',
   description:
-    'Create clear visual separation between elements in your user interface.',
-  category: 'Polaris web components',
+    'The divider component creates clear visual separation between elements in the interface. Use divider to separate distinct content groups in forms, settings panels, lists, or page sections, helping users scan and understand content organization.' +
+    '\n\nDividers support both horizontal and vertical orientations, along with different visual strengths for varying levels of emphasis. For more structured content grouping with headings, use [section](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/section).',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/DropZone.ts

@@ -1,10 +1,10 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'DropZone',
+  name: 'Drop zone',
   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',
+    'The drop zone component lets users upload files through drag-and-drop or by clicking to browse. Use for file uploads such as images, documents, or CSV imports.\n\nThe component provides visual feedback during drag operations and supports file type validation through the `accept` property. Rejected files trigger the `droprejected` event for custom error handling.',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/EmailField.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'EmailField',
+  name: 'Email field',
   description:
-    'Let users enter email addresses with optimized keyboard settings.',
-  category: 'Polaris web components',
+    'The email field component captures email address input. Use it to collect email information in forms, customer profiles, or contact workflows.' +
+    "\n\nEmail field doesn't perform automatic email validation. Implement your own validation logic, and use the `error` property to display validation results. For general text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-field).",
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Form.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Form',
   description:
-    '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',
+    'The form component wraps form controls and enables implicit submission, allowing users to submit from any input by pressing **Enter**. Use form to group related input fields and handle form submission through JavaScript event handlers.' +
+    "\n\nUnlike HTML forms, form doesn't automatically submit data using HTTP—you must register a `submit` event to process form data programmatically. For Shopify Functions configuration forms, use [function settings](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/function-settings).",
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/FunctionSettings.ts

@@ -1,28 +1,13 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'FunctionSettings',
+  name: 'Function settings',
   description:
-    'FunctionSettings should be used when configuring the metafield configuration of a Shopify Function. It provides a structure for various input fields and controls, such as text fields, checkboxes, and selections. It also integrates with the native Contextual Save Bar to handle form submission and reset actions.',
-  category: 'Polaris web components',
+    'The function settings component configures metafield settings for [Shopify Functions](/docs/api/functions). Use function settings to create configuration interfaces that allow merchants to customize function behavior through structured input fields and controls.' +
+    '\n\nThis component provides a standardized layout for settings forms and integrates with the native save bar to handle form submission and reset actions automatically. For general form submission, use [form](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/form).',
+  category: 'Web components',
   subCategory: 'Forms',
-  related: [
-    {
-      type: 'component',
-      name: 'TextField',
-      url: '/docs/api/admin-extensions/components/forms/textfield',
-    },
-    {
-      type: 'component',
-      name: 'NumberField',
-      url: '/docs/api/admin-extensions/components/forms/numberfield',
-    },
-    {
-      type: 'component',
-      name: 'ChoiceList',
-      url: '/docs/api/admin-extensions/components/forms/choicelist',
-    },
-  ],
+  related: [],
 };
 
 export default data;

package/src/docs/shared/components/Grid.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Grid',
   description:
-    'Use `s-grid` to organize your content in a matrix of rows and columns and make responsive layouts for pages. Grid follows the same pattern as the [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout).',
-  category: 'Polaris web components',
+    'The grid component organizes content in a matrix of rows and columns to create responsive page layouts. Use grid to build complex, multi-column layouts that adapt to different screen sizes and maintain consistent alignment.' +
+    '\n\nGrid follows the CSS grid layout pattern and supports flexible column configurations, gap spacing, and alignment properties for precise layout control. For simpler linear layouts (horizontal or vertical), use [stack](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/stack).',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/GridItem.ts

@@ -1,10 +1,12 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'GridItem',
-  description: 'Display content within a single item of a grid layout.',
-  category: 'Polaris web components',
-  subCategory: 'Structure',
+  name: 'Grid item',
+  description:
+    'The grid item component represents a single cell within a grid layout, allowing you to control how content is positioned and sized within the grid. Use grid item as a child of grid to specify column span, row span, and positioning for individual content areas.' +
+    '\n\nGrid item supports precise placement control through column and row properties, enabling you to create complex layouts where different items occupy varying amounts of space or appear in specific grid positions.',
+  category: 'Web components',
+  subCategory: 'Layout and structure',
   related: [],
 };
 

package/src/docs/shared/components/Heading.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Heading',
   description:
-    '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',
+    'The heading component renders hierarchical titles to communicate the structure and organization of page content. Use heading to create section titles and content headers that help users understand information hierarchy and navigate content.' +
+    '\n\nHeading levels adjust automatically based on nesting within parent [section](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/section) components, ensuring meaningful and accessible page outlines without manual level management.',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/docs/shared/components/Icon.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Icon',
   description:
-    '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',
+    'The icon component renders graphic symbols to visually communicate actions, status, and navigation throughout the interface. Use icon to reinforce button actions, indicate status states, or provide wayfinding cues that help users understand available functionality.' +
+    '\n\nIcons support multiple sizes, tones for semantic meaning, and can be integrated with other components like [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button), [badge](/docs/api/{API_NAME}/{API_VERSION}/web-components/feedback-and-status-indicators/badge), and [chip](/docs/api/{API_NAME}/{API_VERSION}/web-components/typography-and-content/chip) to enhance visual communication.',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };

package/src/docs/shared/components/Image.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Image',
   description:
-    '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',
+    'The image component embeds images within the interface with control over presentation and loading behavior. Use image to visually illustrate concepts, showcase products, display user content, or support tasks and interactions with visual context.' +
+    '\n\nImages support responsive sizing, alt text for accessibility, aspect ratio control, and loading states for progressive enhancement. For small preview images in lists or tables, use [thumbnail](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/thumbnail). For profile images, use [avatar](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/avatar).',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };

package/src/docs/shared/components/Link.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Link',
   description:
-    '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',
+    'The link component makes text interactive, allowing users to navigate to other pages or perform specific actions. Use link for navigation, external references, or triggering actions while maintaining standard link semantics and accessibility.' +
+    '\n\nLinks support standard URLs, custom protocols, navigation within Shopify admin pages, and can open in new windows for external destinations. For prominent actions or form submissions, use [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) instead.',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };