Top-nav

Navigation principale horizontale, en liens inter-pages. Visuellement inspirée du pattern tabs (indicateur bordure pleine hauteur), mais sémantiquement correcte : <nav> + <a> + aria-current="page", jamais role="tablist". Main horizontal navigation, inter-page links. Visually inspired by the tabs pattern (full-height border-bottom indicator), but semantically correct: <nav> + <a> + aria-current="page", never role="tablist".

Le site Agentica lui-même n'utilise pas <agtc-top-nav> sur ses propres pages — sa navigation est du HTML écrit à la main (.site-nav) qui consomme les mêmes tokens (ADR-087). Ce choix d'intégration du site ne change rien au contrat ci-dessous, applicable à tout consommateur qui monte le vrai composant. The Agentica site itself does not mount <agtc-top-nav> on its own pages — its nav is hand-written HTML (.site-nav) consuming the same tokens (ADR-087). This site-integration choice does not change the contract below, which applies to any consumer that mounts the real component.

AperçuPreview

Distinction avec `agtc-tabs`Distinction from `agtc-tabs`

	`agtc-top-nav`	`agtc-tabs`
Sémantique ARIAARIA semantics	`role=navigation` + `<a>`	`role=tablist` + `role=tab` + `role=tabpanel`
Navigation clavierKeyboard navigation	Tab + Enter	Flèches ←/→ + Home/EndArrows ←/→ + Home/End
État actifActive state	`aria-current="page"`	`aria-selected="true"`
EffetEffect	Navigation inter-pagesInter-page navigation	Panneau de contenu in-pageIn-page content panel

Règles absoluesAbsolute rules

nav-label toujours fourni — aria-label obligatoire pour les technologies d'assistancenav-label always provided — aria-label mandatory for AT
Bouton d'adoption marqué cta:true — jamais comme un onglet standardAdoption button marked cta:true — never as a standard tab
Jamais role="tablist" — c'est une navigation inter-pagesNever role="tablist" — this is inter-page navigation
Jamais de fond rempli persistant sur le lien actifNever a persistent filled background on the active link

Tokens de composantComponent tokens

Token CSS	RéférenceReference	ValeurValue
`--agtc-component-top-nav-tab-color`	`semantic.color.text.secondary`	#646464
`--agtc-component-top-nav-tab-color-hover`	`semantic.color.text.primary`	#202020
`--agtc-component-top-nav-tab-background-hover`	`semantic.color.background.subtle`	#f0f0f0
`--agtc-component-top-nav-tab-color-active`	`semantic.color.action.primary`	#007a68
`--agtc-component-top-nav-tab-indicator-color`	`semantic.color.action.primary`	#007a68
`--agtc-component-top-nav-tab-font-weight-active`	`semantic.fontWeight.bold`	700
`--agtc-component-top-nav-tab-focus-ring`	`semantic.color.border.focus`	#007a68
`--agtc-component-top-nav-cta-background`	`semantic.color.action.primary`	#007a68
`--agtc-component-top-nav-cta-background-hover`	`semantic.color.action.primary-hover`	#0d3d38
`--agtc-component-top-nav-cta-color`	`semantic.color.text.on-action`	#ffffff
`--agtc-component-top-nav-cta-radius`	`semantic.radius.control`	6px

AccessibilitéAccessibility

<nav aria-label="…"> — landmark obligatoire, nommé via nav-label<nav aria-label="…"> — required landmark, named via nav-label
aria-current="page" appliqué automatiquement au lien actifaria-current="page" automatically applied to the active link
:focus-visible — anneau visible sur tous les liens (WCAG 2.4.7):focus-visible — visible ring on all links (WCAG 2.4.7)
:visited neutralisé — cohérence visuelle (ADR-047):visited neutralized — visual consistency (ADR-047)
Cibles tactiles ≥ 44px (hauteur d'en-tête 64px) — WCAG 2.5.5Touch targets ≥ 44px (header height 64px) — WCAG 2.5.5

ImplémentationImplementation

<agtc-top-nav nav-label="Main navigation"></agtc-top-nav>
<script>
  const nav = document.querySelector('agtc-top-nav');
  nav.items = [
    { label: 'Tokens',      href: '../tokens/' },
    { label: 'Components',  href: '../components/' },
    { label: 'Get started', href: '../get-started.html', cta: true },
  ];
  nav.current = window.location.pathname;
</script>

DOs et DON'TsDOs and DON'Ts

À faireDo

Gérer la langue (labelFr/labelEn) côté consommateur, pas dans le composantHandle language (labelFr/labelEn) on the consumer side, not in the component
Utiliser pour une navigation inter-pages réelleUse for real inter-page navigation

À éviterDon't

Utiliser pour un contenu in-page sans changement de page (→ agtc-tabs)Use for in-page content with no page change (→ agtc-tabs)
Ajouter un border-radius aux liens d'ongletAdd border-radius to the tab links

UX Patterns Reference

Pattern	Source	Applied	Justification
Navigation landmark `<nav aria-label>`	W3C WAI Landmarks	✅	Invisible to AT without a landmark
`aria-current="page"` on the active link	WCAG 2.4.4 / 4.1.2	✅	CSS class alone is insufficient
Full-height border-bottom indicator	NN/g — Horizontal Navigation	✅	Filled background = toggled button
No `role="tablist"` for inter-page nav	W3C APG Tabs	✅	Incorrect semantics without a panel
Visually distinct CTA (pill button)	IxDF — Clear primary action	✅	Adoption is an action, not a destination
`:visited` neutralized	ADR-047	✅	Navigation ≠ read/unread content
Mobile hamburger + `aria-expanded`	NN/g — Mobile nav	✅	No horizontal scrolling