Hig Components Layout

Apple HIG: Layout and Navigation Components

Check for .claude/apple-design-context.md before asking questions. Use existing context and only ask for information not already covered.

Key Principles

1. Organize hierarchically. Structure information from broad categories to specific details. Sidebars for top-level sections, lists for browsable items, detail views for individual content.

2. Use standard navigation patterns. Tab bars for flat navigation between peer sections (iPhone). Sidebars for deep hierarchical navigation (iPad, Mac). Match the pattern to the information architecture and platform.

3. Adapt to screen size. Three-column on iPad collapses to single-column on iPhone. Use size classes and adaptive APIs (NavigationSplitView) for automatic adaptation.

4. Support multitasking on iPad. Respond gracefully to Split View, Slide Over, and Stage Manager. Test at every split ratio and size class transition.

5. Maintain spatial consistency on visionOS. Windows, volumes, and ornaments in shared space. Position predictably. Use ornaments for toolbars and controls without occluding content.

6. Use scroll views for overflow content. Enable paging for discrete content units. Support pull-to-refresh where appropriate. Respect safe areas.

7. Keep navigation predictable. Users should always know where they are, how they got there, and how to go back. Use back buttons, breadcrumbs, and clear section titles.

8. Prefer system components. UINavigationController, UISplitViewController, NavigationSplitView, and TabView provide built-in adaptivity, accessibility, and state restoration.

Reference Index

Navigation Pattern Selection

Layout Adaptation Checklist

• [ ] Compact width (iPhone portrait): Navigation collapses to single stack? Tab bars visible?
• [ ] Regular width (iPad landscape, Mac): Navigation expands to sidebar + detail? Space used well?
• [ ] Multitasking (iPad): Adapts at every split ratio? Works in Slide Over?
• [ ] Accessibility: Supports Dynamic Type at all sizes? VoiceOver order logical?
• [ ] Orientation: Content reflows between portrait and landscape?
• [ ] visionOS: Windows positioned ergonomically? Ornaments accessible? Depth meaningful?

Output Format

1. Recommended navigation pattern with rationale for the app's information architecture. 2. Layout hierarchy from root container down (e.g., TabView > NavigationSplitView > List > Detail). 3. Platform adaptation across targeted platforms and size classes. 4. Size class behavior at each transition.

Questions to Ask

1. What is the app's information architecture? (Sections, hierarchy depth, top-level categories?) 2. How many top-level sections? 3. Which platforms? 4. Need multitasking on iPad? 5. SwiftUI or UIKit?

Related Skills

• hig-foundations -- Layout spacing, margins, safe areas, alignment
• hig-platforms -- Platform-specific navigation conventions
• hig-patterns -- Multitasking, full-screen, and launching patterns
• hig-components-content -- Content displayed within layout containers

---

Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/boxes.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Boxes

Best practices

Prefer keeping a box relatively small in comparison with its containing view.

Consider using padding and alignment to communicate additional grouping within a box.

Content

Provide a succinct introductory title if it helps clarify the box’s contents.

If you need a title, write a brief phrase that describes the contents.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/boxes

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/column-views.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Column views

Best practices

Show the root level of your data hierarchy in the first column.

Consider showing information about the selected item when there are no nested items to display.

Let people resize columns.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/column-views

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/lists-and-tables.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Lists and tables

Best practices

Prefer displaying text in a list or table.

Let people edit a table when it makes sense.

Provide appropriate feedback when people select a list item.

Content

Keep item text succinct so row content is comfortable to read.

Consider ways to preserve readability of text that might otherwise get clipped or truncated.

Use descriptive column headings in a multicolumn table.

Style

Choose a table or list style that coordinates with your data and platform.

Choose a row style that fits the information you need to display.

Platform considerations

iOS, iPadOS, visionOS

Use an info button only to reveal more information about a row’s content.

Avoid adding an index to a table that displays controls — like disclosure indicators — in the trailing ends of its rows.

macOS

Let people resize columns.

Consider using alternating row colors in a multicolumn table.

Use an outline view instead of a table view to present hierarchical data.

tvOS

Confirm that images near a table still look good as each row highlights and slightly increases in size when it becomes focused.

watchOS

When possible, limit the number of rows.

Constrain the length of detail views if you want to support vertical page-based navigation.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/lists-and-tables

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/ornaments.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Ornaments

Best practices

Consider using an ornament to present frequently needed controls or information in a consistent location that doesn’t clutter the window.

In general, keep an ornament visible.

If you need to display multiple ornaments, prioritize the overall visual balance of the window.

