---
system: carbon
category: guidance
topic: components/ui-shell
content_type: guidance
status: latest
version_label: "Carbon v11"
retrieved: 2026-05-12
source_url: https://carbondesignsystem.com/components/UI-shell-header/usage/
derived_from:
  - kb/design-systems/carbon/guidance/foundations/color-system
  - kb/design-systems/carbon/guidance/foundations/themes
tags: [component, navigation, ui-shell, header, side-nav, carbon, ibm]
---

# 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

```jsx
<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.

```jsx
<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:

```jsx
// 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.

```jsx
<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