[Admin UI extensions 2025-10]: IA for Target APIs and components (#3696)

mcvinci · web-flow · commit f0bb01c8d936 · 2026-01-09T19:10:12.000+09:00
* IA for Target APIs

linting

Further revision

* IA for components

revert file change

Revert file change
diff --git a/packages/ui-extensions/src/docs/shared/components/Avatar.ts b/packages/ui-extensions/src/docs/shared/components/Avatar.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'Show a user’s profile image or initials in a compact, visual element.',
   category: 'Polaris web components',
-  subCategory: 'Media',
+  subCategory: 'Media and visuals',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Badge.ts b/packages/ui-extensions/src/docs/shared/components/Badge.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'Inform users about the status of an object or indicate that an action has been completed.',
   category: 'Polaris web components',
-  subCategory: 'Titles and text',
+  subCategory: 'Feedback and status indicators',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Banner.ts b/packages/ui-extensions/src/docs/shared/components/Banner.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Feedback',
+  subCategory: 'Feedback and status indicators',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Box.ts b/packages/ui-extensions/src/docs/shared/components/Box.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Chip.ts b/packages/ui-extensions/src/docs/shared/components/Chip.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Titles and text',
+  subCategory: 'Typography and content',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Divider.ts b/packages/ui-extensions/src/docs/shared/components/Divider.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'Create clear visual separation between elements in your user interface.',
   category: 'Polaris web components',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Grid.ts b/packages/ui-extensions/src/docs/shared/components/Grid.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Heading.ts b/packages/ui-extensions/src/docs/shared/components/Heading.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Titles and text',
+  subCategory: 'Typography and content',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Icon.ts b/packages/ui-extensions/src/docs/shared/components/Icon.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Media',
+  subCategory: 'Media and visuals',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Image.ts b/packages/ui-extensions/src/docs/shared/components/Image.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Media',
+  subCategory: 'Media and visuals',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/OrderedList.ts b/packages/ui-extensions/src/docs/shared/components/OrderedList.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Paragraph.ts b/packages/ui-extensions/src/docs/shared/components/Paragraph.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Titles and text',
+  subCategory: 'Typography and content',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/QueryContainer.ts b/packages/ui-extensions/src/docs/shared/components/QueryContainer.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Section.ts b/packages/ui-extensions/src/docs/shared/components/Section.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Spinner.ts b/packages/ui-extensions/src/docs/shared/components/Spinner.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Feedback',
+  subCategory: 'Feedback and status indicators',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Stack.ts b/packages/ui-extensions/src/docs/shared/components/Stack.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Table.ts b/packages/ui-extensions/src/docs/shared/components/Table.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Text.ts b/packages/ui-extensions/src/docs/shared/components/Text.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   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',
-  subCategory: 'Titles and text',
+  subCategory: 'Typography and content',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Thumbnail.ts b/packages/ui-extensions/src/docs/shared/components/Thumbnail.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'Display a small preview image representing content, products, or media.',
   category: 'Polaris web components',
-  subCategory: 'Media',
+  subCategory: 'Media and visuals',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/Tooltip.ts b/packages/ui-extensions/src/docs/shared/components/Tooltip.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'Displays helpful information in a small overlay when users hover or focus on an element. Use to provide additional context without cluttering the interface.',
   category: 'Polaris web components',
-  subCategory: 'Overlays',
+  subCategory: 'Typography and content',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/docs/shared/components/UnorderedList.ts b/packages/ui-extensions/src/docs/shared/components/UnorderedList.ts
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'Displays a bulleted list of related items. Use to present collections of items or options where the sequence isn’t critical.',
   category: 'Polaris web components',
-  subCategory: 'Structure',
+  subCategory: 'Layout and structure',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/surfaces/admin/api/action/action.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/action/action.doc.ts
@@ -13,8 +13,8 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'ActionExtensionApi',
     },
   ],
-  category: 'API',
-  subCategory: 'Target APIs',
+  category: 'Target APIs',
+  subCategory: 'Core APIs',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/surfaces/admin/api/block/block.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/block/block.doc.ts
@@ -13,8 +13,8 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'BlockExtensionApi',
     },
   ],
-  category: 'API',
-  subCategory: 'Target APIs',
+  category: 'Target APIs',
+  subCategory: 'Core APIs',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts
@@ -18,8 +18,8 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'ValidationData',
     },
   ],
-  category: 'API',
-  subCategory: 'Target APIs',
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/surfaces/admin/api/customer-segment-template/customer-segment-template.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/customer-segment-template/customer-segment-template.doc.ts
@@ -1,7 +1,7 @@
 import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
-  name: 'CustomerSegmentTemplate Extension API',
+  name: 'Customer Segment Template Extension API',
   description:
     'This API is available to all customer segment template extension types.',
   isVisualComponent: false,
@@ -13,8 +13,8 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'CustomerSegmentTemplateApi',
     },
   ],
-  category: 'API',
-  subCategory: 'Target APIs',
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/surfaces/admin/api/discount-function-settings/discount-function-settings.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/discount-function-settings/discount-function-settings.doc.ts
@@ -19,8 +19,8 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'DiscountFunctionSettingsData',
     },
   ],
-  category: 'API',
-  subCategory: 'Target APIs',
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/surfaces/admin/api/intents/intents.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/intents/intents.doc.ts
@@ -1,12 +1,13 @@
 import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
