roboco/docs/ux_ui/design/task-navigation-structure.md

# Navigation/structure spec: breadcrumb, prev/next, constraints distinction

Status: implemented (v0.21.0+) Owner: ux-dev-2 Surface: task detail page (`panel/src/app/(dashboard)/tasks/[taskId]/page.tsx`) and its header (`panel/src/components/tasks/task-detail/task-header.tsx`) and description tab (`panel/src/components/tasks/task-detail/task-description.tsx`).

## Dial read

Per the team design bar, this is dense product UI (task detail / admin panel):

- **DESIGN_VARIANCE:** 2 — the breadcrumb and prev/next controls are a predictable single row above the existing header; no new grid or layout shape.
- **MOTION_INTENSITY:** 1 — hover/focus states only (existing `Button` / `Link` hover treatment), no transition is introduced.
- **VISUAL_DENSITY:** 8 — compact 28px-tall controls that add one row of chrome, nothing more; the constraints card stays a `Card`, not a heavier modal or full-width banner.

## Problem

The task detail page currently has no sense of *where this task sits*: the header's only navigation is a single `ArrowLeft` icon button that always goes to `/tasks` (`task-header.tsx` lines 474-479), regardless of whether the task has a parent. A reader drilling into a subtask of a subtask loses the parent chain the moment they land on the page, and moving between sibling tasks (e.g. checking each dev subtask of the same parent while triaging) requires going back to the list and re-finding the next one every time.

Separately, `task.constraints` (the auto-attached project-wide architectural standard, read-only) renders in `task-description.tsx` as a `Card` with only `border-dashed` and a muted title (lines 181-196) — visually one dash away from the free-form, user-authored `description` card right above it. A reader skimming the page has no fast visual cue that one box is "the project's rule" and the other is "this task's own words."

This spec is a pure design/markup change: no new dependency, no new backend field (`parent_task_id`, `sequence`, and `project_id` already exist on `Task`; `useTask` and `useSubtasks` already exist in `@/hooks/use-tasks`).

## 1. Breadcrumb trail

**Implementation status:** ✓ Complete (v0.21.0+). This diverged from the rich multi-crumb trail originally proposed for this section — see "What shipped" below for the design that actually rendered.

**Component:** `TaskBreadcrumb` at `panel/src/components/tasks/task-detail/task-breadcrumb.tsx`, rendered in the task detail page (`[taskId]/page.tsx`) above the `TaskHeader` component, replacing the standalone `ArrowLeft` button that was removed from `task-header.tsx`.

**What shipped.** A single ancestor level, not the multi-crumb trail below: `{Parent title}  >  {Current title}`. It renders only when `task.parent_task_id` is set — `null` for a root task, so the row is simply absent rather than showing an empty or placeholder crumb. The parent is fetched with one `useTask(parentId)` call (a `Skeleton` covers the loading gap); the parent title is a `Link` to `/tasks/{parent.id}`, truncated with a `title=` tooltip; the current task's own title renders last, non-interactive, in `text-foreground/70`. Separator: `ChevronRight` (`lucide-react`). Deeper ancestry is reached by following the chain up one hop at a time — clicking into the parent shows its own parent, and so on — rather than being flattened into one row.

**Why not the rich trail.** The proposed `Tasks` crumb existed to carry the back-to-list affordance the standalone `ArrowLeft` button used to own; that's redundant with the persistent sidebar's own "Tasks" nav link (`components/layout/sidebar.tsx`), so dropping it doesn't remove a control, it removes a duplicate. The `{Project name}` crumb and the multi-ancestor walk (a `useTask(parentId)` fetch per generation, collapsing behind a `DropdownMenu` past 3 entries) added fetches and layout branching for a case — chains long enough to need collapsing — that's rare given hierarchies cap at 3 levels per `CLAUDE.md`'s MegaTask section; the one-hop-at-a-time model covers it with a fifth of the markup. Full writeup: `docs/guide/task-detail-navigation.md`.

**Accessibility.** The row carries `aria-label="Parent task"`; the current-task span is plain non-interactive text, not a focusable element.

## 2. Prev/next list navigation

**Implementation status:** ✓ Complete (v0.21.0+). List-context-aware navigation, documented separately in `docs/guide/task-detail-navigation.md`.

**Component:** `TaskListNav` at `panel/src/components/tasks/task-detail/task-list-nav.tsx`, rendered in the task detail page (`[taskId]/page.tsx`) alongside the breadcrumb —  two chevron icon buttons that move to adjacent tasks within the current Tasks list filter/sort context, or disabled when viewed outside the list context.

**Data & ordering.** This diverged from the original sibling-order proposal during implementation (see `docs/guide/task-detail-navigation.md` for the full writeup) — "adjacent" means the previous/next row in the **Tasks list's last-visited filter/sort order**, not a `parent_task_id` sibling. The Tasks list page (`tasks/page.tsx`) reports its currently visible, filtered/sorted task order to `useScrollRestorationStore.setTaskListNav({ items, queryString })` whenever it changes; `TaskListNav` reads that `taskListNav` context, finds `task.id`'s index in `items`, and derives the prev/next item from `index - 1` / `index + 1`. The context is session-scoped (`sessionStorage` via the existing Zustand `persist` middleware), so it survives navigation within a session but doesn't persist across sessions. `useSubtasks` / `parent_task_id` / `sequence` are not part of this feature — sibling-order navigation, as originally proposed below, was not what shipped.

