@atlaskit/navigation-system/constellation/layout/usage.mdx

The latest navigation system for Atlassian apps.

---
title: Layout
description: Layout components define a page’s structure and the areas for navigation and content.
order: 4
---

import Image from '@atlaskit/image';

import layoutAnatomyLight from './images/layout-anatomy-light.png';
import layoutAnatomyDark from './images/layout-anatomy-dark.png';
import layoutDoLight from './images/layout-do-light.png';
import layoutDoDark from './images/layout-do-dark.png';
import layoutDontLight from './images/layout-dont-light.png';
import layoutDontDark from './images/layout-dont-dark.png';

import SectionMessage from '@atlaskit/section-message';

## Usage

Use layout to compose the structure of your application. It also defines the page behavior and
navigational areas.

When applying components to the navigational areas,
[see navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).

## Parts

<Image
	src={layoutAnatomyLight}
	srcDark={layoutAnatomyDark}
	alt="Diagram of the navigation system layout areas"
/>

<ol>
	<li>
		<strong>Banner:</strong> Optional. Use to display a <a href="/components/banner">banner</a>.
	</li>
	<li>
		<strong>Top nav:</strong> Use to display{' '}
		<a href="/components/navigation-system/top-nav-items">top nav items</a>.
		<ol type="a">
			<li>
				<strong>Top nav start:</strong> Area for left-aligned actions.
			</li>
			<li>
				<strong>Top nav middle:</strong> Area for centre-aligned actions.
			</li>
			<li>
				<strong>Top nav end:</strong> Area for right-aligned actions.
			</li>
		</ol>
	</li>
	<li>
		<strong>Side nav:</strong> Use to display{' '}
		<a href="https://atlaskit.atlassian.com/packages/navigation/side-nav-items">side nav items</a>.
		Is resizable and collapsible.
		<ol type="a">
			<li>
				<strong>Side nav header:</strong> Optional. Top part of the side nav (fixed).
			</li>
			<li>
				<strong>Side nav content:</strong> Middle part of the side nav. Acts as the scroll
				container.
			</li>
			<li>
				<strong>Side nav footer:</strong> Optional. Bottom part of the side nav (fixed).
			</li>
		</ol>
	</li>
	<li>
		<strong>Main:</strong> Use for the page content. Expands to fill available space.
	</li>
	<li>
		<strong>Panel:</strong> Optional. Use to display supporting or supplementary content. Is
		resizable and collapsible. Wrap `Panel` in `ExitingPersistence` from
		`@atlaskit/motion/exiting-persistence` so it stays in the DOM until its exit animation
		completes.
	</li>
</ol>

### The difference between panel and modal dialog

The main difference between panel and modal dialog is their behaviors:

- **Panel** presents content alongside the **main** area, while a **modal dialog** appears in a
  layer above the page.
- **Panel** can be collapsed and resized. On small viewports (1024px and below), the **panel**
  becomes an overlay.

#### Usage guidance

- Use the **panel** for contextual information or tertiary actions that complement the user's
  workflow. Panels enable multitasking by providing an additional work space, while keeping users
  connected to their primary task.
- Use a **modal dialog** when you need the user to focus on a specific task, such as making a
  decision or completing an action, before they can return to their primary task.

## Accessibility

- Always place slots in this order as direct children of the root: banner, top nav, side nav, main,
  panel. This determines the keyboard tab order, screen reader reading order, and skip link order.
- Provide a unique, meaningful `label` for side nav, panel, and top nav end. The label is exposed as
  the landmark's accessible name. Don't repeat the landmark's role in the label.
- Slots provide landmark roles automatically. Don't add or duplicate landmark roles inside them.
- Use custom skip links sparingly. Too many skip links makes the skip links menu noisy. Consider the
  utility of each one before adding it.

## Best practices

### Design using grid in the main area

<DoDontGrid>
	<DoDont
		type="do"
		image={{
			url: layoutDoLight,
			urlDarkMode: layoutDoDark,
			alt: 'A layout with a grid overlay on the Main area.',
		}}
		isFullWidth
	>
		When designing, use <a href="/foundations/grid">grid</a> to position content within the main
		area only.
	</DoDont>
	<DoDont
		type="dont"
		image={{
			url: layoutDontLight,
			urlDarkMode: layoutDontDark,
			alt: 'A layout with a grid overlay on the Main area, but also on the Side nav and Panel areas.',
		}}
		isFullWidth
	>
		Don't include side nav or panel areas as part of your grid.
	</DoDont>
</DoDontGrid>

## Related

- [Page header](/components/page-header)
- [Top nav items](/components/navigation-system/top-nav-items)
- [Navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)