Spec — "Entrar com gov.br" Sign-in (Login Único)

Federal-only component of the govbr design system (kind = full). The button surface + reliability seal are gov.br-fixed; the OAuth/OIDC flow behind it is the external-provider contract, not re-specified here.

Where it fits

The "Entrar com gov.br" button is the entry point to Login Único — gov.br as an external OIDC provider (auth/oauth-client-external-providers.kmd). It is the gov.br-branded sibling of KoderSignInButton: on a federal surface, it is the sign-in affordance in the product top bar (app-layout/topbar-placement.kmd) or on a sign-in page. After the flow returns, the account carries a reliability seal (selo de confiabilidade) that callers needing an assurance level surface.

R1 — The button (fixed federal brand)

The button's label, seal/mark, and colour are fixed by the federal brand — a product does not restyle them:

• Label: exactly "Entrar com gov.br" (pt-BR; this is the official string — never translated or paraphrased, even on an EN surface, per the gov.br brand).
• Mark: the gov.br "b" avatar/seal at the start of the button.
• Colour: gov.br federal blue --govbr-blue-warm-vivid-70 (#1351B4) fill with white label (primary), matching the govbr button tokens; a secondary/outline variant keeps the blue on white.
• Shape/size: inherits the govbr buttons.kmd sizing (radius, min height 40 px, tap target ≥ 44 px) — it is a real button, not an image link.

It is a <button>/<a role="button"> that starts the OIDC flow; it MUST NOT be a bare image, and its accessible name is its visible label.

R2 — The reliability seal (selo de confiabilidade)

gov.br returns an account trust level — the selo de confiabilidade:

• The seal is surfaced only where the caller needs the assurance level (e.g., a surface that requires Prata+ to proceed). It is NOT decoration on every page.
• The seal SHALL render its level with an accessible name ("Selo de confiabilidade: Prata"), never colour-only (bronze/prata/ouro also differ by label + icon).
• The seal's value comes from the OIDC claims (external-provider spec); this spec fixes only how the level is DISPLAYED.

R3 — Flow hand-off (delegated)

• Pressing the button starts the external-provider OIDC flow with gov.br as the provider — scopes, PKCE, token exchange, refresh, and storage are ALL auth/oauth-client-external-providers.kmd, NOT here.
• On return, the app shows the signed-in account (via the normal KoderUserBadge) and, where required, the seal (R2).
• Failure/cancel states use the standard user-facing error contract (errors/user-facing-messages.kmd) — no gov.br-specific error copy invented here.

R4 — Placement

• On a federal surface, the button replaces KoderSignInButton as the signed-out affordance in the product top bar (topbar-placement.kmd position — right/last on web/desktop), OR is the primary action on a dedicated sign-in page/card.
• It does not live in the federal header bar (govbr-federal-header.kmd); sign-in is product chrome, the federal bar is government identity.
• A surface MAY offer both "Entrar com gov.br" and a native Koder ID sign-in; when both are present, "Entrar com gov.br" follows the external-provider spec's ordering.

R5 — Accessibility (eMAG 3.1 + WCAG 2.2 AA)

• Real button, keyboard-operable, focus-visible, ≥ 44 px tap target.
• Accessible name = "Entrar com gov.br"; the "b" mark is decorative (aria-hidden) since the label already names it.
• The seal is not colour-only (label + icon + accessible name).
• Meets the govbr a11y profile (stack#419): WCAG 2.2 AA + eMAG 3.1 + forced-colors (the button keeps a visible border in forced-colors so the fill is not the only signal).

R6 — Per-preset

R7 — Forbidden patterns

• ❌ Translating/paraphrasing "Entrar com gov.br" (fixed federal string).
• ❌ Recolouring the button or the "b" mark with product tokens.
• ❌ Rendering the seal as colour-only (must carry label + icon + accessible name).
• ❌ Re-specifying the OAuth/OIDC flow here (it is the external-provider spec's).
• ❌ Putting the sign-in button inside the federal header bar (it is product chrome).
• ❌ Surfacing the seal decoratively on surfaces that do not need the assurance level.

Cross-link

• design-system/govbr-federal-pack.kmd — the pack this formalizes (R2/R3).
• auth/oauth-client-external-providers.kmd — the Login-Único OIDC contract (delegated).
• components/buttons.kmd — the button sizing/shape this inherits.
• app-layout/topbar-placement.kmd — where the signed-out affordance sits.
• components/govbr-federal-header.kmd — the sibling federal-only surface (identity bar).
• errors/user-facing-messages.kmd — failure/cancel copy.

Requirements (testable)

Requirement: Fixed federal button surface {#req-govbr-signin-fixed}

The "Entrar com gov.br" button SHALL carry the exact label "Entrar com gov.br", the gov.br "b" mark, and the federal blue colour, none of which SHALL be translated, paraphrased, or recoloured by a product.

Scenario: Button label and colour are federal-fixed on an EN surface

• GIVEN a federal gov.br surface rendered with the EN locale active
• WHEN the sign-in button renders
• THEN its visible label is exactly "Entrar com gov.br" (not translated)
• AND its fill is the gov.br federal blue, not a product-token colour
• AND its accessible name equals the visible label

Requirement: Reliability seal is not colour-only {#req-govbr-signin-seal}

Where a caller surfaces the account reliability seal, it SHALL convey the level (Bronze/Prata/Ouro) by label and icon plus an accessible name, never by colour alone, and SHALL be shown only where the assurance level is needed.

Scenario: Prata seal announces its level

• GIVEN a signed-in gov.br account at the Prata trust level on a surface that requires it
• WHEN the reliability seal renders
• THEN it shows the "Prata" label and its icon
• AND its accessible name is "Selo de confiabilidade: Prata"
• AND the level is not distinguished by colour alone

Requirement: Flow is delegated to the external-provider spec {#req-govbr-signin-delegated}

Pressing the button SHALL start the gov.br external-provider OIDC flow defined by auth/oauth-client-external-providers.kmd; this component SHALL NOT re-specify scopes, token exchange, or storage, and SHALL use the standard user-facing error contract for failure/cancel.

Scenario: Button starts the delegated OIDC flow

• GIVEN the signed-out "Entrar com gov.br" button
• WHEN the user activates it
• THEN the external-provider OIDC flow (gov.br provider) begins
• AND on cancellation the standard user-facing error/cancel copy is shown
• AND no gov.br-specific OAuth parameters are defined by this component

Requirement: Sign-in is product chrome, not the federal bar {#req-govbr-signin-placement}

The "Entrar com gov.br" button SHALL sit in the product top bar (or a sign-in page/card) per app-layout/topbar-placement.kmd, and SHALL NOT be placed inside the gov.br federal header bar.

Scenario: Button lives in the product top bar

• GIVEN a federal gov.br surface that is signed out
• WHEN the layout renders
• THEN the "Entrar com gov.br" button is in the product top bar's sign-in position
• AND it is not rendered inside the federal header (government identity) bar