@vtex/faststore 0.0.10 → 0.0.11

package/dist/docs/product-gallery.md

@@ -197,10 +197,7 @@ Adds `data-fs-gallery-thumbnail-selected="true"` when active. For videos, render
 
 "+N" badge shown when there are more items than `maxVisible`. Only renders on the last thumbnail slot when overflow exists. Clicking opens fullscreen.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `template` | string | `"+{count}"` | `{count}` = number of hidden items |
-| `ariaLabel` | string | `"View all {total} images"` | Applied to the rendered `<button>` so screen readers announce the full action. `{total}` is replaced by the total media count. |
+Content model `gallery-overflow-count`: `template` (`count` = number of hidden items) and `ariaLabel`, applied to the rendered `<button>` so screen readers announce the full action (`total` = the total media count). Both are ICU messages read only from `$content`.
 
 Must be a child of `GalleryThumbnails`, alongside `GalleryThumbnail`.
 
@@ -210,13 +207,13 @@ Must be a child of `GalleryThumbnails`, alongside `GalleryThumbnail`.
 
 Fullscreen overlay (Dialog). Opens via `GalleryOverflowCount`, `clickOpensFullscreen=true` on `GalleryMainMedia`, or `thumbnailOpensFullscreen=true` on Root. No props.
 
-Must be inside `ProductGalleryRoot`. If you omit `GalleryFullscreenTitle`, a default sr-only `"Gallery"` title is rendered automatically so the dialog always has an accessible name.
+Must be inside `ProductGalleryRoot`. If you omit `GalleryFullscreenTitle`, an sr-only title from its `title` message (content type `gallery-fullscreen`) is rendered so the dialog always has an accessible name.
 
 ---
 
 ### GalleryFullscreenTitle
 
-Sets the accessible name for the fullscreen dialog. Optional — when absent, `GalleryFullscreen` renders a default sr-only `"Gallery"` title. No props — pass text as children. Add `className="sr-only"` to hide it visually.
+Sets the accessible name for the fullscreen dialog. Optional — when absent, `GalleryFullscreen` renders its own sr-only `title` message. Children win; without them it renders its `label` message (content type `gallery-fullscreen-title`). Add `className="sr-only"` to hide it visually.
 
 Must be inside `GalleryFullscreen`.
 
@@ -246,23 +243,21 @@ Use inside `GalleryFullscreen` for fullscreen slider navigation, or inline for c
 
 Displays current position and total count.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `template` | string | `"{current} / {total}"` | placeholders: `{current}`, `{total}` |
+Content model `gallery-media-count`: `template`, an ICU message with `current` and `total` arguments, read only from `$content`.
 
 Place anywhere inside `ProductGalleryRoot` — typically inside `GalleryFullscreen` or above `GalleryMainMedia`.
 
-#### Template token vocabulary
+#### Template argument vocabulary
 
-Both template-bearing components draw from one shared token vocabulary. Each token has exactly one meaning, and `{total}` means the same thing wherever it appears (including `GalleryOverflowCount.ariaLabel`):
+Both templates are ICU messages and draw from one shared argument vocabulary. Each argument has exactly one meaning, and `{total}` means the same thing wherever it appears (including `GalleryOverflowCount.ariaLabel`):
 
-| Token | Meaning | Used by |
+| Argument | Meaning | Used by |
 |---|---|---|
 | `{total}` | Total number of media items | `GalleryMediaCount.template`, `GalleryOverflowCount.ariaLabel` |
 | `{current}` | Current 1-based position | `GalleryMediaCount.template` |
 | `{count}` | Number of hidden items (overflow) | `GalleryOverflowCount.template` |
 
-A token only interpolates in the components listed above; elsewhere it is rendered literally. Defaults render exactly as shipped — `GalleryOverflowCount` shows `"+N"` and `GalleryMediaCount` shows `"2 / 10"`.
+A number argument is formatted in the locale. A missing message renders empty and logs `message.missing`; an invalid one renders as authored and logs `message.invalid`.
 
 ---
 
