@shopify/ui-extensions 2025.10.13 → 2025.10.14

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

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

@@ -1,11 +1,12 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ListItem',
+  name: 'List item',
   description:
-    'Represents a single item within an unordered or ordered list. Use only as a child of `s-unordered-list` or `s-ordered-list` components.',
-  category: 'Polaris web components',
-  subCategory: 'Structure',
+    'The list item component represents a single entry within an ordered list or unordered list. Use list item to structure individual points, steps, or items within a list, with each item automatically receiving appropriate list markers (bullets or numbers) from its parent list.' +
+    '\n\nList item must be used as a direct child of ordered list or unordered list components. Each list item can contain text, inline formatting, or other components to create rich list content.',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

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

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Map',
   description:
     'Use Map to display a map on a page. This component is useful for displaying a map of a location, such as a store or a customer’s address.',
-  category: 'Polaris web components',
-  subCategory: 'Interactive',
+  category: 'Web components',
+  subCategory: 'Media and visuals',
   related: [],
 };
 

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

@@ -1,11 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'MapMarker',
+  name: 'Map marker',
   description:
     'Use MapMarker to display a marker on a map. Use only as a child of `s-map` component.',
-  category: 'Polaris web components',
-  subCategory: 'Interactive',
+  category: 'Web components',
+  subCategory: 'Media and visuals',
   related: [],
 };
 

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

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Menu',
   description:
-    'Use Menu to display a list of actions that can be performed on a resource.',
-  category: 'Polaris web components',
+    'The menu component displays a list of actions that can be performed on a resource or within a specific context. Use menu to present multiple related actions in a compact dropdown format, reducing visual clutter while maintaining discoverability.' +
+    '\n\nMenus support action grouping, icons for visual clarity, and keyboard navigation for efficient interaction.',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };

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

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Modal',
   description:
     'Displays content in an overlay. Use to create a distraction-free experience such as a confirmation dialog or a settings panel.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Overlays',
   related: [],
 };

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

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'MoneyField',
+  name: 'Money field',
   description:
-    'Collect monetary values from users with built-in currency formatting and validation.',
-  category: 'Polaris web components',
+    'The money field component collects monetary values from users with built-in currency formatting and validation. Use money field for prices, costs, or financial amounts to provide proper currency symbols, decimal handling, and numeric validation.' +
+    '\n\nMoney fields support currency codes, automatic formatting, and min/max constraints to ensure users enter valid monetary values. For non-currency numeric input, use [number field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/number-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'NumberField',
+  name: 'Number field',
   description:
-    'Collect numerical values from users with optimized keyboard settings and built-in validation.',
-  category: 'Polaris web components',
+    'The number field component captures numeric input with built-in number validation. Use it to collect quantities, prices, or other numeric information.' +
+    '\n\nThe component supports min/max constraints and step increments for guided numeric entry. For monetary values with currency formatting, use [money field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/money-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Option',
   description:
     'Represents a single option within a select component. Use only as a child of `s-select` components.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -1,10 +1,10 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'OptionGroup',
+  name: 'Option group',
   description:
     'Represents a group of options within a select component. Use only as a child of `s-select` components.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -1,11 +1,12 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'OrderedList',
+  name: 'Ordered list',
   description:
-    'Displays a numbered list of related items in a specific sequence. Use to present step-by-step instructions, ranked items, or procedures where order matters.',
-  category: 'Polaris web components',
-  subCategory: 'Layout and structure',
+    'The ordered list component displays a numbered list of related items in a specific sequence. Use ordered list to present step-by-step instructions, ranked items, procedures, or any content where order and sequence matter to understanding.' +
+    "\n\nOrdered lists automatically number items and support nested lists for hierarchical content organization. For items where order doesn't matter, use [unordered list](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/unordered-list).",
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

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

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Page',
   description:
     ' Use `s-page` as the main container for placing content in your app. Page comes with preset layouts and automatically adds spacing between elements.',
-  category: 'Polaris web components',
-  subCategory: 'Structure',
+  category: 'Web components',
+  subCategory: 'Layout and structure',
   related: [],
 };
 

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

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Paragraph',
   description:
-    'Displays a block of text and can contain inline elements such as buttons, links, or emphasized text. Use to present standalone blocks of content as opposed to inline text.',
-  category: 'Polaris web components',
+    'The paragraph component displays blocks of text content and can contain inline elements like buttons, links, or emphasized text. Use paragraph to present standalone blocks of readable content, descriptions, or explanatory text.' +
+    '\n\nParagraphs support alignment options and can wrap inline components to create rich, formatted content blocks. For inline text styling, use [text](/docs/api/{API_NAME}/{API_VERSION}/web-components/typography-and-content/text).',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

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

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'PasswordField',
-  description: 'Securely collect sensitive information from users.',
-  category: 'Polaris web components',
+  name: 'Password field',
+  description:
+    'The password field component securely collects sensitive information from users. Use password field for password entry, where input characters are automatically masked for privacy.' +
+    '\n\nPassword fields support validation, help text, and accessibility features to create secure and user-friendly authentication experiences. 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/PaymentIcon.ts

@@ -1,11 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'PaymentIcon',
+  name: 'Payment icon',
   description:
     'Displays icons representing payment methods. Use to visually communicate available or saved payment options clearly',
-  category: 'Polaris web components',
-  subCategory: 'Media',
+  category: 'Web components',
+  subCategory: 'Media and visuals',
   related: [],
 };
 

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

