@vtex/faststore 0.0.8 → 0.0.11

package/dist/docs/account-address-book.md

@@ -30,7 +30,7 @@ Use `AccountAddressBook` and `AccountAddressForm` (not `ShippingAddress` or `Bil
 ## When NOT to use
 
 - Changing the country of a saved address — an edit keeps its country.
-- Giving an address a name of its own — a saved address has no name field. The SDK's field model (`AccountFieldName`, `fs/address.field.name`) still lists `name`, so adding it later does not change the model, but no component renders or saves it.
+- Giving an address a name of its own — a saved address has no name field. The SDK's field model (`AccountFieldName`) still lists `name`, so adding it later does not change the model, but no component renders or saves it.
 - The address a shopper picks or types during checkout — use `ShippingAddress` / `BillingAddress`.
 - A single address summary with no saved list behind it — compose `AddressSummary` directly.
 - The signed-out prompt — compose `SignInForm` next to a `SessionGuard`. The root renders nothing for a shopper who is not logged in.
@@ -60,7 +60,7 @@ SessionRoot                                   (required ancestor; must resolve t
     ├── AccountAddressBookDeleteConfirm       (optional; the one alert dialog every delete trigger opens)
     ├── AccountAddressBookAddTrigger          (optional; opens the form in add mode; shown in every state)
     └── AccountAddressBookFormSlot            (or AccountAddressBookFormDialog; shows the form while one is open)
-        └── AccountAddressFormRoot            (the form; with no children it renders the parts below in this order)
+        └── AccountAddressFormRoot            (the form; renders only its children, composed in this order)
             ├── AddressCountryControl         (own data; the country list, or the country as text)
             ├── AccountAddressCountryNotice   (what a country change left behind)
             ├── AccountAddressFormRecipientName
@@ -88,7 +88,7 @@ The form opens where you place it. `AccountAddressBookFormSlot` shows it in plac
 
 Deleting needs two parts: an `AccountAddressBookDeleteTrigger` inside each entry, and one `AccountAddressBookDeleteConfirm` under the root. The confirmation is an alert dialog, so wherever you place it, it shows over the page.
 
-To let the shopper choose the country of a new address, compose `AddressCountryControl` explicitly under `AccountAddressFormRoot`, with `AccountAddressCountryNotice` right after it. The control reads where the store ships through its own fragment, and that fragment joins the page query only when the control is in the schema. In the root's default composition the control gets no list, so it shows the root's `defaultCountry` as text.
+To let the shopper choose the country of a new address, compose `AddressCountryControl` explicitly under `AccountAddressFormRoot`, with `AccountAddressCountryNotice` right after it. The control reads where the store ships through its own fragment, and that fragment joins the page query only when the control is in the schema.
 
 ---
 
@@ -112,7 +112,7 @@ To let the shopper choose the country of a new address, compose `AddressCountryC
 - **The notice says what stayed behind.** After a change, `AccountAddressCountryNotice` names the fields the new country left out, with the labels the old country showed, and says they come back on switching back. It is a polite live region that stays mounted, and it is empty when the change carried everything. It changes only with the next country change, never on typing or a blocked save.
 - **The whole address is checked on every save.** The server checks the whole record, so an untouched gap in a saved address blocks the save too. A saved address with gaps shows them when the form opens, without moving focus.
 - **A blocked save names the fields.** The form marks each field in error, moves focus to the first one in form order, keeps what was typed, and announces "Address not saved" and how many fields need attention through a polite status region that stays mounted.
-- **The server's refusal lands on the field it names.** Its message is never shown; the field shows the catalog message for its code (`This field is required.` or `Check this field.`). A refusal that names a field the form does not show, no field at all, or a country, shows an error about the whole form, so a save never fails silently. Each of `NOT_FOUND`, `UNAUTHORIZED`, `UNSUPPORTED_COUNTRY` (the store does not deliver to the country), and the rest has its own message.
+- **The server's refusal lands on the field it names.** Its message is never shown; the field shows its part's `requiredError` or `invalidError` message for the code. A refusal that names a field the form does not show, no field at all, or a country, shows an error about the whole form, so a save never fails silently. Each of `NOT_FOUND`, `UNAUTHORIZED`, `UNSUPPORTED_COUNTRY` (the store does not deliver to the country), and the rest has its own message.
 - **What is sent.** An add sends the country and every field on screen that has text; the values kept for another country are never sent. An edit sends the address id and only the fields that changed; a field the shopper cleared goes as an empty string, which erases it. An edit with no change closes without a call. A second submit while one is in flight does nothing.
 - **Only Save submits.** Enter in a text field does not save, so a shopper who presses it mid-address is not sent a half-typed one. Enter on the Save button still saves.
 - **On success.** A toast confirms, the form closes, and the list shows the result with no reload.
@@ -127,6 +127,8 @@ To let the shopper choose the country of a new address, compose `AddressCountryC
 
 ## Components
 
+Each part with copy reads it only from its own `$content`, whose fields are ICU messages; no part takes a copy prop. A missing message renders empty and logs an error. `AccountAddressFormRoot` has no default parts, since a part it rendered itself would have no `$content`: compose them.
+
 ### AccountAddressBookRoot
 
 No props beyond `className`. Fetches `customerAddressBook` (the address ids) with `fetchStrategy: 'reactive'`, requires `session`, provides `account-address-book`, and declares a skeleton.
@@ -145,39 +147,49 @@ No props beyond `className`. Renders one `<p>` per address line.
 
 ### AccountAddressBookLoading
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `message` | string | catalog copy | Loading message. A blank value falls back to the catalog. |
+Content type `account-address-book-loading`:
+
+| Content field | Description |
+|---|---|
+| message | Loading message |
 
 ### AccountAddressBookEmpty
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `message` | string | catalog copy | Empty message. A blank value falls back to the catalog. |
+Content type `account-address-book-empty`:
+
+| Content field | Description |
+|---|---|
+| message | Empty message |
 
 ### AccountAddressBookError
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `message` | string | catalog copy | Error message. A blank value falls back to the catalog. |
-| `retryLabel` | string | catalog copy | Retry button label. A blank value falls back to the catalog. |
+Content type `account-address-book-error`:
 
-### AccountAddressBookAddTrigger
+| Content field | Description |
+|---|---|
+| message | Error message |
+| retryLabel | Retry button label |
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | catalog copy | Button text. A blank value falls back to the catalog. |
+### AccountAddressBookAddTrigger
 
 A button that opens the form in add mode. It shows in every state of the book, the empty one too.
 
-### AccountAddressBookEditTrigger
+Content type `account-address-book-add-trigger`:
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | catalog copy | Visible text. A blank value falls back to the catalog. |
+| Content field | Description |
+|---|---|
+| label | Button text |
+
+### AccountAddressBookEditTrigger
 
 A button inside `AccountAddressBookItem` that opens the form in edit mode for that entry. Its accessible name is the visible text followed by the address's first line, so each button in a list is told apart.
 
+Content type `account-address-book-edit-trigger`:
+
+| Content field | Description |
+|---|---|
+| label | Visible text |
+
 ### AccountAddressBookFormSlot
 
 No props of its own; `className` and the other `div` attributes land on its element. Shows its children in place while a form is open, and nothing otherwise. Each open starts a new draft.
@@ -186,49 +198,70 @@ No props of its own; `className` and the other `div` attributes land on its elem
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `title` | string | catalog copy for the mode | Dialog title. A blank value falls back to the catalog. |
 | `className` | string | none | Goes on the dialog's popup. The dialog renders in a portal outside the page, so this is the element a store sizes and places. |
 
 Shows its children in a modal dialog while a form is open. Escape and the close button cancel the form.
 
-### AccountAddressBookDeleteTrigger
+Content type `account-address-book-form-dialog`:
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | catalog copy | Visible text. A blank value falls back to the catalog. |
+| Content field | Description |
+|---|---|
+| titleAdd | Title in add mode |
+| titleEdit | Title in edit mode |
+| closeLabel | Close button's accessible name |
+
+### AccountAddressBookDeleteTrigger
 
 A button inside `AccountAddressBookItem` that asks to delete that entry's address. It deletes nothing by itself. Its accessible name is the visible text followed by the address's first line, so each button in a list is told apart.
 
+Content type `account-address-book-delete-trigger`:
+
+| Content field | Description |
+|---|---|
+| label | Visible text |
+
 ### AccountAddressBookDeleteConfirm
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `title` | string | catalog copy | The question. |
-| `description` | string | catalog copy | What deleting means. The address's first line always shows before it. |
-| `cancelLabel` | string | catalog copy | The control that backs out. |
-| `confirmLabel` | string | catalog copy | The control that deletes. |
-| `deletedMessage` | string | catalog copy | Toast after the address is deleted. |
-| `failedMessage` | string | catalog copy | Shown in the dialog when the address was not deleted. |
-| `unauthorizedMessage` | string | catalog copy | Shown in the dialog when the session expired. |
 | `className` | string | none | Goes on the dialog's popup. The dialog renders in a portal outside the page, so this is the element a store sizes and places. |
 
 One per address book, under `AccountAddressBookRoot`. It opens for the entry whose trigger was activated, and it needs a `ToastProvider` ancestor.
 
+Content type `account-address-book-delete-confirm`:
+
+| Content field | Description |
+|---|---|
+| title | The question |
+| description | What deleting means. The address's first line always shows before it. |
+| cancelLabel | The control that backs out |
+| confirmLabel | The control that deletes |
+| deletedMessage | Toast after the address is deleted |
+| failedMessage | Shown when the address was not deleted |
+| unauthorizedMessage | Shown when the session expired |
+
 ### AccountAddressFormRoot
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `defaultCountry` | string | `BRA` | ISO 3166-1 alpha-3 code of the country a new address prefers: taken when the store ships there or its list is unknown. A blank value falls back to `BRA`. |
-| `addedMessage` | string | catalog copy | Toast after an address is added. |
-| `savedMessage` | string | catalog copy | Toast after an address is saved. |
-| `blockedMessage` | string | catalog copy | What the status region announces when a save is blocked. |
 | `returnHref` | link | `{ standard: 'address' }` | Where leaving the form goes on its own page: a page reference, or a site-relative string (an off-site string is refused). Ignored under an address book. |
 
-Requires `session`, provides `account-address-form`, and declares `actions: { address: ['create', 'update'] }`. Needs a `ToastProvider` ancestor. With no children it renders its parts in the default order.
+Requires `session`, provides `account-address-form`, and declares `actions: { address: ['create', 'update'] }`. Needs a `ToastProvider` ancestor. It renders only its children; with none, the form is empty.
 
 The address to edit comes from the book's open edit form, else from an `AccountAddressRecord` above it, else the form opens empty to add.
 
-It renders the shared `FormRoot` and registers itself as the form's only fieldset, so react-hook-form holds the draft. Each field part registers under the `accountAddress` namespace while it is on screen. The address rules still decide what is valid and what is sent: the root checks the draft with the country's rules on Save and never hands a rule to react-hook-form. The form particle's `FormClear`, `FormReset` and `FormError` are not part of this anatomy; `AccountAddressFormCancel` and `AccountAddressFormError` cover them.
+It renders the shared `FormRoot` and registers itself as the form's only fieldset, so react-hook-form holds the draft. Each field part registers under the `accountAddress` namespace while it is on screen. The address rules still decide what is valid and what is sent: the root checks the draft with the country's rules on Save and never hands a rule to react-hook-form. The form particle's `FormClear`, `FormReset` and `FormError` are not part of this anatomy; `AccountAddressFormCancel` and `AccountAddressFormError` cover them. A `FormError` composed anyway shows this form's own status message (`statusFields` or `statusFailed`) for a blocked or refused save, never the server's text.
+
+Content type `account-address-form`:
+
+| Content field | Description |
+|---|---|
+| addedMessage | Toast after an address is added |
+| savedMessage | Toast after an address is saved |
+| statusFilled | Announces the fields a postal code filled, a plural on `count` |
+| statusFields | Announces a save blocked by fields, a plural on `count` |
+| statusFailed | Announces a save that failed |
 
 ### AccountAddressRecord
 
@@ -238,81 +271,147 @@ An id that is not the shopper's and an id that never existed are the same respon
 
 ### AccountAddressRecordError
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `message` | string | catalog copy | Shown when the address could not be read. |
-| `retryLabel` | string | catalog copy | The retry control's text. Retry reloads the page. |
-
 Visible only when the read failed and no address resolved, as an alert. Must be inside `AccountAddressRecord`.
 
-### AddressCountryControl
+Content type `account-address-record-error`:
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | catalog copy | The list's label. A blank value falls back to the catalog. |
+| Content field | Description |
+|---|---|
+| message | Shown when the address could not be read |
+| retryLabel | The retry control's text. Retry reloads the page. |
+
+### AddressCountryControl
 
 Fetches `shippingCountries` (`countries` and `source`) with `fetchStrategy: 'reactive'`, requires `account-address-form`, and declares a skeleton. In add mode with two or more countries it renders a list; with one it renders nothing; in edit mode, or with no list, it renders the country as text.
 
+Content type `address-country-control`:
+
+| Content field | Description |
+|---|---|
+| label | The list's label |
+
 ### AccountAddressCountryNotice
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `message` | string | catalog copy | Replaces the whole sentence. Takes the ICU arguments `count`, `country`, `previous`, and `fields`. A blank or malformed value falls back to the catalog. |
+Requires `account-address-form`. An `<output aria-live="polite">` that stays mounted, empty until a country change leaves fields behind. Its `fields` argument lists the left-behind fields with the labels of `AccountAddressFormFields`' content; with no Fields part mounted it is empty.
 
-Requires `account-address-form`. An `<output aria-live="polite">` that stays mounted, empty until a country change leaves fields behind.
+Content type `account-address-country-notice`:
 
-### AccountAddressFormRecipientName and AccountAddressFormReference
+| Content field | Description |
+|---|---|
+| message | The sentence, with the `count`, `country`, `fields` and `previous` arguments |
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | catalog copy | Field label. A blank value falls back to the catalog. |
+### AccountAddressFormRecipientName and AccountAddressFormReference
 
 The recipient name is required for every country. The reference is optional.
 
+Content type `account-address-form-recipient-name` (AccountAddressFormRecipientName):
+
+| Content field | Description |
+|---|---|
+| label | Field label |
+| requiredError | Error when the field is empty |
+| invalidError | Error when the value is refused |
+| tooLongError | Error past the length limit, with the `maxLength` argument |
+
+Content type `account-address-form-reference` (AccountAddressFormReference):
+
+| Content field | Description |
+|---|---|
+| label | Field label |
+| requiredError | Error when the field is empty |
+| invalidError | Error when the value is refused |
+| tooLongError | Error past the length limit, with the `maxLength` argument |
+
 ### AccountAddressFormFields
 
 No props beyond `className`, which goes on every field's wrapper. One field per field the country asks for, in the country's order.
 
-### AccountAddressFormError
+Content type `account-address-form-fields`:
+
+| Content field | Description |
+|---|---|
+| cepLabel | Label of the `cep` field |
+| cityLabel | Label of the `city` field |
+| communeLabel | Label of the `commune` field |
+| complementLabel | Label of the `complement` field |
+| countyLabel | Label of the `county` field |
+| departmentLabel | Label of the `department` field |
+| districtLabel | Label of the `district` field |
+| municipalityLabel | Label of the `municipality` field |
+| neighborhoodLabel | Label of the `neighborhood` field |
+| numberLabel | Label of the `number` field |
+| postalCodeLabel | Label of the `postalCode` field |
+| postcodeLabel | Label of the `postcode` field |
+| provinceLabel | Label of the `province` field |
+| regionLabel | Label of the `region` field |
+| stateLabel | Label of the `state` field |
+| streetLabel | Label of the `street` field |
+| townLabel | Label of the `town` field |
+| postalCodePlaceholder | Postal code hint, with the `example` argument |
+| streetPlaceholder | Street hint |
+| cepError | Invalid CEP error, with the `example` argument |
+| postalCodeError | Invalid postal code error, with the `example` argument |
+| requiredError | Error when the field is empty |
+| invalidError | Error when the value is refused |
+| tooLongError | Error past the length limit, with the `maxLength` argument |
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `unrenderedFieldMessage` | string | catalog copy | A refusal on a field the form does not show. |
-| `notFoundMessage` | string | catalog copy | The address no longer exists. |
-| `unauthorizedMessage` | string | catalog copy | The session expired. |
-| `saveFailedMessage` | string | catalog copy | The save failed for any other reason. |
-| `rulesFailedMessage` | string | catalog copy | The country's rules did not load. |
-| `countrySwitchFailedMessage` | string | catalog copy | A country change could not load. |
-| `unsupportedCountryMessage` | string | catalog copy | The store does not deliver to the country. |
+### AccountAddressFormError
 
 An alert for the whole form. Renders nothing when there is no error.
 
-### AccountAddressFormSubmit and AccountAddressFormCancel
+Content type `account-address-form-error`:
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | catalog copy | Button text. A blank value falls back to the catalog. |
+| Content field | Description |
+|---|---|
+| unrenderedFieldMessage | A refusal on a field the form does not show |
+| notFoundMessage | The address no longer exists |
+| unauthorizedMessage | The session expired |
+| saveFailedMessage | The save failed for any other reason |
+| rulesFailedMessage | The country's rules did not load |
+| countrySwitchFailedMessage | A country change could not load |
+| unsupportedCountryMessage | The store does not deliver to the country |
+
+### AccountAddressFormSubmit and AccountAddressFormCancel
 
 Submit is disabled until the rules load, while a country change loads, and while a save is in flight, and is marked busy then. Cancel closes the form, or, on its own page, goes to the form root's `returnHref`. Cancel is disabled while a save is in flight, and under a book's `AccountAddressBookFormDialog` Escape and the close control wait for the save to settle, so a refusal is never lost.
 
+Content type `account-address-form-submit` (AccountAddressFormSubmit):
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
+Content type `account-address-form-cancel` (AccountAddressFormCancel):
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
 ### AccountAddressBookProfileNotice
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `href` | link | `{ standard: 'profile' }` | Where the link goes: a page reference, or a site-relative string. |
-| `message` | string | catalog copy | Notice text. |
-| `linkLabel` | string | catalog copy | Link label. |
 
 Fetches `customerProfile` with `fetchStrategy: 'reactive'` and requires `session`.
 
-### AccountAddressBookItemDeliverability
+Content type `account-address-book-profile-notice`:
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `message` | string | catalog copy | Marker text. A blank value falls back to the catalog. |
+| Content field | Description |
+|---|---|
+| message | Notice text |
+| linkLabel | Link label |
+
+### AccountAddressBookItemDeliverability
 
 Fetches `shippingCountries` with `fetchStrategy: 'reactive'` and requires `account-address-book-item`. Renders one `<p>` when it marks an address, and nothing otherwise.
 
+Content type `account-address-book-deliverability`:
+
+| Content field | Description |
+|---|---|
+| message | Marker text |
+
 ---
 
 ## Canonical schema example
@@ -335,7 +434,7 @@ Fetches `shippingCountries` with `fetchStrategy: 'reactive'` and requires `accou
 
 `address-item` appears once in the schema and renders once per saved address. Do not repeat it.
 
-With the form, the same book adds an add trigger, an edit trigger inside the item, and a slot holding the form root. A root with no children renders the default form:
+With the form, the same book adds an add trigger, an edit trigger inside the item, and a slot holding the form root. The root renders only its children, which the next example defines:
 
 ```json
 {
@@ -356,13 +455,26 @@ With the form, the same book adds an add trigger, an edit trigger inside the ite
   "address-country": { "type": "AddressSummaryCountry", "children": [] },
   "address-edit": { "type": "AccountAddressBookEditTrigger", "children": [] },
   "address-form-slot": { "type": "AccountAddressBookFormSlot", "children": ["address-form"] },
-  "address-form": { "type": "AccountAddressFormRoot", "props": { "defaultCountry": "BRA" }, "children": [] }
+  "address-form": {
+    "type": "AccountAddressFormRoot",
+    "props": { "defaultCountry": "BRA" },
+    "children": [
+      "form-country",
+      "form-country-notice",
+      "form-recipient",
+      "form-fields",
+      "form-reference",
+      "form-error",
+      "form-submit",
+      "form-cancel"
+    ]
+  }
 }
 ```
 
 To open the form in a dialog, swap `AccountAddressBookFormSlot` for `AccountAddressBookFormDialog`. The page needs a `ToastProvider` above it.
 
-To offer the country choice, give the form root its parts, with the control first:
+The form root's parts, with the country control first so the shopper can choose the country:
 
 ```json
 {
@@ -447,7 +559,7 @@ To mark the addresses the store does not ship to, add an `AccountAddressBookItem
 - **Placing `AccountAddressBookItemDeliverability` outside `AccountAddressBookItem`.** It needs the country that the entry hands it, and throws without it.
 - **Expecting the marker to appear when the store ships to one country.** Under the single-country fallback it renders nothing on purpose: one guessed country cannot tell a deliverable address from an undeliverable one.
 - **Listing the form's fields in the schema.** `AccountAddressFormFields` renders the ones the country asks for. Do not compose a field per country.
-- **Expecting the default form to offer a country choice.** A childless `AccountAddressFormRoot` shows `defaultCountry` as text. Compose `AddressCountryControl` explicitly to offer the countries the store ships to.
+- **Leaving `AccountAddressFormRoot` with no children.** It has no default parts, so the form renders empty. Compose its parts, with `AddressCountryControl` first to offer the countries the store ships to.
 - **Placing `AddressCountryControl` or `AccountAddressCountryNotice` outside `AccountAddressFormRoot`.** Both need the form; the hook throws without it.
 - **Using `ShippingAddress*` for the account form.** Those parts are the checkout form.
 
@@ -459,27 +571,27 @@ To mark the addresses the store does not ship to, add an `AccountAddressBookItem
 |---|---|---|
 | `AccountAddressBookRoot` | `[data-fs-account-address-book]`; carries `-state` | `flex flex-col gap-4` |
 | `AccountAddressBookList` | `[data-fs-account-address-book-list]`, items via `[data-fs-account-address-book-list-item]` | `flex flex-col gap-4` |
-| `AccountAddressBookItem` | `[data-fs-account-address-book-item]` | `flex flex-col gap-1 rounded-md border border-[#D4D4D4] p-4` |
-| `AccountAddressBookItemLines` | each line `[data-fs-account-address-book-line]` | `text-[14px] text-[#404040]` |
+| `AccountAddressBookItem` | `[data-fs-account-address-book-item]` | `flex flex-col gap-1 rounded-md border border-[var(--color-border-strong)] p-4` |
+| `AccountAddressBookItemLines` | each line `[data-fs-account-address-book-line]` | `text-[14px] text-[var(--color-text-secondary)]` |
 | `AccountAddressBookLoading` | `[data-fs-account-address-book-loading]`, message via `-loading-message` | Leave the message as is: it is already `sr-only` |
 | `AccountAddressBookSkeleton` | `[data-fs-account-address-book-skeleton]`, lines via `-skeleton-line` | `animate-pulse` |
 | `AccountAddressBookEmpty` | `[data-fs-account-address-book-empty]` | `text-[14px] text-[#737373]` |
-| `AccountAddressBookError` | `[data-fs-account-address-book-error]`, message via `-error-message`, button via `[data-fs-account-address-book-retry]` | `flex flex-col gap-2 text-[#B91C1C]` |
-| `AccountAddressBookAddTrigger` | `[data-fs-account-address-book-add]` | `rounded-md bg-[#2563EB] px-4 py-2 font-semibold text-white` |
-| `AccountAddressBookEditTrigger` | `[data-fs-account-address-book-edit]` | `text-[14px] font-semibold text-[#2563EB]` |
-| `AccountAddressBookFormSlot` | `[data-fs-account-address-book-form-slot]` | `rounded-md border border-[#D4D4D4] p-4` |
+| `AccountAddressBookError` | `[data-fs-account-address-book-error]`, message via `-error-message`, button via `[data-fs-account-address-book-retry]` | `flex flex-col gap-2 text-[var(--color-feedback-danger)]` |
+| `AccountAddressBookAddTrigger` | `[data-fs-account-address-book-add]` | `rounded-md bg-[var(--color-blue-surface)] px-4 py-2 font-semibold text-white` |
+| `AccountAddressBookEditTrigger` | `[data-fs-account-address-book-edit]` | `text-[14px] font-semibold text-[var(--color-blue-surface)]` |
+| `AccountAddressBookFormSlot` | `[data-fs-account-address-book-form-slot]` | `rounded-md border border-[var(--color-border-strong)] p-4` |
 | `AccountAddressBookFormDialog` | popup via `[data-fs-account-address-book-form-dialog]`, with the `Dialog` particle's own `data-fs-dialog-*` attributes | `w-full max-w-md rounded-md bg-white p-6` |
-| `AccountAddressBookDeleteTrigger` | `[data-fs-account-address-book-delete]` | `text-[14px] font-semibold text-[#B91C1C]` |
+| `AccountAddressBookDeleteTrigger` | `[data-fs-account-address-book-delete]` | `text-[14px] font-semibold text-[var(--color-feedback-danger)]` |
 | `AccountAddressBookDeleteConfirm` | popup via `[data-fs-account-address-book-delete-confirm]`, with the `AlertDialog` particle's own `data-fs-alert-dialog-*` attributes; the address via `-delete-address`; the refusal via `-delete-error`; the confirming button via `-delete-submit` | `w-full max-w-md rounded-md bg-white p-6` |
 | `AccountAddressFormRoot` | `[data-fs-account-address-form]`, with the form particle's own `data-fs-form` and `data-fs-form-pending`; carries `-mode` (`add` or `edit`); status region via `-status` | `flex flex-col gap-3` |
-| `AddressCountryControl` | `[data-fs-address-country-control]`; carries `-mode` (`select` or `text`) and `-pending` while a change loads; the text via `-text`; the list's trigger via `[data-fs-account-address-form-control]` | `flex flex-col gap-1 text-[14px] text-[#404040]` |
-| `AccountAddressCountryNotice` | `[data-fs-account-address-country-notice]` | `text-[14px] text-[#404040]` |
+| `AddressCountryControl` | `[data-fs-address-country-control]`; carries `-mode` (`select` or `text`) and `-pending` while a change loads; the text via `-text`; the list's trigger via `[data-fs-account-address-form-control]` | `flex flex-col gap-1 text-[14px] text-[var(--color-text-secondary)]` |
+| `AccountAddressCountryNotice` | `[data-fs-account-address-country-notice]` | `text-[14px] text-[var(--color-text-secondary)]` |
 | `AccountAddressFormRecipientName`, `AccountAddressFormFields`, `AccountAddressFormReference` | each field's wrapper `[data-fs-account-address-form-field="<name>"]`; a list field's error via `-field-error` | `flex flex-col gap-1` |
-| `AccountAddressFormError` | `[data-fs-account-address-form-error]`, whose value is the kind of error | `text-[14px] text-[#B91C1C]` |
-| `AccountAddressFormSubmit` | `[data-fs-account-address-form-submit]` | `rounded-md bg-[#2563EB] px-4 py-2 font-semibold text-white` |
-| `AccountAddressFormCancel` | `[data-fs-account-address-form-cancel]` | `rounded-md border border-[#D4D4D4] px-4 py-2` |
+| `AccountAddressFormError` | `[data-fs-account-address-form-error]`, whose value is the kind of error | `text-[14px] text-[var(--color-feedback-danger)]` |
+| `AccountAddressFormSubmit` | `[data-fs-account-address-form-submit]` | `rounded-md bg-[var(--color-blue-surface)] px-4 py-2 font-semibold text-white` |
+| `AccountAddressFormCancel` | `[data-fs-account-address-form-cancel]` | `rounded-md border border-[var(--color-border-strong)] px-4 py-2` |
 | `AccountAddressBookProfileNotice` | `[data-fs-account-address-book-profile-notice]`, text via `-message`, link via `-link` | `rounded-md border border-[#FBBF24] bg-[#FFFBEB] p-3 text-[14px]` |
-| `AccountAddressBookItemDeliverability` | `[data-fs-account-address-book-item-deliverability]` | `text-[14px] text-[#B45309]` |
+| `AccountAddressBookItemDeliverability` | `[data-fs-account-address-book-item-deliverability]` | `text-[14px] text-[var(--color-feedback-warning)]` |
 
 ```json
 {
@@ -490,19 +602,22 @@ To mark the addresses the store does not ship to, add an `AccountAddressBookItem
   },
   "address-item": {
     "type": "AccountAddressBookItem",
-    "style": ["flex", "flex-col", "gap-[4px]", "rounded-[6px]", "border", "border-[#D4D4D4]", "p-[16px]"],
+    "style": ["flex", "flex-col", "gap-[4px]", "rounded-[6px]", "border", "border-[var(--color-border-strong)]", "p-[16px]"],
     "children": []
   }
 }
 ```
 
+The role colors above are the foundation's `visualIdentity` roles (`--color-feedback-danger`, `--color-feedback-warning`), 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-strong": "#D4D4D4", "--color-text-secondary": "#404040", "--color-blue-surface": "#2563EB"}`. A color used once stays a hex.
+
 ---
 
 ## Known gaps
 
 - **A failed profile read fails the whole book.** The notice and the book share one page query, and both roots are non-null. If the profile read fails, the list also goes to its error state. The same limit applies to any later part that joins the page query.
 - **The deliverability marker reads the store's shipping countries when the page loads.** It does not refresh until the page loads again, and it stays silent if that first read failed.