Aim to keep an ornament’s width the same or narrower than the width of the associated window.

Consider using borderless buttons in an ornament.

Use system-provided toolbars and tab bars unless you need to create custom components.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/ornaments

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/outline-views.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Outline views

Best practices

Use a table instead of an outline view to present data that’s not hierarchical.

Expose data hierarchy in the first column only.

Use descriptive column headings to provide context.

Consider letting people click column headings to sort an outline view.

Let people resize columns.

Make it easy for people to expand or collapse nested containers.

Retain people’s expansion choices.

Consider using alternating row colors in multi-column outline views.

Let people edit data if it makes sense in your app.

Consider using a centered ellipsis to truncate cell text instead of clipping it.

Consider offering a search field to help people find values quickly in a lengthy outline view.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/outline-views

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/panels.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Panels

Best practices

Use a panel to give people quick access to important controls or information related to the content they’re working with.

Consider using a panel to present inspector functionality.

Prefer simple adjustment controls in a panel.

Write a brief title that describes the panel’s purpose.

Show and hide panels appropriately.

Avoid including panels in the Window menu’s documents list.

In general, avoid making a panel’s minimize button available.

Refer to panels by title in your interface and in help documentation.

HUD-style panels

Prefer standard panels.

• In a media-oriented app that presents movies, photos, or slides

• When a standard panel would obscure essential content

• When you don’t need to include controls — with the exception of the disclosure triangle, most system-provided controls don’t match a HUD’s appearance.

Maintain one panel style when your app switches modes.

Use color sparingly in HUDs.

Keep HUDs small.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/panels

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/scroll-views.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Scroll views

Best practices

Support default scrolling gestures and keyboard shortcuts.

Make it apparent when content is scrollable.

Avoid putting a scroll view inside another scroll view with the same orientation.

Consider supporting page-by-page scrolling if it makes sense for your content.

In some cases, scroll automatically to help people find their place.

• Your app performs an operation that selects content or places the insertion point in an area that’s currently hidden. For example, when your app locates text that people are searching for, scroll the content to bring the new selection into view.

• People start entering information in a location that’s not currently visible. For example, if the insertion point is on one page and people navigate to another page, scroll back to the insertion point as soon as they begin to enter text.

• The pointer moves past the edge of the view while people are making a selection. In this case, follow the pointer by scrolling in the direction it moves.

• People select something and scroll to a new location before acting on the selection. In this case, scroll until the selection is in view before performing the operation.

If you support zoom, set appropriate maximum and minimum scale values.

Scroll edge effects

• Use a `soft` edge effect in most cases, especially in iOS and iPadOS, to provide a subtle transition that works well for toolbars and interactive elements like buttons.

• Use a `hard` edge effect primarily in macOS for a stronger, more opaque boundary that’s ideal for interactive text, backless controls, or pinned table headers that need extra clarity.

Only use a scroll edge effect when a scroll view is adjacent to floating interface elements.

Apply one scroll edge effect per view.

Platform considerations

iOS, iPadOS

Consider showing a page control when a scroll view is in page-by-page mode.

macOS

If necessary, use small or mini scroll bars in a panel.

visionOS

If necessary, account for the size of the scroll indicator.

watchOS

Prefer vertically scrolling content.

Use tab views to provide page-by-page scrolling.

When displaying paged content, consider limiting the content of an individual page to a single screen height.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/scroll-views

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/sidebars.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Sidebars

Best practices

Extend content beneath the sidebar.

When possible, let people customize the contents of a sidebar.

Group hierarchy with disclosure controls if your app has a lot of content.

Consider using familiar symbols to represent items in the sidebar.

Consider letting people hide the sidebar.

In general, show no more than two levels of hierarchy in a sidebar.

If you need to include two levels of hierarchy in a sidebar, use succinct, descriptive labels to title each group.

Platform considerations

iOS

Avoid using a sidebar.

iPadOS

Consider using a tab bar first.

If necessary, apply the correct appearance to a sidebar.

macOS

Avoid stylizing your app by specifying a fixed color for all sidebar icons.

Consider automatically hiding and revealing a sidebar when its container window resizes.

Avoid putting critical information or actions at the bottom of a sidebar.

visionOS

If your app’s hierarchy is deep, consider using a sidebar within a tab in a tab bar.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/sidebars

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/split-views.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Split views

Best practices

To support navigation, persistently highlight the current selection in each pane that leads to the detail view.

Consider letting people drag and drop content between panes.

Platform considerations

iOS

Prefer using a split view in a regular — not a compact — environment.

iPadOS

Account for narrow, compact, and intermediate window widths.

