Polish example descriptions for style guide compliance

SteveSill · cursoragent · SteveSill · commit a9553b3f92b7 · 2026-02-18T20:06:21.000-07:00
- AdminAction/AdminBlock: lead with business value, not setup instructions
- Banner: remove "dynamic" (banned marketing word)
- DateField: remove reference to unsupported `required` prop
- EmailField/TextField: replace "in real time" with "on each keystroke"
- Link: replace "dynamically" with "building"
- MoneyField: replace "real-time" with "inline"
- NumberField: replace "dynamic" with "inline"
- Pressable: update description to match code (removed accessibilityRole)
- ProgressIndicator: lead with business value, not "Use the"
- Section: lead with outcome, not "Add an" instruction
- Text: lead with purpose, not "Apply" instruction
- TextField: lead with outcome, not "Use the" instruction

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminAction/AdminAction.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminAction/AdminAction.doc.ts
@@ -21,7 +21,7 @@ const data: ReferenceEntityTemplateSchema = {
   defaultExample: {
     image: 'adminaction-default.png',
     description:
-      'Set up an action modal with a `title`, `primaryAction` for syncing, and `secondaryAction` for cancellation. This example creates a complete modal with a sync confirmation message, a primary [Button](/docs/api/admin-extensions/{API_VERSION}/components/actions/button) that posts to your backend, and a cancel button that closes the modal.',
+      'Confirm a product sync with your warehouse before posting to your backend. This example configures the modal `title`, a `primaryAction` [Button](/docs/api/admin-extensions/{API_VERSION}/components/actions/button) that triggers the sync, and a `secondaryAction` cancel button that closes the modal.',
     codeblock: {
       title: 'Configure action modal with buttons',
       tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/AdminBlock/AdminBlock.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/AdminBlock/AdminBlock.doc.ts
@@ -21,7 +21,7 @@ const data: ReferenceEntityTemplateSchema = {
   defaultExample: {
     image: 'adminblock-default.png',
     description:
-      'Set up a block extension with a `title` and status content using [Badge](/docs/api/admin-extensions/{API_VERSION}/components/feedback-and-status-indicators/badge) indicators. This example displays warehouse connection status and inventory details inside a titled block on the product detail page.',
+      'Display warehouse connection status and inventory levels on the product detail page. This example renders [Badge](/docs/api/admin-extensions/{API_VERSION}/components/feedback-and-status-indicators/badge) indicators inside a titled block to show stock and sync information at a glance.',
     codeblock: {
       title: 'Display warehouse status block',
       tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/Banner/Banner.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/Banner/Banner.doc.ts
@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         description:
-          'Show a `success` banner after completing a product update to give merchants immediate visual confirmation. This example renders a dismissible banner with a dynamic message that includes the product ID, so merchants know exactly which resource was updated.',
+          'Show a `success` banner after completing a product update to give merchants immediate visual confirmation. This example renders a dismissible banner with a message that includes the product ID, so merchants know exactly which resource was updated.',
         codeblock: {
           title: 'Confirm successful product update',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/DateField/DateField.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/DateField/DateField.doc.ts
@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         description:
-          "Validate that a selected date is in the future using the `error` prop and `required` attribute. This example checks the expiration date against today's date on each change and displays an inline error for past dates, ensuring merchants only set valid expiry windows.",
+          "Validate that a selected date is in the future using the `error` prop. This example checks the expiration date against today's date on each change and displays an inline error for past dates, ensuring merchants only set valid expiry windows.",
         codeblock: {
           title: 'Validate future date selection',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/EmailField/EmailField.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/EmailField/EmailField.doc.ts
@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         description:
-          'Validate email format in real time using the `error` prop and `required` attribute. This example checks for the presence of an `@` symbol on each keystroke and displays an inline error message, preventing merchants from saving invalid email addresses.',
+          'Validate email format on each keystroke using the `error` prop and `required` attribute. This example checks for the presence of an `@` symbol as the merchant types and displays an inline error message, preventing invalid email addresses from being saved.',
         codeblock: {
           title: 'Validate email format inline',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/Link/Link.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/Link/Link.doc.ts
@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         description:
-          "Open external URLs in new tabs using `target` set to `_blank`. This example links to the product's storefront page and Shopify documentation, constructing the storefront URL dynamically from the product ID in `data.selected`.",
+          "Open external URLs in new tabs using `target` set to `_blank`. This example links to the product's storefront page and Shopify documentation, building the storefront URL from the product ID in `data.selected`.",
         codeblock: {
           title: 'Open external links in new tabs',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/MoneyField/MoneyField.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/MoneyField/MoneyField.doc.ts
@@ -62,7 +62,7 @@ const data: ReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Enforce minimum price constraints using `min` and the `error` prop for real-time validation. This example prevents merchants from setting a wholesale price at zero or below, displaying an inline error until a valid amount is entered.',
+          "Enforce minimum price constraints using `min` and the `error` prop for inline validation. This example prevents merchants from setting a wholesale price at zero or below, displaying an error until they've entered a valid amount.",
         codeblock: {
           title: 'Validate minimum price amount',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/NumberField/NumberField.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/NumberField/NumberField.doc.ts
@@ -62,7 +62,7 @@ const data: ReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Enforce warehouse-specific limits using `min`, `max`, and `step` constraints with dynamic `error` feedback. This example validates slot numbers against a maximum capacity and shows an inline error when the value exceeds the allowed range.',
+          'Enforce warehouse-specific limits using `min`, `max`, and `step` constraints with inline `error` feedback. This example validates slot numbers against a maximum capacity and shows an error when the value exceeds the allowed range.',
         codeblock: {
           title: 'Enforce numeric constraints with errors',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/Pressable/Pressable.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/Pressable/Pressable.doc.ts
@@ -62,7 +62,7 @@ const data: ReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Set `accessibilityRole` and `accessibilityLabel` to provide screen readers with meaningful context for custom interactive regions. This example renders tappable warehouse location rows with [Badge](/docs/api/admin-extensions/{API_VERSION}/components/feedback-and-status-indicators/badge) indicators, where each row announces its full context to assistive technology.',
+          'Provide screen readers with meaningful context for custom interactive regions using `accessibilityLabel`. This example renders tappable warehouse location rows with [Badge](/docs/api/admin-extensions/{API_VERSION}/components/feedback-and-status-indicators/badge) indicators, where each row announces its full context to assistive technology.',
         codeblock: {
           title: 'Add accessible interactive regions',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/ProgressIndicator/ProgressIndicator.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/ProgressIndicator/ProgressIndicator.doc.ts
@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         description:
-          'Use the `base` size for a prominent loading indicator during a long-running sync operation in an [action modal](/docs/api/admin-extensions/{API_VERSION}/components/other/adminaction). This example pairs the indicator with a status message and a cancel [Button](/docs/api/admin-extensions/{API_VERSION}/components/actions/button), keeping merchants informed and in control.',
+          'Show a prominent loading indicator during a long-running sync operation in an [action modal](/docs/api/admin-extensions/{API_VERSION}/components/other/adminaction). This example pairs a `base`-sized indicator with a status message and a cancel [Button](/docs/api/admin-extensions/{API_VERSION}/components/actions/button), keeping merchants informed and in control.',
         codeblock: {
           title: 'Display sync progress in action modal',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/Section/Section.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/Section/Section.doc.ts
@@ -62,7 +62,7 @@ const data: ReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Add an `accessibilityLabel` to provide screen readers with a more descriptive section context than the visible heading alone. This example labels a shipping configuration section with form fields, ensuring assistive technology announces the full purpose of the form group.',
+          'Provide screen readers with a more descriptive section context than the visible heading alone using `accessibilityLabel`. This example labels a shipping configuration section with form fields, ensuring assistive technology announces the full purpose of the form group.',
         codeblock: {
           title: 'Add accessible section descriptions',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/Text/Text.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/Text/Text.doc.ts
@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         description:
-          'Apply `fontStyle` set to `italic` with an `accessibilityRole` of `emphasis` to convey semantic importance to both visual users and screen readers. This example uses `strong` and `emphasis` roles to ensure assistive technology communicates the visual formatting correctly.',
+          'Convey semantic importance to both visual users and screen readers using `fontStyle` and `accessibilityRole`. This example uses `strong` and `emphasis` roles to ensure assistive technology communicates the visual formatting correctly.',
         codeblock: {
           title: 'Show status with semantic emphasis',
           tabs: [
diff --git a/packages/ui-extensions/src/surfaces/admin/components/TextField/TextField.doc.ts b/packages/ui-extensions/src/surfaces/admin/components/TextField/TextField.doc.ts
@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {
     examples: [
       {
         description:
-          'Validate SKU format in real time using the `error` prop and `onChange` callback. This example checks minimum length and character restrictions on each keystroke, displaying inline error messages that prevent merchants from submitting invalid data.',
+          'Validate SKU format on each keystroke using the `error` prop and `onChange` callback. This example checks minimum length and character restrictions as the merchant types, displaying inline error messages that prevent invalid data from being submitted.',
         codeblock: {
           title: 'Validate input with error messages',
           tabs: [
@@ -62,7 +62,7 @@ const data: ReferenceEntityTemplateSchema = {
       },
       {
         description:
-          'Use the `suffix` prop to display a unit or domain after the editable portion of the field. This example adds `kg` to a weight field and `.myshopify.com` to a handle field, making the implied format visible without requiring merchants to type it.',
+          "Display a unit or domain label after the editable portion of the field with the `suffix` prop. This example adds `kg` to a weight field and `.myshopify.com` to a handle field, making the implied format visible so merchants don't need to type it.",
         codeblock: {
           title: 'Add suffix labels to fields',
           tabs: [

Original file line number	Diff line number	Diff line change
`@@ -43,7 +43,7 @@ const data: ReferenceEntityTemplateSchema = {`
`43`	`43`	`examples: [`
`44`	`44`	`{`
`45`	`45`	`description:`
`46`		- 'Show a `success` banner after completing a product update to give merchants immediate visual confirmation. This example renders a dismissible banner with a dynamic message that includes the product ID, so merchants know exactly which resource was updated.',
	`46`	+ 'Show a `success` banner after completing a product update to give merchants immediate visual confirmation. This example renders a dismissible banner with a message that includes the product ID, so merchants know exactly which resource was updated.',
`47`	`47`	`codeblock: {`
`48`	`48`	`title: 'Confirm successful product update',`
`49`	`49`	`tabs: [`
Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ const data: ReferenceEntityTemplateSchema = {`
`62`	`62`	`},`
`63`	`63`	`{`
`64`	`64`	`description:`
`65`		- 'Enforce minimum price constraints using `min` and the `error` prop for real-time validation. This example prevents merchants from setting a wholesale price at zero or below, displaying an inline error until a valid amount is entered.',
	`65`	+ "Enforce minimum price constraints using `min` and the `error` prop for inline validation. This example prevents merchants from setting a wholesale price at zero or below, displaying an error until they've entered a valid amount.",
`66`	`66`	`codeblock: {`
`67`	`67`	`title: 'Validate minimum price amount',`
`68`	`68`	`tabs: [`