-- **The default form offers no country choice.** A childless form root shows `defaultCountry` as text, because only a control placed in the schema joins the page query. Compose `AddressCountryControl` to offer the choice.
 - **The shipping countries are read once per page.** The list comes with the page; a store that changes where it ships shows the change on the next page load.
 - **The postal code has no mask.** It is a plain text field. After the shopper stops typing for 400 ms, a complete code fills the state, city, neighborhood and street the country shows (Argentina, Brazil, Canada, France, Mexico, Spain and the United States). A field the shopper typed or saved is never changed, and a select the shopper's own city depends on is left alone. A field an earlier code filled and the new code does not cover is cleared. A reply for a code or country that changed meanwhile is dropped. A code the platform does not know and a lookup that fails change nothing and say nothing. The merchant cannot turn the fill off.
 - **The fill remembers only the last code asked.** Typing the same code again after another one asks again.

package/dist/docs/account-entry-point.md

@@ -53,10 +53,10 @@ Content model (`account-entry-point`) fields, edited in the CMS:
 |-------|------|----------|-------|
 | `signedOutLabel` | string | no | Cleared or absent keeps the authored prop |
 | `signedInLabel` | string | no | Same |
-| `icon` | string | no | Same, but the name must be listed in `global.json → icons.include` — see below |
+| `icon` | string | no | Same, but the name must be listed in `foundation.json → icons.include` — see below |
 | `loadingLabel` | string | no | Same |
 
