Integrate feedback from Steve

Author: mcvinci

packages/ui-extensions/src/surfaces/admin/components/Box.d.ts

@@ -132,7 +132,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted.
+   * Controls the visual style of the border on all sides (solid, dashed, auto, or none).
    *
    * When set, this overrides the style value specified in the `border` property.
    * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box)for specifying different styles per side: one value applies to all sides,
@@ -396,7 +396,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor overflow: BoxProps['overflow'];
   /**
-   * The padding on all sides of the Box.
+   * The padding on all sides of the box.
    */
   accessor padding: BoxProps['padding'];
   /**
@@ -405,7 +405,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor paddingBlock: BoxProps['paddingBlock'];
   /**
-   * The block-start padding of the Box.
+   * The padding at the top in horizontal writing modes, or at the start edge in vertical writing modes.
    */
   accessor paddingBlockStart: BoxProps['paddingBlockStart'];
   /**
@@ -434,7 +434,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor borderWidth: BoxProps['borderWidth'];
   /**
-   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property.
+   * Controls the visual style of the border on all sides (solid, dashed, auto, or none). When set, this overrides the style value specified in the `border` property.
    */
   accessor borderStyle: BoxProps['borderStyle'];
   /**
@@ -450,7 +450,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor accessibilityLabel: BoxProps['accessibilityLabel'];
   /**
-   * The accessibility visibility of the Box.
+   * Controls the visibility of the box for both visual and assistive technology users. Use `hidden` to hide from screen readers or `exclusive` to hide visually but announce to screen readers.
    */
   accessor accessibilityVisibility: BoxProps['accessibilityVisibility'];
   /**

packages/ui-extensions/src/surfaces/admin/components/Clickable.d.ts

@@ -150,7 +150,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted.
+   * Controls the visual style of the border on all sides (solid, dashed, auto, or none).
    *
    * When set, this overrides the style value specified in the `border` property.
    * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side.

packages/ui-extensions/src/surfaces/admin/components/Grid.d.ts

@@ -128,7 +128,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted.
+   * Controls the visual style of the border on all sides (solid, dashed, auto, or none).
    *
    * When set, this overrides the style value specified in the `border` property.
    * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side.
@@ -568,7 +568,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor paddingBlock: BoxProps['paddingBlock'];
   /**
-   * The block-start padding of the Box.
+   * The padding at the top in horizontal writing modes, or at the start edge in vertical writing modes.
    */
   accessor paddingBlockStart: BoxProps['paddingBlockStart'];
   /**
@@ -597,7 +597,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor borderWidth: BoxProps['borderWidth'];
   /**
-   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property.
+   * Controls the visual style of the border on all sides (solid, dashed, auto, or none). When set, this overrides the style value specified in the `border` property.
    */
   accessor borderStyle: BoxProps['borderStyle'];
   /**

packages/ui-extensions/src/surfaces/admin/components/GridItem.d.ts

@@ -131,7 +131,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * The visual style of the border (solid, dashed, dotted, or none).
+   * The visual style of the border (solid, dashed, auto, or none).
    *
    * @default '' - meaning no override
    */
