Skip to main content

GlobalHeader

The GlobalHeader is a persistent navigation element that appears at the top of every page in the product. It provides users with a consistent anchor point for orientation, navigation, and access to system-wide actions regardless of where they are in the application.

Status: Overview, When to Use, When NOT to Use, and the responsive breakpoint rules below are verbatim from the Naos Figma documentation page (file wK67Nv3wkKyQCFPK5RjyL8, node 5731:3859, "🧩 Naos – Navigation Components", checked 2026-08-19). Nothing below is invented.

Source: DTSL/design-system → packages/product/organisms/globalHeader/src/types/GlobalHeader.types.ts (package @dtsl/global-header, exported as GlobalHeader, GlobalHeaderItems)

Props (verbatim from source)​

export interface GlobalHeaderProps {
	logo: LogoProps
	leftActions?: LeftActions | null
	rightActions?: RightAction[] | null
	className?: string
	hasNavigation?: boolean
	badgeMetaData?: BadgeData | null
}

Also exports RightAction, LeftActions, its own LogoProps (distinct from the atomic Logo's LogoProps), BadgeData, NavActionProps, NavigationMenuActionProps, GlobalHeaderItemType — see source for full shapes.

Anatomy​

From the Figma "Anatomy" diagram (9 labeled parts): 1. Container, 2. Logo, 3. Breadcrumbs (shown as "Level / Level / Level" — optional), 4. Ask AI action, 5. Usage and Plans status/link, 6. Help (icon button), 7. Settings (icon button), 8. Notifications (bell icon — carries a Badge, confirming badgeMetaData targets this), 9. Account/company switcher (e.g. "MyGreatCompany... ⌄").

Items 4–9 populate rightActions; the breadcrumb (3) is the likely target of leftActions.

Real variants (from Figma component properties)​

  • Type: Default / With Logo / Wizard
  • Device: Desktop / Tablet (640–1024px) / Mobile (360–640px)
  • A When nav open state exists for Tablet and Mobile
  • A Loading state exists (skeleton placeholders for logo/breadcrumb/actions)

Real composition, confirmed by the Figma preview card: GlobalHeader is shown together with PageHeader and Navigation (the lateral nav sidebar) as one composed layout — GlobalHeader spans the full top, Navigation occupies the left rail below it, and PageHeader sits in the remaining content area. This matches hasNavigation in the props.

When to Use​

The GlobalHeader is not optional. It should be present on every page of the product, including empty states, error pages, and loading states.

When NOT to Use​

  • Onboarding or authentication flows: full-screen flows such as login, sign-up, or guided setup may suppress the GlobalHeader to reduce distraction.
  • Embedded or iframe contexts: when the product is embedded inside another surface, the host application's navigation takes precedence.

CRITICAL: Real responsive action-collapsing rule (verbatim from Figma)​

More than 406px = 4 buttons + hamburger Between 406 and 360px = 3 buttons + hamburger

This means the number of visible rightActions buttons before the rest collapse into a hamburger/overflow menu depends on the available header width, with concrete thresholds at 406px and 360px — a real, specific implementation constraint, not a general guideline.

Decision Logic​

Is this an onboarding/auth full-screen flow, or an embedded/iframe context?
  YES → GlobalHeader may be suppressed
  NO  → GlobalHeader must be present, on every page including empty/error/loading states

Does the page need a Logo variant?
  Standard app page           → Type = Default
  Marketing/logged-out context → Type = With Logo
  Multi-step flow              → Type = Wizard

Viewport width for action buttons:
  > 406px      → show up to 4 action buttons + hamburger for the rest
  360px–406px  → show up to 3 action buttons + hamburger for the rest

Accessibility​

TODO — not covered on this Figma page (Overview/Usage text was read; no dedicated Accessibility section was found). Needs UX/product input.

Common Mistakes​

  • ❌ Omitting the GlobalHeader on empty states, error pages, or loading states — it's required on all of them, not just "normal" pages
  • ❌ Hardcoding a fixed number of visible action buttons instead of respecting the 406px/360px collapse breakpoints
  • TODO — remaining items need UX/product input.