<!-- Generated by scripts/build-agent-kit.ts for @aistrike-dev/ui@5.0.1. Do not edit. -->

# LeftNavigation vs Tabs vs Stepper

<!-- use-when: Moving the user between views: app areas, sections of a screen, or steps of a task. -->

All three let the user move between views, which is why a row or column of labels in a mockup could be
any of them. The question that decides it is: **what scope is the user moving within?**

| Control | Scope | Order | Where it lives |
| --- | --- | --- | --- |
| `LeftNavigation` | The whole application | Free | The app shell, always visible |
| `Tabs` | One screen | Free | Inside a screen, above its panel |
| `Stepper` | One task | Fixed — steps have prerequisites | Inside a flow |
| `Breadcrumbs` | Position in a hierarchy | N/A — it shows where you are | Above a page title |

The three are nested, not alternatives: `LeftNavigation` picks the area, `Tabs` pick a section of that
area's screen, and a `Stepper` walks the user through one task on it. If two of them look like they
compete for the same job, one of them is at the wrong level.

This guide is about **navigation structures**. If the row of labels filters or reformats content that
stays on screen rather than swapping it, that is a different question — see the selection-controls
guide.

## Decision flow

```
Does clicking move the user to a different area of the application?
        │
        ├── Yes ─────────────────────────────────► LeftNavigation
        └── No — it stays within this screen
                │
                ├── Must the parts be completed in order,
                │   with later parts depending on earlier ones?
                │        │
                │        ├── Yes ────────────────► Stepper
                │        └── No
                │              │
                │              ├── Does it swap in a different
                │              │   panel of content? ─────────► Tabs
                │              └── Does it filter or reformat
                │                  the same content? ────────► see selection-controls
                │
                └── Does it only show where the user already is,
                    with ancestors to click back to? ─────────► Breadcrumbs
```

## LeftNavigation

Primary application navigation. **One per app shell**, always present, with a `collapsed` icon-only
mode for dense screens.

**Reach for it when:**

- Top-level areas: Dashboard, Assets, Findings, Attack Paths, Settings.
- Anything a user should be able to reach from anywhere in the product.

```tsx
import { DashboardLayout } from '@aistrike-dev/ui';

<DashboardLayout navItems={navItems} selectedNavId="findings" onNavSelect={setNavId}>
  {/* LeftNavigation is wired up by the layout - prefer the template over composing it yourself. */}
</DashboardLayout>
```

**Practical limits:** in practice you get this by using `DashboardLayout`, which composes the app bar
and navigation for you — reach for the template before assembling the shell by hand. Do not duplicate
actions that already live in the app bar. Use `collapsed` for dense screens rather than hiding
navigation behind a `temporary` `Drawer`; a temporary drawer is for narrow viewports, not for primary
navigation on desktop.

## Tabs

Peer sections of **one screen**, where only one is relevant at a time. Tabs are structural: they persist
while the user works, and each is a destination you can point someone to ("check the Findings tab").

**Reach for it when:**

- An asset detail page splits into Overview / Findings / Attack Paths / Activity.
- A settings page groups unrelated forms: Profile / Notifications / Integrations.
- A drawer or dialog holds two distinct bodies of content too long to stack.

```tsx
import { Tabs, Tab } from '@aistrike-dev/ui';
import { Box } from '@mui/material';

<Box>
  <Tabs value={tab} onChange={(_, next) => setTab(next)} aria-label="asset detail tabs">
    <Tab label="Overview" />
    <Tab label="Findings" />
    <Tab label="Attack Paths" />
  </Tabs>
  <Box sx={{ pt: 2 }}>{panels[tab]}</Box>
</Box>
```

**Practical limits:** the design system ships the tab strip only — **the panel below it is yours to
render**, keyed off `value`, with `role="tabpanel"` when the content is substantial. Labels are nouns
("Findings"), not actions ("View findings"). Use `variant="scrollable"` with `scrollButtons="auto"` when
there are more tabs than fit, and `orientation="vertical"` in a narrow sidebar.

## Stepper

Progress through **an ordered task** where later steps depend on earlier ones. The order is the point:
if the user can jump around freely, it is not a stepper.

**Reach for it when:**

- Onboarding: Connect → Configure → Review.
- A multi-step form that is too long for one screen.
- A guided remediation flow.

```tsx
import { Stepper, Step, StepLabel } from '@aistrike-dev/ui';

<Stepper activeStep={step}>
  <Step><StepLabel>Connect</StepLabel></Step>
  <Step><StepLabel>Configure</StepLabel></Step>
  <Step><StepLabel>Review</StepLabel></Step>
</Stepper>
```

**Practical limits:** `activeStep` is required, and the stepper only *displays* progress — you own the
step content and the Next/Back buttons. Use `nonLinear` when steps genuinely can be revisited in any
order, but if that is always true, you wanted `Tabs`. `orientation="vertical"` suits long steps with
content between the labels; `alternativeLabel` suits short labels on a wide screen. Step labels describe
the step ("Configure scanning"), not its number.