@@ -423,11 +423,13 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor blockSize: BoxProps['blockSize'];
   /**
-   * The minimum block size of the Box.
+   * The minimum height of the grid item in horizontal writing modes, or minimum width in vertical writing modes.
+   * Prevents the grid item from shrinking below this size.
    */
   accessor minBlockSize: BoxProps['minBlockSize'];
   /**
-   * The maximum block size of the Box.
+   * The maximum height of the grid item in horizontal writing modes, or maximum width in vertical writing modes.
+   * Prevents the grid item from growing beyond this size.
    */
   accessor maxBlockSize: BoxProps['maxBlockSize'];
   /**
@@ -436,11 +438,13 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor inlineSize: BoxProps['inlineSize'];
   /**
-   * The minimum inline size of the Box.
+   * The minimum width of the grid item in horizontal writing modes, or minimum height in vertical writing modes.
+   * Prevents the grid item from shrinking below this size.
    */
   accessor minInlineSize: BoxProps['minInlineSize'];
   /**
-   * The maximum inline size of the Box.
+   * The maximum width of the grid item in horizontal writing modes, or maximum height in vertical writing modes.
+   * Prevents the grid item from growing beyond this size.
    */
   accessor maxInlineSize: BoxProps['maxInlineSize'];
   /**
@@ -452,11 +456,12 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor padding: BoxProps['padding'];
   /**
-   * The block padding of the Box.
+   * The vertical padding (top and bottom) in horizontal writing modes.
+   * Use this for flow-relative padding that adapts to text direction.
    */
   accessor paddingBlock: BoxProps['paddingBlock'];
   /**
-   * The block-start padding of the Box.
+   * The padding at the top in horizontal writing modes, or at the start edge in vertical writing modes.
    */
   accessor paddingBlockStart: BoxProps['paddingBlockStart'];
   /**
@@ -477,7 +482,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor paddingInlineEnd: BoxProps['paddingInlineEnd'];
   /**
-   * The border of the Box.
+   * Applies a border using shorthand syntax to specify width, color, and style in a single property.
    */
   accessor border: BoxProps['border'];
   /**

packages/ui-extensions/src/surfaces/admin/components/Heading.d.ts

@@ -140,7 +140,7 @@ export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
  */
 declare class Heading extends PreactCustomElement implements HeadingProps {
   /**
-   * The ARIA role for the heading, which determines its semantic level (`heading1` through `heading6`).
+   * The ARIA role for the heading. Set to `'heading'` (the default) for standard heading semantics, or `'presentation'` / `'none'` to remove heading semantics for decorative use.
    */
   accessor accessibilityRole: HeadingProps['accessibilityRole'];
   /**

packages/ui-extensions/src/surfaces/admin/components/Heading/Heading.doc.ts

@@ -20,9 +20,8 @@ const data: AdminReferenceEntityTemplateSchema = {
       title: 'Limitations',
       type: 'Generic' as const,
       anchorLink: 'limitations',
-      sectionContent: `- Heading levels are determined automatically based on nesting depth and can't be manually overridden. The component supports up to 3-4 nesting levels (h2, h3, h4), after which all headings remain at h4.
-- Line clamping truncates text visually but doesn't provide a way to show the full heading text on hover or through other interactions. Truncated content might not be fully accessible to screen readers.
-- The component renders with heading semantics by default. To remove heading semantics for decorative use, set \`accessibilityRole\` to \`"presentation"\` or \`"none"\`.`,
+      sectionContent: `- Heading levels (h2, h3, h4) are determined automatically based on nesting depth. You can't set a specific heading level, but you can remove heading semantics entirely by setting \`accessibilityRole\` to \`"presentation"\` or \`"none"\`.
+- Line clamping truncates text visually but doesn't provide a way to show the full heading text on hover or through other interactions. Truncated content might not be fully accessible to screen readers.`,
     },
   ],
   definitions: [

packages/ui-extensions/src/surfaces/admin/components/Image.d.ts

@@ -166,7 +166,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * The visual style of the border (solid, dashed, dotted, or none).
+   * The visual style of the border (solid, dashed, auto, or none).
    *
    * @default '' - meaning no override
    */

packages/ui-extensions/src/surfaces/admin/components/Select/Select.doc.ts

@@ -16,7 +16,7 @@ const data: AdminReferenceEntityTemplateSchema = {
 - **Organize options thoughtfully:** The order of options affects how quickly merchants find what they need. Group related options together, put common choices first, or use alphabetical order when no natural hierarchy exists.
 - **Make options scannable:** Merchants should be able to quickly distinguish between options. Include enough context in each option label so merchants don't need to open and read multiple options to find the right one.
 - **Handle default selections appropriately:** Pre-select an option when there's a clear default choice, but use a placeholder when merchants should make an intentional selection. Avoid confusing merchants with unclear initial states.
-- **Provide clear validation feedback:** When selection is required or invalid, explain what the user needs to do. Context-specific error messages help users complete forms faster than generic validation messages.`,
+- **Provide clear validation feedback:** When selection is required or invalid, explain what the merchant needs to do. Context-specific error messages help merchants complete forms faster than generic validation messages.`,
     },
     {
       title: 'Limitations',

packages/ui-extensions/src/surfaces/admin/components/Stack.d.ts

@@ -127,7 +127,7 @@ export interface BoxProps
       >
     | Extract<RequiredBoxProps['borderWidth'], ''>;
   /**
-   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted.
+   * Controls the visual style of the border on all sides (solid, dashed, auto, or none).
    *
    * When set, this overrides the style value specified in the `border` property.
    * Supports [1-to-4-value syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) for specifying different styles per side.
@@ -546,7 +546,7 @@ declare class BoxElement extends PreactCustomElement implements BoxProps {
    */
   accessor borderWidth: BoxProps['borderWidth'];
   /**
-   * Controls the visual style of the border on all sides, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property.
+   * Controls the visual style of the border on all sides (solid, dashed, auto, or none). When set, this overrides the style value specified in the `border` property.
    */
   accessor borderStyle: BoxProps['borderStyle'];
   /**