# Administration Shell

Phase 4 provides the shared presentation shell for authenticated administration
and account-security pages. It deliberately keeps navigation policy-aware: a
user only receives links for capabilities they are authorized to use, while the
account-security destination remains available to every signed-in user.

## Shell contract

- `App\View\AdminNavigation` owns navigation groups, active route matching,
  breadcrumbs, and the safest authorized home URL.
- `AppServiceProvider` shares the computed navigation state with
  `layouts.admin`; feature views do not duplicate authorization rules.
- `layouts.admin` supplies the sidebar, mobile drawer, sticky toolbar,
  breadcrumbs, account menu, environment marker, flash/error regions, and main
  content landmark.
- `x-admin.page-header` gives administration pages a consistent eyebrow,
  heading, description, and action area.
- `x-admin.icon` provides CSP-safe inline SVG symbols without an external icon
  runtime.

The current destinations are Overview, Users, Roles & permissions, and Account
security. The overview cards follow the same authorization rules as the primary
navigation, so the shell does not advertise forbidden actions.

## Theme behavior

The theme control cycles through system, light, and dark modes. The selected
mode is stored under `7tech-theme` in browser local storage. System mode follows
the operating-system preference; explicit modes set `data-theme` on the root
element. All three modes use the existing black, white, and orange design
tokens.

Theme and shell behavior live in the compiled application JavaScript rather
than inline scripts, preserving the application's content-security policy.

## Accessibility and responsive behavior

- A skip link and named landmarks provide a direct keyboard route to content.
- Navigation exposes `aria-current="page"`; breadcrumbs identify the current
  location and include bound resource names on edit screens.
- Drawer controls maintain `aria-expanded`, move focus to the close control,
  close on overlay activation or Escape, and restore focus to the opener.
- Flash messages can be dismissed, and validation summaries receive focus
  after a failed submission.
- Controls meet the 44-pixel target size used by the application, visible focus
  styles are retained, and status is not conveyed by color alone.
- Reduced-motion preferences disable nonessential transitions.
- At widths up to 64rem the sidebar becomes a drawer. Forms, cards, tables, and
  account controls collapse progressively at 48rem and 34rem. Wide data tables
  retain a local horizontal scroll region instead of overflowing the page.
- Direction-aware layout rules support both left-to-right and right-to-left
  locales.

## Verification

`AdminShellTest` covers accessible shell controls, policy-aware link removal,
active navigation, breadcrumbs, bound-subject labels, and the security-only
experience for a user without dashboard access.

The Phase 4 browser pass covered the signed-in and privileged 2FA flow,
desktop rendering, the 390 × 844 responsive layout, theme cycling, the account
menu, protected navigation, Escape/focus restoration, page overflow, and
browser console output.