@@ -359,12 +354,12 @@ Fill each element's `style` array with Tailwind classes read off the image. Typi
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `ProductGalleryRoot` | Stacks the main media over the thumbnails | `flex flex-col gap-[12px] w-full` |
-| `GalleryMainMedia` | Square framed media, contained, light border | `block w-full aspect-square bg-white border border-[#E5E5E5] rounded-[4px] object-contain p-[16px]` |
+| `GalleryMainMedia` | Square framed media, contained, light border | `block w-full aspect-square bg-white border border-[var(--color-border)] rounded-[4px] object-contain p-[16px]` |
 | `GalleryThumbnails` | Horizontal row of thumbnails | `flex flex-row items-center gap-[8px] w-full mt-[4px]` |
-| `GalleryThumbnail` | Small square button; mark the selected one via its data attribute | `block w-[64px] h-[64px] bg-white border border-[#E5E5E5] rounded-[4px] object-contain p-[4px] cursor-pointer data-[fs-gallery-thumbnail-selected=true]:border-[#C8102E]` |
-| `GalleryOverflowCount` | "+N" badge matching the thumbnail box | `flex items-center justify-center w-[64px] h-[64px] bg-[#F5F5F5] border border-[#E5E5E5] rounded-[4px] text-[13px] font-medium text-[#1A1A1A]` |
+| `GalleryThumbnail` | Small square button; mark the selected one via its data attribute | `block w-[64px] h-[64px] bg-white border border-[var(--color-border)] rounded-[4px] object-contain p-[4px] cursor-pointer data-[fs-gallery-thumbnail-selected=true]:border-[var(--color-primary)]` |
+| `GalleryOverflowCount` | "+N" badge matching the thumbnail box | `flex items-center justify-center w-[64px] h-[64px] bg-[var(--color-surface-muted)] border border-[var(--color-border)] rounded-[4px] text-[13px] font-medium text-[var(--color-text)]` |
 
-Read the border color, radius, and thumbnail size from the image; use arbitrary values (`w-[64px]`, `border-[#E5E5E5]`) to match it. The selected-thumbnail highlight uses the brand color via the `data-[fs-gallery-thumbnail-selected=true]:` variant.
+Read the border color, radius, and thumbnail size from the image; use arbitrary values for sizes (`w-[64px]`) and the shared border variable for the border color (`border-[var(--color-border)]`). The selected-thumbnail highlight uses the brand color via the `data-[fs-gallery-thumbnail-selected=true]:` variant.
 
 Styled gallery example:
 
