Spec — gov.br Federal Header (barra gov.br)

Federal-only component of the govbr design system (kind = full). It has no look-only M3 parity — it is structurally gov.br (design-RFC-014 F2c). Renders only under the govbr DS; other presets do not emit it.

Where it fits

The federal header is the top-most band of a federal gov.br page. It is additive above the product's own top bar (app-layout/topbar-placement.kmd), never a replacement:

┌────────────────────────────────────────────────────────────┐
│  ▸ gov.br        órgão do governo        A− A+ ⚫  VLibras   │ ← federal header (this spec)
├────────────────────────────────────────────────────────────┤
│  ProductLogo    nav…            search        KoderUserBadge │ ← product top bar (topbar-placement.kmd)
├────────────────────────────────────────────────────────────┤
│  page content …                                             │

The product top bar keeps its own contract (user badge, nav, actions — all unchanged); this bar sits above it and carries the government identity. The two never merge.

R1 — Placement & composition

• The federal header is the first element in the document, above the product top bar and above any skip-link target's visible chrome (the eMAG skip-link's first stop is still "skip to main content"; the federal bar is not a nav landmark to trap in).
• It is full-bleed (edge-to-edge), pinned to the top; it MUST respect the top safe-area inset (app-layout/safe-area.kmd) on mobile/PWA.
• It is additive — a product MUST NOT replace or fold its own top bar into it, and MUST NOT move the KoderUserBadge/KoderSignInButton into it (those stay in the product top bar per topbar-placement.kmd).
• Sticky behavior: the federal bar MAY scroll away with the page while the product top bar stays sticky, OR both stay pinned — a product picks one; it MUST NOT pin the federal bar while letting the product bar scroll under it (that inverts the hierarchy).

R2 — Anatomy

• Height: 40–48 px (Compact may reduce to 40; Default 44–48).
• Background: gov.br federal blue --govbr-blue-warm-vivid-70 (#1351B4) on a dark bar, OR white bar with blue signature — the govbr DS preset fixes which; a product does not recolour it (federal identity is fixed).
• Signature colour/asset: fixed by the federal brand; never tinted by product tokens.
• Type: govbr Rawline (UI) per the govbr token set.

R3 — Access affordances (federal-mandatory)

• Contrast / font-size: A− and A+ adjust the page root font-size step; the high-contrast toggle flips a forced-colors-friendly high-contrast theme. These are the eMAG-standard reading aids and MUST be keyboard-operable + announced.
• VLibras: the trigger that mounts the VLibras (Libras / Brazilian Sign Language) translator widget. The header exposes the trigger; the widget itself is the external VLibras integration.
• On Compact these affordances MAY collapse into a single "Acessibilidade" menu, but MUST remain reachable (never dropped).

R4 — Responsiveness

Uses logical properties (margin-inline, text-align: start/end) so it mirrors under dir="rtl" — though gov.br is pt-BR (LTR), the component obeys i18n/rtl-bidi.kmd R1.

R5 — Accessibility (eMAG 3.1 + WCAG 2.2 AA)

• The bar is a role="banner" region OR a <nav aria-label="Barra do governo federal"> wrapping the federal links; the product's own role="banner" is the product top bar — exactly one top-level banner landmark; the federal bar uses a distinct labelled nav.
• gov.br signature link has an accessible name ("gov.br — Portal do Governo Federal").
• Access affordances (A−/A+/contrast/VLibras) are real buttons with labels, keyboard operable, focus-visible; the high-contrast toggle exposes aria-pressed.
• Meets the govbr manifest a11y profile — WCAG 2.2 AA + eMAG 3.1 + forced-colors (stack#419).

R6 — Per-preset

R7 — Forbidden patterns

• ❌ Replacing/absorbing the product top bar into the federal bar (they are additive).
• ❌ Moving KoderUserBadge/KoderSignInButton into the federal bar.
• ❌ Recolouring the gov.br signature with product tokens.
• ❌ Dropping the access affordances (A−/A+/contrast/VLibras) on any breakpoint.
• ❌ Pinning the federal bar while the product bar scrolls under it (inverts hierarchy).
• ❌ Emitting the federal bar under a non-govbr DS preset.

Cross-link

• design-system/govbr-federal-pack.kmd — the pack this formalizes (R2/R3).
• app-layout/topbar-placement.kmd — the product top bar this composes ABOVE.
• app-layout/safe-area.kmd — top inset rule (mobile/PWA).
• components/govbr-signin.kmd — the "Entrar com gov.br" button (may appear in the product top bar, not this federal bar).
• components/skip-link.kmd — the eMAG bypass-block; its first stop is main content.
• themes/verge.kmd — token layer (govbr overrides).

Requirements (testable)

Requirement: Federal header is additive above the product top bar {#req-govbr-fedheader-additive}

The gov.br federal header SHALL render as the top-most full-bleed band ABOVE the product's own top bar and SHALL NOT replace it, fold it in, or relocate the KoderUserBadge/KoderSignInButton out of the product top bar.

Scenario: Federal bar sits above an unchanged product top bar

• GIVEN a federal gov.br surface with the govbr DS active
• WHEN the page renders
• THEN the gov.br federal bar is the first band at the top of the document
• AND the product top bar renders directly below it with its user badge unchanged
• AND no user badge or sign-in control is moved into the federal bar

Requirement: Federal signature links to gov.br and is not recoloured {#req-govbr-fedheader-signature}

The federal header SHALL carry the gov.br federal signature linking to https://www.gov.br with an accessible name, and the signature asset/colour SHALL NOT be tinted by product tokens.

Scenario: Signature is the fixed federal asset

• GIVEN the rendered federal header
• WHEN the gov.br signature is inspected
• THEN it links to https://www.gov.br
• AND it exposes an accessible name identifying the federal government portal
• AND its colour is the fixed federal signature, not a product-token tint

Requirement: Access affordances are always reachable {#req-govbr-fedheader-access}

The federal header SHALL expose the standard federal access affordances (font-size A−/A+, high-contrast toggle, VLibras trigger) as keyboard-operable labelled controls, and SHALL keep them reachable on every breakpoint (collapsing into an "Acessibilidade" menu on Compact rather than dropping any).

Scenario: Compact keeps every affordance behind a menu

• GIVEN the federal header at a Compact window width
• WHEN the access affordances do not fit inline
• THEN they collapse into an "Acessibilidade" menu
• AND every affordance (A−, A+, contrast, VLibras) remains reachable from it
• AND each is keyboard-operable with a visible focus indicator

Requirement: Federal-only rendering {#req-govbr-fedheader-federal-only}

The federal header SHALL be emitted only when the govbr design system is the active preset; under any other preset it SHALL NOT render.

Scenario: Non-govbr surface has no government bar

• GIVEN a surface whose active design system is not govbr
• WHEN the shared layout evaluates whether to include the federal header
• THEN the federal header is not emitted
• AND the product top bar is the top-most band