When to use it

Use HeaderSection when the storefront wants a single supported section API for the global header but still needs a real escape hatch into composition.

It is the right starting point when the page needs:

• a complete top shell quickly
• promo, utility, primary nav, actions, and mobile navigation in one supported family
• benchmark-style variation without forking the section
• an upgrade path that stays inside the public navigation primitives

Preferred usage now

HeaderSection now has two public modes:

Preferred: child slots

Use the compound family when the app wants to explicitly arrange the section regions.

• HeaderSection.Promotion
• HeaderSection.Mobile
• HeaderSection.Desktop
• HeaderSection.Utility
• HeaderSection.Main
• HeaderSection.Logo
• HeaderSection.PrimaryNav
• HeaderSection.Actions
• HeaderSection.MegaMenu
• HeaderSection.MobilePanel
• HeaderSection.MobileFooter

Convenience path: structured props

The original prop API still works:

• promo
• utility
• primaryNav
• featured
• actions
• mobileNav

Treat that prop surface as the fast path, not the long-term composition ceiling.

Family ownership map

HeaderSection is a section-first wrapper built on the public family layer.

• promo zone → PromotionBar
• shell zone → StoreHeader
• utility zone → UtilityNav
• primary navigation zone → PrimaryNav
• featured desktop panel zone → MegaMenu
• mobile navigation zone → MobileNav / MobileMenuDrawer

That ownership map is still the point of the component. It is a useful section, not a black-box template.

Easy path and open path

The easy path is the structured prop API:

• promo
• utility
• primaryNav
• featured
• actions
• mobileNav

Inside primaryNav.items, the preferred keyed model is:

• id — stable ownership key for the nav item
• trigger — desktop trigger label/href overrides
• panel — desktop mega-menu categories and featured items
• mobile — mobile drawer label/href/children overrides

For migration, HeaderSection still accepts the legacy flat NavItem fields href, label, megaMenuCategories, and megaMenuFeatured and maps them forward into the keyed model.

The open path is selective replacement.

Right now the strongest explicit seam is the featured mega-menu region through featured.content. That lets the app swap one major zone while keeping the rest of the section intact.

The promo region is intentionally narrower today. If the top strip needs richer campaign hierarchy, multiple support lines, or a stronger CTA treatment, drop to StoreHeader.Promotion instead of overloading HeaderSection.promo.

Behavior and theming guidance

HeaderSection should be the first answer for most storefront-header questions because it keeps the navigation family visible while staying fast to adopt.

Lead with the keyed nav branches for all new examples and app code. Treat the flat legacy fields as migration-only compatibility, not the preferred authoring shape.

Use it to prove different navigation rhythms through content and component-set shifts:

• promo-heavy commerce
• campaign-led browse flow
• restrained editorial chrome

Use variant="transparent" or variant="overlay" for hero-led openings and variant="default" for standard content and catalog pages.

Use the composition-first path when:

• desktop and mobile structure should diverge more clearly
• the mega-menu region wants editorial or campaign content
• the mobile drawer needs a branded closing section
• the app wants to keep the section abstraction but own the section order directly

If the page grows beyond the section contract entirely, drop to StoreHeader and the lower-level family directly instead of overloading HeaderSection.