---
name: Gamepad Navigation System
description: Controller/gamepad navigation architecture, key decisions, known issues, and the nav map doc location
type: project
---

Gamepad/controller navigation is a core feature of Archipelago — the UI runs on a kiosk with Xbox-style controller input.

**Why:** Archipelago runs on dedicated hardware with a TV/monitor + gamepad. Every page must be fully navigable without a mouse.

**How to apply:** When modifying any page's interactive elements, check that `data-controller-container` and `tabindex` are set correctly. Read `neode-ui/docs/GAMEPAD-NAV-MAP.md` for the full per-page navigation spec and implementation notes.

## Key files
- `neode-ui/src/composables/useControllerNav.ts` — all navigation logic
- `neode-ui/docs/GAMEPAD-NAV-MAP.md` — full nav spec with per-page tables, implementation notes, and Chromium gotchas

## Critical patterns
- Cards on grid pages: `glass-card transition-all hover:-translate-y-1` + `data-controller-container tabindex="0"`
- Settings page is a MIXED page (containers + standalone buttons) — nav searches both together
- ToggleSwitch has `tabindex="-1"` + `data-controller-ignore` so gamepad skips it
- Focus glow uses blurred box-shadow, NOT `0 0 0 Npx` spread (Chromium compositor bug with translateZ(0))
- `outline: none !important` on all containers to kill browser default focus rings