From 563797b5654122d9fac44895ee9be9096011f48d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 16 May 2026 10:50:57 +0000
Subject: [PATCH 1/3] feat: improve accessibility/UX flow and add reusable
 Claude agents & skills

- Add skip-to-content link, reduced-motion safeguards and main landmark
- Wire eslint-plugin-vuejs-accessibility into the flat config + lint scripts
- Promote the Lighthouse accessibility gate to an error and add a11y audits
- Fix 25 a11y findings (redundant roles, label association, focusable menu,
  keyboard parity for escape handlers, carousel mouse/key events)
- Add checked-in .claude/ skills (a11y-review, component-scaffold), an
  accessibility-reviewer agent and settings, documented in AGENTS.md

https://claude.ai/code/session_01LvWGnpirg7doE1sbsxh8g9
---
 .claude/agents/accessibility-reviewer.md      | 30 ++++++++++++
 .claude/settings.json                         | 19 ++++++++
 .claude/skills/a11y-review/SKILL.md           | 48 +++++++++++++++++++
 .claude/skills/component-scaffold/SKILL.md    | 28 +++++++++++
 .lighthouserc.json                            |  9 ++--
 AGENTS.md                                     | 15 ++++++
 assets/css/tokens.css                         | 28 +++++++++++
 components/content/ProseHr.vue                |  2 +-
 .../navigation/NavigationLanguageSelector.vue |  1 +
 components/features/footer/Footer.vue         |  2 +-
 .../features/home/carousel/Carousel.vue       |  7 ++-
 .../home/server-concept/ServerConcept.vue     |  1 -
 .../features/home/team/TeamMemberCard.vue     |  2 +-
 components/features/home/team/TeamMembers.vue | 13 +++--
 .../home/timeline/VerticalTimeline.vue        |  2 +-
 .../features/navigation/LanguageSelector.vue  | 10 ++--
 .../features/navigation/NavigationBar.vue     | 15 ++++--
 .../opencollective/OpenCollectiveStats.vue    |  1 -
 components/features/sponsoring/Sponsoring.vue |  1 -
 eslint.config.mjs                             | 16 ++++++-
 i18n/locales/de.json                          |  3 +-
 i18n/locales/en.json                          |  3 +-
 layouts/default.vue                           |  3 +-
 package.json                                  |  3 ++
 pages/blog/[...slug].vue                      |  3 +-
 pnpm-lock.yaml                                | 25 ++++++++++
 26 files changed, 258 insertions(+), 32 deletions(-)
 create mode 100644 .claude/agents/accessibility-reviewer.md
 create mode 100644 .claude/settings.json
 create mode 100644 .claude/skills/a11y-review/SKILL.md
 create mode 100644 .claude/skills/component-scaffold/SKILL.md

