@vtex/faststore 0.0.1

package/dist/docs/footer-root.md

@@ -0,0 +1,145 @@
+# FooterRoot
+
+**Category:** layout
+**Purpose:** The footer landmark. Renders the `<footer>` element that wraps the store's footer sections, giving the region one accessibility landmark (`contentinfo`) and one styling hook. Carries no content and no commerce data of its own.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The band that closes the page, usually separated from the page content by a background-color change, a top border, or a block of generous padding. It is a container rather than a visible widget: what you see are the blocks inside it. The image is the source of truth for layout.
+
+Reach for `FooterRoot` when:
+
+- The bottom of the image holds a **grouped band of store information** — link columns, payment icons, social icons, a logo, or a copyright line — visually set apart from the page's main content.
+- That band spans the full width and reads as one region, even when its inner blocks are laid out in columns.
+
+One `FooterRoot` per page. Do not add a second one for a subdivision of the band.
+
+---
+
+## When to use
+
+- As the wrapper for the footer band, placed at the **top level of a layout schema** so the footer is shared by every page that references the layout.
+- Any time the page needs a `contentinfo` landmark, so assistive technology can jump to the store information in one gesture.
+
+## When NOT to use
+
+- As a generic centered layout wrapper — that is `Container`. `FooterRoot` is a landmark and should appear once.
+- Inside `article`, `aside`, `main`, `nav`, or `section`. Nested there, the element still renders but the browser exposes **no** `contentinfo` landmark, which defeats the reason it exists.
+- For the header or any other page chrome. `FooterRoot` renders a `<footer>` element specifically.
+- As a styled box with a background unrelated to the page's footer region — use a plain element with a class.
+
+---
+
+## Composition
+
+`FooterRoot` is a passthrough wrapper: it renders a `<footer>` and places its children inside, in order. It has no required parent and no required children — anything valid in the schema can be a child, and child order reflects visual order.
+
+```
+Container                   ← the layout's root element
+├── Slot                    ← where the page's own tree is injected
+└── FooterRoot
+    ├── Container           ← groups the footer's inner blocks
+    │   ├── Text
+    │   └── NavigationLink
+    └── FooterCopyright     ← legal notice, the band's last line
+```
+
+A layout's `root` names an element, and `FooterRoot` sits among that root's children as a **sibling** of the single `Slot` every layout must declare — never inside it. Keeping it at that level, outside any `section` or `nav`, is what makes the element a `contentinfo` landmark. `Slot` is a reserved layout element type rather than a catalog component, so it is the one `type` that will not be found in `catalog.json`.
+
+`FooterRoot` provides no data context, so any commerce-aware block placed inside it still needs its own provider ancestor.
+
+---
+
+## Components
+
+### FooterRoot
+
+No props. It accepts only standard `<footer>` attributes (e.g. `className`).
+
+---
+
+## Canonical schema example
+
+A layout whose root holds the page `Slot` and a `FooterRoot` beside it, with a link column and a copyright line inside the footer:
+
+```json
+{
+  "frame": {
+    "type": "Container",
+    "children": ["slot", "footer"]
+  },
+  "slot": {
+    "type": "Slot"
+  },
+  "footer": {
+    "type": "FooterRoot",
+    "style": ["bg-[#F5F5F5]", "px-[32px]", "py-[40px]"],
+    "children": ["footer-inner", "footer-copyright"]
+  },
+  "footer-inner": {
+    "type": "Container",
+    "style": ["flex", "gap-[48px]"],
+    "children": ["footer-links-help-title", "footer-links-help-faq"]
+  },
+  "footer-links-help-title": {
+    "type": "Text",
+    "props": { "as": "h3" },
+    "style": ["text-[14px]", "font-semibold", "text-[#1A1A1A]"]
+  },
+  "footer-links-help-faq": {
+    "type": "NavigationLink",
+    "props": { "href": "/faq" },
+    "style": ["text-[14px]", "text-[#666666]"]
+  },
+  "footer-copyright": {
+    "type": "FooterCopyright",
+    "style": ["text-[12px]", "text-[#8A8A8A]", "mt-[32px]"]
+  }
+}
+```
+
+Element ids double as content keys for content-backed children, so name them for the section (`footer-links-help`) rather than for its current styling (`footer-column-2`).
+
+---
+
+## Common mistakes
+
+- **`Footer`, `FooterSection`, `PageFooter`, or `SiteFooter`.** The correct name is `FooterRoot`.
+- **Using `Container` for the footer band.** `Container` renders a `<div>` with no landmark. Use `FooterRoot` for the band and `Container` for grouping inside it.
+- **Nesting `FooterRoot` inside a `section` or inside the page-content slot.** It must sit at the top level of the layout, as a sibling of the `Slot`, or the `contentinfo` landmark disappears.
+- **Adding a `FooterRoot` per page.** The footer belongs in the shared layout so every page inherits one copy; a page that should carry no footer references a layout that defines none.
+- **Expecting props for the footer's content.** `FooterRoot` has none — the copy lives in the child elements.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `FooterRoot` | The footer band: background, full-width padding, top border, and the stacking of its inner blocks | `bg-[#F5F5F5] px-[32px] py-[40px] border-t border-[#E5E5E5] flex flex-col gap-[32px]` |
+
+The hook is `data-fs-footer`, so a store-level swatch can target the whole region without touching the sections inside it.
+
+```json
+{
+  "footer": {
+    "type": "FooterRoot",
+    "style": ["bg-[#111111]", "text-[#FFFFFF]", "px-[32px]", "py-[48px]", "flex", "flex-col", "gap-[32px]"],
+    "children": ["footer-copyright"]
+  },
+  "footer-copyright": {
+    "type": "FooterCopyright",
+    "style": ["text-[12px]", "text-[#B3B3B3]"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[container]] — the generic centered layout wrapper; renders a `<div>` with no landmark, and groups blocks *inside* `FooterRoot`.
+- [[footer-copyright]] — the CMS-editable legal notice that closes the band.
+- `Text`, `NavigationLink`, `Icon`, `Image`, and `Separator` — the shipped primitives the footer band is built from. They carry no `.md` of their own; read their schemas from `catalog.json`.

package/dist/docs/footer-social.md

@@ -0,0 +1,151 @@
+# FooterSocial
+
+**Category:** navigation
+**Purpose:** Links to the store's official social profiles, rendered as a row of platform icons with an optional heading, both editable in the CMS. The content arrives through the compiler-injected `$content` prop, backed by the `footer-social` content model declared next to the component; the `heading` and `entries` props are the authored fallback for stores with no CMS binding. One element renders the whole row.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The image is the source of truth for layout. A FooterSocial row is present when you see:
+
+- A **short row of social brand marks** — the Instagram camera, the Facebook `f`, the LinkedIn `in`, the YouTube play button, a TikTok note — usually monochrome, often circled or squared, and all the same size.
+- Often a **short heading above or beside them**: *Siga a gente*, *Follow us*, *Redes sociais*.
+- The glyphs are **platform marks that are links**, not card flags and not text. Rounded rectangles reading Visa or Mastercard are a different component.
+- Usually **four to six marks**, far fewer than a payment strip carries.
+
+---
+
+## When to use
+
+- The row of social profile links in a footer, or in any band that points shoppers at the brand's own accounts.
+- One instance per row. Every profile in the row is one item of this component's content, not its own element.
+
+## When NOT to use
+
+- A row of **accepted payment brands** (Visa, Pix, Boleto) → use `PaymentMethods`; card flags rather than platform marks, and no links.
+- **Share this product** buttons on a PDP → those act on the current page rather than linking to the store's own profiles, and they are not this display row.
+- A **feed or embed** of the brand's posts → that reads a platform API; this component only links out.
+- Institutional or editorial **text links** (Contact, Returns) → use `FooterLinkGroup`, which renders labelled text links in a headed column.
+- The **value-proposition strip** (free shipping, secure purchase) → use [[incentives]]; those items pair an icon with a line or two of copy.
+
+---
+
+## Composition
+
+`FooterSocial` is a leaf in the schema — it has no sub-components and takes no children. The profiles come from content, not from child elements.
+
+```
+FooterRoot
+├── FooterLinkGroup      ← "Ajuda"          (siblings; order is visual order)
+├── FooterLinkGroup      ← "Institucional"
+├── FooterSocial         ← the social row
+├── PaymentMethods       ← the flag strip
+└── FooterCopyright
+```
+
+**Content, then prop, per field.** The heading resolves from the CMS entry first and the `heading` prop second; the list resolves the same way, independently. The list is replaced whole rather than merged — an entry supplying an empty list wins over an authored list, because a merchant who cleared the row cleared it. When no entry survives the filter below, the component renders `null` (self-hide) and the footer omits the row. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
+
+**Nothing in the model is required, so a half-filled entry still renders.** An entry with only a heading keeps the authored `entries` prop under the merchant's heading, and vice versa. What the component drops is per profile, never the whole row: a profile is skipped when its label is blank, or when it carries neither a `platform` nor an `iconUrl` — an icon nobody can name is the one thing this must not ship.
+
+**Every link opens in a new tab**, unconditionally, and therefore always carries `rel="noopener noreferrer"`. There is no authorable target: an official profile is always outbound. The component writes no "(opens in new tab)" cue, because a hardcoded English string cannot be overridden in a store that is not written in English — a merchant who wants the cue writes it into the label, which is the only channel that carries their language.
+
+**A destination the allowlist refuses renders as text.** Every `url` passes through the shared render-time check, which admits `http:`, `https:`, `mailto:`, `tel:`, and site-relative paths. A refused one — a `javascript:` value, a protocol-relative `//host`, or a URL not yet pasted — renders the profile's label as visible text with no link and no glyph, rather than a mark that looks clickable and goes nowhere. The rejection logs once with the entry index and a bounded reason.
+
+**Every predefined name must be registered.** A `platform` resolves to a sprite symbol the store's build has to include; the store's `global.json` writes the names out under `icons.include` — it is JSON, so it cannot import `SOCIAL_PLATFORM_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing mark. `linkedin` and `youtube` need provisioned icon data as well: unlike the other three they have no embedded fallback, so a store that registers them without running `sukima icon-data fetch` fails to build.
+
+---
+
+## Components
+
+### FooterSocial
+
+| Prop | Type | Required | Notes |
+|-------|------|----------|-------|
+| `heading` | string | no | Authored fallback. Ignored when a CMS entry supplies a heading |
+| `entries` | array | no | Authored fallback list of `{ label, url, platform?, iconUrl? }`. Ignored when a CMS entry supplies `entries` |
+
+Content model (`footer-social`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `heading` | string | no | Optional row heading. When set it also names the list for assistive tech; when blank or absent the list is left unnamed rather than given an invented English default |
+| `entries` | array | no | Ordered profiles. Reordering here reorders the row with no deployment. Optional so a heading-only entry falls back to the authored list. Declares `minItems: 1` and no ceiling — Admin-form guidance only, unenforced on the read path, so an empty list still reaches the component and self-hides there |
+| `entries[].platform` | enum | no | One of `facebook`, `instagram`, `linkedin`, `pinterest`, `youtube`. Renders the sprite glyph, decorative, with the label beside it as screen-reader-only text |
+| `entries[].url` | string | yes | The profile's address. Opens in a new tab. A value the allowlist refuses renders the label as plain text instead of a link |
+| `entries[].label` | string | yes | The platform's name. Names the link for assistive tech on both glyph paths; a blank label drops the profile |
+| `entries[].iconUrl` | string | no | An uploaded image, for a platform with no predefined name (TikTok, WhatsApp, X). Wins over `platform` when both are set |
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "footer-social": {
+    "type": "FooterSocial",
+    "style": ["flex", "flex-col", "gap-[12px]"]
+  }
+}
+```
+
+The element id is the content key, so name it for the section rather than its styling. Renaming it orphans the merchant's entry: the profiles stay in the Content Platform while the component reads a key nobody writes.
+
+---
+
+## Common mistakes
+
+- **`SocialLinks`, `SocialIcons`, `FooterSocialLinks`, `SocialMedia`.** The correct name is `FooterSocial`.
+- **One element per platform.** The most common wrong answer by far: a row of bare `Icon` elements, one per network, is not this component. It is not editable, the marks are not links, and none of them carries an accessible name. One `FooterSocial` element renders the whole row and each profile is an item in its content.
+- **Reaching for `NavigationLink` around an `Icon`.** That is what this component already does per entry; composing it by hand loses the content model, the link check, and the accessible name.
+- **Expecting a `tiktok`, `whatsapp`, or `x` platform.** None of those names resolves — and `x` is the close icon, not the brand. Upload a mark through `iconUrl` and give the entry a `label`.
+- **Expecting a `twitter` platform.** Deliberately absent: both icon vocabularies still draw the old bird, so the mark rides `iconUrl` like the others rather than being frozen into the enum.
+- **Setting `iconUrl` and `platform` and expecting the glyph.** The upload wins; drop `iconUrl` to get the sprite glyph back.
+- **Giving it children.** It is a leaf; the profiles are content, which is what makes adding one a CMS save instead of a deployment.
+- **Adding an `alt` field beside `label`.** One label names the link on both paths. Two fields for one accessible name is how the legacy footer ended up announcing the icon's own name instead of the merchant's.
+- **Authoring a `target`.** Every link opens in a new tab already; there is no setting, because there is only one correct value.
+- **Shipping without the icon size swatch.** Predefined glyphs default to 24×24 and uploaded images to their natural size, so a mixed row renders ragged until `data-fs-footer-social-icon` is sized.
+
+---
+
+## Styling
+
+`FooterSocial` renders one root you style directly, plus per-part hooks. The glyph hook covers both the `<svg>` and the `<img>` path, which is what makes a mixed row line up.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `FooterSocial` | Stacks the heading over the row | `flex flex-col gap-[12px]` |
+| `data-fs-footer-social-heading` | The row heading | `text-[14px] font-bold uppercase text-[#1a1a1a]` |
+| `data-fs-footer-social-list` | The mark row, wrapping on narrow screens | `flex flex-wrap items-center gap-[12px] list-none p-0 m-0` |
+| `data-fs-footer-social-item` | The box one mark occupies | `flex items-center` |
+| `data-fs-footer-social-link` | The tap target around one mark | `flex items-center justify-center w-[32px] h-[32px] rounded-full` |
+| `data-fs-footer-social-icon` | Both glyph paths, sized to match | `w-[24px] h-[24px] object-contain` |
+| `data-fs-footer-social-text` | The fallback for a refused destination | `text-[14px] text-[#767676]` |
+
+The list carries an explicit `role="list"`. Keep it: WebKit drops the implicit list role from a `<ul>` whose computed `list-style` is `none`, and `list-none` is exactly what the row needs, so the attribute is what holds the semantics the named list was chosen for.
+
+`data-fs-footer-social-platform` carries the enum member on each item with a predefined platform — `[data-fs-footer-social-platform="instagram"]` targets one brand, for a mark that needs its own color. It is absent on items with no `platform`.
+
+Styled example:
+
+```json
+{
+  "footer-social": {
+    "type": "FooterSocial",
+    "style": ["flex", "flex-col", "gap-[12px]"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[footer-root]] — the `<footer>` landmark the row usually sits inside.
+- [[payment-methods]] — the flag strip beside it; same `$content` mechanics and the same two glyph paths, card brands instead of platform marks, and no links.
+- [[footer-link-group]] — the headed link columns; same `$content` mechanics and the same link check, text links instead of glyphs.
+- [[footer-copyright]] — the legal line below it; same `$content` mechanics, plain text.
+- [[incentives]] — the benefit strip in the same band; also icon-driven, but each item pairs its glyph with copy and links nowhere.
+- `Icon` — the particle each predefined mark renders. It carries no `.md` of its own; read its schema from `catalog.json`.
+- `Image` — the particle an uploaded mark renders. It carries no `.md` of its own; read its schema from `catalog.json`.
+- `NavigationLink` — the particle wrapping each mark. It carries no `.md` of its own; read its schema from `catalog.json`.

package/dist/docs/free-shipping-progress.md

@@ -0,0 +1,87 @@
+# FreeShippingProgress
+
+**Category:** commerce
+**Purpose:** Reactive progress bar for the cart's nearest free-shipping goal. Reads `cart.freeShippingProgress` and the reactive `cart.total`, then renders one of three states: below-threshold ("faltam {value} para frete grátis" + a partially filled bar), earned ("você ganhou frete grátis!" + a full bar), or absent (renders nothing). Composed at the **top of a cart / mini-cart drawer** to nudge the shopper to add a bit more.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Look for a **strip at the top of an open cart or mini-cart** with a horizontal progress bar and a short line of copy such as "Faltam R$ 72,00 para frete grátis" or "Você ganhou frete grátis!". The bar fills left-to-right toward a goal. Examples:
+
+- A thin bar plus a one-line message above the cart item list.
+- A "free shipping" banner with a fill indicator that grows as the cart total rises.
+
+---
+
+## The three states
+
+| State | Condition | Renders |
+|---|---|---|
+| Below threshold | `qualified === false`, cart total below `threshold` | Below-threshold message + a bar filled to `cartTotal / threshold` |
+| Earned | field `qualified === true`, OR the reactive cart total reaches `threshold` | Earned message + a full bar |
+| Absent (self-hide) | `cart.freeShippingProgress === null` (no destination, no eligible promotion, empty cart, still loading, or degraded) | **Nothing** — no bar, no message, no wrapper |
+
+## Reactive fill (no extra calls)
+
+`freeShippingProgress` is a lazy field kept out of `CartFragment`, so its cached value (`threshold`, `qualified`) does not refresh on cart mutations. The bar therefore derives the **live** fill and remaining from the reactive `cart.total` — which *is* fresh via cache-write propagation — against the fetched `threshold`:
+
+- `isQualified = qualified || (threshold != null && cartTotal >= threshold)` — the field flag covers the already-earned case (where `threshold` is `null`); the reactive comparison flips it at the boundary between page loads.
+- `liveRemaining = isQualified ? 0 : max(threshold − cartTotal, 0)`
+- `fill = isQualified ? 1 : clamp(cartTotal / threshold, 0..1)`
+
+The bar updates instantly on every add/remove with **no** refetch of `freeShippingProgress`. `threshold` refreshes only on a full page re-sync. `Money.amount` is a string at runtime and is always `Number()`-coerced before math/formatting.
+
+---
+
+## When to use
+
+- As the **first child of `cart-filled`** — the top strip of an open mini-cart drawer, above the item list, where a free-shipping bar drives "add a bit more". The americanas `default.json` uses this placement.
+- Alongside `CartRoot` / `CartTotalizerRoot` on the same page — all three select the same top-level `cart {}` field, so the compiler merges them into one query (no double fetch).
+
+## When NOT to use
+
+- On an empty cart — there is nothing to ship and the field is `null` there anyway (the component self-hides).
+- As a general-purpose progress bar — use the `Meter` particle directly for non-free-shipping meters.
+
+---
+
+## Composition
+
+```
+FreeShippingProgressRoot        ← reactive provider; self-hides on null/loading
+├── FreeShippingProgressMessage ← below-threshold vs earned copy (front-formatted)
+└── FreeShippingProgressBar     ← composes the Meter particle at value = fill * 100
+```
+
+### Key components
+
+| Component | Props | Notes |
+|---|---|---|
+| `FreeShippingProgressRoot` | `$data` | Provides `FreeShippingProgressContext`; the copy formats from the active storefront context; renders nothing when the field is `null` |
+| `FreeShippingProgressMessage` | `label?`, `qualifiedLabel?` | `label` is a `{value}`-token template (default `"faltam {value} para frete grátis"`); `qualifiedLabel` default `"você ganhou frete grátis!"`; `children` overrides the text |
+| `FreeShippingProgressBar` | — | Renders a `Meter` bar; `aria-valuetext` mirrors the visible copy |
+
+Copy is front-localized and front-formatted from the Root's `locale`/`currency` (default `pt-BR`/`BRL`), not the payload `currencyCode`.
+
+---
+
+## Schema
+
+```json
+{
+  "free-shipping-progress": {
+    "type": "FreeShippingProgressRoot",
+    "children": ["free-shipping-progress-message", "free-shipping-progress-bar"]
+  },
+  "free-shipping-progress-message": {
+    "type": "FreeShippingProgressMessage",
+    "props": { "label": "faltam {value} para frete grátis", "qualifiedLabel": "você ganhou frete grátis!" }
+  },
+  "free-shipping-progress-bar": {
+    "type": "FreeShippingProgressBar"
+  }
+}
+```
+
+Place `free-shipping-progress` as the **first child of `cart-filled`** (before `unavailable-recovery`) so it sits at the top of the open drawer.

package/dist/docs/gallery.md

@@ -0,0 +1,84 @@
+# Gallery
+
+**Category:** content
+**Purpose:** Generic media gallery. Manages selected index, fullscreen, and zoom state. Receives media items directly via prop — no GraphQL fragment. Use on non-PDP contexts where media comes from a custom source.
+
+---
+
+## When to use
+
+- Any page that needs a gallery but is **not** a PDP (e.g. editorial content, lookbooks, custom landing pages).
+- Stories and editor preview where static media fixtures are passed directly.
+- When you need to compose a gallery with data that does not come from `productBySlug`.
+
+## When NOT to use
+
+- PDP product media → use `ProductGalleryRoot` instead. It declares the GraphQL fragment automatically and passes data as `$data`.
+
+---
+
+## Difference from ProductGalleryRoot
+
+| | `GalleryRoot` | `ProductGalleryRoot` |
+|---|---|---|
+| Data source | `media` prop (manual) | GraphQL fragment on `productBySlug` |
+| Page type | Non-PDP | PDP |
+| Sub-components | Same | Same |
+
+On a PDP, always prefer `ProductGalleryRoot`. On any other context, use `GalleryRoot` and pass a `media` array.
+
+---
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `media` | `GalleryMediaItem[]` | `[]` | Array of image or video items to display |
+| `defaultIndex` | number | `0` | Initially selected media index |
+| `selectOnHover` | boolean | `false` | Hovering a thumbnail selects it without clicking |
+| `thumbnailOpensFullscreen` | boolean | `false` | Clicking any thumbnail opens fullscreen |
+
+`GalleryMediaItem` shape:
+
+```ts
+{ type: 'image' | 'video'; url: string; altText: string; previewImageUrl?: string }
+```
+
+---
+
+## Composition and sub-components
+
+`GalleryRoot` accepts the same children as `ProductGalleryRoot`. Refer to [[product-gallery]] for the full composition guide, layout patterns (thumbnail alignment, slider, fullscreen, zoom), props for each sub-component, canonical schema examples, and common mistakes.
+
+---
+
+## Minimal schema example
+
+```json
+{
+  "gallery": {
+    "type": "GalleryRoot",
+    "props": { "defaultIndex": 0 },
+    "children": ["gallery-main", "gallery-thumbnails"]
+  },
+  "gallery-main": {
+    "type": "GalleryMainMedia",
+    "props": { "objectFit": "contain", "aspectRatio": "1 / 1" }
+  },
+  "gallery-thumbnails": {
+    "type": "GalleryThumbnails",
+    "props": { "maxVisible": 5 },
+    "children": ["gallery-thumbnail"]
+  },
+  "gallery-thumbnail": {
+    "type": "GalleryThumbnail",
+    "props": { "objectFit": "contain", "aspectRatio": "1 / 1" }
+  }
+}
+```
+
+---
+
+## Related
+
+- [[product-gallery]] — PDP variant with GraphQL fragment; full sub-component documentation lives here.

package/dist/docs/header-root.md

@@ -0,0 +1,150 @@
+# HeaderRoot
+
+**Category:** layout
+**Purpose:** The header landmark. Renders the `<header>` element that wraps the store's header chrome, giving the region one accessibility landmark (`banner`) and one styling hook. Carries no content and no commerce data of its own.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The band that opens the page, usually separated from the page content by a bottom border, a background-color change, or a block of generous padding. It is a container rather than a visible widget: what you see are the blocks inside it. The image is the source of truth for layout.
+
+Reach for `HeaderRoot` when:
+
+- The top of the image holds a **grouped band of store chrome** — a logo, a navigation row, a postal-code or region control, a search field, a cart icon, or a sign-in entry point — visually set apart from the page's main content.
+- That band spans the full width and reads as one region, even when its inner blocks sit on two rows (brand row above, navigation row below).
+
+One `HeaderRoot` per page. Do not add a second one for the navigation row or any other subdivision of the band.
+
+---
+
+## When to use
+
+- As the wrapper for the header band, placed at the **top level of a layout schema** so the header is shared by every page that references the layout.
+- Any time the page needs a `banner` landmark, so assistive technology can jump to the store chrome in one gesture.
+
+## When NOT to use
+
+- As a generic full-width layout wrapper — that is `Container`. `HeaderRoot` is a landmark and should appear once.
+- Inside `article`, `aside`, `main`, `nav`, or `section`. Nested there, the element still renders but the browser exposes **no** `banner` landmark, which defeats the reason it exists.
+- For the footer or any other page chrome. `HeaderRoot` renders a `<header>` element specifically.
+- For a section heading block inside the page content — that is a heading and a `Container`, not a landmark.
+
+---
+
+## Composition
+
+`HeaderRoot` is a passthrough wrapper: it renders a `<header>` and places its children inside, in order. It has no required parent and no required children — anything valid in the schema can be a child, and child order reflects visual order.
+
+```
+Container                       ← the layout's root element
+├── HeaderRoot
+│   ├── Logo                    ← the brand, linking home
+│   ├── Container               ← the navigation surface for one breakpoint
+│   │   └── NavigationMenuRoot
+│   │       └── NavigationLinkList
+│   └── Container               ← the actions cluster
+│       ├── RegionRoot
+│       └── AccountEntryPoint
+└── Slot                        ← where the page's own tree is injected
+```
+
+A layout's `root` names an element, and `HeaderRoot` sits among that root's children as a **sibling** of the single `Slot` every layout must declare — never inside it. Keeping it at that level, outside any `section` or `nav`, is what makes the element a `banner` landmark. `Slot` is a reserved layout element type rather than a catalog component, so it is the one `type` that will not be found in `catalog.json`.
+
+`HeaderRoot` provides no data context, so any commerce-aware block placed inside it still needs its own provider ancestor. An `AccountEntryPoint` in the header needs a `SessionRoot` above the header, and a `RegionTrigger` needs a `RegionRoot` between it and the header.
+
+---
+
+## Components
+
+### HeaderRoot
+
+No props. It accepts only standard `<header>` attributes (e.g. `className`).
+
+---
+
+## Canonical schema example
+
+A layout whose root holds a `HeaderRoot` and the page `Slot` beside it, with a logo and a navigation row inside the header:
+
+```json
+{
+  "frame": {
+    "type": "Container",
+    "children": ["header", "slot"]
+  },
+  "header": {
+    "type": "HeaderRoot",
+    "style": ["w-full", "flex", "items-center", "gap-[24px]", "px-[16px]", "border-b", "border-[#E5E5E5]"],
+    "children": ["header-logo", "header-nav"]
+  },
+  "header-logo": {
+    "type": "Logo",
+    "props": { "src": "/logo.svg", "alt": "Loja XYZ", "href": "/" }
+  },
+  "header-nav": {
+    "type": "NavigationMenuRoot",
+    "children": ["header-nav-links"]
+  },
+  "header-nav-links": {
+    "type": "NavigationLinkList",
+    "props": {
+      "links": [
+        { "label": "Ofertas", "href": "/ofertas" },
+        { "label": "Novidades", "href": "/novidades" }
+      ]
+    }
+  },
+  "slot": {
+    "type": "Slot"
+  }
+}
+```
+
+Element ids double as content keys for content-backed children, so name them for the sub-feature (`header-nav-links`) rather than for its current placement (`header-item-2`).
+
+---
+
+## Common mistakes
+
+- **`Header`, `HeaderSection`, `PageHeader`, `SiteHeader`, or `Navbar`.** The correct name is `HeaderRoot`.
+- **Using `Container` for the header band.** `Container` renders a `<div>` with no landmark. Use `HeaderRoot` for the band and `Container` for grouping inside it.
+- **Nesting `HeaderRoot` inside a `section` or inside the page-content slot.** It must sit at the top level of the layout, as a sibling of the `Slot`, or the `banner` landmark disappears.
+- **Adding a `HeaderRoot` per page.** The header belongs in the shared layout so every page inherits one copy; a page that should carry no header references a layout that defines none.
+- **Wrapping the navigation row in a second `HeaderRoot`.** Two of them means two `banner` landmarks. Group extra rows with `Container` inside the one header.
+- **Expecting props for the header's content.** `HeaderRoot` has none — the logo, links and labels live in the child elements.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `HeaderRoot` | The header band: background, full-width padding, bottom border, and the arrangement of its inner blocks | `w-full flex items-center gap-[24px] px-[16px] py-[12px] border-b border-[#E5E5E5] bg-white` |
+
+The hook is `data-fs-header`, so a store-level swatch can target the whole region without touching the sub-features inside it.
+
+```json
+{
+  "header": {
+    "type": "HeaderRoot",
+    "style": ["sticky", "top-0", "z-10", "w-full", "flex", "items-center", "gap-[24px]", "bg-white", "px-[16px]"],
+    "children": ["header-logo"]
+  },
+  "header-logo": {
+    "type": "Logo",
+    "props": { "src": "/logo.svg", "alt": "Loja XYZ" }
+  }
+}
+```
+
+---
+
+## Related
+
+- [[footer-root]] — the same idea at the other end of the page; renders `<footer>` and exposes `contentinfo`.
+- [[container]] — the generic layout wrapper; renders a `<div>` with no landmark, and groups blocks *inside* `HeaderRoot`.
+- [[logo]] — the brand mark that opens the header and links home.
+- [[navigation-link-list]] — the CMS-editable link collection the navigation row renders.
+- [[region]] — the postal-code control that sits in the header's actions cluster.
+- [[account-entry-point]] — the session-aware sign-in / my-account control, which needs a `SessionRoot` above the header.