From b1ff0b7b48103dca6df2b5724b75776e1e43f552 Mon Sep 17 00:00:00 2001
From: Alexander Payne <alex@alexanderwhitestone.com>
Date: Sun, 26 Apr 2026 01:51:01 -0400
Subject: [PATCH] =?UTF-8?q?feat(a11y):=20add=20skip=20navigation=20link=20?=
 =?UTF-8?q?(WCAG=202.4.1)=20=E2=80=94=20Closes=20#545?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements V1 skip navigation fix by:
- Adding .skip-link CSS to a11y-fixes.css (visually hidden until focus)
- Updating header_banner.tmpl to emit skip link as first element
- Updating README with V1 entry and description

Fixes #545
---
 deploy/gitea-a11y/README.md                       | 12 ++++++++++++
 .../gitea-a11y/custom/public/css/a11y-fixes.css   | 15 +++++++++++++++
 .../custom/templates/custom/header_banner.tmpl    |  1 +
 3 files changed, 28 insertions(+)

diff --git a/deploy/gitea-a11y/README.md b/deploy/gitea-a11y/README.md
index b03dc2f1..bece23b3 100644
--- a/deploy/gitea-a11y/README.md
+++ b/deploy/gitea-a11y/README.md
@@ -6,6 +6,7 @@ Applied fixes identified by the accessibility audit (#492):
 
 | Fix | Issue | WCAG | Description |
 |-----|-------|------|-------------|
+| V1 | #545 | 2.4.1 | Skip navigation link — `<a href="#main" class="skip-link">Skip to content</a>` added to header, visually hidden until focus |
 | R1 | #551 | Best Practice | Password visibility toggle (eye icon) on sign-in page |
 | R2 | #552 | 3.3.1 | `aria-required="true"` on required form fields |
 | R3 | #553 | 4.1.2 | `aria-label` on star/fork count links ("2 stars", "0 forks") |
@@ -43,6 +44,17 @@ bash deploy/gitea-a11y/deploy-gitea-a11y.sh root@my-gitea-host.com
 Gitea supports custom template overrides by placing files in `custom/templates/`.
 The templates here override the default Gitea templates with a11y improvements.
 
+### V1: Skip Navigation Link
+
+Adds a skip navigation link as the first focusable element in the header,
+allowing keyboard users to bypass the navigation and jump directly to the main
+content. The link is visually hidden by default and becomes visible on focus.
+
+- Meets WCAG 2.4.1 (Bypass Blocks)
+- Uses `<a href="#main" class="skip-link">Skip to content</a>`
+- Styled via `.skip-link` CSS rules (hidden off-screen, brought into view on `:focus`)
+- Implemented in `custom/header_banner.tmpl` alongside the banner landmark
+
 ### R1: Password Visibility Toggle
 
 Adds an eye icon (👁) button next to the password field that toggles between
diff --git a/deploy/gitea-a11y/custom/public/css/a11y-fixes.css b/deploy/gitea-a11y/custom/public/css/a11y-fixes.css
index f4c8694c..ac2799ac 100644
--- a/deploy/gitea-a11y/custom/public/css/a11y-fixes.css
+++ b/deploy/gitea-a11y/custom/public/css/a11y-fixes.css
@@ -9,3 +9,18 @@
 .markdown-body a:focus {
   color: #3a5518 !important;
 }
+
+/* V1 (#545): Skip navigation link — visually hidden until keyboard focus */
+.skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+  background: #000;
+  color: #fff;
+  padding: 8px 16px;
+  z-index: 10000;
+  transition: top 0.3s ease-in-out;
+}
+.skip-link:focus {
+  top: 0;
+}
diff --git a/deploy/gitea-a11y/custom/templates/custom/header_banner.tmpl b/deploy/gitea-a11y/custom/templates/custom/header_banner.tmpl
index 2d46cece..777bd437 100644
--- a/deploy/gitea-a11y/custom/templates/custom/header_banner.tmpl
+++ b/deploy/gitea-a11y/custom/templates/custom/header_banner.tmpl
@@ -13,6 +13,7 @@
 
 {{define "custom/header_banner"}}
 <header role="banner">
+  <a href="#main" class="skip-link">Skip to content</a>
 {{end}}
 
 {{define "custom/header_banner_close"}}