@@ -379,7 +374,7 @@ Styled gallery example:
   "gallery-main": {
     "type": "GalleryMainMedia",
     "props": { "objectFit": "contain", "aspectRatio": "1 / 1", "clickOpensFullscreen": true },
-    "style": ["block", "w-full", "aspect-square", "bg-white", "border", "border-[#E5E5E5]", "rounded-[4px]", "object-contain", "p-[16px]"]
+    "style": ["block", "w-full", "aspect-square", "bg-white", "border", "border-[var(--color-border)]", "rounded-[4px]", "object-contain", "p-[16px]"]
   },
   "gallery-thumbnails": {
     "type": "GalleryThumbnails",
@@ -390,16 +385,20 @@ Styled gallery example:
   "gallery-thumbnail": {
     "type": "GalleryThumbnail",
     "props": { "objectFit": "contain", "aspectRatio": "1 / 1" },
-    "style": ["block", "w-[64px]", "h-[64px]", "bg-white", "border", "border-[#E5E5E5]", "rounded-[4px]", "object-contain", "p-[4px]", "cursor-pointer", "data-[fs-gallery-thumbnail-selected=true]:border-[#C8102E]"]
+    "style": ["block", "w-[64px]", "h-[64px]", "bg-white", "border", "border-[var(--color-border)]", "rounded-[4px]", "object-contain", "p-[4px]", "cursor-pointer", "data-[fs-gallery-thumbnail-selected=true]:border-[var(--color-primary)]"]
   },
   "gallery-overflow": {
     "type": "GalleryOverflowCount",
     "props": { "template": "+{count}" },
-    "style": ["flex", "items-center", "justify-center", "w-[64px]", "h-[64px]", "bg-[#F5F5F5]", "border", "border-[#E5E5E5]", "rounded-[4px]", "text-[13px]", "font-medium", "text-[#1A1A1A]"]
+    "style": ["flex", "items-center", "justify-center", "w-[64px]", "h-[64px]", "bg-[var(--color-surface-muted)]", "border", "border-[var(--color-border)]", "rounded-[4px]", "text-[13px]", "font-medium", "text-[var(--color-text)]"]
   }
 }
 ```
 
+The role colors above are the foundation's `visualIdentity` roles (`--color-primary`), so they follow the store when it changes them.
+
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-border": "#E5E5E5", "--color-surface-muted": "#F5F5F5", "--color-text": "#1A1A1A"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/product-information.md

@@ -93,8 +93,8 @@ Renders the product description, optionally collapsed behind a "show more" toggl
 | `collapse` | `'none' \| 'showMore' \| 'section'` | `'none'` | Selects the collapse pattern. `'none'` renders the full block with no toggle (today's behavior). `'showMore'` clamps the body to `collapsedLines` and reveals the rest with a trigger that flips the clamp. `'section'` collapses the whole panel behind one trigger; the body uses Base UI Collapsible with `hidden="until-found"` so the full text stays in the SSR DOM and remains indexable. |
 | `defaultExpanded` | boolean | `true` | Initial open state for the panel. Only consulted when `collapse !== 'none'`. SSR-safe. |
 | `collapsedLines` | number | `4` | Line count for the CSS clamp in `'showMore'` mode. Ignored for `'none'` and `'section'`. |
-| `moreLabel` | string | `'Show more'` | Trigger label shown when the panel is collapsed. Localize per storefront (e.g. `'mais informações'` for pt-BR). |
-| `lessLabel` | string | `'Show less'` | Trigger label shown when the panel is expanded (e.g. `'menos informações'`). |
+
+**Content model** (`product-information-description`): `moreLabel` (trigger label while collapsed, e.g. `'mais informações'` for pt-BR) and `lessLabel` (while expanded, e.g. `'menos informações'`), both ICU messages read only from `$content` and formatted only when `collapse !== 'none'`. A missing message renders an empty trigger label and logs `message.missing`.
 
 The wrapper element follows from the resolved branch: plain text renders as `<p>` (semantic body-text exposure for screen-reader paragraph navigation and SEO); rich HTML renders as `<div>` so block-level markup inside `descriptionHtml` (`<p>`, `<ul>`, headings) stays valid DOM. The element that hosts the rendered description text carries `data-fs-text=""` so project-level `Text` typography defined in `foundation.json` cascades to the description automatically — no need to repeat font, size, color, leading, or tracking classes inline on every description node. With `collapse: 'none'` that element is the wrapper itself; with `collapse: 'showMore'` or `'section'` it is the panel (the `Collapsible.Root` and the trigger `<button>` deliberately do not carry it so body typography does not cascade onto the trigger label).
 
@@ -249,17 +249,17 @@ Stacks the title, description, and other lines. Typical: `flex flex-col gap-[4px
 
 ### ProductInformationTitle
 
-The main heading — large and bold. Typical: `text-[20px] leading-[1.3] font-semibold text-[#1A1A1A] tracking-[-0.005em] m-0`. Scale `text-[...]` to the heading size in the image; read the ink color as an arbitrary hex.
+The main heading — large and bold. Typical: `text-[20px] leading-[1.3] font-semibold text-[var(--color-text)] tracking-[-0.005em] m-0`. Scale `text-[...]` to the heading size in the image; the ink color is a variable the page or layout `theme` declares, as the note at the end of this section shows.
 
 ### ProductInformationDescription
 
-Body copy — smaller, lighter, comfortable line height. Typical: `text-[14px] leading-[1.6] font-normal text-[#666666]`. The element that hosts the text carries `data-fs-text=""` in every collapse mode (the wrapper itself for `collapse: 'none'`, the panel for `'showMore'` and `'section'`), so if the project's `foundation.json` defines `Text.base` with the body-text typography (font, size, leading, weight, color), those styles cascade to the description automatically and no inline typography classes are needed on the description node.
+Body copy — smaller, lighter, comfortable line height. Typical: `text-[14px] leading-[1.6] font-normal text-[var(--color-text-muted)]`. The element that hosts the text carries `data-fs-text=""` in every collapse mode (the wrapper itself for `collapse: 'none'`, the panel for `'showMore'` and `'section'`), so if the project's `foundation.json` defines `Text.base` with the body-text typography (font, size, leading, weight, color), those styles cascade to the description automatically and no inline typography classes are needed on the description node.
 
-When `collapse` is `'showMore'` or `'section'`, the trigger element is a real `<button>` rendered as a sibling of the panel inside the Collapsible root. Style it via the `data-fs-product-information-description-trigger` attribute hook so the trigger inherits the description's flex container without being centered or stretched. Typical: `[&_[data-fs-product-information-description-trigger]]:self-start [&_[data-fs-product-information-description-trigger]]:text-[14px] [&_[data-fs-product-information-description-trigger]]:font-medium [&_[data-fs-product-information-description-trigger]]:underline`. Pair with the brand's link color via an arbitrary hex (e.g. `[&_[data-fs-product-information-description-trigger]]:text-[#e60014]`).
+When `collapse` is `'showMore'` or `'section'`, the trigger element is a real `<button>` rendered as a sibling of the panel inside the Collapsible root. Style it via the `data-fs-product-information-description-trigger` attribute hook so the trigger inherits the description's flex container without being centered or stretched. Typical: `[&_[data-fs-product-information-description-trigger]]:self-start [&_[data-fs-product-information-description-trigger]]:text-[14px] [&_[data-fs-product-information-description-trigger]]:font-medium [&_[data-fs-product-information-description-trigger]]:underline`. Pair with the brand's link color via an arbitrary hex (e.g. `[&_[data-fs-product-information-description-trigger]]:text-[var(--color-primary)]`).
 
 ### ProductInformationBrand / Sku / ReferenceId
 
-Secondary labels — small and muted. Typical: `text-[12px] leading-[1.4] font-normal text-[#8A8A8A]`. Use `uppercase tracking-[0.04em]` for an eyebrow-style brand label when the image shows it that way.
+Secondary labels — small and muted. Typical: `text-[12px] leading-[1.4] font-normal text-[var(--color-text-subtle)]`. Use `uppercase tracking-[0.04em]` for an eyebrow-style brand label when the image shows it that way.
 
 Styled example — brand, title, and description visible:
 
@@ -272,20 +272,24 @@ Styled example — brand, title, and description visible:
   },
   "product-brand": {
     "type": "ProductInformationBrand",
-    "style": ["text-[12px]", "leading-[1.4]", "font-normal", "text-[#8A8A8A]", "uppercase", "tracking-[0.04em]"]
+    "style": ["text-[12px]", "leading-[1.4]", "font-normal", "text-[var(--color-text-subtle)]", "uppercase", "tracking-[0.04em]"]
   },
   "product-title": {
     "type": "ProductInformationTitle",
     "props": { "as": "h1" },
-    "style": ["text-[20px]", "leading-[1.3]", "font-semibold", "text-[#1A1A1A]", "tracking-[-0.005em]", "m-0"]
+    "style": ["text-[20px]", "leading-[1.3]", "font-semibold", "text-[var(--color-text)]", "tracking-[-0.005em]", "m-0"]
   },
   "product-description": {
     "type": "ProductInformationDescription",
-    "style": ["text-[14px]", "leading-[1.6]", "font-normal", "text-[#666666]"]
+    "style": ["text-[14px]", "leading-[1.6]", "font-normal", "text-[var(--color-text-muted)]"]
   }
 }
 ```
 
+The role colors above are the foundation's `visualIdentity` roles (`--color-primary`), so they follow the store when it changes them.
+
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text": "#1A1A1A", "--color-text-muted": "#666666", "--color-text-subtle": "#8A8A8A"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/product-list.md

@@ -26,7 +26,7 @@
 - **Image layout is configurable.** `ProductCardImage` exposes `aspectRatio` (e.g. `1/1`, `3/4`, `16/9`) and `objectFit`; they are orthogonal — `aspectRatio` sizes the box, `objectFit` fits the pixels. Alt text comes from `item.image.alt` (the catalog alt text, falling back to the product name at the data source).
 - **Availability is a derived card state.** The optional `ProductCard` wrapper emits `data-fs-product-card-out-of-stock` when `item.availableForSale === false || item.availableQuantity === 0` (unset ⇒ in stock), so a swatch can grey / reduce the opacity of the whole card. It is a derived state attribute, not a boolean prop, and the wrapper never suppresses its children — price and discount still render on an out-of-stock card. Dropping unavailable products entirely is the shelf's `availableOnly` config (`ProductShelfRoot`, T2), not a card concern.
 - **The card border is a style toggle.** The `ProductCard` wrapper also takes a `bordered` prop (default `true`) and reflects it onto `data-fs-product-card-bordered` (`"true"` / `"false"`, always present). A border is not an independently placeable part, so it is a boolean appearance config, not compose-or-omit; the actual border look is a swatch keyed off the attribute value — the component ships none. Because the attribute carries an explicit value, a swatch can style both the bordered and the unbordered case (`[data-fs-product-card-bordered='true']` / `'false']`). It is orthogonal to the out-of-stock state and does not affect children.
-- **Tax display is a config.** When the root config `usePriceWithTaxes` is on, `ProductCardPrice` and `ProductCardListPrice` render **tax-inclusive** values — `base × (1 + rate)` with `rate = item.taxPercentage ?? item.tax / item.price` (missing/zero-price tax data ⇒ rate `0`, prices unchanged). The same rate applies to both, so the list-price guard still compares the base prices. `ProductCardTaxLabel` renders the configured `taxesLabel` beside the price, but **only when `usePriceWithTaxes` is enabled** (state-driven presence — compose to place it, omit to hide). Default is tax-exclusive (off).
+- **Tax display is a config.** When the root config `usePriceWithTaxes` is on, `ProductCardPrice` and `ProductCardListPrice` render **tax-inclusive** values — `base × (1 + rate)` with `rate = item.taxPercentage ?? item.tax / item.price` (missing/zero-price tax data ⇒ rate `0`, prices unchanged). The same rate applies to both, so the list-price guard still compares the base prices. `ProductCardTaxLabel` renders its `label` message beside the price, but **only when `usePriceWithTaxes` is enabled** (state-driven presence — compose to place it, omit to hide). Default is tax-exclusive (off).
 
 ---
 
@@ -38,9 +38,8 @@
 |------|------|---------|-------|
 | `products` | `ProductListItem[]` | `[]` | The products to render; published through the products context |
 | `usePriceWithTaxes` | boolean | `false` | When true, card prices render tax-inclusive and `ProductCardTaxLabel` shows |
-| `taxesLabel` | string | `Tax included` | Text rendered by `ProductCardTaxLabel` when tax display is on |
 
-`ProductShelfRoot` exposes the same `usePriceWithTaxes` / `taxesLabel` config (it publishes the same config context).
+`ProductShelfRoot` exposes the same `usePriceWithTaxes` config (it publishes the same config context).
 
 ### ProductListGrid
 
@@ -77,7 +76,9 @@ Renders `item.listPrice` (strikethrough via swatch) formatted like the selling p
 
 ### ProductCardTaxLabel
 
-Renders the config `taxesLabel` (default "Tax included") beside the price, **only when `usePriceWithTaxes` is enabled** — otherwise renders nothing (state-driven presence, no toggle: compose it to place the label, omit it to hide it). Children override the text. Emits `data-fs-product-card-tax-label` for styling. Reads only the config (not the item), so its placement in the card template is free.
+Renders its `label` message beside the price, **only when `usePriceWithTaxes` is enabled** — otherwise renders nothing (state-driven presence, no toggle: compose it to place the label, omit it to hide it). Children override the text.
+
+**Content model** (`product-card-tax-label`): `label`, an ICU message read only from `$content` and formatted only while the label renders. A missing message renders an empty label and logs `message.missing`. Emits `data-fs-product-card-tax-label` for styling. Reads only the config (not the item), so its placement in the card template is free.
 
 ### ProductCardDiscount
 
@@ -133,7 +134,7 @@ The same card template composes inside a `ProductShelf` — swap `ProductListRoo
 {
   "list": {
     "type": "ProductListRoot",
-    "props": { "usePriceWithTaxes": true, "taxesLabel": "Tax included" },
+    "props": { "usePriceWithTaxes": true },
     "children": ["grid"]
   },
   "grid": {
@@ -150,7 +151,7 @@ The same card template composes inside a `ProductShelf` — swap `ProductListRoo
   "card-discount": { "type": "ProductCardDiscount", "props": { "format": "percentage" } },
   "card-price": { "type": "ProductCardPrice" },
   "card-list-price": { "type": "ProductCardListPrice" },
-  "card-tax-label": { "type": "ProductCardTaxLabel" }
+  "card-tax-label": { "type": "ProductCardTaxLabel", "props": { "label": "Tax included" } }
 }
 ```
 

package/dist/docs/product-shelf.md

@@ -57,7 +57,6 @@ The image is the source of truth for the heading text, `first`/`itemsPerPage`, a
 |------|------|---------|-------|
 | `itemsPerPage` | number | `5` | Cards per page; bind to `CarouselRoot`'s `itemsPerPage` |
 | `usePriceWithTaxes` | boolean | `false` | Card prices render tax-inclusive |
-| `taxesLabel` | string | `'Tax included'` | Text for the tax label part |
 | `first` | number | `5` | Content field. Products fetched (legacy `numberOfItems`) → `$first` |
 | `sort` | `relevance \| price_asc \| price_desc \| name_asc \| name_desc \| release \| orders \| discount` | `relevance` | Content field → `$orderBy` through the `values` table |
 | `searchTerm` | string | — | Content field → `filter.searchTerm` |

package/dist/docs/promotion.md

@@ -87,7 +87,7 @@ Content model (`promotion`) fields, edited in the CMS:
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `Promotion` | The callout container — stacks image, title, and body | `flex flex-col gap-[8px] p-[16px] rounded-[8px] bg-[#F5F5F5] w-full` |
+| `Promotion` | The callout container — stacks image, title, and body | `flex flex-col gap-[8px] p-[16px] rounded-[8px] bg-[var(--color-surface-muted)] w-full` |
 
 Styled example:
 
@@ -95,11 +95,13 @@ Styled example:
 {
   "promo": {
     "type": "Promotion",
-    "style": ["flex", "flex-col", "gap-[8px]", "p-[16px]", "rounded-[8px]", "bg-[#F5F5F5]", "w-full"]
+    "style": ["flex", "flex-col", "gap-[8px]", "p-[16px]", "rounded-[8px]", "bg-[var(--color-surface-muted)]", "w-full"]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-surface-muted": "#F5F5F5"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/region.md

@@ -75,15 +75,13 @@ Root region provider. Reads the resolved `Region` slice reactively and broadcast
 
 ### RegionTrigger
 
-Opens the modal. Shows its unset label while no region is set; compose `RegionValue` as its child so the active region reads inside the control once one is. Not interactive while the region is unresolved.
+Opens the modal. Shows its unset label (the `unsetLabel` message) while no region is set; compose `RegionValue` as its child so the active region reads inside the control once one is. Not interactive while the region is unresolved.
 
 Its accessible name carries the active region, so a screen reader announces where the shopper is shopping rather than a label that reads the same in every state. An authored `aria-label` **prefixes** the visible text rather than replacing it — `"Alterar região: São Paulo 01310-100"`, and `"Alterar região: Informe seu CEP"` while unset — because WCAG 2.5.3 requires the accessible name to contain the visible label, and a name a voice-control user cannot read off the screen is one they cannot speak. Author the verb alone (`"Alterar região"`); the component appends the state.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `unsetLabel` | string | `"Informe seu CEP"` | Shown while no region is set |
+No props of its own.
 
-**Content model** (`region-trigger`): `unsetLabel`, `ariaLabel`.
+**Content model** (`region-trigger`): `unsetLabel` (ICU message), `ariaLabel` (plain text that prefixes the accessible name).
 
 ### RegionValue
 
@@ -122,18 +120,15 @@ A refusal also takes focus back to the field, so the shopper lands on the value
 
 Submits the draft. Inert while the draft is empty and while a write is in flight, so a double activation dispatches exactly one mutation. The pending state is exposed as `aria-busy` with no built-in spinner. The value is passed to the server exactly as the shopper typed it, mask included — the server is authoritative on format.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `"Aplicar"` | Button label |
-| `pendingLabel` | string | `"Aplicando..."` | Shown while the write is in flight |
+Its text is the `label` message, and `pendingLabel` while the write is in flight. Authored `children` replace both, and then no message is formatted. No props of its own.
 
-**Content model** (`region-submit`): `label`, `pendingLabel`.
+**Content model** (`region-submit`): `label`, `pendingLabel`, both ICU messages.
 
 ### RegionError
 
-Shows why the latest write was refused, announced as an alert when it appears. Renders nothing when there is no error. A rejection the server codes (`INVALID_POSTAL_CODE`, `UNSERVED_POSTAL_CODE`) and a transport failure (`NETWORK_ERROR`) render the message catalog's copy in the store's language; the server's own English message is shown only for a code the catalog does not know. The authored generic message covers a transport failure, where there is no server message to show, and wins over the catalog there. No props.
+Shows why the latest write was refused, announced as an alert when it appears. Renders nothing when there is no error. A rejection the server codes (`INVALID_POSTAL_CODE`, `UNSERVED_POSTAL_CODE`) and a transport failure (`NETWORK_ERROR`) render their message from `$content`; the server's English message is never shown, and a code this component does not know shows `genericMessage` and logs `message.unknown-code`. An unauthored message renders empty and logs `message.missing`. No props.
 
-**Content model** (`region-error`): `genericMessage`.
+**Content model** (`region-error`): `genericMessage` (`NETWORK_ERROR`), `invalidPostalCode` (`INVALID_POSTAL_CODE`), `unservedPostalCode` (`UNSERVED_POSTAL_CODE`), all ICU messages.
 
 ### RegionUnknownLink
 
@@ -150,6 +145,8 @@ Link text comes from authored content, else from `children`.
 
 **Content model** (`region-unknown-link`): `text`, `href`.
 
+Every message reads only from `$content`: an unauthored one renders empty and logs `message.missing`. A store without CMS authors the message fields on the element, as below; a CMS-bound store keeps them in content.
+
 ---
 
 ## Canonical schema example
@@ -159,7 +156,11 @@ Header region control with the full modal:
 ```json
 {
   "region": { "type": "RegionRoot", "children": ["region-trigger", "region-modal"] },
-  "region-trigger": { "type": "RegionTrigger", "children": ["region-value"] },
+  "region-trigger": {
+    "type": "RegionTrigger",
+    "props": { "unsetLabel": "Informe seu CEP" },
+    "children": ["region-value"]
+  },
   "region-value": { "type": "RegionValue" },
   "region-modal": { "type": "RegionModalController", "children": ["region-dialog"] },
   "region-dialog": { "type": "DialogRoot", "children": ["region-portal"] },
@@ -173,8 +174,15 @@ Header region control with the full modal:
   "region-title": { "type": "DialogTitle", "props": { "children": "Escolha sua região" } },
   "region-form": { "type": "RegionForm", "children": ["region-input", "region-submit"] },
   "region-input": { "type": "RegionPostalCodeControl", "props": { "label": "CEP" } },
-  "region-submit": { "type": "RegionSubmit" },
-  "region-error": { "type": "RegionError" },
+  "region-submit": { "type": "RegionSubmit", "props": { "label": "Aplicar", "pendingLabel": "Aplicando..." } },
+  "region-error": {
+    "type": "RegionError",
+    "props": {
+      "genericMessage": "Não foi possível definir sua região.",
+      "invalidPostalCode": "Informe um CEP válido.",
+      "unservedPostalCode": "Ainda não entregamos neste CEP."
+    }
+  },
   "region-unknown": { "type": "RegionUnknownLink" }
 }
 ```

package/dist/docs/save-card.md

@@ -86,12 +86,11 @@ as the shopper left it.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `"Save this card for next time"` | The toggle's own label text. |
-| `nicknameLabel` | string | `"Card nickname"` | Label for the nickname field; rendered only while checked. |
 | `nicknamePlaceholder` | string | — | Optional placeholder for the nickname field. |
-| `consentNoticeLabel` | string | `"Checking this also lets us store your personal data for future purchases."` | Shown beside the toggle while the account has not already granted the data-storage consent. |
 | `disabled` | boolean | `false` | Disables both the toggle and the nickname field. |
 
+**Content model** (`save-card`): `label`, the toggle's own label text; `nicknameLabel`, the label for the nickname field, rendered only while checked; `consentNoticeLabel`, shown beside the toggle while the account has not already granted the data-storage consent; and `genericErrorMessage`, the alert for a refused consent write. Every code the write can return (`ClientPreferencesUpdateErrorCode` and `NETWORK_ERROR`) is one the shopper cannot act on, so all of them show `genericErrorMessage`; a code the package does not know (one a newer server added) shows it too and logs `message.unknown-code`. Each is read only from `$content`; a missing message renders empty and logs `message.missing`.
+
 **Data:** declares its own `fragment SaveCardData on Query` (selects `Query.clientPreferences.savePersonalData`
 only — a single boolean, not a card field) — a small, thin fragment the compiler merges into the page
 query alongside `PaymentSectionRoot`'s own selection; no explicit `dataSources` entry needed.
@@ -104,7 +103,7 @@ choice.
 **Checking the toggle** records the shopper's intent for this card *and* grants the account's
 data-storage consent in the same action; the nickname field appears immediately below. **Unchecking**
 withdraws only this transaction's intent — it never revokes a consent an unrelated control may have
-granted. On a rejected consent write, the first error message renders inline.
+granted. On a rejected consent write, the first error renders inline, worded from `genericErrorMessage`.
 
 ---
 
@@ -153,11 +152,13 @@ Single DOM root wrapping the toggle field, an optional nickname field, and an op
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `SaveCard` (root `div`) | Stacks the toggle field, nickname field, and error | `flex flex-col gap-[8px]` |
-| Consent notice (`data-fs-save-card-consent-notice`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
+| Consent notice (`data-fs-save-card-consent-notice`) | De-emphasized helper text | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
 | Nickname field wrapper (`data-fs-save-card-nickname-field`) | Spacing above the field | `mt-[8px]` |
-| Inline error (`data-fs-save-card-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
+| Inline error (`data-fs-save-card-error`) | Warning-toned alert text | `text-[12px] font-medium` |
 | Placing (`data-fs-save-card-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from `data-fs-save-card-pending`, which this component already emits for its own local consent dispatch; the root is also `inert` and `aria-disabled` while placing | `opacity-60 cursor-not-allowed` |
 
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares them, color the error row `text-[var(--color-feedback-danger)]`, the success row `text-[var(--color-feedback-success)]` and the notice row `text-[var(--color-feedback-warning)]`, never with a hex.
+
 Styled example:
 
 ```json