@shopify/ui-extensions 2025.10.12 → 2025.10.14

package/package.json

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

package/src/api.ts

@@ -1,11 +1,15 @@
 /**
- * This defines the i18n.translate() signature.
+ * The translation function signature for internationalization. Use this to translate string keys defined in your locale files into localized content for the current user's language.
  */
 export interface I18nTranslate {
   /**
-   * This returns a translated string matching a key in a locale file.
+   * Returns a translated string matching a key in a locale file. Use this to display localized text in your extension based on the merchant's language preferences. Supports interpolation with replacement values and pluralization with the `count` option. Returns a string when replacements are primitives, or an array when replacements include UI components.
+   *
+   * @param key - The translation key from your locale file (for example, "banner.title")
+   * @param options - Optional replacement values for interpolation or the special `count` property for pluralization
    *
    * @example translate("banner.title")
+   * @example translate("items.count", { count: 5 })
    */
   <ReplacementType = string>(
     key: string,
@@ -15,14 +19,16 @@ export interface I18nTranslate {
     : (string | ReplacementType)[];
 }
 
+/**
+ * Internationalization utilities for formatting and translating content according to the user's locale. Use these methods to display numbers, currency, dates, and translated strings that match the merchant's language and regional preferences.
+ */
 export interface I18n {
   /**
-   * Returns a localized number.
-   *
-   * This function behaves like the standard `Intl.NumberFormat()`
-   * with a style of `decimal` applied. It uses the buyer's locale by default.
+   * Returns a localized number formatted according to the user's locale. Use this to display numbers like quantities, percentages, or measurements in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `decimal` applied. Uses the current user's locale by default.
    *
-   * @param options.inExtensionLocale - if true, use the extension's locale
+   * @param number - The number to format
+   * @param options.inExtensionLocale - If true, use the extension's default locale instead of the user's locale
+   * @param options - Additional Intl.NumberFormatOptions for customizing the number format
    */
   formatNumber: (
     number: number | bigint,
@@ -30,12 +36,11 @@ export interface I18n {
   ) => string;
 
   /**
-   * Returns a localized currency value.
+   * Returns a localized currency value formatted according to the user's locale and currency conventions. Use this to display prices, totals, or financial amounts in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `currency` applied. Uses the current user's locale by default.
    *
-   * This function behaves like the standard `Intl.NumberFormat()`
-   * with a style of `currency` applied. It uses the buyer's locale by default.
-   *
-   * @param options.inExtensionLocale - if true, use the extension's locale
+   * @param number - The currency amount to format
+   * @param options.inExtensionLocale - If true, use the extension's default locale instead of the user's locale
+   * @param options - Additional Intl.NumberFormatOptions for customizing the currency format, such as the currency code
    */
   formatCurrency: (
     number: number | bigint,
@@ -43,16 +48,14 @@ export interface I18n {
   ) => string;
 
   /**
-   * Returns a localized date value.
+   * Returns a localized date value formatted according to the user's locale and date conventions. Use this to display dates and times in the appropriate format for the merchant's region, such as order dates, timestamps, or schedule information. This function behaves like the standard `Intl.DateTimeFormat()` and uses the current user's locale by default. Formatting options can be passed to customize the date display style.
    *
-   * This function behaves like the standard `Intl.DateTimeFormatOptions()` and uses
-   * the buyer's locale by default. Formatting options can be passed in as
-   * options.
+   * @param date - The Date object to format
+   * @param options.inExtensionLocale - If true, use the extension's default locale instead of the user's locale
+   * @param options - Additional Intl.DateTimeFormatOptions for customizing the date format
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat0
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
    * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
-   *
-   * @param options.inExtensionLocale - if true, use the extension's locale
    */
   formatDate: (
     date: Date,
@@ -60,13 +63,7 @@ export interface I18n {
   ) => string;
 
   /**
-   * Returns translated content in the buyer's locale,
-   * as supported by the extension.
-   *
-   * - `options.count` is a special numeric value used in pluralization.
-   * - The other option keys and values are treated as replacements for interpolation.
-   * - If the replacements are all primitives, then `translate()` returns a single string.
-   * - If replacements contain UI components, then `translate()` returns an array of elements.
+   * Returns translated content in the user's locale, as supported by the extension. Use this to display localized strings from your extension's locale files. The special `options.count` property enables pluralization. Other option keys and values are treated as replacements for interpolation in your translation strings. Returns a single string when replacements are primitives, or an array when replacements contain UI components.
    */
   translate: I18nTranslate;
 }

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

@@ -0,0 +1,200 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const CHECKOUT_PATH =
+  '/docs/api/checkout-ui-extensions/latest/using-polaris-components';
+
+interface DefinitionsConfiguration {
+  properties?: boolean;
+  events?: boolean;
+  slots?: boolean;
+  methods?: boolean;
+}
+
+interface ComponentDoc {
+  name: ReferenceEntityTemplateSchema['name'];
+  description: ReferenceEntityTemplateSchema['description'];
+  category: ReferenceEntityTemplateSchema['category'];
+  related?: ReferenceEntityTemplateSchema['related'];
+  requires?: ReferenceEntityTemplateSchema['requires'];
+  type?: ReferenceEntityTemplateSchema['type'];
+  isVisualComponent?: ReferenceEntityTemplateSchema['isVisualComponent'];
+  definitions: DefinitionsConfiguration;
+  typeName?: string;
+  subcomponent?: {
+    name: ReferenceEntityTemplateSchema['name'];
+    description?: ReferenceEntityTemplateSchema['description'];
+    definitions: DefinitionsConfiguration;
+  };
+  usefulFor?: string;
+  considerations?: string;
+  bestPractices?: string;
+  subCategory?: ReferenceEntityTemplateSchema['subCategory'];
+  extraContent?: ReferenceEntityTemplateSchema['subSections'];
+  extraExamples?: ReferenceEntityTemplateSchema['examples'];
+}
+
+function toPascalCase(name: string) {
+  return name
+    .split(' ')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
+function buildDefinitions({
+  name,
+  description,
+  definitions,
+  typeName: typeNameOverride,
+}: {
+  name: string;
+  description?: string;
+  definitions: DefinitionsConfiguration;
+  typeName?: string;
+}) {
+  const typeName = typeNameOverride ?? toPascalCase(name);
+  // Components with events or methods export a separate {Name}ElementProps
+  // interface; simpler components only export {Name}Props.
+  const propsType =
+    definitions.events || definitions.methods
+      ? `${typeName}ElementProps`
+      : `${typeName}Props`;
+
+  return [
+    ...(description
+      ? [
+          {
+            title: `${name}`,
+            description,
+            type: propsType,
+          },
+        ]
+      : []),
+
+    ...(!description && definitions.properties
+      ? [
+          {
+            title: 'Properties',
+            description: '',
+            type: propsType,
+          },
+        ]
+      : []),
+
+    ...(definitions.events
+      ? [
+          {
+            title: 'Events',
+            description: `Learn more about [registering events](${CHECKOUT_PATH}#event-handling).`,
+            type: `${typeName}ElementEvents`,
+          },
+        ]
+      : []),
+
+    ...(definitions.slots
+      ? [
+          {
+            title: 'Slots',
+            description: `Learn more about [component slots](${CHECKOUT_PATH}#slots).`,
+            type: `${typeName}ElementSlots`,
+          },
+        ]
+      : []),
+
+    ...(definitions.methods
+      ? [
+          {
+            title: 'Methods',
+            description: `Learn more about [component methods](${CHECKOUT_PATH}#methods).`,
+            type: `${typeName}ElementMethods`,
+          },
+        ]
+      : []),
+  ];
+}
+
+export function createComponentDoc({
+  name,
+  description,
+  category,
+  related = [],
+  requires = '',
+  type = '',
+  subCategory = '',
+  isVisualComponent = true,
+  definitions,
+  typeName,
+  subcomponent,
+  usefulFor,
+  considerations,
+  bestPractices,
+  extraContent = [],
+  extraExamples,
+}: ComponentDoc): ReferenceEntityTemplateSchema {
+  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 {
+    name,
+    description,
+    category,
+    related,
+    isVisualComponent,
+    thumbnail: `${kebabCasedName}-thumbnail.png`,
+    requires,
+    type,
+    subCategory,
+    definitions: [
+      ...buildDefinitions({name, definitions, typeName}),
+      ...(subcomponent ? buildDefinitions(subcomponent) : []),
+    ],
+    defaultExample: {
+      image: `${kebabCasedName}-default.png`,
+      codeblock: {
+        title: 'Code',
+        tabs: [
+          {
+            code: `./examples/basic-${kebabCasedName}.example.html`,
+            language: 'html',
+          },
+        ],
+      },
+    },
+    examples: extraExamples,
+    subSections: [
+      ...(usefulFor
+        ? [
+            {
+              title: 'Useful for',
+              type: 'Generic' as const,
+              anchorLink: 'useful-for',
+              sectionContent: usefulFor,
+            },
+          ]
+        : []),
+      ...(considerations
+        ? [
+            {
+              title: 'Considerations',
+              type: 'Generic' as const,
+              anchorLink: 'considerations',
+              sectionContent: considerations,
+            },
+          ]
+        : []),
+      ...(bestPractices
+        ? [
+            {
+              type: 'Generic' as const,
+              anchorLink: 'best-practices',
+              title: 'Best Practices',
+              sectionContent: bestPractices,
+            },
+          ]
+        : []),
+      ...extraContent,
+    ],
+  };
+}

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: [],
 };