@octopusdeploy/design-system-components/skills/octopus-design-system/rules/navigation.md

The design systems component library.

# Navigation and Page Layouts

## Tabs

Use `Tab` and `Tabs` from `@octopusdeploy/design-system-components`.

❌ Don't use `ControlledTabsContainer` from `@octopusdeploy/design-system-octopus-components` —
it is deprecated (08/12/2025).

**Use tabs sparingly.** Tabs are for switching between related views of content within the same
page context — not for navigation between different routes. Each tab must render within the same
page; a tab must never map to a separate URL or route.

❌ Don't use tabs as a navigation mechanism where each tab is a different page/route.
✅ Do use tabs to switch between related content sections that share the same page context.

```tsx
import { Tab } from "@octopusdeploy/design-system-components";

// Tab and Tabs are exported from the Tab module
```

## Page layouts

Page layout components from `@octopusdeploy/design-system-components` provide the screen-level
structure for portal pages. Use these rather than building custom page shells.

The `Page` export contains layout components including level-based page layouts
(`Level1PageLayout`, `Level2InnerPageLayout`, etc.). These provide the correct content hierarchy,
padding, and semantic structure for portal pages.

Check for `@deprecated` markers on sidebar-related props in page layout components — those slots
are being phased out.

`GlobalLayout` has two requirements:
- It uses `flex: 1` internally and requires a flex container parent with a defined height (e.g.
  `height: 100vh; display: flex; flex-direction: column`). Without this it will not fill the screen.
- It requires a `scrollAreaRef` prop. Provide it with:
  ```tsx
  const scrollAreaRef = React.useRef<HTMLDivElement>(null);
  ```

## NavigationBar

`NavigationBar` handles the top-level navigation. It is set up once at the application level as
part of layout components. Do not re-implement navigation elements per-page.

## Breadcrumbs

Use `Breadcrumbs` for hierarchical location indicators within a page. These are driven by the
portal's routing infrastructure in most cases.

## Stepper and ProgressTracker

| Component | When to use |
|---|---|
| `Stepper` + `StepCard` | Multi-step wizard flows where the user moves through sequential steps |
| `ProgressTracker` | Showing progress through a sequence where each step has a status |
| `StepCount` | Compact step indicator for simpler flows |

Use `Stepper` for wizard-style setup flows. It is not appropriate for progress bars — use
`Progress` for that.

## Breadcrumbs vs Stepper

- `Breadcrumbs` = where you are in the hierarchy (navigation context)
- `Stepper` = where you are in a sequential multi-step UI flow (e.g. a setup wizard)

## SectionHeader

Use `SectionHeader` to label major content sections within a page. Do not create custom heading
elements with manual styling.

## Pagination

Use `Pagination` for paginated data sets. Wire it to your data fetching state directly — do not
build custom pagination UI.