@vtex/faststore 0.0.10 → 0.0.12

package/dist/docs/account-saved-cards.md

@@ -39,9 +39,9 @@ AccountSavedCardsRoot             ← requires 'session'; provides 'account-save
 ├── AccountSavedCardsEmpty
 └── AccountSavedCardsList         ← provides 'account-saved-card'
     └── AccountSavedCardItem      ← one row per card; provides 'card-summary', 'account-saved-card-data'
-        ├── CardSummary           (default when the row has no children)
-        ├── AccountSavedCardExpiry (default when the row has no children)
-        └── AccountSavedCardRemove (default when the row has no children) ← provides 'account-saved-card-remove'
+        ├── CardSummary
+        ├── AccountSavedCardExpiry
+        └── AccountSavedCardRemove ← provides 'account-saved-card-remove'
             └── AlertDialogRoot
                 ├── AccountSavedCardRemoveTrigger
                 └── AlertDialogPortal > AlertDialogBackdrop + AlertDialogViewport > AlertDialogPopup
@@ -51,8 +51,6 @@ AccountSavedCardsRoot             ← requires 'session'; provides 'account-save
                     └── AccountSavedCardRemoveConfirm
 ```
 
-`AccountSavedCardRemove` with no children renders the prompt shown under it.
-
 The Root renders nothing unless the session is `loggedIn`, and no chrome: no navigation, no page title, no landmark. It derives one state and exposes it on `data-fs-account-saved-cards-state`:
 
 | State | When | Renders |
@@ -73,7 +71,7 @@ The heading and the removal feedback render in every state. Every part except th
 
 Reads the card ids (`customerSavedCards`, reactive) and publishes the section state. No schema props.
 
-It also holds the section's removal: which card is being removed (one at a time) and how the last removal ended. It declares `actions: { savedCard: ['remove'] }`, so every remove control inside reaches the action, including the one a bare Item renders.
+It also holds the section's removal: which card is being removed (one at a time) and how the last removal ended. It declares `actions: { savedCard: ['remove'] }`, so every remove control inside reaches the action.
 
 ### AccountSavedCardsHeading
 
@@ -103,9 +101,9 @@ A `<ul>` repeating its child once per card.
 
 ### AccountSavedCardItem
 
-A `<li>` that provides its card to the CardSummary parts, `AccountSavedCardExpiry`, and `AccountSavedCardRemove`. With no children it renders `CardSummary`'s default (mark, network name, mask, last four digits), then `AccountSavedCardExpiry`, then `AccountSavedCardRemove`. It shows no label: the account's read does not return one.
+A `<li>` that provides its card to the CardSummary parts, `AccountSavedCardExpiry`, and `AccountSavedCardRemove`. It renders only its children; with none, the row is empty. It shows no label: the account's read does not return one.
 
-An expired card's row carries `data-fs-account-saved-card-expired`, and an unusable one's `data-fs-account-saved-card-unusable`, so a swatch can dim it. A working card's row carries neither. While its card is being removed, the row carries `data-fs-account-saved-card-removing`. Compose the three parts as children to rearrange the row or to reword it from the CMS. Leave `AccountSavedCardRemove` out only for a read-only list.
+An expired card's row carries `data-fs-account-saved-card-expired`, and an unusable one's `data-fs-account-saved-card-unusable`, so a swatch can dim it. A working card's row carries neither. While its card is being removed, the row carries `data-fs-account-saved-card-removing`. Compose `CardSummary`, `AccountSavedCardExpiry` and `AccountSavedCardRemove` as children, in the order the row needs. Leave `AccountSavedCardRemove` out only for a read-only list.
 
 ### AccountSavedCardExpiry
 
@@ -123,7 +121,7 @@ The label is in `data-fs-account-saved-card-expiry-label`, the `MM/YY` date in `
 
 ### AccountSavedCardRemove
 
-The controller for one row's removal prompt. It owns the prompt's open state and passes it to its single `AlertDialogRoot` child; the schema never sets `open`. With no children it renders the default prompt. No schema props.
+The controller for one row's removal prompt. It owns the prompt's open state and passes it to its single `AlertDialogRoot` child; the schema never sets `open`. With no children it renders nothing. No schema props.
 
 Opening the prompt dispatches nothing. Confirm dispatches `savedCard.remove` with the row's card id. The prompt then stays open until the server answers, and Escape and Cancel cannot close it meanwhile. On success the row leaves the list, and the prompt goes with it. On failure the prompt closes, focus returns to the trigger, and the row stays. An expired or unusable card is removed like any other.
 
@@ -133,7 +131,7 @@ The row's control that opens the prompt. Its visible text is short ("Remove"); a
 
 ### AccountSavedCardRemoveTitle, AccountSavedCardRemoveDescription
 
-The prompt's title and accessible description. With no children, the description renders the card's `CardSummary` before its text, so the prompt names the card it removes.
+The prompt's title and accessible description. With no children, the description renders the card's `CardSummary` before its text, so the prompt names the card it removes; that `CardSummary` reads the description's `cardEndingIn` message as its `endingIn`.
 
 ### AccountSavedCardRemoveCancel
 
@@ -158,23 +156,26 @@ The status region stays mounted so screen readers announce it. No message disapp
 
 ## Text
 
