Carbon Design System — UI Shell

Overview

The UI Shell is Carbon's application-level navigation framework. It provides the structural chrome for IBM Cloud and enterprise products: a persistent header, an optional side panel (left nav), and an optional right panel (switcher/notifications). These elements combine to form the outer shell of any Carbon-based app.

Shell components are styled with the g100 (dark) or g10 (light) theme regardless of the page theme — the shell is always themed independently.

Components

Header (`Header`, `HeaderName`, `HeaderNavigation`)

The full-width top bar. Contains:

Product name — HeaderName with optional prefix: [IBM] Product name
Global nav (optional) — HeaderNavigation with HeaderMenuItem links
Action bar (optional) — icon buttons for search, notifications, app switcher
Menu button — hamburger icon; visible on mobile and when side nav is present

<Header aria-label="IBM Platform">
  <SkipToContent />
  <HeaderMenuButton aria-label="Open menu" onClick={toggleSideNav} isActive={isSideNavExpanded} />
  <HeaderName href="/" prefix="IBM">Platform</HeaderName>
  <HeaderNavigation aria-label="Main">
    <HeaderMenuItem href="/dashboard">Dashboard</HeaderMenuItem>
    <HeaderMenuItem href="/reports">Reports</HeaderMenuItem>
    <HeaderMenu aria-label="Settings" menuLinkName="Settings">
      <HeaderMenuItem href="/profile">Profile</HeaderMenuItem>
      <HeaderMenuItem href="/preferences">Preferences</HeaderMenuItem>
    </HeaderMenu>
  </HeaderNavigation>
  <HeaderGlobalBar>
    <HeaderGlobalAction aria-label="Search" onClick={handleSearch}>
      <Search size={20} />
    </HeaderGlobalAction>
  </HeaderGlobalBar>
</Header>

SideNav

Left panel for hierarchical navigation. Two modes:

Rail (icon-only, collapsed, 48px wide) — shows icons with tooltips; used on wider viewports when space is at a premium.

Full (expanded, 256px wide) — shows icons + labels; can be fixed or expandable.

<SideNav aria-label="Side navigation" expanded={isSideNavExpanded} isRail>
  <SideNavItems>
    <SideNavLink renderIcon={Dashboard} href="/dashboard">Dashboard</SideNavLink>
    <SideNavMenu renderIcon={Document} title="Reports">
      <SideNavMenuItem href="/reports/monthly">Monthly</SideNavMenuItem>
      <SideNavMenuItem href="/reports/annual">Annual</SideNavMenuItem>
    </SideNavMenu>
    <SideNavLink renderIcon={Settings} href="/settings">Settings</SideNavLink>
  </SideNavItems>
</SideNav>

SideNavLink — top-level flat destination
SideNavMenu — expandable group; contains SideNavMenuItem children
SideNavMenuItem — nested item, no icon (text only)
Maximum nesting: 2 levels (menu → menu item)

SideNavDivider

Visual separator between logical groups within the side nav.

Panel (right panel)

Optional slide-in panel from the right. Used for notifications, help, or the app switcher. Not part of the core shell by default; composed with HeaderPanel + Switcher.

Responsive behavior

Viewport	Header	SideNav
≥ 1056px (lg)	Full, all items visible	Fixed expanded or rail
672–1055px (md)	Truncated nav, hamburger visible	Overlay on hamburger press
< 672px (sm)	Hamburger only	Overlay on hamburger press

On smaller viewports, SideNav becomes an overlay that opens on top of content.

Theming

The shell's background is always themed separately from page content:

// g100 (dark) shell is default for IBM products
<Theme theme="g100">
  <Header>…</Header>
  <SideNav>…</SideNav>
</Theme>
<Theme theme="white">
  <main>…</main>
</Theme>

$shell-header-bg-01 and $shell-side-nav-bg-01 are the relevant tokens (mapped from the shell theme).

SkipToContent

Always include SkipToContent as the first child of Header. It renders a hidden link that appears on keyboard focus and skips to the main content region, satisfying WCAG 2.4.1.

<Header>
  <SkipToContent />
  …
</Header>

Accessibility

Header: role="banner", aria-label required
SideNav: role="navigation", aria-label required
Active link: aria-current="page" on the current SideNavLink or HeaderMenuItem
HeaderMenuButton: aria-expanded reflects open/closed state of side nav
SideNavMenu (expandable): aria-expanded on the trigger button
Focus order: SkipToContent → Header actions → SideNav → main content

Ui Shell