@abraracs/better-shopify-wc-mcp 1.0.0

package/docs/badge.md

@@ -0,0 +1,266 @@
+---
+title: Badge
+description: >-
+  Inform users about the status of an object or indicate that an action has been
+  completed.
+api_name: app-home
+source_url:
+  html: >-
+    https://shopify.dev/docs/api/app-home/polaris-web-components/titles-and-text/badge
+  md: >-
+    https://shopify.dev/docs/api/app-home/polaris-web-components/titles-and-text/badge.md
+---
+
+# Badge
+
+Inform users about the status of an object or indicate that an action has been completed.
+
+## Properties
+
+* color
+
+  "base" | "strong"
+
+  Default: 'base'
+
+  Modify the color to be more or less intense.
+
+* icon
+
+  "" | "replace" | "search" | "split" | "link" | "edit" | "product" | "variant" | "collection" | "select" | "info" | "incomplete" | "complete" | "color" | "money" | "adjust" | "affiliate" | "airplane" | "alert-bubble" | "alert-circle" | "alert-diamond" | "alert-location" | "alert-octagon" | "alert-octagon-filled" | "alert-triangle" | "alert-triangle-filled" | "app-extension" | "apps" | "archive" | "arrow-down" | "arrow-down-circle" | "arrow-down-right" | "arrow-left" | "arrow-left-circle" | "arrow-right" | "arrow-right-circle" | "arrow-up" | "arrow-up-circle" | "arrow-up-right" | "arrows-in-horizontal" | "arrows-out-horizontal" | "asterisk" | "attachment" | "automation" | "backspace" | "bag" | "bank" | "barcode" | "battery-low" | "bill" | "blank" | "blog" | "bolt" | "bolt-filled" | "book" | "book-open" | "bug" | "bullet" | "business-entity" | "button" | "button-press" | "calculator" | "calendar" | "calendar-check" | "calendar-compare" | "calendar-list" | "calendar-time" | "camera" | "camera-flip" | "caret-down" | "caret-left" | "caret-right" | "caret-up" | "cart" | "cart-abandoned" | "cart-discount" | "cart-down" | "cart-filled" | "cart-sale" | "cart-send" | "cart-up" | "cash-dollar" | "cash-euro" | "cash-pound" | "cash-rupee" | "cash-yen" | "catalog-product" | "categories" | "channels" | "chart-cohort" | "chart-donut" | "chart-funnel" | "chart-histogram-first" | "chart-histogram-first-last" | "chart-histogram-flat" | "chart-histogram-full" | "chart-histogram-growth" | "chart-histogram-last" | "chart-histogram-second-last" | "chart-horizontal" | "chart-line" | "chart-popular" | "chart-stacked" | "chart-vertical" | "chat" | "chat-new" | "chat-referral" | "check" | "check-circle" | "check-circle-filled" | "checkbox" | "chevron-down" | "chevron-down-circle" | "chevron-left" | "chevron-left-circle" | "chevron-right" | "chevron-right-circle" | "chevron-up" | "chevron-up-circle" | "circle" | "circle-dashed" | "clipboard" | "clipboard-check" | "clipboard-checklist" | "clock" | "clock-list" | "clock-revert" | "code" | "code-add" | "collection-featured" | "collection-list" | "collection-reference" | "color-none" | "compass" | "compose" | "confetti" | "connect" | "content" | "contract" | "corner-pill" | "corner-round" | "corner-square" | "credit-card" | "credit-card-cancel" | "credit-card-percent" | "credit-card-reader" | "credit-card-reader-chip" | "credit-card-reader-tap" | "credit-card-secure" | "credit-card-tap-chip" | "crop" | "currency-convert" | "cursor" | "cursor-banner" | "cursor-option" | "data-presentation" | "data-table" | "database" | "database-add" | "database-connect" | "delete" | "delivered" | "delivery" | "desktop" | "disabled" | "disabled-filled" | "discount" | "discount-add" | "discount-automatic" | "discount-code" | "discount-remove" | "dns-settings" | "dock-floating" | "dock-side" | "domain" | "domain-landing-page" | "domain-new" | "domain-redirect" | "download" | "drag-drop" | "drag-handle" | "drawer" | "duplicate" | "email" | "email-follow-up" | "email-newsletter" | "empty" | "enabled" | "enter" | "envelope" | "envelope-soft-pack" | "eraser" | "exchange" | "exit" | "export" | "external" | "eye-check-mark" | "eye-dropper" | "eye-dropper-list" | "eye-first" | "eyeglasses" | "fav" | "favicon" | "file" | "file-list" | "filter" | "filter-active" | "flag" | "flip-horizontal" | "flip-vertical" | "flower" | "folder" | "folder-add" | "folder-down" | "folder-remove" | "folder-up" | "food" | "foreground" | "forklift" | "forms" | "games" | "gauge" | "geolocation" | "gift" | "gift-card" | "git-branch" | "git-commit" | "git-repository" | "globe" | "globe-asia" | "globe-europe" | "globe-lines" | "globe-list" | "graduation-hat" | "grid" | "hashtag" | "hashtag-decimal" | "hashtag-list" | "heart" | "hide" | "hide-filled" | "home" | "home-filled" | "icons" | "identity-card" | "image" | "image-add" | "image-alt" | "image-explore" | "image-magic" | "image-none" | "image-with-text-overlay" | "images" | "import" | "in-progress" | "incentive" | "incoming" | "info-filled" | "inheritance" | "inventory" | "inventory-edit" | "inventory-list" | "inventory-transfer" | "inventory-updated" | "iq" | "key" | "keyboard" | "keyboard-filled" | "keyboard-hide" | "keypad" | "label-printer" | "language" | "language-translate" | "layout-block" | "layout-buy-button" | "layout-buy-button-horizontal" | "layout-buy-button-vertical" | "layout-column-1" | "layout-columns-2" | "layout-columns-3" | "layout-footer" | "layout-header" | "layout-logo-block" | "layout-popup" | "layout-rows-2" | "layout-section" | "layout-sidebar-left" | "layout-sidebar-right" | "lightbulb" | "link-list" | "list-bulleted" | "list-bulleted-filled" | "list-numbered" | "live" | "live-critical" | "live-none" | "location" | "location-none" | "lock" | "map" | "markets" | "markets-euro" | "markets-rupee" | "markets-yen" | "maximize" | "measurement-size" | "measurement-size-list" | "measurement-volume" | "measurement-volume-list" | "measurement-weight" | "measurement-weight-list" | "media-receiver" | "megaphone" | "mention" | "menu" | "menu-filled" | "menu-horizontal" | "menu-vertical" | "merge" | "metafields" | "metaobject" | "metaobject-list" | "metaobject-reference" | "microphone" | "microphone-muted" | "minimize" | "minus" | "minus-circle" | "mobile" | "money-none" | "money-split" | "moon" | "nature" | "note" | "note-add" | "notification" | "number-one" | "order" | "order-batches" | "order-draft" | "order-filled" | "order-first" | "order-fulfilled" | "order-repeat" | "order-unfulfilled" | "orders-status" | "organization" | "outdent" | "outgoing" | "package" | "package-cancel" | "package-fulfilled" | "package-on-hold" | "package-reassign" | "package-returned" | "page" | "page-add" | "page-attachment" | "page-clock" | "page-down" | "page-heart" | "page-list" | "page-reference" | "page-remove" | "page-report" | "page-up" | "pagination-end" | "pagination-start" | "paint-brush-flat" | "paint-brush-round" | "paper-check" | "partially-complete" | "passkey" | "paste" | "pause-circle" | "payment" | "payment-capture" | "payout" | "payout-dollar" | "payout-euro" | "payout-pound" | "payout-rupee" | "payout-yen" | "person" | "person-add" | "person-exit" | "person-filled" | "person-list" | "person-lock" | "person-remove" | "person-segment" | "personalized-text" | "phablet" | "phone" | "phone-down" | "phone-down-filled" | "phone-in" | "phone-out" | "pin" | "pin-remove" | "plan" | "play" | "play-circle" | "plus" | "plus-circle" | "plus-circle-down" | "plus-circle-filled" | "plus-circle-up" | "point-of-sale" | "point-of-sale-register" | "price-list" | "print" | "product-add" | "product-cost" | "product-filled" | "product-list" | "product-reference" | "product-remove" | "product-return" | "product-unavailable" | "profile" | "profile-filled" | "question-circle" | "question-circle-filled" | "radio-control" | "receipt" | "receipt-dollar" | "receipt-euro" | "receipt-folded" | "receipt-paid" | "receipt-pound" | "receipt-refund" | "receipt-rupee" | "receipt-yen" | "receivables" | "redo" | "referral-code" | "refresh" | "remove-background" | "reorder" | "replay" | "reset" | "return" | "reward" | "rocket" | "rotate-left" | "rotate-right" | "sandbox" | "save" | "savings" | "scan-qr-code" | "search-add" | "search-list" | "search-recent" | "search-resource" | "send" | "settings" | "share" | "shield-check-mark" | "shield-none" | "shield-pending" | "shield-person" | "shipping-label" | "shipping-label-cancel" | "shopcodes" | "slideshow" | "smiley-happy" | "smiley-joy" | "smiley-neutral" | "smiley-sad" | "social-ad" | "social-post" | "sort" | "sort-ascending" | "sort-descending" | "sound" | "sports" | "star" | "star-circle" | "star-filled" | "star-half" | "star-list" | "status" | "status-active" | "stop-circle" | "store" | "store-import" | "store-managed" | "store-online" | "sun" | "table" | "table-masonry" | "tablet" | "target" | "tax" | "team" | "text" | "text-align-center" | "text-align-left" | "text-align-right" | "text-block" | "text-bold" | "text-color" | "text-font" | "text-font-list" | "text-grammar" | "text-in-columns" | "text-in-rows" | "text-indent" | "text-indent-remove" | "text-italic" | "text-quote" | "text-title" | "text-underline" | "text-with-image" | "theme" | "theme-edit" | "theme-store" | "theme-template" | "three-d-environment" | "thumbs-down" | "thumbs-up" | "tip-jar" | "toggle-off" | "toggle-on" | "transaction" | "transaction-fee-add" | "transaction-fee-dollar" | "transaction-fee-euro" | "transaction-fee-pound" | "transaction-fee-rupee" | "transaction-fee-yen" | "transfer" | "transfer-in" | "transfer-internal" | "transfer-out" | "truck" | "undo" | "unknown-device" | "unlock" | "upload" | "variant-list" | "video" | "video-list" | "view" | "viewport-narrow" | "viewport-short" | "viewport-tall" | "viewport-wide" | "wallet" | "wand" | "watch" | "wifi" | "work" | "work-list" | "wrench" | "x" | "x-circle" | "x-circle-filled"
+
+  The type of icon to be displayed in the badge.
+
+* size
+
+  "base" | "large" | "large-100"
+
+  Default: 'base'
+
+  Adjusts the size.
+
+* tone
+
+  "info" | "success" | "warning" | "critical" | "auto" | "neutral" | "caution"
+
+  Default: 'auto'
+
+  Sets the tone of the Badge, based on the intention of the information being conveyed.
+
+## Slots
+
+* children
+
+  HTMLElement
+
+  The content of the Badge.
+
+Examples
+
+### Examples
+
+* #### Code
+
+  ##### jsx
+
+  ```jsx
+  <>
+    <s-badge>Fulfilled</s-badge>
+    <s-badge tone="info">Draft</s-badge>
+    <s-badge tone="success">Active</s-badge>
+    <s-badge tone="caution">Open</s-badge>
+    <s-badge tone="warning">On hold</s-badge>
+    <s-badge tone="critical">Action required</s-badge>
+  </>
+  ```
+
+  ##### html
+
+  ```html
+  <s-badge>Fulfilled</s-badge>
+  <s-badge tone="info">Draft</s-badge>
+  <s-badge tone="success">Active</s-badge>
+  <s-badge tone="caution">Open</s-badge>
+  <s-badge tone="warning">On hold</s-badge>
+  <s-badge tone="critical">Action required</s-badge>
+  ```
+
+* #### Order status badges
+
+  ##### Description
+
+  Demonstrates how different badge tones can visually represent various order fulfillment states, enabling merchants to quickly understand order progress at a glance.
+
+  ##### jsx
+
+  ```jsx
+  <s-stack direction="inline" gap="base">
+    <s-badge tone="success">Fulfilled</s-badge>
+    <s-badge tone="warning">Partially fulfilled</s-badge>
+    <s-badge tone="neutral">Unfulfilled</s-badge>
+    <s-badge tone="critical">Cancelled</s-badge>
+  </s-stack>
+  ```
+
+  ##### html
+
+  ```html
+  <s-stack direction="inline" gap="base">
+    <s-badge tone="success">Fulfilled</s-badge>
+    <s-badge tone="warning">Partially fulfilled</s-badge>
+    <s-badge tone="neutral">Unfulfilled</s-badge>
+    <s-badge tone="critical">Cancelled</s-badge>
+  </s-stack>
+  ```
+
+* #### Status indicators with icons
+
+  ##### Description
+
+  Showcases how badges can incorporate both tones and icons to provide contextual information across different merchant scenarios, such as product management, inventory tracking, and payment status.
+
+  ##### jsx
+
+  ```jsx
+  <s-stack gap="base">
+    {/* Product status */}
+    <s-stack direction="inline" gap="base">
+      <s-badge tone="success" icon="view">
+        Active
+      </s-badge>
+      <s-badge tone="warning" icon="clock">
+        Scheduled
+      </s-badge>
+      <s-badge tone="critical">Archived</s-badge>
+    </s-stack>
+
+    {/* Inventory status */}
+    <s-stack direction="inline" gap="base">
+      <s-badge tone="success">In stock</s-badge>
+      <s-badge tone="warning" icon="alert-triangle">
+        Low stock
+      </s-badge>
+      <s-badge tone="critical">Out of stock</s-badge>
+    </s-stack>
+  </s-stack>
+  ```
+
+  ##### html
+
+  ```html
+  <s-stack gap="base">
+    <!-- Product status -->
+    <s-stack direction="inline" gap="base">
+      <s-badge tone="success" icon="view">Active</s-badge>
+      <s-badge tone="warning" icon="clock">Scheduled</s-badge>
+      <s-badge tone="critical">Archived</s-badge>
+    </s-stack>
+
+    <!-- Inventory status -->
+    <s-stack direction="inline" gap="base">
+      <s-badge tone="success">In stock</s-badge>
+      <s-badge tone="warning" icon="alert-triangle">Low stock</s-badge>
+      <s-badge tone="critical">Out of stock</s-badge>
+    </s-stack>
+  </s-stack>
+  ```
+
+* #### Within table context
+
+  ##### Description
+
+  Illustrates how badges can be seamlessly integrated into table layouts to provide quick, visually distinct status indicators for individual table rows.
+
+  ##### jsx
+
+  ```jsx
+  <s-table>
+    <s-table-header-row>
+      <s-table-header>Order</s-table-header>
+      <s-table-header>Fulfillment</s-table-header>
+      <s-table-header>Payment</s-table-header>
+    </s-table-header-row>
+    <s-table-body>
+      <s-table-row>
+        <s-table-cell>#1001</s-table-cell>
+        <s-table-cell>
+          <s-badge tone="success">Fulfilled</s-badge>
+        </s-table-cell>
+        <s-table-cell>
+          <s-badge tone="success">Paid</s-badge>
+        </s-table-cell>
+      </s-table-row>
+    </s-table-body>
+  </s-table>
+  ```
+
+  ##### html
+
+  ```html
+  <s-table>
+    <s-table-header-row>
+      <s-table-header>Order</s-table-header>
+      <s-table-header>Fulfillment</s-table-header>
+      <s-table-header>Payment</s-table-header>
+    </s-table-header-row>
+    <s-table-body>
+      <s-table-row>
+        <s-table-cell>#1001</s-table-cell>
+        <s-table-cell>
+          <s-badge tone="success">Fulfilled</s-badge>
+        </s-table-cell>
+        <s-table-cell>
+          <s-badge tone="success">Paid</s-badge>
+        </s-table-cell>
+      </s-table-row>
+    </s-table-body>
+  </s-table>
+  ```
+
+* #### Different sizes for emphasis
+
+  ##### Description
+
+  Demonstrates the two available badge sizes for creating visual hierarchy.
+
+  ##### jsx
+
+  ```jsx
+  <s-stack direction="inline" gap="base">
+    <s-badge size="base">New</s-badge>
+    <s-badge size="large">Attention needed</s-badge>
+  </s-stack>
+  ```
+
+  ##### html
+
+  ```html
+  <s-stack direction="inline" gap="base">
+    <s-badge size="base">New</s-badge>
+    <s-badge size="large">Attention needed</s-badge>
+  </s-stack>
+  ```
+
+## Useful for
+
+* Communicating the state of an object
+* Identifying objects that need attention or action
+* Quickly scanning complex lists to find specific object states
+
+## Best practices
+
+* `base`: use in tables where many badges are displayed
+* `large`: use when badge needs to stand out prominently
+* Text truncates automatically, keep labels short to avoid truncation
+* Badges are static indicators, not interactive or dismissible
+* Use `critical` or `warning` tones for errors needing immediate attention
+* Use consistent styles and icons for common statuses
+* When using badges in line items, integrate them with the full content group rather than attaching only to the header
+* Don't use badges for merchant-created information. Instead, use a Chip or ClickableChip
+
+## Content guidelines
+
+Badge labels should:
+
+* Use 1-2 words maximum: `Fulfilled`, `Partially refunded`
+* Always use past tense: `Refunded` not `Refund`