-Every text resolves in this order: `children`, then the part's CMS entry (`$content`, a blank field counts as unset), then the catalog message in the store's locale.
+Every text is `children` or else the part's own message field (`$content`). A missing message, absent or blank, renders empty and logs an error; no part falls back to other text.
 
-| Part | CMS fields | Catalog ids |
-|---|---|---|
-| `AccountSavedCardsHeading` | `text` | `fs/saved-cards.heading` |
-| `AccountSavedCardsEmpty` | `text` | `fs/saved-cards.empty` |
-| `AccountSavedCardsLoading` | `text` | `fs/saved-cards.loading` |
-| `AccountSavedCardsError` | `text`, `sessionExpiredText`, `signInLabel` | `fs/saved-cards.load-failed`, `fs/saved-cards.session-expired`, `fs/saved-cards.sign-in` |
-| `AccountSavedCardExpiry` | `expiresLabel`, `expiredLabel`, `expiredText`, `unusableText` | `fs/saved-cards.expires`, `fs/saved-cards.expired`, `fs/saved-cards.expired-no-date`, `fs/saved-cards.unusable` |
-| `AccountSavedCardRemoveTrigger` | `text` | `fs/saved-cards.remove.trigger` |
-| `AccountSavedCardRemoveTitle` | `text` | `fs/saved-cards.remove.title` |
-| `AccountSavedCardRemoveDescription` | `text` | `fs/saved-cards.remove.description` |
-| `AccountSavedCardRemoveCancel` | `text` | `fs/saved-cards.remove.cancel` |
-| `AccountSavedCardRemoveConfirm` | `text`, `pendingText` | `fs/saved-cards.remove.confirm`, `fs/saved-cards.remove.pending` |
-| `AccountSavedCardsRemoveFeedback` | `successText`, `failureText`, `sessionExpiredText`, `signInLabel` | `fs/saved-cards.remove.success`, `fs/saved-cards.remove.failed`, `fs/saved-cards.session-expired`, `fs/saved-cards.sign-in` |
-
-`AccountSavedCardExpiry` and `AccountSavedCardsRemoveFeedback` take no children. `expiresLabel` and `expiredLabel` precede the date, which the component always places; `expiredText` and `unusableText` stand alone. The trigger's hidden card name follows its text whatever the source. Children on the Confirm replace only its idle label. Only a part placed in the schema reads its CMS entry: the expiry line and the prompt an Item renders by default always show the catalog wording.
+| Part | Message fields |
+|---|---|
+| `AccountSavedCardsHeading` | `text` |
+| `AccountSavedCardsEmpty` | `text` |
+| `AccountSavedCardsLoading` | `text` |
+| `AccountSavedCardsError` | `text`, `sessionExpiredText`, `signInLabel` |
+| `AccountSavedCardExpiry` | `expiresLabel`, `expiredLabel`, `expiredText`, `unusableText` |
+| `CardSummary` | `endingIn` (`lastDigits`) |
+| `AccountSavedCardRemoveTrigger` | `text`, `cardEndingIn` (`lastDigits`) |
+| `AccountSavedCardRemoveTitle` | `text` |
+| `AccountSavedCardRemoveDescription` | `text`, `cardEndingIn` (`lastDigits`) |
+| `AccountSavedCardRemoveCancel` | `text` |
+| `AccountSavedCardRemoveConfirm` | `text`, `pendingText` |
+| `AccountSavedCardsRemoveFeedback` | `successText`, `failureText`, `sessionExpiredText`, `signInLabel` |
+
+Every field is an ICU message (`format: 'icu-message'`). The trigger's hidden card name is the card's name followed by its `cardEndingIn` message.
+
+`AccountSavedCardExpiry` and `AccountSavedCardsRemoveFeedback` take no children. `expiresLabel` and `expiredLabel` precede the date, which the component always places; `expiredText` and `unusableText` stand alone. The trigger's hidden card name follows its text whatever the source. Children on the Confirm replace only its idle label. Only a part placed in the schema has `$content`, so the Item and `AccountSavedCardRemove` have no default parts. The `CardSummary` that `AccountSavedCardRemoveDescription` renders with no children is the exception: the description passes it its own `cardEndingIn` message.
 
 ## Canonical schema example
 
@@ -196,8 +197,7 @@ Every text resolves in this order: `children`, then the part's CMS entry (`$cont
   "saved-cards-loading": { "type": "AccountSavedCardsLoading" },
   "saved-cards-error": { "type": "AccountSavedCardsError" },
   "saved-cards-empty": { "type": "AccountSavedCardsEmpty" },
-  "saved-cards-list": { "type": "AccountSavedCardsList", "children": ["saved-card-item"] },
-  "saved-card-item": { "type": "AccountSavedCardItem" }
+  "saved-cards-list": { "type": "AccountSavedCardsList", "children": ["saved-card-item"] }
 }
 ```
 
@@ -209,7 +209,7 @@ Nested inside another account page, with a lower heading:
 }
 ```
 
