fix(webapp): let keyboard users skip repeated navigation (#1620)

Author: FelixTJDietrich

.changeset/accessible-navigation.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": patch
+---
+
+Keyboard users can skip repeated navigation and move directly to the page's main content. The documentation now explains the current accessibility assessment and how to report barriers.

docs/contributor/accessibility-audit-plan.md

@@ -0,0 +1,50 @@
+---
+title: Accessibility audit plan
+description: Scope and evidence requirements for evaluating the web application against WCAG 2.2 AA.
+---
+
+# Accessibility audit plan
+
+The audit follows [WCAG-EM](https://www.w3.org/WAI/test-evaluate/conformance/wcag-em/). Automated
+checks supplement rather than replace manual evaluation.
+
+## Scope
+
+- **Standard:** [WCAG 2.2](https://www.w3.org/TR/WCAG22/), Levels A and AA
+- **Application:** the Hephaestus SPA, including public, authentication, loading, empty, error, and
+  permission-denied states
+- **Complete processes:** authentication, workspace creation, developer feedback, mentor, settings,
+  workspace administration, and instance administration
+- **Outside the application scope:** linked external sites and identity-provider pages
+
+Hephaestus controls and presentation around imported content remain in scope even when the content
+comes from a third party.
+
+## Evaluation matrix
+
+| Surface or process | Representative routes and states | Manual status |
+| --- | --- | --- |
+| Public and legal | `/`, `/about`, `/imprint`, `/privacy`, not found | Not evaluated |
+| Authentication | `/login`, workspace login, callback and error | Not evaluated |
+| Workspace creation | provider selection, GitHub, GitLab, validation and errors | Not evaluated |
+| Workspace home | dashboard, teams, achievements and user profiles | Not evaluated |
+| Developer feedback | reviews, trace, observations, findings, delivery and targets | Not evaluated |
+| Mentor | thread list, greeting, transcript, composer and copilot | Not evaluated |
+| Personal settings | settings, integrations and destructive actions | Not evaluated |
+| Workspace administration | members, practices, review operations, models, usage and integrations | Not evaluated |
+| Instance administration | users, workspaces, audit, catalogue, providers, models and usage | Not evaluated |
+
+For each row, record the tested revision and deployment, route or process, state, applicable WCAG
+criteria, result, tester, date, and exact operating-system, browser, and assistive-technology versions.
+The manual matrix must include keyboard-only operation, NVDA with Firefox on Windows, and VoiceOver
+with Safari on macOS. Link every failure to an issue containing its reproduction steps, user impact,
+WCAG criterion, owner, and target release.
+
+## Automated checks
+
+`bun run --filter webapp test:storybook` runs the maintained Storybook states in Chromium and treats
+axe violations as errors. Record the revision, browser version, command result, and retained report
+with each audit. Automated results do not establish WCAG conformance.
+
+Until every matrix row is evaluated and each failure is fixed or linked, the public accessibility
+statement must make no conformance claim.

docs/docusaurus.config.ts

@@ -215,6 +215,10 @@ const config: Config = {
 							label: "Release Notes",
 							href: "https://github.com/ls1intum/Hephaestus/releases",
 						},
+						{
+							label: "Accessibility",
+							to: "/user/accessibility",
+						},
 						{
 							label: "Open Hephaestus",
 							href: "https://hephaestus.aet.cit.tum.de",

docs/sidebars.contributor.ts

@@ -15,6 +15,7 @@ const sidebars: SidebarsConfig = {
 				"local-verification",
 				"testing",
 				"e2e-testing",
+				"accessibility-audit-plan",
 				"security-mutation-testing",
 				"coding-guidelines",
 				"api-error-handling",

docs/sidebars.user.ts

@@ -19,6 +19,7 @@ const sidebars: SidebarsConfig = {
 			label: "Optional features",
 			items: ["leaderboard", "achievements"],
 		},
+		{ type: "doc", id: "accessibility", label: "Accessibility" },
 	],
 };
 

docs/user/accessibility.mdx

@@ -0,0 +1,40 @@
+---
+title: Accessibility
+description: The accessibility status, testing approach, and support channels for Hephaestus.
+---
+
+# Accessibility statement
+
+**Last reviewed: 30 August 2026**
+
+Hephaestus aims to be usable by people who navigate with a keyboard, magnify content, use speech
+input, or use a screen reader.
+
+## Conformance status
+
+Conformance of the Hephaestus web application with
+[WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/) **has not yet been established**. Automated checks
+pass for the maintained Storybook states, but the required keyboard and assistive-technology review
+of the integrated application is incomplete. We therefore make no WCAG conformance claim yet.
+
+This statement covers the Hephaestus single-page application, including its presentation of imported
+content. Linked external sites and identity-provider pages are outside its scope.
+
+## Current evidence
+
+The current assessment uses automated component checks in Chromium and source analysis. Integrated
+keyboard and screen-reader evaluation is incomplete, so these results do not establish WCAG
+conformance. The scope and evidence requirements are in the
+[accessibility audit plan](/contributor/accessibility-audit-plan).
+
+## Known limitations
+
+The integrated keyboard, NVDA, and VoiceOver evaluations are incomplete, so accessibility barriers
+may remain.
+
+## Feedback and contact
+
+If an accessibility problem prevents you from using Hephaestus, open an
+[accessibility issue](https://github.com/ls1intum/Hephaestus/issues/new?labels=webapp&title=%5BA11y%5D%20).
+Include the page, what you were trying to do, browser, assistive technology, and version when
+possible. Do not include private workspace data in a public report.

webapp/src/components/core/SkipToContent.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, userEvent } from "storybook/test";
+
+import { SkipToContent } from "./SkipToContent";
+
+const meta = {
+	title: "Common/Skip to content",
+	component: SkipToContent,
+	parameters: { layout: "fullscreen" },
+	tags: ["autodocs"],
+} satisfies Meta<typeof SkipToContent>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const KeyboardNavigation: Story = {
+	render: () => (
+		<>
+			<SkipToContent />
+			<main id="main-content" tabIndex={-1} className="p-6">
+				<h1>Main content</h1>
+				<button type="button">First action</button>
+			</main>
+		</>
+	),
+	play: async ({ canvas }) => {
+		await userEvent.tab();
+		const skipLink = canvas.getByRole("link", { name: "Skip to main content" });
+		await expect(skipLink).toHaveFocus();
+		await expect(skipLink).toBeVisible();
+
+		await userEvent.keyboard("{Enter}");
+		await expect(canvas.getByRole("main")).toHaveFocus();
+
+		await userEvent.tab();
+		await expect(canvas.getByRole("button", { name: "First action" })).toHaveFocus();
+	},
+};

webapp/src/components/core/SkipToContent.tsx

@@ -0,0 +1,18 @@
+export function SkipToContent() {
+	return (
+		<a
+			href="#main-content"
+			className="sr-only fixed left-4 top-4 z-[100] rounded-md bg-background px-4 py-2 text-sm font-medium text-foreground shadow-lg ring-2 ring-ring focus:not-sr-only"
+			onClick={(event) => {
+				const target = event.currentTarget.ownerDocument.getElementById(
+					event.currentTarget.hash.slice(1),
+				);
+				if (!target) return;
+				event.preventDefault();
+				target.focus();
+			}}
+		>
+			Skip to main content
+		</a>
+	);
+}

webapp/src/components/ui/sidebar.tsx

@@ -284,9 +284,13 @@ function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
 	);
 }
 
-function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
+/**
+ * ⚠️ Diverges from the shadcn registry: the inset is layout-only. Route layouts own the main
+ * landmark so global footers can remain outside it.
+ */
+function SidebarInset({ className, ...props }: React.ComponentProps<"div">) {
 	return (
-		<main
+		<div
 			data-slot="sidebar-inset"
 			className={cn(
 				"bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2 relative flex w-full flex-1 flex-col",

webapp/src/routes/__root.tsx

@@ -22,6 +22,7 @@ import { CookieConsentBanner } from "@/components/consent/CookieConsentBanner";
 import Footer from "@/components/core/Footer";
 import Header from "@/components/core/Header";
 import { AppSidebar, type SidebarContext } from "@/components/core/sidebar/AppSidebar";
+import { SkipToContent } from "@/components/core/SkipToContent";
 import { StandardPageSurface } from "@/components/core/StandardPageSurface";
 import { Chat } from "@/components/mentor/Chat";
 import { Copilot } from "@/components/mentor/Copilot";
@@ -78,9 +79,10 @@ function RootLayout() {
 		return (
 			<>
 				<HeadContent />
+				<SkipToContent />
 				<CookieConsentBanner />
 				<ProviderColorScope>
-					<main>
+					<main id="main-content" tabIndex={-1}>
 						<Outlet />
 					</main>
 				</ProviderColorScope>
@@ -92,6 +94,7 @@ function RootLayout() {
 	return (
 		<>
 			<HeadContent />
+			<SkipToContent />
 			{/* Rendered early so keyboard/AT users reach the consent region before the app chrome. */}
 			<CookieConsentBanner />
 			<ImpersonationBanner />
@@ -103,7 +106,7 @@ function RootLayout() {
 						style={{ marginRight: "var(--right-sidebar-width, 0)" }}
 					>
 						<HeaderContainer />
-						<div className="flex min-h-0 flex-1 flex-col">
+						<main id="main-content" tabIndex={-1} className="flex min-h-0 flex-1 flex-col">
 							{surface === "standard" ? (
 								<StandardPageSurface className="flex-1">
 									<Outlet />
@@ -117,13 +120,13 @@ function RootLayout() {
 									<Outlet />
 								</div>
 							)}
-							{surface !== "fullscreen" && (
-								<Footer
-									buildInfo={environment.buildInfo}
-									isProduction={environment.deployment.isProduction}
-								/>
-							)}
-						</div>
+						</main>
+						{surface !== "fullscreen" && (
+							<Footer
+								buildInfo={environment.buildInfo}
+								isProduction={environment.deployment.isProduction}
+							/>
+						)}
 					</SidebarInset>
 				</SidebarProvider>
 			</ProviderColorScope>
@@ -141,7 +144,7 @@ export const Route = createRootRouteWithContext<MyRouterContext>()({
 	component: RootLayout,
 	notFoundComponent: () => (
 		<div className="mx-auto flex w-full max-w-2xl flex-col items-center justify-center py-16 text-center">
-			<h2 className="text-3xl font-bold mb-4">Page Not Found</h2>
+			<h1 className="text-3xl font-bold mb-4">Page Not Found</h1>
 			<p className="text-muted-foreground mb-8">
 				The page you're looking for doesn't exist or you don't have permission to view it.
 			</p>