**Controls.** Two `Button variant="outline" size="icon"` using `ChevronLeft` / `ChevronRight` (`lucide-react`), each wrapped in a `Tooltip`:

- **Prev** links (`Link href="/tasks/{id}{queryString}"`) to `items[index - 1]`; **disabled** (not hidden — a disabled control at the boundary communicates "this is the first one," an absent control reads as "there is no prev/next feature here") when the current task is first in the captured list order, or when no list context exists for this session, or when the current task isn't part of the captured order (opened via a direct link, search, or notification instead of from the list).
- **Next** mirrors this at `index + 1`, disabled when current is last (or the same no-context/not-in-list cases as Prev).
- Each button's tooltip shows the target item's `title` when enabled, or the fixed explanation "Open this task from the Tasks list to enable prev/next navigation within that list's filter/sort order." when disabled — so hovering a disabled button still explains why, rather than looking broken.
- The href carries the captured `queryString` (the Tasks list's filters/sort at the time it was visited), so navigating there preserves that view.

**Keyboard.** ✓ Implemented. `Alt+ArrowLeft` / `Alt+ArrowRight` navigate prev/next exactly as the visible buttons do (same disabled-at-boundary and no-context behavior — the shortcut is a no-op when the corresponding button would be disabled). A `window` `keydown` listener in `TaskListNav` is suppressed whenever the focused element is an `input`, `textarea`, or `contenteditable` node, so it doesn't fight text-field cursor movement.

**Empty state.** When no list context has been captured this session, or the current task isn't found in the captured `items`, both buttons render disabled with the fallback tooltip above rather than being omitted — consistent with the boundary-disabled treatment, so the control's presence is predictable regardless of which task the reader is on.

## 3. Constraints visual distinction

**Implementation status:** ✓ Complete (v0.21.0+). Constraints now render with distinctive amber styling and a ShieldAlert icon.

**File:** `panel/src/components/tasks/task-detail/task-description.tsx` (lines 181-199).

**Treatment — amber "read-only architectural" tint, matching the existing convention already used for the *same* concept elsewhere in the panel:** the per-project Conventions tab uses `border-amber-500/40` for its "this is a committed, canonical rule" card (`conventions-tab.tsx` line 412), and `edit-project-dialog.tsx` uses `text-amber-600 dark:text-amber-400` plus a `KeyRound` icon (line 214-215) for the same "system-controlled, read-only" semantic on the git-token field. `task.constraints` is generated from that same `.roboco/conventions.yml` map (per `CLAUDE.md`'s Architectural Conventions Standard section), so reusing that exact token pairing — instead of introducing a new color — makes the same underlying concept look the same everywhere it appears, rather than inventing a fourth "read-only" treatment.

```tsx
<Card className="border-amber-500/40 bg-amber-500/5">
  <CardHeader className="pb-3">
    <CardTitle className="text-base flex items-center gap-2 text-amber-700 dark:text-amber-400">
      <Lock className="h-4 w-4" />
      Constraints
    </CardTitle>
  </CardHeader>
  <CardContent>
    <p className="text-xs text-muted-foreground mb-3">
      Architectural standard derived from the project conventions —
      read-only. Applies to every task in this project.
    </p>
    <Markdown>{task.constraints}</Markdown>
  </CardContent>
</Card>
```

- `Lock` (`lucide-react`, already a project dependency — no new icon package) replaces no icon at all today, signaling "not editable" at a glance before the reader even reads the label — the `description` card above it has an `Edit3` pencil in its header for the opposite reason (it IS editable), so the two icons now read as a matched pair of opposite affordances.
- `bg-amber-500/5` is a barely-there tint (5% opacity) — enough to differentiate the card body from the plain-white `description` card above without competing with it or reading as a warning/error state (which would call for `destructive`/red, wrong semantic here — this is informational, not an alert).
- The header text and icon both take `text-amber-700 dark:text-amber-400` (matching `edit-project-dialog.tsx`'s exact light/dark pair) instead of the current plain `text-muted-foreground`, so the section title itself carries the distinction, not just the border.
- The explanatory caption paragraph (already present, unchanged) stays `text-muted-foreground` — only the card chrome and heading change color; body copy stays neutral for readability.

**Placement.** Unchanged — still renders directly below the `description` `Card` in the Overview tab, so the reading order (task's own words, then the project-wide rule) is preserved; only the visual weight changes.

## Non-goals

- No new shadcn/ui primitive (no `breadcrumb.tsx` added to `components/ui`) — the breadcrumb composes existing `Link`, `Skeleton`, and `lucide-react` icons already in the tree, per the "fewest files" bar.
- No change to how ancestors are fetched server-side — the breadcrumb reuses `useTask` exactly as it exists today; no new endpoint, no new query param. Prev/next reuses the Tasks list's already-fetched page data instead of a dedicated sibling endpoint.
- No persisted "last visited sibling" or breadcrumb history — this is a point-in-time structural view of the current task's position, not a session/browsing-history feature.
- No persisted keyboard-shortcut preference (e.g. a toggle to disable `Alt+Arrow`) — the shortcut always mirrors whatever the visible buttons currently allow.