Spec — Navigation containers

Facet *isual*of Koder Design. Material parity: https://m3.material.io/components/navigation-bar, https://m3.material.io/components/navigation-rail, https://m3.material.io/components/navigation-drawer.

Adaptive trio — pick by window-size class

*ame component family*— destinations / icons / order stay consistent; only the layout container swaps. Implementations must share state (selected destination, badges) across the three.

R1 — Navigation bar (Compact)

Anatomy:

┌──────────────────────────────────────────────┐
│  ⌂        ⌥        ⚙                          │
│ Home    Inbox   Settings                       │
└──────────────────────────────────────────────┘

• *eight* 80 px (incl. safe-area bottom inset)
• *tems* 3-5 destinations (never 1 or 2 — use back nav or tabs;

  never > 5 — use rail / drawer)

• *ontainer bg* surface-container
• *eritem* 24 px icon + 12 px gap + label (`labelmedium`)
• *elected* pillshaped tonal `secondarycontainer` behind icon +

  bold label color

• Optional: badge on icon (per components/badges.kmd)
• *afe area* respects gesture-nav inset on Android / iOS

R2 — Navigation rail (Medium / Expanded compact)

Anatomy:

┌──────┐
│  ☰   │  ← optional menu button
│  ────│
│  ⌂   │
│ Home │
│      │
│  ⌥   │
│ Inbox│
│      │
│  ⚙   │
│ Set… │
│  ────│
│  ⊕   │  ← optional FAB at top OR bottom
└──────┘

• *idth* 80 dp
• *tems* 3-7 destinations
• *eritem* 24 px icon + 4 px gap + 1line label

  (label-medium, can be hidden via prop)

• *elected indicator* full-width tonal block behind item (height

  56 px), with secondary-container bg

• *ptional FAB* anchored to top (after menu button) OR bottom
• *eader* optional menu / app icon button at top

R3 — Navigation drawer (Expanded / Large)

Two sub-variants:

Anatomy (standard drawer):

┌─────────────────────┐
│  App name           │
│ ──────────────────  │
│  ⌂   Home           │
│  ⌥   Inbox      • 3 │
│  ⚙   Settings       │
│ ──────────────────  │
│  Recent             │
│  📄  Document 1     │
│  📄  Document 2     │
│  📄  Document 3     │
│ ──────────────────  │
│  + New              │
└─────────────────────┘

• *idth* 256-360 dp (default 320 dp)
• *tems* fullwidth list rows; selected has `secondarycontainer`

  tonal bg

• *er-item* 24 px leading icon + 12 px gap + label

  (label-large) + optional trailing badge

• *ection headers* subheader divider (per dividers.kmd § R5)
• *ontainer bg* surface-container-low (standard) /

  surface-container (modal, with elevation)

R4 — Consistent state across variants

Implementations expose a single "destinations" source of truth; the view layer renders the appropriate container per window-size class.

R5 — Selected state animation

Reduced motion: instant change, no slide.

R6 — Header content

Drawer header is title-medium (16/24, weight 500); app icon 32 px to the left.

R7 — Footer content

R8 — Modal drawer mode

Modal drawer slides in from the edge with a scrim (40% black overlay on the rest of the page).

• Trigger: menu icon button in app bar (☰)
• Dismiss: scrim tap, Esc key, swipe-left gesture, menu icon again
• Width: same 256-360 dp
• Z-order: above app bar, above bottom bar, below dialogs

Use modal drawer on Compact / Medium classes when standard drawer would dominate the screen. Switch to standard drawer at Expanded / Large by default.

R9 — Standard drawer mode

Always visible alongside main content. Used at Expanded / Large classes for primary navigation.

• No scrim
• No swipetodismiss
• Always reflects current destination
• Can be collapsed to rail via prop (usercontrolled or layoutdriven)

R10 — Accessibility

• Container: role="navigation" + aria-label="Primary"
• Each destination: role="link" (if it navigates URL) OR

  role="button" (if it triggers in-app routing)

  • aria-current="page" on selected destination
• Badges: included in destination's aria-label

  ("Inbox, 3 unread")

• Modal drawer trigger: aria-haspopup="dialog" + aria-expanded
• Modal drawer container: role="dialog" + aria-modal="true" +

  aria-labelledby (pointing to drawer header) when open

• Keyboard:
  • Tab: enters first destination
  • Arrow Up / Down (rail / drawer) OR Left / Right (bar): moves

    between destinations

  • Enter / Space: navigates
  • Esc: closes modal drawer
• Skiptocontent link before nav for screen readers (matches app

  bar contract)

R11 — States

R12 — Density

R13 — Per-preset variation

R14 — Forbidden patterns

• ❌ Navigation bar on Expanded / Large window-size class (use rail

  or drawer)

• ❌ Navigation drawer on Compact (use bar or modal drawer)
• ❌ Mixing bar + drawer on the same screen (pick one container)
• ❌ Navigation bar with 1 or 2 items (use back navigation or tabs)
• ❌ Navigation bar with > 5 items (overflow to drawer / rail)
• ❌ Tab bar pattern (URL-distinct destinations as Tabs component) —

  use nav containers when destinations are top-level

• ❌ Navigation rail without selected indicator (defeats purpose)
• ❌ Standard drawer on Compact (consumes too much screen real estate)
• ❌ Navigation that hides on scroll (primary nav must always be

  reachable; secondary or sticky toolbars can hide)

• ❌ Bar / rail with destinations that route to different orgs /

  tenants (use tenant switcher in drawer header instead)

Cross-link

• app-layout/window-size-classes.kmd — adaptive container per class
• app-layout/safe-area.kmd — bar bottom inset rule
• themes/elevation.kmd — modal drawer scrim role
• themes/color-roles.kmd — secondary-container for selected
• themes/typography.kmd — label-medium / label-large
• interaction/states.kmd — hover / focused / selected layers
• components/badges.kmd — per-destination badge contract
• components/tabs.kmd — sibling for *ithin-context*switching

  (NOT for top-level destinations)

• components/app-bars.kmd — modal drawer trigger lives in top bar
• foundations/elements.kmd — Container + Navigator families