# Layout containers in detail

Companion to `../SKILL.md` for the `hig-components-layout` skill.

## Tab bars

- Keep tabs few and stable. Each tab keeps its own navigation state; switching
  back returns people to where they left off.
- Never hide or disable a tab because of state. Show the tab and explain
  inside it (an empty state or sign-in prompt).
- Badges (`.badge(3)`) are for counts people act on, not marketing.
- Minimize behavior, the bottom accessory, the search tab and the iOS 27
  prominent tab are in [bars-and-tabs.md](bars-and-tabs.md).

## Sidebars and split views

- The sidebar lists destinations, grouped into sections when there are many.
  It does not hold actions or forms.
- Let the system collapse columns in compact width;
  `NavigationSplitView` becomes a stack on iPhone automatically. Use
  `preferredCompactColumn` to choose what shows first.
- Keep selection visible: the chosen sidebar row stays highlighted while its
  detail is shown.
- iOS 26 draws the sidebar as a glass layer floating over content. Use
  `.backgroundExtensionEffect()` on hero images in the detail column so they
  extend visually beneath the sidebar instead of stopping at its edge.

## Navigation stacks and bars

- The title names the current place. Use large titles at the root of a
  hierarchy and inline titles deeper in.
- The back button shows the previous title or "Back"; never replace it with a
  custom control that breaks the edge-swipe gesture.
- Drive navigation from data: a `NavigationPath` or a typed selection binding
  makes deep links and state restoration straightforward.
- Put no more than a couple of frequent actions in the bar. Secondary actions
  go in a `Menu` behind an ellipsis item.

## Toolbars

- Declare actions with `.toolbar` and semantic placements so the system
  positions them per platform. Grouping, `ToolbarSpacer`, overflow, priority
  and pinning are in [bars-and-tabs.md](bars-and-tabs.md).
- Use `.toolbarRole(.editor)` on document-style screens and let people
  customise Mac and iPad toolbars with `id`-based toolbar items.

## Scroll views

- Content should scroll under bars and the tab bar; the scroll edge effect
  keeps controls legible on iOS 26.
- Show scroll indicators for long content, and use `.scrollTargetBehavior(.paging)`
  or `.viewAligned` only when the content really is paged.
- Never nest two scroll views on the same axis.
- Use `.safeAreaInset(edge:)` for a persistent footer (a checkout summary)
  so the content scrolls clear of it.

## Windows and panels (iPadOS, macOS, visionOS)

- Support multiple windows when people might compare two items; use
  `WindowGroup(for:)` with a value so each window restores its item.
- Open auxiliary windows with `openWindow(value:)`; a Mac utility panel is a
  `Window` or `UtilityWindow` scene, not a sheet.
- Size layouts with flexible frames and size classes so the same scene works
  from a narrow iPad split to a full Mac display.
- Add `Settings` for Mac preferences instead of a settings tab.

## Adapting across sizes

1. Check compact width (iPhone portrait, iPad slide over) and regular width.
2. Confirm split views collapse to a sensible first column.
3. Confirm tab bars turn into a sidebar where `.sidebarAdaptable` is used.
4. Test the largest Dynamic Type size: bars stay usable, content scrolls.
5. Test right-to-left: back buttons, sidebars and swipe edges mirror.