@shopify/ui-extensions 2026.1.1 → 2026.1.3

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

@@ -3,8 +3,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 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',
+    'The modal component displays content in an overlay. Use to create a distraction-free experience such as a confirmation dialog or a settings panel.\n\nA button triggers the modal using the `commandFor` attribute. Content within the modal scrolls if it exceeds available height.',
+  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,10 +1,11 @@
 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',
+    '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: 'Layout and structure',
   related: [],
 };

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

@@ -3,9 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 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',
+    "The page component provides a styled page layout within your app, including breadcrumbs, page actions, and content areas with automatic spacing.\n\nUse page when you need a complete page layout with Polaris styling. For apps that need to set the Shopify admin's native title bar (title, breadcrumbs, actions) without a styled page layout, use the [title bar](/docs/api/{API_NAME}/{API_VERSION}/app-bridge-web-components/title-bar) App Bridge component instead.",
+  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

@@ -3,8 +3,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 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',
+    "The popover component displays contextual content in an overlay triggered by a button using the [`commandFor`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#commandfor) attribute. Use for secondary actions, settings, or information that doesn't require a full modal.\n\nFor interactions that need more space or user focus, such as confirmations or complex forms, use [modal](/docs/api/{API_NAME}/{API_VERSION}/web-components/overlays/modal) instead.",
+  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

@@ -6,7 +6,7 @@ const data: SharedReferenceEntityTemplateSchema = {
 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: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Overlays',
   related: [],
 };

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

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

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Stack',
   description:
-    'Organizes elements horizontally or vertically along the block or inline axis. Use to structure layouts, group related components, or control spacing between elements.',
-  category: 'Polaris web components',
+    'The stack component organizes elements horizontally or vertically along the block or inline axis. Use stack to structure layouts, group related components, control spacing between elements, or create flexible arrangements that adapt to content.' +
+    '\n\nStacks support gap spacing, alignment, wrapping, and distribution properties to create consistent, responsive layouts without custom CSS. For complex multi-column layouts with precise grid positioning, use [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/Summary.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Summary',
   description:
     'Provides a clickable label for collapsible Details content. Use to create clear, accessible disclosure controls that show or hide additional information.',
-  category: 'Polaris web components',
-  subCategory: 'Interactive',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

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

@@ -2,8 +2,10 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Switch',
-  description: 'Give users a clear way to toggle options on or off.',
-  category: 'Polaris web components',
+  description:
+    'The switch component provides a clear way for users to toggle options or settings on and off. Use switch for binary controls that take effect immediately, like enabling features, activating settings, or controlling visibility.' +
+    "\n\nSwitches provide instant visual feedback and are ideal for settings that don't require a save action to apply changes. For selections that require explicit submission, use [checkbox](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/checkbox) instead.",
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Table',
   description:
-    'Display data clearly in rows and columns, helping users view, analyze, and compare information. Automatically renders as a list on small screens and a table on large ones.',
-  category: 'Polaris web components',
+    'The table component displays data clearly in rows and columns, helping users view, analyze, and compare structured information. Use table to present datasets, product lists, order details, or any tabular content that benefits from organized rows and columns.' +
+    '\n\nTables automatically adapt to screen size, rendering as lists on small screens and tables on larger ones for optimal readability across devices.',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

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

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableBody',
+  name: 'Table body',
   description:
-    'Define the main content area of a table, containing rows and cells that display data.',
-  category: 'Polaris web components',
+    'The table body component represents the main content area of a table, containing the data rows. Use table body as a child of table to structure your table data, with each table row within the body representing a single record or entry.' +
+    '\n\nTable body must contain table row components, which in turn contain table cell components for the actual data values.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

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

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableCell',
-  description: 'Display data within a cell in a table row.',
-  category: 'Polaris web components',
+  name: 'Table cell',
+  description:
+    'The table cell component represents a single data cell within a table row. Use table cell as a child of table row to display individual data values, with each cell corresponding to a column in the table.' +
+    '\n\nTable cell automatically inherits styling and alignment from its parent table structure and supports text content or other inline components.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

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

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableHeader',
-  description: 'Display column names at the top of a table.',
-  category: 'Polaris web components',
+  name: 'Table header',
+  description:
+    'The table header component represents a single column header within a table header row. Use table header as a child of table header row to define column headings and optionally enable column sorting.' +
+    '\n\nTable header provides semantic meaning for screen readers and can include sorting controls when configured. Each header corresponds to a column in the table body.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

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

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableHeaderRow',
+  name: 'Table header row',
   description:
-    'Define a header row in a table, displaying column names and enabling sorting.',
-  category: 'Polaris web components',
+    'The table header row component represents the header row of a table, containing column headings. Use table header row as the first child of table (before table body) to define the table structure and provide column labels.' +
+    '\n\nTable header row must contain table header components for each column. These headers provide context for the data columns and can support sorting functionality.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

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

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableRow',
-  description: 'Display a row of data within the body of a table.',
-  category: 'Polaris web components',
+  name: 'Table row',
+  description:
+    'The table row component represents a single row of data within a table body. Use table row as a child of table body to structure individual records or entries in the table.' +
+    '\n\nTable row must contain table cell components, with each cell representing a data value for the corresponding column. The number of cells should match the number of headers in the table.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

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

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Text',
   description:
-    'Displays inline text with specific visual styles or tones. Use to emphasize or differentiate words or phrases within a Paragraph or other block-level components.',
-  category: 'Polaris web components',
+    'The text component displays inline text with specific visual styles or tones. Use text to emphasize or differentiate words or phrases within paragraphs or other block-level components, applying weight, color, or semantic styling.' +
+    '\n\nText supports multiple visual variants, alignment options, and line clamping for flexible inline typography control. For block-level text content, use [paragraph](/docs/api/{API_NAME}/{API_VERSION}/web-components/typography-and-content/paragraph).',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

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

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TextArea',
+  name: 'Text area',
   description:
-    'Collect longer text content from users with a multi-line input that expands automatically.',
-  category: 'Polaris web components',
+    'The text area component captures multi-line text input. Use it to collect descriptions, notes, comments, or other extended text content.' +
+    '\n\nThe component supports configurable height, character limits, and validation. For single-line 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/TextField.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TextField',
+  name: 'Text field',
   description:
-    'Lets users enter or edit text within a single-line input. Use to collect short, free-form information from users.',
-  category: 'Polaris web components',
+    'The text field component captures single-line text input. Use it to collect short, free-form information like names, titles, or identifiers.' +
+    '\n\nThe component supports various input configurations including placeholders, character limits, and validation. For multi-line text entry, use [text area](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-area). For specialized input types, use [email field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/email-field), [URL field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/url-field), [password field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/password-field), or [search field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/search-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

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

@@ -3,8 +3,9 @@ import {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Thumbnail',
   description:
-    'Display a small preview image representing content, products, or media.',
-  category: 'Polaris web components',
+    'The thumbnail component displays small preview images representing content, products, or media items. Use thumbnail to provide visual identification in lists, tables, or cards where space is constrained and quick recognition is important.' +
+    '\n\nThumbnails support multiple sizes, alt text for accessibility, and fallback states for missing images. For full-size images, use [image](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/image). For user profile images, use [avatar](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/avatar).',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };