[Components]: Description improvements for version 2025-04 (#3878)

* Intros, best practices, limitations, and prop descriptions

Linting

Prop descriptions

Linting

Prop description improvements

* Remove component name code styling

Restore links + catch other code syntax instances

Linting

* Update selection-action target descriptions

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

* Incorporate feedback from Steve

* Integrate feedback from tech writers session

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

* Integrate feedback from Steve

---------

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

Author: mcvinci

packages/ui-extensions/src/surfaces/admin/api/action/action.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`AdminAction`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminaction) component.',
+    'the [AdminAction](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminaction) component.',
   defaultExample: {
     description:
       'Send selected product IDs to your backend for bulk processing. This example shows how to map selected items, make an authenticated API call, and close the modal when the operation completes.',

packages/ui-extensions/src/surfaces/admin/api/block/block.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`AdminBlock`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminblock) component.',
+    'the [AdminBlock](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminblock) component.',
   defaultExample: {
     description:
       "Fetch and display a product's title, inventory, and status in a block extension. This example queries the [GraphQL Admin API](/docs/api/admin-graphql/) when the extension loads and shows a loading indicator while fetching.",

packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`FunctionSettings`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/forms/functionsettings) component.',
+    'the [FunctionSettings](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/forms/functionsettings) component.',
   defaultExample: {
     description:
       'Save a minimum quantity validation rule with a [number field](/docs/api/admin-extensions/{API_VERSION}/components/forms/numberfield) input. This example calls `applyMetafieldChange`, checks the result type, and displays success or error [banners](/docs/api/admin-extensions/{API_VERSION}/components/feedback-and-status-indicators/banner) based on the response.',

packages/ui-extensions/src/surfaces/admin/api/customer-segment-template/customer-segment-template.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`CustomerSegmentTemplate`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/other/customersegmenttemplate) component.',
+    'the [CustomerSegmentTemplate](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/other/customersegmenttemplate) component.',
   defaultExample: {
     description:
       'Create a segment template targeting customers who spent $500+ across 5+ orders. This example uses `total_spent` and `orders_count` queries to identify high-value customers, and demonstrates `shopify.i18n.translate` for internationalized template titles and descriptions.',

packages/ui-extensions/src/surfaces/admin/api/discount-function-settings/discount-function-settings.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`FunctionSettings`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/forms/functionsettings) component.',
+    'the [FunctionSettings](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/forms/functionsettings) component.',
   defaultExample: {
     description:
       'Save a minimum purchase threshold to a metafield with decimal number validation. This example uses a [text field](/docs/api/admin-extensions/{API_VERSION}/components/forms/textfield) for input, calls `applyMetafieldChange`, and displays a success or error [banner](/docs/api/admin-extensions/{API_VERSION}/components/feedback-and-status-indicators/banner).',

packages/ui-extensions/src/surfaces/admin/api/order-routing-rule/order-routing-rule.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`FunctionSettings`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/forms/functionsettings) component.',
+    'the [FunctionSettings](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/forms/functionsettings) component.',
   defaultExample: {
     description:
       'Set preferred and fallback fulfillment locations with [text field](/docs/api/admin-extensions/{API_VERSION}/components/forms/textfield) inputs. This example applies two metafield changes in a single batch operation to configure location priority for order routing.',

packages/ui-extensions/src/surfaces/admin/api/print-action/print-action.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`AdminPrintAction`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminprintaction) component.',
+    'the [AdminPrintAction](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminprintaction) component.',
   defaultExample: {
     description:
       "Generate a packing slip PDF for selected orders by calling your app's backend service. This example shows extracting order IDs from the selected resources, making an API call to your backend to generate the PDF, and returning the printable URL to display the document.",

packages/ui-extensions/src/surfaces/admin/api/product-configuration/product-details-configuration.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`AdminBlock`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminblock) component.',
+    'the [AdminBlock](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminblock) component.',
   defaultExample: {
     description:
       'Open the product [resource picker](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/resource-picker-api) to select up to five components for a [bundle](/docs/apps/build/product-merchandising/bundles). This example filters out draft and archived products, saves the bundle configuration to your backend, and tracks the selection count.',

packages/ui-extensions/src/surfaces/admin/api/product-configuration/product-variant-details-configuration.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`AdminBlock`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminblock) component.',
+    'the [AdminBlock](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminblock) component.',
   defaultExample: {
     description:
       'Use the product variant [resource picker](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/resource-picker-api) to select component variants for a [bundle](/docs/apps/build/product-merchandising/bundles). This example picks product variants, tracks selections, and posts the product variant IDs to configure the bundle.',

packages/ui-extensions/src/surfaces/admin/api/purchase-options-card-action/purchase-options-card-action.doc.ts

@@ -7,7 +7,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   type: 'API',
   requires:
-    'the [`AdminAction`](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminaction) component.',
+    'the [AdminAction](/docs/api/admin-extensions/{API_VERSION}/polaris-web-components/settings-and-templates/adminaction) component.',
   defaultExample: {
     description:
       'Checks for `sellingPlanId` presence, then posts the product and plan IDs to your backend and closes the modal. For subscription management actions.',