macOS

• Vertical
• Horizontal
• Multiple

Set reasonable defaults for minimum and maximum pane sizes.

Consider letting people hide a pane when it makes sense.

Provide multiple ways to reveal hidden panes.

Prefer the thin divider style.

tvOS

Choose a split view layout that keeps the panes looking balanced.

Display a single title above a split view, helping people understand the content as a whole.

Choose the title’s alignment based on the type of content the secondary pane contains.

visionOS

To display supplementary information, prefer a split view instead of a new window.

watchOS

Automatically display the most relevant detail view.

If your app displays multiple detail pages, place the detail views in a vertical[tab view](https://developer.apple.com/design/human-interface-guidelines/tab-views).

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/split-views

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/tab-bars.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Tab bars

Best practices

Use a tab bar to support navigation, not to provide actions.

Make sure the tab bar is visible when people navigate to different sections of your app.

Use the appropriate number of tabs required to help people navigate your app.

Avoid overflow tabs.

Don’t disable or hide tab bar buttons, even when their content is unavailable.

Include tab labels to help with navigation.

Consider using SF Symbols to provide familiar, scalable tab bar icons.

Use a badge to indicate that critical information is available.

Avoid applying a similar color to tab labels and content layer backgrounds.

Platform considerations

iPadOS

• Tab bar
• Sidebar

Prefer a tab bar for navigation.

Let people customize the tab bar.

tvOS

• Specify a tint, color, or image for the tab bar background

• Choose a font for tab items, including a different font for the selected item

• Specify tints for selected and unselected items

• Add button icons, like settings and search

Be aware of tab bar scrolling behaviors.

In a live-viewing app, organize tabs in a consistent way.

• Live content

• Cloud DVR or other recorded content

• Other content

visionOS

Supply a symbol and a text label for each tab.

If it makes sense in your app, consider using a sidebar within a tab.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/tab-bars

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/tab-views.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Tab views

Best practices

Use a tab view to present closely related areas of content.

Make sure the controls within a pane affect content only in the same pane.

Provide a label for each tab that describes the contents of its pane.

Avoid using a pop-up button to switch between tabs.

Avoid providing more than six tabs in a tab view.

Anatomy

In general, inset a tab view by leaving a margin of window-body area on all sides of a tab view.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/tab-views

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/windows.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Windows

• A _primary_ window presents the main navigation and content of an app, and actions associated with them.

• An _auxiliary_ window presents a specific task or area in an app. Dedicated to one experience, an auxiliary window doesn’t allow navigation to other app areas, and it typically includes a button people use to close it after completing the task.

Best practices

Make sure that your windows adapt fluidly to different sizes to support multitasking and multiwindow workflows.

Choose the right moment to open a new window.

Consider providing the option to view content in a new window.

Avoid creating custom window UI.

Use the term _window_ in user-facing content.

Platform considerations

iPadOS

• Full screen. App windows fill the entire screen, and people switch between them — or between multiple windows of the same app — using the app switcher.

• Windowed. People can freely resize app windows. Multiple windows can be onscreen at once, and people can reposition them and bring them to the front. The system remembers window size and placement even when an app is closed.

• Full screen
• Windowed

Make sure window controls don’t overlap toolbar items.

Consider letting people use a gesture to open content in a new window.

macOS

macOS window states

• Main. The frontmost window that people view is an app’s main window. There can be only one main window per app.

• Key. Also called the _active window_ , the key window accepts people’s input. There can be only one key window onscreen at a time. Although the front app’s main window is usually the key window, another window — such as a panel floating above the main window — might be key instead. People typically click a window to make it key; when people click an app’s Dock icon to bring all of that app’s windows forward, only the most recently accessed window becomes key.

• Inactive. A window that’s not in the foreground is an inactive window.

Make sure custom windows use the system-defined appearances.

Avoid putting critical information or actions in a bottom bar, because people often relocate a window in a way that hides its bottom edge.

visionOS

visionOS windows

Prefer using a window to present a familiar interface and to support familiar tasks.

Retain the window’s glass background.

Choose an initial window size that minimizes empty areas within it.

Aim for an initial shape that suits a window’s content.

Choose a minimum and maximum size for each window to help keep your content looking great.

Minimize the depth of 3D content you display in a window.

visionOS volumes

Prefer using a volume to display rich, 3D content.

Place 2D content so it looks good from multiple angles.

In general, use dynamic scaling.

Take advantage of the default baseplate appearance to help people discern the edges of a volume.

Consider offering high-value content in an ornament.

Choose an alignment that supports the way people interact with your volume.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/windows