feat(a11y): add skip navigation link for WCAG 2.4.1 compliance

Add R5 skip navigation link template and supporting CSS to meet WCAG 2.4.1 Bypass Blocks (A). - New template: deploy/gitea-a11y/custom/templates/custom/skip_link.tmpl Provides a "Skip to main content" anchor as the first focusable element. - Updated deploy/gitea-a11y/custom/public/css/a11y-fixes.css (V5): Styles for .skip-link, visually hidden off-screen until focus. - Updated README.md with R5 documentation and activation instructions. - deploy-gitea-a11y.sh: include R5 in deployed fixes list. Usage: Insert `{{template "custom/skip_link" .}}` immediately after <body> in custom/header.tmpl. Targets #545. Part of STEP35 FREE BURN — Gitea-first a11y V1.
2026-04-30 19:44:29 -04:00
parent ba4220d5ed
commit c28d462c4a
4 changed files with 76 additions and 8 deletions
--- a/deploy/gitea-a11y/README.md
+++ b/deploy/gitea-a11y/README.md
@@ -10,6 +10,7 @@ Applied fixes identified by the accessibility audit (#492):
 | 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") |
 | R4 | #554 | 1.3.1 | `<time datetime="...">` elements for relative timestamps |
+| R5 | #545 | 2.4.1 | Skip navigation link for keyboard users |

 ## Structure

@@ -20,14 +21,18 @@ deploy/gitea-a11y/
 └── custom/
    ├── public/
    │   ├── css/
+    │   │   └── a11y-fixes.css   # Global CSS fixes (R4, R5)
    │   └── js/
    └── templates/
        ├── custom/
-        │   └── time_relative.tmpl    # R4: <time> helper
-        ├── repo/
-        │   └── list_a11y.tmpl        # R3: aria-label on counts
-        └── user/auth/
-            └── signin_inner.tmpl     # R1+R2: password toggle + aria-required
+        │   ├── a11y_head.tmpl   # R4: Inject CSS into <head>
+        │   ├── header_banner.tmpl # Bypass: <header role="banner">
+        │   ├── skip_link.tmpl    # R5: Skip navigation link (WCAG 2.4.1)
+        │   └── time_relative.tmpl # R4: <time> helper
+        ├── user/auth/
+        │   └── signin_inner.tmpl # R1+R2: password toggle + aria-required
+        └── repo/
+            └── list_a11y.tmpl    # R3: aria-label on star/fork counts
 ```

 ## Deploy
@@ -60,5 +65,24 @@ readers announce the meaning, not just the number.

 ### R4: `<time>` Elements

-Wraps relative timestamps ("2 minutes ago") in `<time datetime="2026-04-13T17:00:00Z">`
+Wraps relative timestamps ("2 minutes ago") in `<time datetime="...">`
 providing both human-readable text and machine-readable ISO 8601 dates.
+
+### R5: Skip Navigation Link (WCAG 2.4.1)
+
+Adds a "Skip to main content" link as the first focusable element.
+Keyboard users can press Tab at the top of a page to jump directly
+to the main content area, bypassing repeated navigation menus.
+
+**Template:** `custom/skip_link.tmpl`  
+**Insert:** At the very start of `<body>` in your custom `header.tmpl`:
+
+```handlebars
+{{template "custom/skip_link" .}}
+```
+
+Gitea's default page layout uses `<main id="main">` as the content target.
+If your instance uses `#content`, adjust the `href` in the template.
+
+The CSS in `a11y-fixes.css` visually hides the link off-screen until it
+receives keyboard focus, meeting WCAG 2.4.1 Bypass Blocks (A).
--- a/deploy/gitea-a11y/custom/public/css/a11y-fixes.css
+++ b/deploy/gitea-a11y/custom/public/css/a11y-fixes.css
@@ -9,3 +9,25 @@
 .markdown-body a:focus {
  color: #3a5518 !important;
 }
+
+/* V5 (#545): Skip navigation link (WCAG 2.4.1) — visible on focus only */
+.skip-link {
+  position: absolute;
+  top: -100px;
+  left: 8px;
+  background: #1a1a1a;
+  color: #fff;
+  padding: 12px 16px;
+  font-size: 14px;
+  font-weight: 600;
+  z-index: 9999;
+  border-radius: 0 0 4px 4px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+  transition: top 0.2s ease-in-out, background 0.2s;
+  text-decoration: none;
+}
+.skip-link:focus {
+  top: 0;
+  outline: 3px solid #ffcc00;
+  outline-offset: 2px;
+}
--- a/deploy/gitea-a11y/custom/templates/custom/skip_link.tmpl
+++ b/deploy/gitea-a11y/custom/templates/custom/skip_link.tmpl
@@ -0,0 +1,20 @@
+{{/*
+  Gitea a11y fix: V1 — Skip navigation link (WCAG 2.4.1)
+
+  Provides a "Skip to main content" link as the first focusable element
+  in the document. Screen reader and keyboard users can activate it
+  to bypass repeated navigation and go straight to the main content.
+
+  Usage: Insert immediately after the opening <body> tag.
+  Include via custom/header.tmpl:
+
+      {{template "custom/skip_link" .}}
+
+  The target should match the id of the main content region. Gitea's
+  main area uses id="main" by default. If your instance uses a
+  different id (e.g. "content"), adjust the href accordingly.
+
+  WCAG 2.4.1 Bypass Blocks — A.
+*/}}
+
+<a href="#main" class="skip-link" aria-label="Skip to main content">Skip to main content</a>
--- a/deploy/gitea-a11y/deploy-gitea-a11y.sh
+++ b/deploy/gitea-a11y/deploy-gitea-a11y.sh
@@ -6,9 +6,10 @@
 #
 # Fixes:
 #   R1: Password visibility toggle on sign-in (#551)
-#   R2: aria-required on required form fields (#552)
-#   R3: aria-label on star/fork count links (#553)
+#   R2: aria-required on required fields (#552)
+#   R3: aria-label on star/fork counts (#553)
 #   R4: <time> elements for relative timestamps (#554)
+#   R5: Skip navigation link for keyboard users (#545)
 #
 # Usage:
 #   bash deploy/gitea-a11y/deploy-gitea-a11y.sh [ssh-host]
@@ -53,5 +54,6 @@ echo "  R1: Password toggle on /user/sign_in"
 echo "  R2: aria-required on required fields"
 echo "  R3: aria-label on star/fork counts"
 echo "  R4: <time> elements on timestamps"
+echo "  R5: Skip navigation link (WCAG 2.4.1)"
 echo ""
 echo "Verify at: https://forge.alexanderwhitestone.com/user/sign_in"