-**An icon chosen in the CMS has to be declared in the store first.** Icon references resolve at compile time: the compiler collects every value of every `icon`-typed prop across the page and layout schemas and emits one sprite per route. A name that arrives at runtime from a CMS entry is never seen by that pass, so it renders a `<use>` pointing at a symbol the route's sprite does not carry — no build error, no runtime error, no glyph. For a merchant to be able to pick the icon in the Admin, the store must list the candidates under `global.json → icons.include`, which puts them in the root sprite regardless of what any schema references.
+**An icon chosen in the CMS has to be declared in the store first.** Icon references resolve at compile time: the compiler collects every value of every `icon`-typed prop across the page and layout schemas and emits one sprite per route. A name that arrives at runtime from a CMS entry is never seen by that pass, so it renders a `<use>` pointing at a symbol the route's sprite does not carry — no build error, no runtime error, no glyph. For a merchant to be able to pick the icon in the Admin, the store must list the candidates under `foundation.json → icons.include`, which puts them in the root sprite regardless of what any schema references.
 
 **One element, two links, chosen by the session.** `loggedIn` renders the signed-in link; `anonymous` and `identified` both render the signed-out one, because an identified but unauthenticated shopper cannot reach their account yet. There is no prop that selects between them — the merchant authors one element and the session decides.
 