package/docs/banner.md

@@ -0,0 +1,350 @@
+---
+title: Banner
+description: >-
+  Highlights important information or required actions prominently within the
+  interface. Use to communicate statuses, provide feedback, or draw attention to
+  critical updates.
+api_name: app-home
+source_url:
+  html: 'https://shopify.dev/docs/api/app-home/polaris-web-components/feedback/banner'
+  md: >-
+    https://shopify.dev/docs/api/app-home/polaris-web-components/feedback/banner.md
+---
+
+# Banner
+
+Highlights important information or required actions prominently within the interface. Use to communicate statuses, provide feedback, or draw attention to critical updates.
+
+## Properties
+
+* dismissible
+
+  boolean
+
+  Default: false
+
+  Determines whether the close button of the banner is present.
+
+  When the close button is pressed, the `dismiss` event will fire, then `hidden` will be true, any animation will complete, and the `afterhide` event will fire.
+
+* heading
+
+  string
+
+  Default: ''
+
+  The title of the banner.
+
+* hidden
+
+  boolean
+
+  Default: false
+
+  Determines whether the banner is hidden.
+
+  If this property is being set on each framework render (as in 'controlled' usage), and the banner is `dismissible`, ensure you update app state for this property when the `dismiss` event fires.
+
+  If the banner is not `dismissible`, it can still be hidden by setting this property.
+
+* tone
+
+  "info" | "success" | "warning" | "critical" | "auto"
+
+  Default: 'auto'
+
+  Sets the tone of the Banner, based on the intention of the information being conveyed.
+
+  The banner is a live region and the type of status will be dictated by the Tone selected.
+
+  * `critical` creates an [assertive live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately.
+  * `neutral`, `info`, `success`, `warning` and `caution` creates an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message.
+
+## Events
+
+Learn more about [registering events](https://shopify.dev/docs/api/app-home/using-polaris-components#event-handling).
+
+* afterhide
+
+  CallbackEventListener\<typeof tagName> | null
+
+* dismiss
+
+  CallbackEventListener\<typeof tagName> | null
+
+### CallbackEventListener
+
+```ts
+(EventListener & {
+      (event: CallbackEvent<T>): void;
+    }) | null
+```
+
+### CallbackEvent
+
+```ts
+Event & {
+  currentTarget: HTMLElementTagNameMap[T];
+}
+```
+
+## Slots
+
+* children
+
+  HTMLElement
+
+  The content of the Banner.
+
+* secondary-actions
+
+  HTMLElement
+
+  The secondary actions to display at the bottom of the Banner.
+
+  Only Buttons with the `variant` of "secondary" or "auto" are permitted. A maximum of two `s-button` components are allowed.
+
+Examples
+
+### Examples
+
+* #### Code
+
+  ##### jsx
+
+  ```jsx
+  <s-banner heading="Order archived" tone="info" dismissible>
+    This order was archived on March 7, 2017 at 3:12pm EDT.
+  </s-banner>
+  ```
+
+  ##### html
+
+  ```html
+  <s-banner heading="Order archived" tone="info" dismissible>
+    This order was archived on March 7, 2017 at 3:12pm EDT.
+  </s-banner>
+  ```
+
+* #### Basic information banner
+
+  ##### Description
+
+  Demonstrates a simple informational banner used to communicate status updates or completed actions, providing clear and concise feedback to the user.
+
+  ##### jsx
+
+  ```jsx
+  <s-banner heading="Order archived">
+    This order was archived on March 7, 2017 at 3:12pm EDT.
+  </s-banner>
+  ```
+
+  ##### html
+
+  ```html
+  <s-banner heading="Order archived">
+    This order was archived on March 7, 2017 at 3:12pm EDT.
+  </s-banner>
+  ```
+
+* #### Warning banner with specific actions
+
+  ##### Description
+
+  Illustrates a warning banner that highlights a potential issue and provides actionable buttons to help users resolve the problem quickly and effectively.
+
+  ##### jsx
+
+  ```jsx
+  <s-banner heading="127 products missing shipping weights" tone="warning">
+    Products without weights may show inaccurate shipping rates, leading to
+    checkout abandonment.
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/products?filter=missing-weights"
+    >
+      Review products
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="javascript:void(0)"
+    >
+      Setup guide
+    </s-button>
+  </s-banner>
+  ```
+
+  ##### html
+
+  ```html
+  <s-banner heading="127 products missing shipping weights" tone="warning">
+    Products without weights may show inaccurate shipping rates, leading to
+    checkout abandonment.
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/products?filter=missing-weights"
+    >
+      Review products
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="javascript:void(0)"
+    >
+      Setup guide
+    </s-button>
+  </s-banner>
+  ```
+
+* #### Critical banner with clear next steps
+
+  ##### Description
+
+  Demonstrates an urgent banner design that signals a critical issue requiring immediate action, with clear and prominent secondary action buttons to guide users.
+
+  ##### jsx
+
+  ```jsx
+  <s-banner heading="Order #1024 flagged for fraud review" tone="critical">
+    This order shows multiple risk indicators and cannot be auto-fulfilled. Review
+    required within 24 hours to prevent automatic cancellation.
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/orders/1024/risk"
+    >
+      Review order details
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/settings/payments/fraud"
+    >
+      Adjust fraud settings
+    </s-button>
+  </s-banner>
+  ```
+
+  ##### html
+
+  ```html
+  <s-banner heading="Order #1024 flagged for fraud review" tone="critical">
+    This order shows multiple risk indicators and cannot be auto-fulfilled. Review
+    required within 24 hours to prevent automatic cancellation.
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/orders/1024/risk"
+    >
+      Review order details
+    </s-button>
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/settings/payments/fraud"
+    >
+      Adjust fraud settings
+    </s-button>
+  </s-banner>
+  ```
+
+* #### Dismissible success banner
+
+  ##### Description
+
+  Success confirmation with dismiss option for completed operations.
+
+  ##### jsx
+
+  ```jsx
+  <s-banner heading="Products imported" tone="success" dismissible={true}>
+    Successfully imported 50 products to your store.
+  </s-banner>
+  ```
+
+  ##### html
+
+  ```html
+  <s-banner heading="Products imported" tone="success" dismissible="true">
+    Successfully imported 50 products to your store.
+  </s-banner>
+  ```
+
+* #### Info banner with clear value proposition
+
+  ##### Description
+
+  Informational banner highlighting app updates with clear benefits and actions.
+
+  ##### jsx
+
+  ```jsx
+  <s-banner heading="Point of Sale v2.4 available" tone="info" dismissible>
+    New version includes faster checkout processing and inventory sync
+    improvements.
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/apps/pos/changelog"
+    >
+      View changes
+    </s-button>
+    <s-button slot="secondary-actions" variant="secondary">
+      Install update
+    </s-button>
+  </s-banner>
+  ```
+
+  ##### html
+
+  ```html
+  <s-banner heading="Point of Sale v2.4 available" tone="info" dismissible>
+    New version includes faster checkout processing and inventory sync
+    improvements.
+    <s-button
+      slot="secondary-actions"
+      variant="secondary"
+      href="/admin/apps/pos/changelog"
+    >
+      View changes
+    </s-button>
+    <s-button slot="secondary-actions" variant="secondary">
+      Install update
+    </s-button>
+  </s-banner>
+  ```
+
+## Useful for
+
+* Showing important information or changes
+* Prompting merchants to take a specific action
+* Displaying warnings, errors, or critical information
+* Communicating persistent conditions that need attention
+
+## Outside of a section
+
+Banners placed outside of a section will display in their own card and should be located at the top of the page. They're useful for conveying messages that apply to the entire page or areas not visible within the viewport, such as validation errors further down the page.
+
+## In a section
+
+Banners placed inside a section will have styles applied contextually. They're useful for conveying messages relevant to a specific section or piece of content.
+
+## Best practices
+
+* Seeing these banners can be stressful, so use them sparingly to avoid overwhelming users.
+* Focus on a single piece of information or required action to avoid overwhelming users.
+* Make the message concise and scannable. Users shouldn’t need to spend a lot of time figuring out what they need to know and do.
+* Info, Warning and Critical banners should contain a call to action and clear next steps. Users should know what to do after seeing the banner.
+* Avoid banners that can't be dismissed unless the user is required to take action.
+
+## Content guidelines
+
+* Keep titles concise and clear
+* Limit body content to 1-2 sentences where possible
+* Use action-led buttons with strong verbs (e.g., "Activate Apple Pay" not "Try Apple Pay")
+* Avoid unnecessary words and articles in button text
+* For warning and critical banners, explain how to resolve the issue