-With the row composed, so the expiry line and the removal prompt can be reworded from the CMS:
+The row, composed part by part, since the Item and `AccountSavedCardRemove` render only their children:
 
 ```json
 {
@@ -251,13 +251,14 @@ With the row composed, so the expiry line and the removal prompt can be reworded
 
 - **`AccountSavedCards`, `SavedCardsList`, `MyCards`.** The Root is `AccountSavedCardsRoot`; the list is `AccountSavedCardsList`.
 - **Using `SavedCards` or `SavedCardOption` in the account.** Those are the checkout's cart-scoped picker and need a payment section.
+- **Using `AccountSavedCardRemove` or its parts in the checkout's saved-card list.** They need `AccountSavedCardsRoot` and read the `CustomerSavedCard` entity, which a checkout row is not. The checkout removes an expired card with `SavedCardRemove` inside `SavedCardOption` (see [[saved-cards]]), which calls the same `savedCard.remove` action with the account-side id.
 - **Placing `AccountSavedCardItem` directly in the Root.** It must be inside `AccountSavedCardsList`.
 - **Composing `AccountSavedCardsEmpty` as the only state part.** Compose Loading and Error too, or a slow or failed read shows nothing under the heading.
 - **Setting `as: "h1"`.** Not accepted; the page title belongs to the page shell.
-- **Passing `text` as a schema prop.** Text comes from children, the CMS entry, or the catalog.
+- **Leaving a message field blank.** Nothing falls back: the part renders that text empty and logs an error.
 - **Placing the Root outside the `my-account` layout.** It requires `session`; without a `SessionRoot` the build fails.
 - **Giving the Item custom children without `AccountSavedCardExpiry`.** The row then hides when the card expires and whether it can be used.
-- **Expecting CMS wording on an Item with no children.** Its default expiry line and removal prompt are not in the schema, so they read only the catalog; place `AccountSavedCardExpiry` and the `AccountSavedCardRemove` composition explicitly.
+- **Leaving an Item or `AccountSavedCardRemove` with no children.** Neither has a default: the row renders empty and the prompt never appears. Place `CardSummary`, `AccountSavedCardExpiry` and the `AccountSavedCardRemove` composition explicitly.
 - **Giving the Item custom children without `AccountSavedCardRemove`.** The shopper can no longer remove the card. Do it only for a read-only list.
 - **Leaving out `AccountSavedCardsRemoveFeedback`.** A removal then ends with no message: a success only drops the row, and a failure says nothing.
 - **Placing the feedback inside the Item.** A removed card's row unmounts, taking the message with it.
@@ -273,24 +274,28 @@ With the row composed, so the expiry line and the removal prompt can be reworded
 | `AccountSavedCardsRoot` | Section spacing | `flex flex-col gap-[16px]` |
 | `AccountSavedCardsHeading` | Heading typography | `text-[20px] font-semibold text-[#1F1F1F]` |
 | `AccountSavedCardsList` | Row stack | `flex flex-col gap-[8px]` |
-| `AccountSavedCardItem` | Row box; dim expired and unusable rows | `rounded-[8px] border border-[#E5E5E5] p-[12px] data-[fs-account-saved-card-expired]:opacity-60 data-[fs-account-saved-card-unusable]:opacity-60` |
-| `AccountSavedCardExpiry` | Line typography; color by state | `mt-[4px] text-[13px] text-[#6B6B6B] data-[fs-account-saved-card-expiry-status=expired]:text-[#B42318] data-[fs-account-saved-card-expiry-status=unusable]:text-[#B42318]` |
-| `AccountSavedCardsEmpty` | Statement typography | `text-[14px] text-[#6B6B6B]` |
+| `AccountSavedCardItem` | Row box; dim expired and unusable rows | `rounded-[8px] border border-[var(--color-border)] p-[12px] data-[fs-account-saved-card-expired]:opacity-60 data-[fs-account-saved-card-unusable]:opacity-60` |
+| `AccountSavedCardExpiry` | Line typography; color by state | `mt-[4px] text-[13px] text-[var(--color-text-muted)] data-[fs-account-saved-card-expiry-status=expired]:text-[var(--color-feedback-danger)] data-[fs-account-saved-card-expiry-status=unusable]:text-[var(--color-feedback-danger)]` |
+| `AccountSavedCardsEmpty` | Statement typography | `text-[14px] text-[var(--color-text-muted)]` |
 | `AccountSavedCardsLoading` | Placeholder stack; rows via `[&_[data-fs-account-saved-cards-loading-row]]` | `flex flex-col gap-[8px] [&_[data-fs-account-saved-cards-loading-row]]:h-[48px] [&_[data-fs-account-saved-cards-loading-row]]:rounded-[8px] [&_[data-fs-account-saved-cards-loading-row]]:bg-[#F0F0F0]` |
-| `AccountSavedCardsError` | Alert box and link | `rounded-[8px] bg-[#FDECEC] p-[12px] text-[14px] text-[#B42318] [&_a]:underline` |
+| `AccountSavedCardsError` | Alert box and link | `rounded-[8px] bg-[#FDECEC] p-[12px] text-[14px] text-[var(--color-feedback-danger)] [&_a]:underline` |
 | `AccountSavedCardItem` (removing) | Fade the row while it is removed | `data-[fs-account-saved-card-removing]:opacity-60` |
-| `AccountSavedCardRemoveTrigger` | Link-like control | `mt-[8px] text-[13px] text-[#B42318] underline disabled:opacity-50` |
+| `AccountSavedCardRemoveTrigger` | Link-like control | `mt-[8px] text-[13px] text-[var(--color-feedback-danger)] underline disabled:opacity-50` |
 | `AlertDialogPopup` | Prompt box (style the AlertDialog parts directly) | `w-full max-w-[420px] rounded-[12px] bg-white p-[24px] shadow-xl` |
-| `AccountSavedCardRemoveConfirm` | Destructive button; dim while pending | `rounded-[6px] bg-[#B42318] px-[16px] py-[8px] text-white aria-disabled:opacity-70` |
-| `AccountSavedCardsRemoveFeedback` | Message typography; alert color | `text-[14px] [&_[role=alert]]:text-[#B42318] [&_a]:underline` |
+| `AccountSavedCardRemoveConfirm` | Destructive button; dim while pending | `rounded-[6px] bg-[var(--color-feedback-danger)] px-[16px] py-[8px] text-white aria-disabled:opacity-70` |
+| `AccountSavedCardsRemoveFeedback` | Message typography; alert color | `text-[14px] [&_[role=alert]]:text-[var(--color-feedback-danger)] [&_a]:underline` |
 
 ```json
 {
   "saved-cards": { "type": "AccountSavedCardsRoot", "style": ["flex", "flex-col", "gap-[16px]"] },
-  "saved-card-item": { "type": "AccountSavedCardItem", "style": ["rounded-[8px]", "border", "border-[#E5E5E5]", "p-[12px]"] }
+  "saved-card-item": { "type": "AccountSavedCardItem", "style": ["rounded-[8px]", "border", "border-[var(--color-border)]", "p-[12px]"] }
 }
 ```
 
+The role colors above are the foundation's `visualIdentity` roles (`--color-feedback-danger`), 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-text-muted": "#6B6B6B"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/alert-dialog.md

@@ -185,7 +185,7 @@ A delete-address confirmation. The confirm `Button` is inert here: in a store, t
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `AlertDialogTrigger` | The button that opens the prompt | `px-[16px] py-[8px] text-[14px] font-medium text-[#B42318] border border-[#FDA29B] rounded-[6px]` |
+| `AlertDialogTrigger` | The button that opens the prompt | `px-[16px] py-[8px] text-[14px] font-medium text-[var(--color-feedback-danger)] border border-[#FDA29B] rounded-[6px]` |
 | `AlertDialogBackdrop` | The dimmed layer over the page | `fixed inset-0 bg-black/40` |
 | `AlertDialogViewport` | Fixed positioning and centering of the popup | `fixed inset-0 flex items-center justify-center p-[16px]` |
 | `AlertDialogPopup` | The card: layout, background, radius, shadow, and its enter and exit | `flex flex-col gap-[8px] w-full max-w-[448px] p-[24px] bg-white rounded-[12px] shadow-xl data-[starting-style]:opacity-0 data-[ending-style]:opacity-0` |
@@ -195,6 +195,8 @@ A delete-address confirmation. The confirm `Button` is inert here: in a store, t
 
 `AlertDialogRoot` and `AlertDialogPortal` have no styling surface. Base UI sets `data-open`, `data-closed`, `data-starting-style`, and `data-ending-style` on the popup and the backdrop, so enter and exit animations key on those attributes.
 
+The role colors above are the foundation's `visualIdentity` roles (`--color-feedback-danger`), so they follow the store when it changes them.
+
 ---
 
 ## Related

package/dist/docs/avatar.md

@@ -77,7 +77,7 @@ The fallback shows whenever there is no image, the image is still loading, or it
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `Avatar` | `data-fs-avatar` is the circle: size, shape, background, and the initials' type | `inline-flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-full bg-[#E5E7EB] text-[14px] font-medium` |
+| `Avatar` | `data-fs-avatar` is the circle: size, shape, background, and the initials' type | `inline-flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-full bg-[var(--color-surface-strong)] text-[14px] font-medium` |
 | Image | `data-fs-avatar-image` is the `<img>` once loaded | `size-full object-cover` |
 | Initials | `data-fs-avatar-fallback` is the initials span | `uppercase` |
 
@@ -88,12 +88,14 @@ The fallback shows whenever there is no image, the image is still loading, or it
     "props": { "name": "Jane Doe", "alt": "Jane Doe" },
     "style": [
       "inline-flex", "size-10", "shrink-0", "items-center", "justify-center", "overflow-hidden",
-      "rounded-full", "bg-[#E5E7EB]", "text-[14px]", "font-medium", "[&_img]:size-full", "[&_img]:object-cover"
+      "rounded-full", "bg-[var(--color-surface-strong)]", "text-[14px]", "font-medium", "[&_img]:size-full", "[&_img]:object-cover"
     ]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-surface-strong": "#E5E7EB"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/billing-address.md

@@ -90,27 +90,37 @@ a form the shopper cannot see.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `sameAsDeliveryLabel` | string | `"Billing address same as delivery address"` | The toggle's own label text. |
-| `defaultCountry` | string | `"BRA"` | Initial country selected when the custom form first mounts. |
-| `countryLabel` | string | `"Country"` | Label for the country selector inside the custom form. |
-| `recipientNameLabel` | string | `"Recipient's name"` | Label for the recipient-name descriptor field. Not rendered by the custom-address form today — the write contract has no matching input slot — kept for parity with the other seven field labels. |
-| `streetLabel` | string | `"Street"` | Label for the street descriptor field. |
-| `numberLabel` | string | `"Number"` | Label for the street-number descriptor field. |
-| `complementLabel` | string | `"Complement (optional)"` | Label for the complement descriptor field. Its "(optional)" suffix is the only signal that the field is not required — the actual `required` attribute is driven independently, so authoring this without the suffix loses the visual cue, not the behavior. |
-| `neighborhoodLabel` | string | `"Neighborhood"` | Label for the neighborhood descriptor field. Unused when the active country's descriptor has no `neighborhood` field (e.g. USA). |
-| `cityLabel` | string | `"City"` | Label for the city descriptor field. |
-| `stateLabel` | string | `"State"` | Label for the state descriptor field. |
-| `postalCodeLabel` | string | `"Postal code"` | Label for the postal-code descriptor field. |
-| `submitLabel` | string | `"Save billing address"` | Label for the button that persists a custom address. |
-| `submitPendingLabel` | string | `"Saving..."` | Submit button's label while the write is in flight. |
-| `requiredNoticeLabel` | string | `"This payment method requires a billing address."` | Shown when the selected method's validator marks a billing address required. |
-| `unsavedAddressNoticeLabel` | string | `"No billing address has been saved yet — the delivery address will be used unless you save one below."` | Shown, `role="status"`, while the custom-address form is open and no address has been persisted yet. |
-| `billingMatchNoticeLabel` | string | `"Your billing address must match the one on your card or bank statement, or your bank may decline the order."` | Always-on billing-match disclaimer. Gated only by this prop and `billingMatchNoticeVisible` — unlike the two notices above, it never changes with the toggle, the form, `billingAddressRequired`, or a saved address. |
-| `billingMatchNoticeVisible` | boolean | `true` | Switches the billing-match disclaimer above on or off. A blank `billingMatchNoticeLabel` also renders nothing, even while this is `true` — the two rules never combine into an empty element. |
-| `fieldRequiredMessage` | string | `"This field is required."` | Shown as an inline field error under a required, blank address field once it has been touched (T38) — see Accessibility Contract below. One prop, not one per field: every rendered field but `complement` shares the same rule. An authored empty or whitespace-only string falls back to this default. |
-| `postalCodeInvalidMessage` | string | `"Enter a valid postal code."` | Shown as an inline field error under a touched, non-blank postal code that does not match the selected country's format (the descriptor's `rule.pattern`, the same one the delivery form enforces). Only the postal code reads this prop; the English default matches every other default on this form, so an author localises it with the rest. A blank postal code reads `fieldRequiredMessage` instead, never this. The message never contains the typed value. An authored empty or whitespace-only string falls back to this default. |
+| `defaultCountry` | string | `"BRA"` | Initial country selected when the custom form first mounts: `BRA`, `USA`, `CAN` or `MEX`. The store authors it; the form does not follow the store's own country. A code with no descriptor falls back to the first available country (`BRA`); `CAN` and `MEX` are kept while their descriptor is still loading, and the form shows the country and no fields until it arrives. |
+| `billingMatchNoticeVisible` | boolean | `true` | Switches the billing-match disclaimer on or off. A blank `billingMatchNoticeLabel` message also renders nothing, even while this is `true` — the two rules never combine into an empty element. |
 | `disabled` | boolean | `false` | Disables the toggle, every form field, the country selector, and the submit button. |
 
