Overview
Foundations
Brand
Colors
Typography
Spacing & Layout
Semantic Tokens
Icons
Shadows
Components
Patterns
Design System
Header
The header is the top-level navigation bar that provides brand identity, quick actions (search, notifications, colour mode toggle), and user context via an avatar. All colours are driven by semantic tokens that adapt automatically between light and dark modes.
Preview
Interactive header with a functional dark mode toggle. Click the moon/sun icon to switch colour modes and see how all tokens adapt in real time.
Specifications
Header
Height
56px
Padding
10px 20px
Logo Height
36px
Icon Size
16px
Icon Buttons
Padding
8px
Border Radius
6px
Min Size
32px 32px
Notification Badge
Font Size
11px
Min Width
16px
Height
16px
Border Radius
Full
Avatar
Size
32px
Border Radius
Full
Font Size
12px
Font Weight
Bold 700
Divider
Height
24px
Width
1px
Margin
0 8px
Theming
The header uses shared semantic tokens for backgrounds, borders, and text — plus component-specific tokens for the notification badge and avatar. All values adapt automatically between light and dark modes.
Colors
Property
Token
Light
Dark
Background
--bg-card
white
gray.800
Border Bottom
--border
gray.200
gray.700
Icons
--text-faint
gray.400
gray.600
Divider
--border
gray.200
gray.700
Notification Badge
Property
Token
Light
Dark
Background
--count-badge-bg
red.500
red.500
Text
--count-badge-text
white
white
Icon Button States
Property
Token
Light
Dark
Hover BG
--bg-hover
gray.50
gray.800
Active BG
--bg-active
gray.200
gray.700
Focus Ring
--focus-ring
brand.600
brand.600
Avatar
Property
Token
Light
Dark
Background
--avatar-bg
secondary.100
secondary.700
Text
--avatar-text
secondary.700
secondary.100
Best Practices
Do
Keep the header height fixed at 56px for layout consistency
Use semantic tokens so the header adapts to colour mode automatically
Place the logo on the left and user actions on the right
Use a vertical divider to visually separate action icons from the avatar
Don't
Don't overcrowd the header with too many actions — keep it focused
Don't hardcode colours — use semantic tokens for theme support
Don't hide the notification badge when the count is zero — simply omit it
Don't forget hover and focus states on icon buttons for accessibility
Accessibility
Landmark Role
Use the <header> element or role="banner" so assistive technologies identify the header as a navigation landmark. This helps screen reader users jump directly to the header.
Keyboard Navigation
All icon buttons must be focusable and activated with Enter or Space. Tab order should flow left-to-right through the action icons and avatar. Visible focus rings use the --focus-ring token.
Labels and Announcements
Every icon button requires an aria-label (e.g., "Toggle color mode", "Search", "8 notifications"). The notification badge count should be announced via aria-label on the bell button, not just visually.