@@ -1,9 +1,9 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'PhoneField',
+  name: 'Phone field',
   description: 'Use PhoneField to allow users to enter phone numbers.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Popover',
   description:
     'Popovers are used to display content in an overlay that can be triggered by a button.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Overlays',
   related: [],
 };

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

@@ -1,10 +1,10 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'PressButton',
+  name: 'Press button',
   description:
     'Allows users to toggle between active/inactive states. Use to represent a persistent on/off or selected/unselected status.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };

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

@@ -1,10 +1,10 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ProductThumbnail',
+  name: 'Product thumbnail',
   description: 'Use ProductThumbnail to display a product thumbnail',
-  category: 'Polaris web components',
-  subCategory: 'Media',
+  category: 'Web components',
+  subCategory: 'Media and visuals',
   related: [],
 };
 

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

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Progress',
   description:
     'Displays an indicator showing the completion status of a task. Use to visually communicate progress in either determinate (known percentage) or indeterminate (unknown duration) states.',
-  category: 'Polaris web components',
-  subCategory: 'Feedback',
+  category: 'Web components',
+  subCategory: 'Feedback and status indicators',
   related: [],
 };
 

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

@@ -1,11 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'QRCode',
+  name: 'QR code',
   description:
     'Displays a scannable QR code representing data such as URLs or text. Use to let users quickly access information by scanning with a smartphone or other device.',
-  category: 'Polaris web components',
-  subCategory: 'Other',
+  category: 'Web components',
+  subCategory: 'Media and visuals',
   related: [],
 };
 

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

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'QueryContainer',
+  name: 'Query container',
   description:
-    'Establishes a query container for responsive design. Use `s-query-container` to define an element as a containment context, enabling child components or styles to adapt based on the container’s size.',
-  category: 'Polaris web components',
+    "The query container component establishes a container query context for responsive design. Use query container to define an element as a containment context, enabling child components or styles to adapt based on the container's size rather than viewport width." +
+    '\n\nQuery containers support modern responsive patterns where components respond to their container dimensions, creating more flexible and reusable layouts.',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

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

@@ -1,11 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'ScrollBox',
+  name: 'Scroll box',
   description:
     'Provides a scrollable container for long content that exceeds the available space. Use to display lists, order summaries, or other lengthy content while maintaining a constrained layout.',
-  category: 'Polaris web components',
-  subCategory: 'Structure',
+  category: 'Web components',
+  subCategory: 'Layout and structure',
   related: [],
 };
 

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

@@ -1,10 +1,10 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'SearchField',
+  name: 'Search field',
   description:
-    'Let users enter search terms or find specific items using a single-line input field.',
-  category: 'Polaris web components',
+    'The search field component captures search terms for filtering and search functionality. Use it to enable inline search within specific sections or lists, like filtering products or searching customers. 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/Section.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Section',
   description:
-    'Groups related content into clearly-defined thematic areas. Sections have contextual styling that automatically adapts based on nesting depth. They also adjust heading levels to maintain a meaningful and accessible page structure.',
-  category: 'Polaris web components',
+    'The section component groups related content into clearly-defined thematic areas with consistent styling and structure. Use section to organize page content into logical blocks, each with its own heading and visual container.' +
+    '\n\nSections automatically adapt their styling based on nesting depth and adjust heading levels to maintain meaningful, accessible page hierarchies. For simple visual separation without headings, use [divider](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/divider).',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

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

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Select',
   description:
-    'Allow users to pick one option from a menu. Ideal when presenting four or more choices to keep interfaces uncluttered.',
-  category: 'Polaris web components',
+    'The select component allows users to choose one option from a dropdown menu. Use select when presenting four or more choices to keep interfaces uncluttered and scannable, or when space is limited.' +
+    '\n\nSelect components support option grouping, placeholder text, help text, and validation states to create clear selection interfaces. For more visual selection layouts with radio buttons or checkboxes, use [choice list](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/choice-list).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -0,0 +1,14 @@
+import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
+
+const data: SharedReferenceEntityTemplateSchema = {
+  name: 'Sheet',
+  description: `
+The Sheet component displays essential information for customers at the bottom of the screen, appearing above other elements. Use it sparingly to avoid distracting customers during checkout. This component requires access to [Customer Privacy API](/docs/api/checkout-ui-extensions/latest/configuration#collect-buyer-consent) to be rendered.
+
+The library automatically applies the [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) to both the activator and the sheet content.`,
+  category: 'Web components',
+  subCategory: 'Overlays',
+  related: [],
+};
+
+export default data;

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

@@ -1,11 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'SkeletonParagraph',
+  name: 'Skeleton paragraph',
   description:
     'Displays a placeholder representation of text content while it loads. Use to improve perceived performance by showing users where text will appear.',
-  category: 'Polaris web components',
-  subCategory: 'Feedback',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

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

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Spinner',
   description:
-    'Displays an animated indicator showing users that content or actions are loading. Use to communicate ongoing processes, such as fetching data from a server. For loading states on buttons, use the “loading” property on the Button component instead.',
-  category: 'Polaris web components',
+    'The spinner component displays an animated indicator showing users that content or actions are loading. Use spinner to communicate ongoing processes like fetching data, processing requests, or waiting for operations to complete.' +
+    '\n\nSpinners support multiple sizes and should be used for page or section loading states. For button loading states, use the `loading` property on the [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) component instead.',
+  category: 'Web components',
   subCategory: 'Feedback and status indicators',
   related: [],
 };