+**Content (`billing-address`):** every word of the form is a message field the store authors in `$content`; a missing or blank one renders empty and logs `message.missing`. Country names in the selector are not copy: they come from `Intl.DisplayNames` in the store locale ("Brazil" in `en-US`, "Brasil" in `pt-BR`).
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `sameAsDeliveryLabel` | `Billing address same as delivery address` | The toggle's own label text. |
+| `countryLabel` | `Country` | Label for the country selector inside the custom form. |
+| `recipientNameLabel` | `Recipient's name` | Label for the recipient-name descriptor field. Not rendered by the custom-address form today — the write contract has no matching input slot — kept for parity with the other seven field labels. |
+| `streetLabel` | `Street` | Label for the street descriptor field. |
+| `numberLabel` | `Number` | Label for the street-number descriptor field. |
+| `complementLabel` | `Complement (optional)` | Label for the complement descriptor field. Its "(optional)" suffix is the only signal that the field is not required — the actual `required` attribute is driven independently, so authoring this without the suffix loses the visual cue, not the behavior. |
+| `neighborhoodLabel` | `Neighborhood` | Label for the neighborhood descriptor field. Unused when the active country's descriptor has no `neighborhood` field (e.g. USA or Canada). |
+| `cityLabel` | `City` | Label for the city descriptor field. |
+| `stateLabel` | `State` | Label for the state descriptor field. |
+| `postalCodeLabel` | `Postal code` | Label for the postal-code descriptor field. |
+| `submitLabel` | `Save billing address` | Label for the button that persists a custom address. |
+| `submitPendingLabel` | `Saving...` | Submit button's label while the write is in flight. |
+| `requiredNoticeLabel` | `This payment method requires a billing address.` | Shown when the selected method's validator marks a billing address required. |
+| `unsavedAddressNoticeLabel` | `No billing address has been saved yet — the delivery address will be used unless you save one below.` | Shown, `role="status"`, while the custom-address form is open and no address has been persisted yet. |
+| `billingMatchNoticeLabel` | `Your billing address must match the one on your card or bank statement, or your bank may decline the order.` | Always-on billing-match disclaimer. Gated only by this message and `billingMatchNoticeVisible` — unlike the two notices above, it never changes with the toggle, the form, `billingAddressRequired`, or a saved address. |
+| `fieldRequiredMessage` | `This field is required.` | Shown as an inline field error under a required, blank address field once it has been touched (T38) — see Accessibility Contract below. One field, not one per address field: every rendered field but `complement` shares the same rule. |
+| `postalCodeInvalidMessage` | `Enter a valid postal code.` | Shown as an inline field error under a touched, non-blank postal code that does not match the selected country's format (the descriptor's `rule.pattern`, the same one the delivery form enforces). Only the postal code reads it. A blank postal code reads `fieldRequiredMessage` instead, never this. The message never contains the typed value. |
+| `missingFieldsMessage` | `Fill in the postal code and the country of your billing address.` | Inline alert when the server refuses the address without a postal code or country (`MISSING_BILLING_ADDRESS_FIELDS`). |
+| `invalidCountryMessage` | `Choose a valid country for your billing address.` | Inline alert when the server refuses the country (`INVALID_COUNTRY_CODE`). |
+| `genericErrorMessage` | `Unable to save your billing address. Please try again.` | Inline alert for `MISSING_CART_CONTEXT`, `CART_NOT_FOUND` and `NETWORK_ERROR`. A code the package does not know (one a newer server added) shows it too and logs `message.unknown-code`. |
+
+A field a library-backed descriptor adds with no label field here shows its canonical field name.
+
 **Data:** declares no fragment and no `fetchStrategy`, so it fetches no shopper data. It reads only the
 payment context (`requiresContext: 'payment'`): the selected method's validator and the shared payment
 draft. **Nothing prefills the custom-address form** — there is no server field that echoes back an