## Breadcrumbs

Not a way to move between peers — a statement of **where the user is** in a hierarchy, with ancestors
they can click back to.

```tsx
import { Breadcrumbs, Link, Typography } from '@aistrike-dev/ui';

<Breadcrumbs aria-label="breadcrumb">
  <Link href="/assets">Assets</Link>
  <Link href="/assets/web-01">web-01</Link>
  <Typography variant="body1">Finding 4821</Typography>
</Breadcrumbs>
```

**Practical limits:** the current page is plain text, never a link. Only worth it when the hierarchy is
genuinely deep; in a flat app it is noise. Never a substitute for primary navigation. `DetailsPageLayout`
already provides a breadcrumb slot.

## Worked examples

| Scenario | Control | Why |
| --- | --- | --- |
| Dashboard / Assets / Findings / Settings | `LeftNavigation` | Top-level app areas |
| Asset page: Overview / Findings / Attack Paths | `Tabs` | Peer sections of one screen |
| Settings: Profile / Notifications / Integrations | `Tabs` | Unrelated sections, one screen |
| Onboarding: Connect → Configure → Review | `Stepper` | Ordered, with prerequisites |
| A 4-page "Create policy" form | `Stepper` | One task split across screens |
| Assets → web-01 → Finding 4821 | `Breadcrumbs` | Shows position, links ancestors |
| All / Open / Resolved over one findings table | Not navigation — a filter | See selection-controls |
| Table view vs card view of the same list | Not navigation — a view mode | See selection-controls |
| Navigation on a phone-width viewport | `Drawer` (`temporary`) holding the nav | Standard mobile pattern |
| A dense analyst screen needing more width | `LeftNavigation` with `collapsed` | Keeps navigation reachable |
| Row actions: Edit / Duplicate / Delete | `Menu` | Actions, not navigation |

## Anti-patterns

- **Tabs as primary navigation.** Top-level areas belong in `LeftNavigation`; tabs live inside a screen.
- **Tabs for wizard steps.** Tabs imply free movement between peers. A sequence with prerequisites is a
  `Stepper`.
- **A `Stepper` for peer views.** If the user can visit them in any order and always could, they are
  tabs.
- **Tabs used as a filter.** If the columns never change and the "tabs" only narrow the same list, it is
  a filter — see the selection-controls guide.
- **A `temporary` `Drawer` as desktop primary navigation.** Use `LeftNavigation` with `collapsed`.
- **Breadcrumbs as navigation.** They show location. Moving between areas is `LeftNavigation`.
- **A linked current page in breadcrumbs.** The last crumb is plain text.
- **Two navigation levels competing.** A `LeftNavigation` and a tab strip offering the same
  destinations means one is at the wrong level.
- **Hand-composing the app shell.** `DashboardLayout` already wires the app bar and navigation together.
- **Action verbs as tab labels.** Tabs are places, so their labels are nouns.

## Accessibility

- `LeftNavigation` renders a `nav` landmark labelled "Primary", and exposes labels via tooltips when
  `collapsed` — so an icon-only rail stays usable.
- `Tabs` need an `aria-label` on the strip. Keyboard: arrows move focus, Enter or Space selects. Pair
  substantial panel content with `role="tabpanel"` so the relationship is announced.
- `Stepper` must make the current step obvious in text, not only by colour, and step labels must be
  descriptive enough to be read out of context.
- `Breadcrumbs` need `aria-label="breadcrumb"`, with the current page as plain text so it is not
  announced as a link.

## When you are unsure, ask

The ambiguous case is **`Tabs` vs `Stepper`** for a long form: it depends on whether the steps really
have prerequisites, which a mockup rarely shows. **If you cannot confidently choose, stop and ask,
naming the options and the one you lean toward.**

> "The 'Create policy' flow has four sections. I'm leaning toward a `Stepper`, since 'Review' can't be
> meaningful before the earlier sections are filled in. If users should be able to fill them in any
> order, `Tabs` would fit better. Which is it?"

> "This screen has a left rail and a tab strip that both list Findings. One of them is at the wrong
> level — should the rail be app-level areas only, with tabs scoped to the asset?"

A single clarifying question is far cheaper than shipping a control whose behaviour surprises the user.

## References

- **Organisms → LeftNavigation**, **Molecules → Tabs**, **Organisms → Stepper**,
  **Molecules → Breadcrumbs** — stories for each.
- **Templates → DashboardLayout**, **Templates → DetailsPageLayout** — where these are already composed.
- **Guidelines → Choosing → Selection Controls** — filters and view modes, which are not navigation.
- **Guidelines → Choosing → Overlay Surfaces** — where `Drawer` fits.
- [MUI Tabs](https://mui.com/material-ui/react-tabs/) · [MUI Stepper](https://mui.com/material-ui/react-stepper/) · [MUI Breadcrumbs](https://mui.com/material-ui/react-breadcrumbs/)