Intro, best practices, limitations, prop descs

Linting

Improve prop descriptions + revert example desc changes

Further description improvements

Further description improvements

Further description improvements

More description improvements

Further description improvements

Description tweaks

Intro description tweaks

Revisions to limitations and best practices

Update descriptions for App Home / Admin UI Polaris components

Cherry-picked from 3c68898 with merge conflict resolution.

Updated component descriptions for ChoiceList, DateField, DatePicker, EmailField, NumberField, SearchField, TextArea, and TextField to be more concise and focused on App Home / Admin UI use cases, removing POS-specific references.

Co-authored-by: Cursor <cursoragent@cursor.com>

Update best practices and limitations for App Home / Admin UI Polaris components

Cherry-picked from c11d32e with merge conflict resolution.

Updated best practices and limitations sections for ChoiceList, DateField, DatePicker, EmailField, NumberField, SearchField, TextArea, and TextField components. Combined concise, focused guidance with detailed practical examples to provide comprehensive documentation that balances clarity with actionable advice.

Co-authored-by: Cursor <cursoragent@cursor.com>

Refinements to descriptions

ColorField + ColorPicker descriptions

DateField + DatePicker descriptions

Forms description improvements

Descriptions for layout and structure components

Media and visuals descriptions

Descriptions for Typography and content

Revert changes to Modal

Revert changes to props for Modal, Popover, DropZone, and Page

Revert accidental changes to Image and TextArea

Component cross-references in intros

Links + de-duplicating best practices / limitations

Remove link

Clarify defaultValue + placeholder props

Update remaining defaultValue descriptions to plain English

Update the 5 remaining instances of the old "uncontrolled components"
description across shared.d.ts and components.d.ts to match the
clearer defaultValue description style.

Co-authored-by: Cursor <cursoragent@cursor.com>

Use 'The placeholder' instead of 'Placeholder' in prop descriptions

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: mcvinci

packages/ui-extensions/src/docs/shared/components/Avatar.ts

@@ -3,7 +3,8 @@ import {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Avatar',
   description:
-    'Show a user’s profile image or initials in a compact, visual element.',
+    "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}/polaris-web-components/media-and-visuals/thumbnail). For full-size images, use [`Image`](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/media-and-visuals/image).',
   category: 'Polaris web components',
   subCategory: 'Media and visuals',
   related: [],

packages/ui-extensions/src/docs/shared/components/Badge.ts

@@ -3,7 +3,8 @@ 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.',
+    '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}/polaris-web-components/typography-and-content/chip) instead.',
   category: 'Polaris web components',
   subCategory: 'Feedback and status indicators',
   related: [],

packages/ui-extensions/src/docs/shared/components/Banner.ts

@@ -3,7 +3,8 @@ 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.',
+    '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}/polaris-web-components/feedback-and-status-indicators/badge).',
   category: 'Polaris web components',
   subCategory: 'Feedback and status indicators',
   related: [],

packages/ui-extensions/src/docs/shared/components/Box.ts

@@ -3,7 +3,8 @@ 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.',
+    "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}/polaris-web-components/layout-and-structure/stack) or [`Grid`](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/grid).',
   category: 'Polaris web components',
   subCategory: 'Layout and structure',
   related: [],

packages/ui-extensions/src/docs/shared/components/Button.ts

@@ -3,7 +3,8 @@ 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.',
+    'The `Button` component 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.' +
+    '\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}/polaris-web-components/actions/link). For grouping multiple related buttons, use [`ButtonGroup`](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/actions/buttongroup).',
   category: 'Polaris web components',
   subCategory: 'Actions',
   related: [],

packages/ui-extensions/src/docs/shared/components/ButtonGroup.ts

@@ -2,7 +2,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'ButtonGroup',
-  description: 'Displays multiple buttons in a layout.',
+  description:
+    'The `ButtonGroup` component displays multiple related buttons in a structured layout. Use `ButtonGroup` 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}/polaris-web-components/actions/button).',
   category: 'Polaris web components',
   subCategory: 'Actions',
   related: [],

packages/ui-extensions/src/docs/shared/components/Checkbox.ts

@@ -3,7 +3,8 @@ 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.',
+    '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}/polaris-web-components/forms/switch) instead.',
   category: 'Polaris web components',
   subCategory: 'Forms',
   related: [],

packages/ui-extensions/src/docs/shared/components/Chip.ts

@@ -3,7 +3,8 @@ 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.',
+    '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}/polaris-web-components/feedback-and-status-indicators/badge). For interactive or removable chips, use [`ClickableChip`](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/actions/clickablechip).',
   category: 'Polaris web components',
   subCategory: 'Typography and content',
   related: [],

packages/ui-extensions/src/docs/shared/components/Choice.ts

@@ -3,7 +3,8 @@ 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.',
+    'The `Choice` component creates individual selectable options within a `ChoiceList`. Use `Choice` to define each option that merchants can select, supporting both single selection (radio buttons) and multiple selection (checkboxes) modes.' +
+    '\n\n`Choice` components support labels, help text, and custom content through slots, providing flexible option presentation within choice lists.',
   category: 'Polaris web components',
   subCategory: 'Forms',
   related: [],

packages/ui-extensions/src/docs/shared/components/ChoiceList.ts

@@ -3,7 +3,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'ChoiceList',
   description:
-    'Present multiple options to users, allowing either single selections with radio buttons or multiple selections with checkboxes.',
+    'The `ChoiceList` 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 offers multiple layout variants including list, inline, block, and grid formats to suit different space constraints and visual requirements. For compact dropdown selection with four or more options, use [`Select`](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/select).',
   category: 'Polaris web components',
   subCategory: 'Forms',
   related: [],