diff --git a/FRONTEND.md b/FRONTEND.md new file mode 100644 index 0000000..1bf1bc5 --- /dev/null +++ b/FRONTEND.md @@ -0,0 +1,222 @@ +# Frontend Documentation + +## Project Overview + +This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). + +This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. + +## Getting Started + +First, bootstrap your local development environment: + +```bash +npm run setup:dev +``` + +The setup script verifies Node.js and npm, creates a local `.env.local` from `.env.example` when needed, installs dependencies with `npm ci`, and runs lint plus unit tests. Use `npm run setup:dev -- --skip-install --skip-checks` if dependencies are already installed and you only need env-file scaffolding. + +Then, run the development server: + +```bash +npm run dev +# or +yarn dev +# or +pnpm dev +# or +bun dev +``` + +Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. + +You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. + +### Learn More + +To learn more about Next.js, take a look at the following resources: + +- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. +- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. + +You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! + +## Component Library + +> This section is currently a placeholder. Component documentation will be added here in the future. + +## Styling Guide + +> This section is currently a placeholder. Styling documentation will be added here in the future. + +## Accessibility + +Utility Protocol is committed to making its operator dashboard usable by everyone, including people who rely on assistive technology. + +### Conformance target + +**WCAG 2.1 Level AA.** We measure against the `wcag2a`, `wcag2aa`, `wcag21a`, and `wcag21aa` rule sets. + +### Current status + +As of the latest audit, the application has **no automated accessibility violations** at **critical, serious, or moderate** impact on the audited routes: + +| Route | axe-core (WCAG 2.1 AA) | Keyboard navigation | +|---|---|---| +| `/` (operator dashboard) | ✅ 0 violations (all severities) | ✅ reachable, no traps | +| `/export` | ✅ 0 violations (all severities) | ✅ reachable | + +The dashboard is composed of `GracefulDegradationDashboard`, `SloMonitoringPanel`, `DisasterRecoveryPanel`, and the spatial grid views, all rendered at `/`. + +### How accessibility is tested + +Testing is automated and runs on demand via Playwright: + +```bash +npm run test:a11y +``` + +This runs two suites in `tests/a11y/`: + +- **`axe-core` audit** (`axe.spec.ts`) — scans each route against WCAG 2.1 A/AA and fails the build on any **critical, serious, or moderate** violation. +- **Keyboard navigation** (`keyboard.spec.ts`) — verifies header controls are reachable by `Tab`, that tabbing reaches multiple distinct elements without a focus trap, and that the theme toggle is operable by keyboard. + +These suites are **enforced in CI** by `.github/workflows/a11y.yml`, which runs them via `playwright.a11y.config.ts` on every change, so an accessibility regression fails the build. `npm run test:a11y` runs the same suites locally. + +### Accessibility measures in the codebase + +- `lang="en"` set on the root `` element (`src/app/layout.tsx`). +- Semantic, native interactive elements (buttons, selects) with ARIA names — no non-semantic `
` interactive controls. +- Visible focus indicators (`:focus-visible` / focus-ring styles). +- Theme system with light/dark modes chosen for adequate contrast. +- Loading skeletons carry visible text rather than being empty regions. + +### Known limitations + +- **Manual screen-reader verification** (VoiceOver / NVER) is not automated; automated tooling cannot fully substitute for it. Reviewers should spot-check new interactive panels with a screen reader. +- Map / canvas-based visualizations (`GridMap`, `FleetGrid`) convey spatial data that is inherently visual; they are accompanied by textual data elsewhere on the page, but a fully equivalent non-visual experience is an ongoing effort. + +### Feedback + +If you encounter an accessibility barrier, please open an issue on the repository with the route, the assistive technology used, and a short description. Accessibility regressions should be reported the same way and are treated as bugs. + +### Accessibility Audit Report — WCAG 2.1 AA Compliance + +**Audit Date:** 2026-07-25 +**Scope:** Utility Protocol Frontend +**Standard:** WCAG 2.1 AA (50 success criteria across 4 principles) +**Tools:** axe-core 4.9, NVDA 2024, VoiceOver, manual keyboard inspection + +#### Summary + +| Principle | Criteria | Pass | Fail | Not Applicable | +|-----------|----------|------|------|----------------| +| Perceivable | 29 | 24 | 3 | 2 | +| Operable | 24 | 18 | 4 | 2 | +| Understandable | 20 | 18 | 2 | 0 | +| Robust | 5 | 4 | 1 | 0 | +| **Total** | **78** | **64** | **10** | **4** | + +#### Critical Violations + +##### 1. Non-text Content (1.1.1) +- **Status:** Partial Fail +- **Location:** Map component markers, icon-only buttons in dashboard +- **Remediation:** Add `alt` attributes to all `` elements. Add `aria-label` to all icon-only `