@@ -147,7 +157,7 @@ the blocking themselves; both stay exactly as advisory as described above.
 **A third notice, `billingMatchNoticeLabel`, is configuration-driven, not state-driven like the two
 above.** The required-note and the unsaved-notice each appear and disappear by runtime state (the
 selected method's validator; the form being open with nothing saved yet). This one does not: its
-presence is a pure function of `billingMatchNoticeLabel` and `billingMatchNoticeVisible` alone, and it
+presence is a pure function of the `billingMatchNoticeLabel` message and `billingMatchNoticeVisible` alone, and it
 renders before the toggle field on every render — including the default state, where "same as delivery"
 stays checked and the shopper never opens the form. It never reacts to the toggle, to
 `billingAddressRequired`, to a saved address, or to order placement; a merchant switches it off with
@@ -158,10 +168,49 @@ static disclaimer, not a live region reacting to an event.
 **Focus on refusal:** while the custom-address form is open, it registers itself so that when `PlaceOrder` refuses an order because the address was never saved, keyboard focus moves into the form: to the first rendered required field that is still blank; if none is blank, to the first rendered field whose value fails its country's format (a postal code `123` for BRA); and only when every field is filled and well-formed, to the submit control. The field the focus lands on, blank or malformed, is marked touched, so its message (`required` for a blank field, `format` for a malformed one) shows with the focus and no blur is needed. The country selector is never the target, and a disabled field or a disabled submit control (for example while saving) takes no focus. The reason stays in `PlaceOrder`'s existing alert and this component's unsaved-address notice. Focus moves only on the refused click.
 
 **Country adaptivity is entirely data-driven**, reusing the same country descriptors the delivery
-address step uses: Brazil shows a neighborhood/bairro field, the United States does not, and adding a
-new country anywhere in this codebase is a data-only change that this component picks up automatically
-— never a code change here. The postal code's format is the same data: the descriptor's `rule.pattern`
-gates the submit button and the field error, so a country's format is defined once for both forms.
+address step uses: Brazil shows a neighborhood/bairro field, the United States and Canada do not, Mexico
+shows a neighborhood and a number, and adding a new country anywhere in this codebase is a data-only
+change that this component picks up automatically — never a code change here. Brazil and the United
+States are written in the descriptor table; Canada and Mexico are read from `@vtex/country-forms` when
+the form mounts, so the selector lists them (Brazil, United States, Canada, Mexico) once they have
+loaded. The postal code's format is the same data: the descriptor's `rule` (a pattern for Brazil and the
+United States, the library's own verdict for Canada and Mexico) gates the submit button and the field
+error, so a country's format is defined once for both forms. A Canadian or Mexican postal code is
+submitted in the library's stored form (`K1A 0B1`), not as typed.
+
+### Countries and postal codes
+
+The selector lists the same countries for every store. It is not filtered by the countries the store ships
+to, because a card's billing country does not depend on where the store delivers.
+
+Canada and Mexico take their field set and required flags from `@vtex/country-forms` (the pinned 1.14.0),
+and the repository holds no regular expression, list or mask for either. Only the English copy is written
+in `packages/faststore/src/matter/shipping-address/library-country-descriptors.ts`. Canada has no number
+or neighborhood field, so a Canadian shopper types the house number inside the street. Mexico adds both,
+and the neighborhood is required: every rendered field except the complement is, so a Mexican shopper
+without one cannot save. The state is free text for both countries, although the library lists 13
+provinces and 32 states.
+
+The postal code rules are the library's. Canada refuses a first letter of D, F, I, O, Q, U or W and
+ignores case and the space, but accepts a Z in first position and D, F, I, O, Q or U later in the code, so
+it is looser than Canada Post's alphabet. Mexico takes five digits and refuses a value below `01000`.
+Both judge the trimmed value, so ` 06600 ` passes. The Brazilian and US patterns test the raw value, so a
+leading or trailing space fails them. The US pattern accepts a ZIP+4 with or without the hyphen
+(`021011234`), and a Brazilian or US postal code is submitted exactly as typed.
+
+Other countries need more than a data entry. The library covers `ARG`, `CHL`, `COL`, `ECU` and `PER` with a
+select whose options depend on another field (a city or neighborhood chosen by state), which a descriptor
+cannot express. A country with a flat field list joins by adding its ISO code to `LIBRARY_COUNTRIES` with a
+copy row there.
+
+If a country's chunk fails to load, it is left out of the selector, the form keeps working with the others,
+nothing is shown about it, and the next mount retries it.
+
+The server does not back the client rule. `paymentBillingAddressUpdate` checks only that `postalCode` and
+`country` are present and that the country is three capital letters, so this verdict is the only postal
+code guard for billing. Two answers were not measured on a live Canadian or Mexican account: which `state`
+value the Checkout expects (`ON` or `Ontario`, `CMX` or `Ciudad de México`), and whether a card issuer's
+address check wants the Canadian postal code with or without the space.
 
 ---
 
@@ -175,7 +224,25 @@ gates the submit button and the field error, so a country's format is defined on
   },
   "billing-address": {
     "type": "BillingAddress",
-    "props": { "sameAsDeliveryLabel": "Billing address same as delivery address" },
+    "props": {
+      "sameAsDeliveryLabel": "Billing address same as delivery address",
+      "countryLabel": "Country",
+      "streetLabel": "Street",
+      "numberLabel": "Number",
+      "complementLabel": "Complement (optional)",
+      "neighborhoodLabel": "Neighborhood",
+      "cityLabel": "City",
+      "stateLabel": "State",
+      "postalCodeLabel": "Postal code",
+      "recipientNameLabel": "Recipient's name",
+      "submitLabel": "Save billing address",
+      "submitPendingLabel": "Saving...",
+      "requiredNoticeLabel": "This payment method requires a billing address.",
+      "unsavedAddressNoticeLabel": "No billing address has been saved yet — the delivery address will be used unless you save one below.",
+      "billingMatchNoticeLabel": "Your billing address must match the one on your card or bank statement, or your bank may decline the order.",
+      "fieldRequiredMessage": "This field is required.",
+      "postalCodeInvalidMessage": "Enter a valid postal code."
+    },
     "style": ["flex", "flex-col", "gap-3"]
   }
 }