-  name: 'Intents',
+  name: 'Intents API',
   overviewPreviewDescription:
     'Orchestrate workflows and operations across Shopify resources',
   description: `The Intents API provides a way to invoke existing admin workflows for creating, editing, and managing Shopify resources.`,
   isVisualComponent: true,
-  category: 'API',
+  category: 'Target APIs',
+  subCategory: 'Utility APIs',
   thumbnail: 'intents.png',
   requires:
     'an Admin [block](/docs/api/admin-extensions/unstable/extension-targets#block-locations) or [action](/docs/api/admin-extensions/unstable/extension-targets#action-locations) extension.',
diff --git a/packages/ui-extensions/src/surfaces/admin/api/order-routing-rule/order-routing-rule.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/order-routing-rule/order-routing-rule.doc.ts
@@ -0,0 +1,21 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Order Routing Rule API',
+  description:
+    'This API is available to extensions that render in the order routing settings using the `admin.settings.order-routing-rule.render` target.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'OrderRoutingRuleApi',
+      description: '',
+      type: 'OrderRoutingRuleApi',
+    },
+  ],
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+};
+
+export default data;
diff --git a/packages/ui-extensions/src/surfaces/admin/api/picker/picker.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/picker/picker.doc.ts
@@ -1,14 +1,15 @@
 import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
-  name: 'Picker',
+  name: 'Picker API',
   overviewPreviewDescription: 'Opens a Picker in your app',
   description: `The Picker API provides a search-based interface to help users find and select one or more resources that you provide, such as product reviews, email templates, or subscription options, and then returns the selected resource ids to your extension.
 
 > Tip:
 > If you are picking products, product variants, or collections, you should use the [Resource Picker](resource-picker) API instead.`,
   isVisualComponent: true,
-  category: 'API',
+  category: 'Target APIs',
+  subCategory: 'Utility APIs',
   thumbnail: 'picker.png',
   requires:
     'an Admin [block](/docs/api/admin-extensions/unstable/extension-targets#block-locations), [action](/docs/api/admin-extensions/unstable/extension-targets#action-locations), or [print](/docs/api/admin-extensions/unstable/extension-targets#print-locations) extension.',
@@ -102,7 +103,7 @@ const data: ReferenceEntityTemplateSchema = {
   },
   related: [
     {
-      name: 'Resource Picker',
+      name: 'Resource Picker API',
       subtitle: 'APIs',
       url: 'resource-picker',
       type: 'pickaxe-3',
diff --git a/packages/ui-extensions/src/surfaces/admin/api/print-action/print-action.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/print-action/print-action.doc.ts
@@ -13,8 +13,8 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'PrintActionExtensionApi',
     },
   ],
-  category: 'API',
-  subCategory: 'Target APIs',
+  category: 'Target APIs',
+  subCategory: 'Core APIs',
   related: [],
 };
 
diff --git a/packages/ui-extensions/src/surfaces/admin/api/product-configuration/product-details-configuration.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/product-configuration/product-details-configuration.doc.ts
@@ -0,0 +1,21 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Product Details Configuration API',
+  description:
+    'This API is available to product configuration extensions that render on the product details page. See the [tutorial](/docs/apps/selling-strategies/bundles/product-config) for more information.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'ProductDetailsConfigurationApi',
+      description: '',
+      type: 'ProductDetailsConfigurationApi',
+    },
+  ],
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+};
+
+export default data;
diff --git a/packages/ui-extensions/src/surfaces/admin/api/product-configuration/product-variant-details-configuration.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/product-configuration/product-variant-details-configuration.doc.ts
@@ -0,0 +1,21 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Product Variant Details Configuration API',
+  description:
+    'This API is available to product configuration extensions that render on the product variant details page. See the [tutorial](/docs/apps/selling-strategies/bundles/product-config) for more information.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'ProductVariantDetailsConfigurationApi',
+      description: '',
+      type: 'ProductVariantDetailsConfigurationApi',
+    },
+  ],
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+};
+
+export default data;
diff --git a/packages/ui-extensions/src/surfaces/admin/api/purchase-options-card-action.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/purchase-options-card-action.doc.ts
@@ -0,0 +1,21 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Purchase Options Card Configuration API',
+  description:
+    'This API is available to action extensions that render in the purchase options card on product and product variant details pages when selling plan groups are present.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'PurchaseOptionsCardConfigurationApi',
+      description: '',
+      type: 'PurchaseOptionsCardConfigurationApi',
+    },
+  ],
+  category: 'Target APIs',
+  subCategory: 'Contextual APIs',
+  related: [],
+};
+
+export default data;
diff --git a/packages/ui-extensions/src/surfaces/admin/api/resource-picker/resource-picker.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/resource-picker/resource-picker.doc.ts
diff --git a/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/should-render/should-render.doc.ts
diff --git a/packages/ui-extensions/src/surfaces/admin/api/standard/standard.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/standard/standard.doc.ts
diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminAction/AdminAction.ext.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminAction/AdminAction.ext.doc.ts
diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminBlock/AdminBlock.ext.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminBlock/AdminBlock.ext.doc.ts
diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminPrintAction/AdminPrintAction.ext.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminPrintAction/AdminPrintAction.ext.doc.ts