@@ -98,7 +98,7 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 - **Placing it outside a `SessionRoot`.** The compiler rejects it, and the runtime throws.
 - **Authoring `$content` in the schema.** `$content` is compiler-injected from the page's or layout's content entry; naming it in `props` fails the build.
 - **Expecting a default glyph.** The base icon dialect has no account icon, so a store that authors no `icon` gets a label-only link. Author one from the store's own collection.
-- **Letting a merchant pick the icon without declaring it.** An `icon` supplied by a CMS entry renders nothing at all unless the store lists the name in `global.json → icons.include`: the compiler builds each route's sprite from the schemas, and a runtime value never reaches that pass.
+- **Letting a merchant pick the icon without declaring it.** An `icon` supplied by a CMS entry renders nothing at all unless the store lists the name in `foundation.json → icons.include`: the compiler builds each route's sprite from the schemas, and a runtime value never reaches that pass.
 - **Hiding the announced text with `display:none`.** That removes it from the accessibility tree and defeats the announcement; use a clipping technique instead.
 
 ---
@@ -123,7 +123,7 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 ```
 
 The glyph carries a fixed intrinsic size, so reach it through the root when the header needs another.
-Author that once per store as the `AccountEntryPoint` base swatch in `global.json → styles`:
+Author that once per store as the `AccountEntryPoint` base swatch in `foundation.json → styles`:
 
 ```json
 {

package/dist/docs/account-menu.md

@@ -72,9 +72,11 @@ Two kinds of entry are excluded from the match entirely: one marked `external`,
 
 ### AccountMenuList
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `'Account'` | Accessible name of the navigation landmark. |
+Content model (`account-menu-list`) field, an ICU message with no package default:
+
+| Field | Type | Source (English) | Notes |
+|-------|------|------------------|-------|
+| `label` | message | `Account` | Accessible name of the navigation landmark. |
 
 It takes no children: one `<li>` per resolved section is what it renders. With no sections to render it renders nothing at all, rather than an empty landmark for a screen-reader user to land in.
 
@@ -89,15 +91,14 @@ Exposed as `AccountMenu.IndexRedirect`. The account's root has no section of its
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `loadingLabel` | string | — | Announced while the first section opens. |
-| `emptyMessage` | string | `'No account section is configured.'` | What the root says when there is no section to open. |
 | `className` | string | — | Applied to whichever element renders. |
 
-Content model (`account-menu-index-redirect`) fields, edited in the CMS, each winning over its prop when published; a blank field falls through:
+Content model (`account-menu-index-redirect`) fields, edited in the CMS:
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `loadingLabel` | string | no | The waiting announcement |
-| `emptyMessage` | string | no | The no-section message |
+| `loadingLabel` | string | no | The waiting announcement; wins over its prop when published, and a blank field falls through |
+| `emptyMessage` | message | no | The no-section message (source `No account section is configured.`); no package default |
 
 **It replaces the current history entry with the first section that stays in the account.** It reads the Root's resolved list and skips, in order: an entry marked `external`, a destination the allowlist refused, a destination that is not site-relative even though the merchant did not flag it, and the root itself in any spelling that matches it. Replace, never push: back from the section leaves the account instead of bouncing through its root.
 
@@ -113,16 +114,14 @@ Exposed as `AccountMenu.SignOut`. A button that ends the session and leaves the
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'Sign out'` | The button's text. |
-| `errorMessage` | string | `"We couldn't sign you out. Please try again."` | Shown when the sign-out did not happen. |
 | `className` | string | — | Applied to the wrapper. |
 
-Content model (`account-menu-sign-out`) fields, edited in the CMS, each winning over its prop when published; a blank field falls through:
+Content model (`account-menu-sign-out`) fields, ICU messages with no package default:
 
-| Field | Type | Required | Notes |
-|-------|------|----------|-------|
-| `label` | string | no | The button's text |
-| `errorMessage` | string | no | The failure message |
+| Field | Type | Source (English) | Notes |
+|-------|------|------------------|-------|
+| `label` | message | `Sign out` | The button's text |
+| `errorMessage` | message | `We couldn't sign you out. Please try again.` | The failure message |
 
 The component declares `actions: { session: ['logout'] }` and writes only through `$actions.session.logout()`.
 
@@ -161,7 +160,7 @@ Returns `{ items, current }` — the resolved sections and the current one as `{
 
 Bound to a CMS entry, the Root authors no `items` at all — the entry supplies the whole list.
 
-No part carries a `style` reference: each takes its type's `base` swatch from `global.json → styles` on its own. Reference a named swatch only when the store defines one, since a `$name` the store does not define expands to nothing, without an error.
+No part carries a `style` reference: each takes its type's `base` swatch from `foundation.json → styles` on its own. Reference a named swatch only when the store defines one, since a `$name` the store does not define expands to nothing, without an error.
 
 The account root's page, whose only content is the redirect:
 
@@ -178,7 +177,7 @@ The account root's page, whose only content is the redirect:
 
 - **Placing the Root beside the slot instead of around it.** The layout's own consumers would be satisfied and the page's would not: a context reaches only descendants. Context-constraint validation reports it as a build error rather than as an empty menu at runtime.
 - **Putting the `<nav>` around the section's content.** That is what the two-part split exists to prevent; do not wrap the slot in `AccountMenuList`.
-- **Leaving `label` unauthored.** The default is `Account`; a store with its own wording should say so, because a landmark's name is how a screen-reader user tells it from every other one.
+- **Leaving `label` unauthored.** There is no package default: an unauthored label leaves the landmark nameless, and a landmark's name is how a screen-reader user tells it from every other one.
 - **Styling the current item and nothing else.** The hook exists beside `aria-current`, never instead of it. Removing the programmatic signal leaves position conveyed by appearance alone.
 - **Publishing an empty list and expecting the defaults.** Empty is a configuration, not an absence. The account's root then has no section to open, and says so.
 - **Placing `AccountMenuIndexRedirect` on a section's page.** It navigates away from whatever page hosts it; it belongs on the account page alone.
@@ -207,7 +206,7 @@ The account root's page, whose only content is the redirect:
 | Sign-out button | `data-fs-account-menu-sign-out-button` is the `<button>`; style `:disabled` for the wait | `text-left text-sm underline` |
 | Sign-out failure | `data-fs-account-menu-sign-out-error` is the alert | `text-sm text-red-600` |
 
-The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, in CSS alone. A store authors them as `AccountMenuList.base` in `global.json → styles`, abridged here:
+The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, in CSS alone. A store authors them as `AccountMenuList.base` in `foundation.json → styles`, abridged here:
 
 ```json
 {