diff --git a/.claude/agents/accessibility-reviewer.md b/.claude/agents/accessibility-reviewer.md
new file mode 100644
index 0000000..f37db4f
--- /dev/null
+++ b/.claude/agents/accessibility-reviewer.md
@@ -0,0 +1,30 @@
+---
+name: accessibility-reviewer
+description: >-
+  Use to independently review UI changes for accessibility and UX-flow
+  regressions before a PR is opened or when a reviewer requests an a11y pass.
+  Reports findings only; does not edit code unless explicitly asked.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are an accessibility specialist reviewing changes to a Nuxt 3 / Vue 3
+site (Tailwind, @nuxt/content, @nuxtjs/i18n).
+
+Process:
+1. Determine the changed UI files: `git diff --name-only main...HEAD` filtered
+   to `components/`, `layouts/`, `pages/`, `assets/css/`.
+2. Read each changed file fully and apply the `a11y-review` skill checklist
+   (WCAG 2.1 AA: structure/semantics, keyboard/focus, names/labels/i18n,
+   contrast/motion).
+3. Run `pnpm lint` and report any `vuejs-accessibility/*` violations.
+
+Output a single report grouped by severity:
+- **Blocker** — keyboard trap, missing accessible name, broken landmark,
+  contrast failure.
+- **Should fix** — heading order, redundant landmarks, missing
+  `aria-expanded`.
+- **Nice to have** — minor polish.
+
+Each finding: `file:line`, the problem, and a concrete fix. Be precise and
+brief. Do not modify files unless the caller explicitly instructs you to.
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..5bac224
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(pnpm install)",
+      "Bash(pnpm dev)",
+      "Bash(pnpm build)",
+      "Bash(pnpm generate)",
+      "Bash(pnpm lint)",
+      "Bash(pnpm lint:fix)",
+      "Bash(pnpm exec eslint .)",
+      "Bash(pnpm seo:lighthouse)",
+      "Bash(pnpm seo:check)",
+      "Bash(git diff:*)",
+      "Bash(git status)",
+      "Bash(git log:*)"
+    ]
+  }
+}
diff --git a/.claude/skills/a11y-review/SKILL.md b/.claude/skills/a11y-review/SKILL.md
new file mode 100644
index 0000000..7619c4f
--- /dev/null
+++ b/.claude/skills/a11y-review/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: a11y-review
+description: >-
+  Audit Vue/Nuxt components and pages in this repo for accessibility (WCAG 2.1
+  AA) and UX-flow issues. Use whenever adding or changing UI, before opening a
+  PR with visual changes, or when the user asks for an accessibility check.
+---
+
+# Accessibility & UX-Flow Review
+
+Apply this checklist to every changed `.vue` file under `components/`,
+`layouts/`, and `pages/`. Report findings as a short list grouped by
+severity (blocker / should-fix / nice-to-have) with `file:line` refs.
+
+## Structure & semantics
+- One `<h1>` per page; headings increase by one level (no skipped levels).
+- Use semantic elements (`<button>`, `<nav>`, `<main>`, `<header>`,
+  `<footer>`) instead of `div`/`span` with click handlers.
+- Exactly one `<main id="main-content">`; landmark roles are not duplicated
+  with identical `aria-label`s.
+- Interactive `<div>`/`<span>` is forbidden — use a real `<button>`/`<a>`.
+
+## Keyboard & focus
+- Every interactive element is reachable and operable by keyboard.
+- Visible focus style (`focus-visible:ring-*`) on all focusable elements.
+- Disclosure/menu toggles expose `aria-expanded` and `aria-controls`.
+- Overlays/dialogs trap focus, restore focus on close, close on `Escape`.
+- The skip link in `layouts/default.vue` still targets `#main-content`.
+
+## Names, labels, i18n
+- Icon-only controls have an `aria-label` sourced from i18n
+  (`accessibility.*`), never a hard-coded string.
+- All `<img>`/`<NuxtImg>` have meaningful `alt` (empty `alt=""` only for
+  purely decorative images).
+- Form fields have associated `<label>`s.
+- Add new strings to both `i18n/locales/en.json` and `de.json`.
+
+## Visual & motion
+- Text/background contrast meets WCAG AA (4.5:1, or 3:1 for large text);
+  verify against Tailwind tokens in `assets/css/tokens.css`.
+- Animations/transitions respect `prefers-reduced-motion` (covered globally
+  in `tokens.css` — do not reintroduce unconditional long transitions).
+- Tap targets are at least 24x24 px.
+
+## Verification
+- Run `pnpm lint` (eslint-plugin-vuejs-accessibility is wired in).
+- For page-level changes, run `pnpm seo:lighthouse` and keep the
+  `categories:accessibility` gate (error, minScore 0.9) green.
diff --git a/.claude/skills/component-scaffold/SKILL.md b/.claude/skills/component-scaffold/SKILL.md
new file mode 100644
index 0000000..80f6bc0
--- /dev/null
+++ b/.claude/skills/component-scaffold/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: component-scaffold
+description: >-
+  Scaffold a new feature in this Nuxt repo following the house pattern:
+  domain types first, then a composable, then section/UI components, then wire
+  the page. Use when adding any new feature, section, or page.
+---
+
+# Feature Scaffold (types -> composables -> sections -> page)
+
+Follow this order strictly; it is the repo convention from `AGENTS.md`.
+
+1. **Domain types** — add to `types/` (e.g. `types/<feature>.ts`). Model the
+   data the feature renders before touching UI.
+2. **Composable** — add `composables/use<Feature>.ts` that loads/derives the
+   data and exposes a typed, reactive API. Keep data logic out of components.
+3. **Section / UI components** — build under
+   `components/features/<feature>/`, reusing `components/base/*` primitives.
+   Use `<script setup lang="ts">`, 2-space indent, `PascalCase.vue`.
+4. **Page assembly** — the route file in `pages/` only composes sections and
+   calls the composable; it contains no business logic.
+
+## Constraints
+- Do not add new dependencies or config presets without clear justification.
+- Respect the existing directory structure; extend, don't rearrange.
+- Every new string goes into both `i18n/locales/en.json` and `de.json`.
+- Before finishing, run the `a11y-review` skill on the new components and
+  ensure `pnpm lint` and `pnpm build` pass.
diff --git a/.lighthouserc.json b/.lighthouserc.json
index fc5f2f6..976380d 100644
--- a/.lighthouserc.json
+++ b/.lighthouserc.json
@@ -23,7 +23,7 @@
       "assertions": {
         "categories:seo": ["error", { "minScore": 0.95 }],
         "categories:best-practices": ["warn", { "minScore": 0.9 }],
-        "categories:accessibility": ["warn", { "minScore": 0.9 }],
+        "categories:accessibility": ["error", { "minScore": 0.9 }],
         "robots-txt": "error",
         "canonical": "error",
         "hreflang": "error",
@@ -32,8 +32,11 @@
         "html-lang-valid": "error",
         "meta-description": "error",
         "document-title": "error",
-        "image-alt": "warn",
-        "link-text": "warn"
+        "image-alt": "error",
+        "link-text": "error",
+        "color-contrast": ["warn", { "minScore": 0.9 }],
+        "tap-targets": "warn",
+        "heading-order": "warn"
       }
     },
     "upload": {
diff --git a/AGENTS.md b/AGENTS.md
index 1ab0be5..19d0f07 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,3 +41,18 @@
 - For neue Features zuerst Domain-Typen unter `types/` und Composables unter `composables/` anlegen, dann Sections/UI-Komponenten bauen und die Seite nur noch daraus zusammensetzen.
 - Do not introduce new dependencies or configuration presets without clear justification.
 - Respect the existing directory structure; extend rather than rearrange where possible.
+
+## Reusable Agents & Skills (`.claude/`)
+These are checked in so every CLI/web session gets the same standards. Treat
+them as rules, not suggestions:
+- **`.claude/skills/component-scaffold`** — MUST be followed when adding any
+  new feature/section/page (types → composables → sections → page).
+- **`.claude/skills/a11y-review`** — MUST be run on every changed
+  `components/`, `layouts/`, or `pages/` file before finishing UI work.
+- **`.claude/agents/accessibility-reviewer`** — delegate an independent
+  accessibility pass to this subagent before opening a PR with visual changes.
+- Accessibility tooling is enforced in CI: `eslint-plugin-vuejs-accessibility`
+  via `pnpm lint`, and the Lighthouse `accessibility` gate
+  (error, minScore 0.9) via `pnpm seo:lighthouse`. Keep both green.
+- When adding new skills/agents, place them under `.claude/` and document
+  them here so they remain the single source of truth.
diff --git a/assets/css/tokens.css b/assets/css/tokens.css
index 3360c77..7799ab6 100644
--- a/assets/css/tokens.css
+++ b/assets/css/tokens.css
@@ -5,6 +5,34 @@ html { scroll-behavior: smooth; }
 /* Respect user preference to reduce motion */
 @media (prefers-reduced-motion: reduce) {
   html { scroll-behavior: auto; }
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* Skip link: visually hidden until focused via keyboard */
+.skip-link {
+  position: absolute;
+  left: 0.5rem;
+  top: -3rem;
+  z-index: 100;
+  padding: 0.5rem 1rem;
+  border-radius: 0.5rem;
+  background: var(--color-surface);
+  color: var(--color-text);
+  box-shadow: 0 2px 8px rgb(0 0 0 / 25%);
+  transition: top 0.15s ease-in-out;
+}
+
+.skip-link:focus {
+  top: 0.5rem;
+  outline: 2px solid var(--color-secondary);
+  outline-offset: 2px;
 }
 
   /* Utility: Gradient-Text auf Basis der Brand-Token */
diff --git a/components/content/ProseHr.vue b/components/content/ProseHr.vue
index 83fbe36..5f3eda6 100644
--- a/components/content/ProseHr.vue
+++ b/components/content/ProseHr.vue
@@ -1,3 +1,3 @@
 <template>
-  <hr role="separator" class="my-6 border-t border-gray-200 dark:border-gray-700 transition-colors">
+  <hr class="my-6 border-t border-gray-200 dark:border-gray-700 transition-colors">
 </template>
\ No newline at end of file
diff --git a/components/features/blog/base/navigation/NavigationLanguageSelector.vue b/components/features/blog/base/navigation/NavigationLanguageSelector.vue
index 676479b..4efacea 100644
--- a/components/features/blog/base/navigation/NavigationLanguageSelector.vue
+++ b/components/features/blog/base/navigation/NavigationLanguageSelector.vue
@@ -53,6 +53,7 @@ onClickOutside(dropdown, () => {
         class="absolute z-30 mt-2 overflow-hidden origin-top-right bg-white text-gray-900 dark:text-white dark:bg-gray-800 rounded-xl shadow-xxl transition-all transform"
         :class="props.mobile ? 'left-0 right-0' : 'right-0 w-48'"
         role="menu"
+        tabindex="-1"
         :aria-labelledby="props.mobile ? 'mobile-language-menu-button' : 'language-menu-button'"
         @keydown.esc="isOpen = false"
     >
diff --git a/components/features/footer/Footer.vue b/components/features/footer/Footer.vue
index 4a73888..7816648 100644
--- a/components/features/footer/Footer.vue
+++ b/components/features/footer/Footer.vue
@@ -12,7 +12,7 @@ const versionLabel = computed(() =>
 </script>
 
 <template>
-  <footer class="mt-auto bg-[var(--color-surface)] dark:bg-[var(--color-surface)]" role="contentinfo" :aria-label="t('footer.aria_label')">
+  <footer class="mt-auto bg-[var(--color-surface)] dark:bg-[var(--color-surface)]" :aria-label="t('footer.aria_label')">
     <!-- Main section -->
     <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
       <div class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-4 gap-6 md:gap-8">
diff --git a/components/features/home/carousel/Carousel.vue b/components/features/home/carousel/Carousel.vue
index f4ca7b5..7612cec 100644
--- a/components/features/home/carousel/Carousel.vue
+++ b/components/features/home/carousel/Carousel.vue
@@ -227,9 +227,10 @@ function withAlpha(rgb: string, a: number) {
 </script>
 
 <template>
+  <!-- carousel container per WAI-ARIA APG; section with a name is implicitly a region and owns the keyboard interaction -->
+  <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -->
   <section
     class="w-full"
-    role="region"
     :aria-label="ariaLabel"
     aria-roledescription="carousel"
     @keydown="onKeydown"
@@ -240,11 +241,15 @@ function withAlpha(rgb: string, a: number) {
     <div class="relative">
 
       <!-- Ratio wrapper -->
+      <!-- focusable swipe surface; pointer/touch gestures have keyboard parity via the section keydown handler -->
+      <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -->
       <div
         class="group relative z-10 w-full overflow-hidden rounded-xl border border-[var(--color-border)] bg-[var(--color-surface)] touch-pan-y select-none min-h-[58svh] md:min-h-0"
         :style="{ paddingTop: aspectPercent }"
         @mouseenter="isHovering = true"
         @mouseleave="isHovering = false"
+        @focusin="isHovering = true"
+        @focusout="isHovering = false"
         @pointerdown.passive="onPointerDown"
         @pointerup.passive="onPointerUp"
         @touchstart.passive="onPointerDown"
diff --git a/components/features/home/server-concept/ServerConcept.vue b/components/features/home/server-concept/ServerConcept.vue
index a630bb6..b4ed833 100644
--- a/components/features/home/server-concept/ServerConcept.vue
+++ b/components/features/home/server-concept/ServerConcept.vue
@@ -29,7 +29,6 @@ const iconFor = (name?: string): IconDefinition => iconMap[name ?? ''] ?? faCirc
 <template>
   <section
     class="relative isolate w-full"
-    role="region"
     :aria-labelledby="headingId"
     :aria-describedby="props.subtitle ? descriptionId : undefined"
   >
diff --git a/components/features/home/team/TeamMemberCard.vue b/components/features/home/team/TeamMemberCard.vue
index b37cbff..857e793 100644
--- a/components/features/home/team/TeamMemberCard.vue
+++ b/components/features/home/team/TeamMemberCard.vue
@@ -35,7 +35,7 @@ const ariaLabel = computed(() => t('team.card_aria', { name: props.name, role: p
 </script>
 
 <template>
-  <li class="snap-start shrink-0 w-72" role="listitem">
+  <li class="snap-start shrink-0 w-72">
     <component
       :is="profileHref ? NuxtLink : 'div'"
       :to="profileHref"
diff --git a/components/features/home/team/TeamMembers.vue b/components/features/home/team/TeamMembers.vue
index 371e254..38d227f 100644
--- a/components/features/home/team/TeamMembers.vue
+++ b/components/features/home/team/TeamMembers.vue
@@ -65,9 +65,9 @@ const onWheel = (e: WheelEvent) => {
 
     <div class="mb-4 flex flex-col items-stretch gap-3 sm:flex-row sm:items-end sm:justify-between">
       <div class="flex gap-3">
-        <label class="sr-only" :for="'team-search'">{{ t('team.search_label') }}</label>
+        <label class="sr-only" for="team-search">{{ t('team.search_label') }}</label>
         <input
-          :id="'team-search'"
+          id="team-search"
           v-model="query"
           type="search"
           :placeholder="t('team.search_placeholder')"
@@ -75,9 +75,9 @@ const onWheel = (e: WheelEvent) => {
         />
 
         <div class="flex items-center gap-2">
-          <label class="text-sm text-gray-700 dark:text-gray-300" :for="'team-role'">{{ t('team.filter_role') }}</label>
+          <label class="text-sm text-gray-700 dark:text-gray-300" for="team-role">{{ t('team.filter_role') }}</label>
           <select
-            :id="'team-role'"
+            id="team-role"
             v-model="selectedRole"
             class="rounded-lg border border-zinc-300/70 dark:border-zinc-700/80 bg-white/90 dark:bg-zinc-900/70 px-2 py-2 text-sm text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-brand-500"
           >
@@ -88,9 +88,9 @@ const onWheel = (e: WheelEvent) => {
       </div>
 
       <div class="flex items-center gap-2">
-        <label class="text-sm text-gray-700 dark:text-gray-300" :for="'team-limit'">{{ t('team.limit_label') }}</label>
+        <label class="text-sm text-gray-700 dark:text-gray-300" for="team-limit">{{ t('team.limit_label') }}</label>
         <select
-          :id="'team-limit'"
+          id="team-limit"
           v-model.number="visibleCount"
           class="rounded-lg border border-zinc-300/70 dark:border-zinc-700/80 bg-white/90 dark:bg-zinc-900/70 px-2 py-2 text-sm text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-brand-500"
         >
@@ -109,7 +109,6 @@ const onWheel = (e: WheelEvent) => {
     >
       <ul
         class="team-scroll flex gap-4 overflow-x-auto pb-4 snap-x snap-mandatory [scrollbar-color:theme(colors.zinc.400)_transparent] [scrollbar-width:thin]"
-        role="list"
         :aria-label="t('team.list_label')"
         @wheel.prevent="onWheel"
       >
diff --git a/components/features/home/timeline/VerticalTimeline.vue b/components/features/home/timeline/VerticalTimeline.vue
index f9cb8a1..25432fb 100644
--- a/components/features/home/timeline/VerticalTimeline.vue
+++ b/components/features/home/timeline/VerticalTimeline.vue
@@ -97,7 +97,7 @@ const shouldBlur = (index: number) => {
   <section class="relative" :class="lineColorClass">
     <!-- Central line (visible from md breakpoint upwards) -->
 
-    <ol role="list" :aria-label="ariaLabelComputed" class="relative mx-auto max-w-5xl space-y-10">
+    <ol :aria-label="ariaLabelComputed" class="relative mx-auto max-w-5xl space-y-10">
       <div class="pointer-events-none absolute left-1/2 top-0 hidden h-full w-px -translate-x-1/2 bg-[var(--line)] md:block" aria-hidden="true" />
       <template v-for="(ev, i) in displayedEvents" :key="ev.id">
         <slot
diff --git a/components/features/navigation/LanguageSelector.vue b/components/features/navigation/LanguageSelector.vue
index 55dbba8..530c96a 100644
--- a/components/features/navigation/LanguageSelector.vue
+++ b/components/features/navigation/LanguageSelector.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, computed, nextTick, navigateTo, onMounted, onBeforeUnmount } from '#imports';
+import { ref, computed, nextTick, navigateTo, onMounted, onBeforeUnmount, onKeyStroke } from '#imports';
 import { FontAwesomeIcon } from '@fortawesome/vue-fontawesome'
 import { faLanguage, faChevronDown } from '@fortawesome/free-solid-svg-icons'
 const { t } = useI18n();
@@ -48,6 +48,10 @@ const toggleDropdown = async () => {
   else await openDropdown('first');
 };
 
+onKeyStroke('Escape', () => {
+  if (isOpen.value) closeDropdown(true);
+});
+
 const onButtonKeydown = async (e: KeyboardEvent) => {
   if (e.key === 'ArrowDown') { e.preventDefault(); await openDropdown('first'); }
   else if (e.key === 'ArrowUp') { e.preventDefault(); await openDropdown('last'); }
@@ -130,7 +134,7 @@ const selectLocale = async (localeCode: string) => {
 </script>
 
 <template>
-  <div v-if="variant === 'desktop'" class="relative" @keydown.escape.window="closeDropdown(true)">
+  <div v-if="variant === 'desktop'" class="relative">
     <button
       @click="toggleDropdown"
       :aria-label="t('navigation.change_language')"
@@ -181,7 +185,7 @@ const selectLocale = async (localeCode: string) => {
     </Transition>
   </div>
 
-  <div v-else class="flex flex-col" @keydown.escape.window="isOpen = false">
+  <div v-else class="flex flex-col">
     <div class="flex items-center gap-3 px-4 py-3 text-base font-medium text-[var(--color-text)]/70 dark:text-[var(--color-text)]/85">
       <FontAwesomeIcon :icon="faLanguage" class="text-xl" />
       {{ t('navigation.change_language') }}
diff --git a/components/features/navigation/NavigationBar.vue b/components/features/navigation/NavigationBar.vue
index 8c693a8..8eb7c69 100644
--- a/components/features/navigation/NavigationBar.vue
+++ b/components/features/navigation/NavigationBar.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, computed, watch, useRoute } from '#imports';
+import { ref, computed, watch, useRoute, onKeyStroke } from '#imports';
 import NavigationItem from './NavigationItem.vue'
 import LanguageSelector from './LanguageSelector.vue'
 import NavigationIconButton from '~/components/base/buttons/NavigationIconButton.vue'
@@ -95,6 +95,8 @@ watch(
   () => route.fullPath,
   () => closeMenus()
 )
+
+onKeyStroke('Escape', () => closeMenus())
 </script>
 
 <template>
@@ -102,9 +104,8 @@ watch(
   <header
     v-if="variant === 'top'"
     :class="['sticky top-0 z-50 w-full bg-[var(--color-surface)]/90 dark:bg-[var(--color-surface)]/95 backdrop-blur', elevationClasses[elevation]]"
-    @keydown.escape.window="closeMenus"
   >
-    <div class="mx-auto max-w-screen-xl px-4 sm:px-6 lg:px-8" role="navigation" :aria-label="t('navigation.main')">
+    <div class="mx-auto max-w-screen-xl px-4 sm:px-6 lg:px-8">
       <div class="flex h-16 items-center justify-between">
         <div class="flex items-center">
           <NuxtLinkLocale to="/" :aria-label="t('navigation.overview')" class="flex items-center gap-2 text-[var(--color-text)] no-underline hover:opacity-90 dark:text-[var(--color-text)]">
@@ -113,7 +114,7 @@ watch(
           </NuxtLinkLocale>
         </div>
 
-        <nav class="hidden items-center gap-2 lg:flex" role="navigation" :aria-label="t('navigation.main')">
+        <nav class="hidden items-center gap-2 lg:flex" :aria-label="t('navigation.main')">
           <template v-for="item in allNavItems" :key="item.type === 'link' ? item.path : item.textKey">
             <NavigationItem
               v-if="item.type === 'link'"
@@ -128,8 +129,11 @@ watch(
                 :open="openGroup === item.textKey"
                 @toggle.prevent
               >
+                <!-- summary is the native disclosure button: Enter/Space fire a click natively, so keyboard parity exists -->
+                <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions, vuejs-accessibility/click-events-have-key-events -->
                 <summary
                   class="flex items-center gap-2 px-3 py-2 rounded-full text-[var(--color-text)] no-underline transition-colors hover:bg-[var(--color-surface)]/70 dark:hover:bg-[var(--color-surface)]/60 focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-secondary)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-surface)] cursor-pointer list-none"
+                  :aria-expanded="openGroup === item.textKey ? 'true' : 'false'"
                   @click.prevent="toggleGroup(item.textKey)"
                 >
                   <IconFa v-if="item.icon" :icon="item.icon" class="h-4 w-4" />
@@ -173,10 +177,11 @@ watch(
       leave-from-class="opacity-100 translate-y-0"
       leave-to-class="opacity-0 -translate-y-2"
     >
+      <!-- decorative backdrop; click-to-dismiss is a pointer convenience, keyboard users dismiss via Escape or the toggle button -->
+      <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions, vuejs-accessibility/click-events-have-key-events -->
       <div
         v-if="mobileMenuOpen"
         class="fixed inset-0 top-16 z-40 bg-black/40 backdrop-blur-sm lg:hidden"
-        aria-hidden="false"
         @click.self="mobileMenuOpen = false"
       >
         <nav
diff --git a/components/features/opencollective/OpenCollectiveStats.vue b/components/features/opencollective/OpenCollectiveStats.vue
index 2eb88ca..83bf45d 100644
--- a/components/features/opencollective/OpenCollectiveStats.vue
+++ b/components/features/opencollective/OpenCollectiveStats.vue
@@ -81,7 +81,6 @@ const updatedLabel = computed(() => {
   <section
     id="opencollective"
     class="relative isolate w-full"
-    role="region"
     :aria-labelledby="headingId"
     :aria-describedby="descriptionId"
     :aria-label="t('collective.section_aria')"
diff --git a/components/features/sponsoring/Sponsoring.vue b/components/features/sponsoring/Sponsoring.vue
index 6b1b95b..a947e16 100644
--- a/components/features/sponsoring/Sponsoring.vue
+++ b/components/features/sponsoring/Sponsoring.vue
@@ -90,7 +90,6 @@ watch(
   <section
     id="sponsoring"
     class="relative isolate w-full"
-    role="region"
     :aria-labelledby="headingId"
     :aria-describedby="descriptionId"
     :aria-label="sectionAria"
diff --git a/eslint.config.mjs b/eslint.config.mjs
index b4ea1ef..5dc6942 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -1,7 +1,21 @@
 // @ts-check
+import vuejsAccessibility from 'eslint-plugin-vuejs-accessibility'
 import withNuxt from './.nuxt/eslint.config.mjs'
 
-export default withNuxt({
+const a11yConfigs = vuejsAccessibility.configs['flat/recommended'].map(config => ({
+  ...config,
+  files: ['**/*.vue'],
+  rules: {
+    ...config.rules,
+    // Labels associated via `for`/`id` are valid; do not also require nesting.
+    'vuejs-accessibility/label-has-for': [
+      'error',
+      { required: { some: ['nesting', 'id'] }, allowChildren: false }
+    ]
+  }
+}))
+
+export default withNuxt(...a11yConfigs, {
   rules: {
     'linebreak-style': ['error', 'unix'],
     'max-len': [
diff --git a/i18n/locales/de.json b/i18n/locales/de.json
index 389385b..712a38c 100644
--- a/i18n/locales/de.json
+++ b/i18n/locales/de.json
@@ -160,7 +160,8 @@
     "section_subtitle": "Das Wichtigste, um auf dem Netzwerk loszulegen."
   },
   "accessibility": {
-    "logo_alt": "OneLiteFeather Logo"
+    "logo_alt": "OneLiteFeather Logo",
+    "skip_to_content": "Zum Hauptinhalt springen"
   },
   "article": {
     "share": "Diesen Artikel teilen",
diff --git a/i18n/locales/en.json b/i18n/locales/en.json
index 95a2321..56eafab 100644
--- a/i18n/locales/en.json
+++ b/i18n/locales/en.json
@@ -160,7 +160,8 @@
     "section_subtitle": "Everything you need to know to get started on the network."
   },
   "accessibility": {
-    "logo_alt": "OneLiteFeather Logo"
+    "logo_alt": "OneLiteFeather Logo",
+    "skip_to_content": "Skip to main content"
   },
   "article": {
     "share": "Share this article",
diff --git a/layouts/default.vue b/layouts/default.vue
index 31cb596..ebacc88 100644
--- a/layouts/default.vue
+++ b/layouts/default.vue
@@ -21,8 +21,9 @@ useSiteNavigationSchema()
     <Body class="dark:bg-gray-900 overflow-x-hidden">
       <!-- Local wrapper ensures flex layout even if <Body> classes are not applied by the renderer -->
       <div class="min-h-screen flex flex-col">
+        <a href="#main-content" class="skip-link">{{ t('accessibility.skip_to_content') }}</a>
         <LayoutNavigationBar />
-        <main class="px-4 mx-auto sm:px-6 lg:px-8 w-full flex-1">
+        <main id="main-content" tabindex="-1" class="px-4 mx-auto sm:px-6 lg:px-8 w-full flex-1 focus:outline-none">
           <slot/>
         </main>
         <LayoutFooter />
diff --git a/package.json b/package.json
index 268f4a2..96cc74e 100644
--- a/package.json
+++ b/package.json
@@ -21,6 +21,8 @@
     "dev": "nuxt dev",
     "generate": "nuxt generate",
     "preview": "nuxt preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "postinstall": "nuxt prepare",
     "seo:check": "node scripts/seo-check.mjs",
     "seo:lighthouse": "lhci autorun --config=./.lighthouserc.json"
@@ -44,6 +46,7 @@
     "cheerio": "^1.0.0",
     "debug": "^4.4.3",
     "eslint": "^9.39.1",
+    "eslint-plugin-vuejs-accessibility": "^2.5.0",
     "nitro": "3.0.260429-beta",
     "nuxt": "^4.2.1",
     "nuxt-gtag": "4.1.0",
diff --git a/pages/blog/[...slug].vue b/pages/blog/[...slug].vue
index eb260b8..3f9e76b 100644
--- a/pages/blog/[...slug].vue
+++ b/pages/blog/[...slug].vue
@@ -28,8 +28,7 @@ useHead(() => (blog.value as BlogArticle | null)?.head || {})
     <article
       v-if="blog"
       class="bg-white dark:bg-neutral-900 rounded-xl shadow-md overflow-hidden ring-1 ring-black/5 dark:ring-white/10 focus-within:outline focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-primary"
-      role="article"
-      :aria-labelledby="'article-title'"
+      aria-labelledby="article-title"
     >
       <NuxtPicture
         v-if="blog?.headerImage"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c58430a..a945f50 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -103,6 +103,9 @@ importers:
       eslint:
         specifier: ^9.39.1
         version: 9.39.4(jiti@2.7.0)
+      eslint-plugin-vuejs-accessibility:
+        specifier: ^2.5.0
+        version: 2.5.0(eslint@9.39.4(jiti@2.7.0))(globals@17.6.0)
       nitro:
         specifier: 3.0.260429-beta
         version: 3.0.260429-beta(better-sqlite3@12.10.0)(chokidar@5.0.0)(dotenv@17.4.2)(giget@3.2.0)(ioredis@5.10.1)(jiti@2.7.0)(lru-cache@11.3.6)(rollup@4.60.4)(vite@7.3.3(@types/node@25.8.0)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.47.1)(yaml@2.9.0))
@@ -3322,6 +3325,10 @@ packages:
   argparse@2.0.1:
     resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
 
+  aria-query@5.3.2:
+    resolution: {integrity: sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==}
+    engines: {node: '>= 0.4'}
+
   ast-kit@2.2.0:
     resolution: {integrity: sha512-m1Q/RaVOnTp9JxPX+F+Zn7IcLYMzM8kZofDImfsKZd8MbR+ikdOzTeztStWqfrqIxZnYWryyI9ePm3NGjnZgGw==}
     engines: {node: '>=20.19.0'}
@@ -4110,6 +4117,13 @@ packages:
       '@typescript-eslint/parser':
         optional: true
 
+  eslint-plugin-vuejs-accessibility@2.5.0:
+    resolution: {integrity: sha512-oZ2fL4tS91Cm/ezH3BueNP+FtpbbeS627OSqqgp9/lsN//glmoPcLBT6D53xwGocLtyBybaT99tX4ThBh8+ytA==}
+    engines: {node: '>=16.0.0'}
+    peerDependencies:
+      eslint: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0
+      globals: '>= 13.12.1'
+
   eslint-processor-vue-blocks@2.0.0:
     resolution: {integrity: sha512-u4W0CJwGoWY3bjXAuFpc/b6eK3NQEI8MoeW7ritKj3G3z/WtHrKjkqf+wk8mPEy5rlMGS+k6AZYOw2XBoN/02Q==}
     peerDependencies:
@@ -10208,6 +10222,8 @@ snapshots:
 
   argparse@2.0.1: {}
 
+  aria-query@5.3.2: {}
+
   ast-kit@2.2.0:
     dependencies:
       '@babel/parser': 7.29.3
@@ -11041,6 +11057,15 @@ snapshots:
       '@stylistic/eslint-plugin': 5.10.0(eslint@9.39.4(jiti@2.7.0))
       '@typescript-eslint/parser': 8.59.3(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)
 
+  eslint-plugin-vuejs-accessibility@2.5.0(eslint@9.39.4(jiti@2.7.0))(globals@17.6.0):
+    dependencies:
+      aria-query: 5.3.2
+      eslint: 9.39.4(jiti@2.7.0)
+      globals: 17.6.0
+      vue-eslint-parser: 10.4.0(eslint@9.39.4(jiti@2.7.0))
+    transitivePeerDependencies:
+      - supports-color
+
   eslint-processor-vue-blocks@2.0.0(@vue/compiler-sfc@3.5.34)(eslint@9.39.4(jiti@2.7.0)):
     dependencies:
       '@vue/compiler-sfc': 3.5.34

From af32e097f8f447f9d941144d09f97b6e4f818894 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 16 May 2026 10:51:43 +0000
Subject: [PATCH 2/3] chore: ignore .wrangler build artifacts

https://claude.ai/code/session_01LvWGnpirg7doE1sbsxh8g9
---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 1e322aa..c98e1f8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@
 .nuxt
 .nitro
 .cache
+.wrangler
 dist
 
 # Lighthouse CI local run artefacts (the workflow uploads its own copy)

From ea77b9bb8f2b596170f2d9fccbbce151fd5d013e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 16 May 2026 11:30:39 +0000
Subject: [PATCH 3/3] fix(a11y): resolve Lighthouse accessibility gate failures

- Darken Java server address button to emerald-700 for 4.5:1 contrast
- Drop invalid role="menuitem" from desktop nav links (no menu parent)
- Remove invalid role="listitem" on <article> + redundant role="list"
- Enlarge carousel and sponsor pagination dots to 24px touch targets
---
 components/features/home/carousel/Carousel.vue    | 11 ++++++++---
 .../home/server-addresses/ServerAddresses.vue     |  4 ++--
 .../home/server-concept/ServerConcept.vue         |  3 +--
 components/features/navigation/NavigationItem.vue |  1 -
 components/features/sponsoring/Sponsoring.vue     | 15 ++++++++++-----
 5 files changed, 21 insertions(+), 13 deletions(-)

diff --git a/components/features/home/carousel/Carousel.vue b/components/features/home/carousel/Carousel.vue
index 7612cec..ff900b6 100644
--- a/components/features/home/carousel/Carousel.vue
+++ b/components/features/home/carousel/Carousel.vue
@@ -314,13 +314,18 @@ function withAlpha(rgb: string, a: number) {
             v-for="(_s, i) in normalizedSlides"
             :key="i"
             type="button"
-            class="h-3.5 w-3.5 rounded-full transition ring-1 ring-white/60"
-            :class="i === current ? 'bg-[var(--color-brand-accent,#38bdf8)] ring-2 ring-offset-1 ring-offset-black/20' : 'bg-white/50 hover:bg-white/80'"
+            class="group grid h-6 w-6 place-items-center rounded-full focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80"
             :aria-label="`Show slide ${i + 1}`"
             :aria-current="i === current ? 'true' : undefined"
             :aria-controls="`carousel-slide-${i}`"
             @click.stop="goTo(i)"
-          />
+          >
+            <span
+              aria-hidden="true"
+              class="h-3.5 w-3.5 rounded-full transition ring-1 ring-white/60"
+              :class="i === current ? 'bg-[var(--color-brand-accent,#38bdf8)] ring-2 ring-offset-1 ring-offset-black/20' : 'bg-white/50 group-hover:bg-white/80'"
+            />
+          </button>
         </div>
       </div>
 
diff --git a/components/features/home/server-addresses/ServerAddresses.vue b/components/features/home/server-addresses/ServerAddresses.vue
index 57d492e..af121ff 100644
--- a/components/features/home/server-addresses/ServerAddresses.vue
+++ b/components/features/home/server-addresses/ServerAddresses.vue
@@ -107,8 +107,8 @@ const onCopyBedrockPort = async () => {
             :title="t('server.connect.java')"
             :address="props.javaAddress"
             icon="desktop_windows"
-            iconClass="text-emerald-600 dark:text-emerald-400"
-            buttonClass="bg-emerald-600"
+            iconClass="text-emerald-700 dark:text-emerald-400"
+            buttonClass="bg-emerald-700"
             :copied="copiedJava"
             :onCopy="onCopyJava"
           />
diff --git a/components/features/home/server-concept/ServerConcept.vue b/components/features/home/server-concept/ServerConcept.vue
index b4ed833..b032692 100644
--- a/components/features/home/server-concept/ServerConcept.vue
+++ b/components/features/home/server-concept/ServerConcept.vue
@@ -42,12 +42,11 @@ const iconFor = (name?: string): IconDefinition => iconMap[name ?? ''] ?? faCirc
         </SectionHeading>
       </div>
 
-      <div class="grid grid-cols-1 gap-4 sm:gap-6 md:grid-cols-3" role="list">
+      <div class="grid grid-cols-1 gap-4 sm:gap-6 md:grid-cols-3">
         <article
           v-for="(p, idx) in points"
           :key="p.id ?? idx"
           class="h-full rounded-2xl border border-zinc-200 dark:border-zinc-800 bg-white/80 dark:bg-zinc-900/80 p-5 shadow-sm ring-1 ring-zinc-200/70 dark:ring-zinc-800/70 transition hover:shadow-md"
-          role="listitem"
         >
           <header class="mb-3 flex items-center gap-3">
             <FontAwesomeIcon
diff --git a/components/features/navigation/NavigationItem.vue b/components/features/navigation/NavigationItem.vue
index 2d377d6..23278da 100644
--- a/components/features/navigation/NavigationItem.vue
+++ b/components/features/navigation/NavigationItem.vue
@@ -35,7 +35,6 @@ const isExternal = computed(() => /^https?:\/\//i.test(props.path));
       :to="path"
       class="relative inline-flex items-center gap-2 px-3 py-2 rounded-full text-[var(--color-text)] no-underline transition-colors hover:bg-[var(--color-surface)]/70 dark:hover:bg-[var(--color-surface)]/60 focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-secondary)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-surface)]"
       :class="isActive ? 'bg-[var(--color-secondary)]/15 text-[var(--color-secondary)]' : ''"
-      role="menuitem"
       :aria-current="isActive ? 'page' : undefined"
       @click="handleClick"
     >
diff --git a/components/features/sponsoring/Sponsoring.vue b/components/features/sponsoring/Sponsoring.vue
index a947e16..edd994e 100644
--- a/components/features/sponsoring/Sponsoring.vue
+++ b/components/features/sponsoring/Sponsoring.vue
@@ -196,14 +196,19 @@ watch(
                 v-for="(s, idx) in enhancedSponsors"
                 :key="s.name"
                 type="button"
-                class="relative h-3 w-3 rounded-full transition-all transform focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-brand-accent,#38bdf8)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-surface)]"
-                :class="idx === current
-                  ? 'bg-[var(--color-brand-accent,#38bdf8)] scale-110 ring-2 ring-[var(--color-border)]/10 ring-offset-2 ring-offset-[var(--color-surface)] shadow-[0_0_0_2px_rgba(56,189,248,0.25)]'
-                  : 'bg-zinc-300 dark:bg-zinc-700 scale-100 ring-1 ring-[var(--color-border)]/40'"
+                class="group grid h-6 w-6 place-items-center rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-brand-accent,#38bdf8)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-surface)]"
                 :aria-label="ariaLabelFor(s.name)"
                 :aria-current="idx === current ? 'true' : undefined"
                 @click="current = idx"
-              />
+              >
+                <span
+                  aria-hidden="true"
+                  class="relative h-3 w-3 rounded-full transition-all transform"
+                  :class="idx === current
+                    ? 'bg-[var(--color-brand-accent,#38bdf8)] scale-110 ring-2 ring-[var(--color-border)]/10 ring-offset-2 ring-offset-[var(--color-surface)] shadow-[0_0_0_2px_rgba(56,189,248,0.25)]'
+                    : 'bg-zinc-300 dark:bg-zinc-700 scale-100 ring-1 ring-[var(--color-border)]/40'"
+                />
+              </button>
             </div>
           </div>
         </div>