@@ -229,13 +296,15 @@ while the box is unchecked, and an optional inline error.
 | Same as delivery (`data-fs-billing-address-same-as-delivery`) | Present on the root while the box is checked, absent while it is unchecked. It sits on the node the style array styles, so target it as `data-[fs-billing-address-same-as-delivery]:…`, never with a descendant variant | `data-[fs-billing-address-same-as-delivery]:gap-[8px]` |
 | Panel (`data-fs-billing-address-panel`) | Always present, right after the toggle field, and the toggle's `aria-controls` target. `hidden` and empty while the box is checked; holds the custom-form wrapper while unchecked. Never give it a display utility (`flex`, `grid`, `block`, …): one defeats `hidden` | none — style the form inside it |
 | Custom-form wrapper (`data-fs-billing-address-form`), inside the panel | Field grid | `grid grid-cols-2 gap-[8px]` |
-| Required-billing-address note (`data-fs-billing-address-required-note`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
-| Unsaved-address notice (`data-fs-billing-address-unsaved-notice`) | De-emphasized, non-error helper text | `text-[12px] text-[#666666]` |
-| Billing-match disclaimer (`data-fs-billing-address-match-notice`) | De-emphasized helper text, first child of the root | `text-[12px] text-[#666666]` |
-| Field error (`data-fs-field-error`) | Per-field validation message, shown once a field is touched: a blank required field, or a non-blank postal code that fails the country's format (T38); a refused submit that focuses the field touches it without a blur | `text-[12px] font-medium text-[#B00020]` |
-| Inline error (`data-fs-billing-address-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
+| Required-billing-address note (`data-fs-billing-address-required-note`) | De-emphasized helper text | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| Unsaved-address notice (`data-fs-billing-address-unsaved-notice`) | De-emphasized, non-error helper text | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| Billing-match disclaimer (`data-fs-billing-address-match-notice`) | De-emphasized helper text, first child of the root | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| Field error (`data-fs-field-error`) | Per-field validation message, shown once a field is touched: a blank required field, or a non-blank postal code that fails the country's format (T38); a refused submit that focuses the field touches it without a blur | `text-[12px] font-medium` |
+| Inline error (`data-fs-billing-address-error`) | Warning-toned alert text | `text-[12px] font-medium` |
 | Placing (`data-fs-billing-address-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from `data-fs-billing-address-pending`, which this component already emits for its own local submit 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

package/dist/docs/binding-switcher.md

@@ -41,8 +41,11 @@ Renders a host `div` (`data-fs-binding-switcher`). No fragment. Declares `action
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `bindings` | object | — | `foundation.json` `localization.bindings`, keyed by binding id. No library default. The store passes `$data.Global.localization.bindings`. |
-| `label` | string | `"Language"` | Accessible name, rendered as the select label. |
-| `notice` | string | `"This page isn't available in the selected language."` | Shown when the page loaded with `fs_notice=no-equivalent`. Inline `<output>` (implicit `status` role). |
+
+Copy comes from `$content` (content type `binding-switcher`):
+
+- **`label`:** the accessible name, rendered as the select label.
+- **`notice`:** shown when the page loaded with `fs_notice=no-equivalent`. Inline `<output>` (implicit `status` role).
 
 ---
 

package/dist/docs/buy-button.md

@@ -75,12 +75,9 @@ Root data provider. Declares the GraphQL fragment and exposes product/variant co
 
 ### BuyButtonButton
 
-The rendered button. Dispatches `$actions.cart.addItem(...)` on click.
+The rendered button. Dispatches `$actions.cart.addItem(...)` on click. No props.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `availableLabel` | string | `"Comprar"` | Label shown when the variant is available for sale |
-| `unavailableLabel` | string | `"Indisponivel"` | Label shown when the variant is not available |
+**Content model** (`buy-button-labels`): `availableLabel` (shown when the variant is available for sale) and `unavailableLabel` (shown when it is not), both ICU messages read only from `$content`. A missing message renders empty and logs `message.missing`. `children` replaces the label, and then no message is formatted.
 
 **Actions:** declares `actions: { cart: ['addItem'] }`; the compiler threads the `addItem` handler in via `$actions.cart`. Renders `null` when `BuyButtonRoot` has no valid variant data. Disabled (and `aria-busy`) while the add is in-flight (the button tracks its own pending state). Must be a descendant of `BuyButtonRoot`.
 
@@ -132,9 +129,9 @@ Fill each element's `style` array with Tailwind classes read off the image. Typi
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `BuyButtonRoot` | Layout wrapper only — it renders no box of its own | `block w-full mt-[8px]` |
-| `BuyButtonButton` | The CTA: full-width pill in the brand color, with hover and disabled states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[#C8102E] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer transition-colors hover:bg-[#A50D26] disabled:opacity-50 disabled:cursor-not-allowed` |
+| `BuyButtonButton` | The CTA: full-width pill in the brand color, with hover and disabled states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[var(--color-primary)] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer transition-colors hover:bg-[var(--color-primary-hover)] disabled:opacity-50 disabled:cursor-not-allowed` |
 
-Read the button's fill color straight off the image as an arbitrary hex (`bg-[#C8102E]`); derive the hover shade as a slightly darker value. Always include `disabled:` styling — the button auto-disables when the variant is unavailable. Do not invent a swatch or token for the brand color; inline hex only.
+The button's fill is the brand color, so write it as the role's variable (`bg-[var(--color-primary)]`), never as the hex read off the image. Its hover and active shades are slightly darker values that several elements of the page share, so declare them in the page or layout `theme` (`--color-primary-hover`, `--color-primary-active`). Always include `disabled:` styling — the button auto-disables when the variant is unavailable.
 
 Styled example:
 
@@ -148,11 +145,13 @@ Styled example:
   "buy-button-action": {
     "type": "BuyButtonButton",
     "props": { "availableLabel": "Comprar", "unavailableLabel": "Indisponível" },
-    "style": ["inline-flex", "items-center", "justify-center", "w-full", "h-[44px]", "px-[20px]", "bg-[#C8102E]", "text-white", "rounded-[4px]", "text-[14px]", "font-bold", "tracking-[0.06em]", "uppercase", "cursor-pointer", "transition-colors", "duration-150", "hover:bg-[#A50D26]", "active:bg-[#8A0B20]", "disabled:opacity-50", "disabled:cursor-not-allowed"]
+    "style": ["inline-flex", "items-center", "justify-center", "w-full", "h-[44px]", "px-[20px]", "bg-[var(--color-primary)]", "text-white", "rounded-[4px]", "text-[14px]", "font-bold", "tracking-[0.06em]", "uppercase", "cursor-pointer", "transition-colors", "duration-150", "hover:bg-[var(--color-primary-hover)]", "active:bg-[var(--color-primary-active)]", "disabled:opacity-50", "disabled:cursor-not-allowed"]
   }
 }
 ```
 
+The page or layout `theme` that declares the shades: `{"--color-primary-hover": "#A50D26", "--color-primary-active": "#8A0B20"}`.
+
 ---
 
 ## Related