From d2751046cd8b814b817062f6fd027153925e1866 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?=
 <ralf.d.mueller+AI@gmail.com>
Date: Tue, 14 Apr 2026 09:44:01 +0200
Subject: [PATCH 1/2] fix: Lighthouse a11y + CLS issues on homepage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses real failures surfaced after PR #430 pointed Lighthouse at
the canonical deployed URL instead of the stale fork URL.

## Accessibility (0.92 → target 1.0)

### aria-allowed-role + label-content-name-mismatch
Anchor cards used <article role="button" aria-label="Open {title}
details">, which fails two axe rules:
- <article> has implicit role "article"; overriding to "button" is
  invalid per ARIA in HTML spec
- aria-label started with "Open" instead of the visible h3 text, so
  the accessible name didn't match the visible label

Fixed by changing <article> to <div role="button"> and using
aria-labelledby pointing at the h3 id. Accessible name now exactly
matches the visible title.

Event delegation uses the .anchor-card class, not the tag name, so
nothing breaks.

### select-name
#header-role-filter had no associated label. Added aria-label
referencing the existing "All roles" translation string.

### color-contrast
.meta-badge text inherited .anchor-card-meta's gray-500/400 colors,
which only reach ~3.9:1 (light) / ~3.1:1 (dark) on the badge's
gray-100/700 background — below the WCAG AA 4.5:1 threshold for
normal text. Explicitly set gray-700/200 on .meta-badge for ~5.3:1
in both themes.

## Performance (0.75 → target ≥ 0.9)

### cumulative-layout-shift (weight 25)
#page-content started empty and populated asynchronously with the
card grid, causing the single biggest CLS contributor on the page.
Added min-height: calc(100vh - 12rem) to reserve viewport space so
the browser doesn't shift layout when the content arrives.

### unsized-images
Logo images (header + onboarding modal) had no explicit width/height,
so the browser couldn't reserve space and had to reflow when the
image loaded. Added width/height attributes derived from the actual
logo.png aspect ratio (1024×451) and added w-auto so the CSS height
constraint still wins visually.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 website/src/components/card-grid.js        |  8 ++++----
 website/src/components/header.js           |  9 ++++++---
 website/src/components/onboarding-modal.js |  2 +-
 website/src/styles/main.css                | 11 +++++++++++
 website/src/translations/de.json           |  1 +
 website/src/translations/en.json           |  1 +
 6 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/website/src/components/card-grid.js b/website/src/components/card-grid.js
index 0281af48..4e563de2 100644
--- a/website/src/components/card-grid.js
+++ b/website/src/components/card-grid.js
@@ -112,17 +112,17 @@ function renderAnchorCard(anchor, categoryColor) {
   const safeId = escapeHtml(anchor.id)
 
   return `
-    <article
+    <div
       class="anchor-card${umbrellaClass}"
       data-anchor="${safeId}"
       data-roles="${escapeHtml(anchor.roles ? anchor.roles.join(',') : '')}"
       data-tags="${escapeHtml(anchor.tags ? anchor.tags.join(',') : '')}"
       tabindex="0"
       role="button"
-      aria-label="${escapeHtml(i18n.t('card.openDetails').replace('{title}', anchor.title))}"
+      aria-labelledby="anchor-card-title-${safeId}"
     >
       <div class="anchor-card-header">
-        <h3 class="anchor-card-title">${escapeHtml(anchor.title)}</h3>
+        <h3 id="anchor-card-title-${safeId}" class="anchor-card-title">${escapeHtml(anchor.title)}</h3>
         <div class="flex gap-1">
           <button
             class="anchor-copy-link-btn"
@@ -215,7 +215,7 @@ function renderAnchorCard(anchor, categoryColor) {
       </div>
 
       <div class="anchor-card-indicator" style="background-color: ${categoryColor}"></div>
-    </article>
+    </div>
   `
 }
 
diff --git a/website/src/components/header.js b/website/src/components/header.js
index 7c04cec9..0bda6f3a 100644
--- a/website/src/components/header.js
+++ b/website/src/components/header.js
@@ -11,7 +11,7 @@ export function renderHeader() {
           <!-- Logo left, spanning both rows -->
           <div class="flex items-center">
             <a href="#/" class="no-underline flex flex-col items-center">
-              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" class="max-h-24" />
+              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" width="218" height="96" class="max-h-24 w-auto" />
               <span class="text-xs text-[var(--color-text-secondary)] leading-tight" data-i18n="header.slogan">${i18n.t('header.slogan')}</span>
             </a>
             <button
@@ -54,7 +54,8 @@ export function renderHeader() {
                 <button
                   id="lang-toggle"
                   class="rounded-md px-2 py-1 text-sm font-medium text-[var(--color-text-secondary)] hover:text-[var(--color-text)] hover:bg-[var(--color-bg-secondary)] transition-colors"
-                  aria-label="Toggle language"
+                  aria-label="${i18n.t('header.langToggleAria')}"
+                  data-i18n-aria="header.langToggleAria"
                 >${langLabel}</button>
                 <button
                   id="theme-toggle"
@@ -82,6 +83,8 @@ export function renderHeader() {
               />
               <select
                 id="header-role-filter"
+                aria-label="${i18n.t('filter.allRoles')}"
+                data-i18n-aria="filter.allRoles"
                 class="rounded-lg border-2 border-[var(--color-border)] bg-[var(--color-bg)] px-4 py-2 text-base text-[var(--color-text)] focus:outline-none focus:ring-2 focus:ring-[var(--color-primary)] focus:border-[var(--color-primary)] transition-colors duration-300"
               >
                 <option value="" data-i18n="filter.allRoles">${i18n.t('filter.allRoles')}</option>
@@ -97,7 +100,7 @@ export function renderHeader() {
         <div class="sm:hidden">
           <div class="flex flex-col items-center">
             <a href="#/" class="no-underline flex flex-col items-center">
-              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" class="max-h-16" />
+              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" width="145" height="64" class="max-h-16 w-auto" />
               <span class="text-xs text-[var(--color-text-secondary)] leading-tight text-center" data-i18n="header.slogan">${i18n.t('header.slogan')}</span>
             </a>
             <div class="flex items-center gap-3 mt-2">
diff --git a/website/src/components/onboarding-modal.js b/website/src/components/onboarding-modal.js
index fc66e4d3..295335e4 100644
--- a/website/src/components/onboarding-modal.js
+++ b/website/src/components/onboarding-modal.js
@@ -101,7 +101,7 @@ function buildModalContent() {
       </div>
 
       <div class="text-center px-6 pb-4">
-        <img src="${baseUrl}logo.png" alt="Semantic Anchors" class="h-24 mx-auto mb-3" />
+        <img src="${baseUrl}logo.png" alt="Semantic Anchors" width="218" height="96" class="h-24 w-auto mx-auto mb-3" />
         <h2 id="onboarding-title" class="text-lg font-medium text-[var(--color-text-secondary)]">
           ${slogan2}
         </h2>
diff --git a/website/src/styles/main.css b/website/src/styles/main.css
index b23f4b42..6554604f 100644
--- a/website/src/styles/main.css
+++ b/website/src/styles/main.css
@@ -65,6 +65,13 @@ body {
   font-family: Inter, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
 }
 
+/* Reserve viewport height so the browser doesn't shift layout when the
+   card grid / doc content loads asynchronously. This is the single biggest
+   lever for Cumulative Layout Shift on the homepage (Lighthouse weight 25). */
+#page-content {
+  min-height: calc(100vh - 12rem);
+}
+
 /* Force sans-serif on all card descendants to override AsciiDoc serif fonts */
 .anchor-card,
 .anchor-card *,
@@ -164,6 +171,10 @@ body {
   @apply flex items-center gap-1;
   @apply px-2 py-1 rounded;
   @apply bg-gray-100 dark:bg-gray-700;
+  /* Explicit text color for WCAG AA contrast on the badge background.
+     Default .anchor-card-meta text (gray-500/400) only reaches ~3.9:1 / ~3.1:1,
+     below the 4.5:1 threshold for normal text. */
+  @apply text-gray-700 dark:text-gray-200;
 }
 
 .feedback-badge {
diff --git a/website/src/translations/de.json b/website/src/translations/de.json
index 87da146e..ec8898c1 100644
--- a/website/src/translations/de.json
+++ b/website/src/translations/de.json
@@ -2,6 +2,7 @@
   "app.title": "Semantic Anchors",
   "app.description": "Gemeinsames Vokabular für LLM-Kommunikation",
   "header.langToggle": "EN",
+  "header.langToggleAria": "EN — switch to English",
   "header.slogan": "Ein Wort, und die KI versteht den Rest.",
   "header.themeToggle.dark": "Zum Dunkelmodus wechseln",
   "header.themeToggle.light": "Zum Hellmodus wechseln",
diff --git a/website/src/translations/en.json b/website/src/translations/en.json
index 1dd76578..f633ca83 100644
--- a/website/src/translations/en.json
+++ b/website/src/translations/en.json
@@ -2,6 +2,7 @@
   "app.title": "Semantic Anchors",
   "app.description": "Shared vocabulary for LLM communication",
   "header.langToggle": "DE",
+  "header.langToggleAria": "DE — switch to German",
   "header.slogan": "One word, and the AI gets the rest.",
   "header.themeToggle.dark": "Switch to dark mode",
   "header.themeToggle.light": "Switch to light mode",

From f999826834840ff0b372ad93a5232bd67da02be2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?=
 <ralf.d.mueller+AI@gmail.com>
Date: Tue, 14 Apr 2026 10:15:36 +0200
Subject: [PATCH 2/2] fix: address CodeRabbit findings on #431
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. Mobile lang-toggle still had hardcoded aria-label="Toggle language".
   Now uses i18n.t('header.langToggleAria') + data-i18n-aria, matching
   the desktop fix from the parent commit.

2. de.json aria-label was English ("EN — switch to English"). Now
   properly localized: "EN — zu Englisch wechseln".

3. Anchor card heading ids are now namespaced with the category id.
   An anchor can belong to multiple categories and is rendered once per
   category section, so the previous "anchor-card-title-<id>" pattern
   produced duplicate DOM ids for those anchors. New pattern:
   "anchor-card-title-<categoryId>-<anchorId>".
---
 website/src/components/card-grid.js | 17 ++++++++++++-----
 website/src/components/header.js    |  3 ++-
 website/src/translations/de.json    |  2 +-
 3 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/website/src/components/card-grid.js b/website/src/components/card-grid.js
index 4e563de2..cb1d4f73 100644
--- a/website/src/components/card-grid.js
+++ b/website/src/components/card-grid.js
@@ -90,16 +90,21 @@ function renderCategorySection(category, allAnchors) {
       </h2>
 
       <div class="anchor-cards-grid">
-        ${categoryAnchors.map((anchor) => renderAnchorCard(anchor, color)).join('')}
+        ${categoryAnchors.map((anchor) => renderAnchorCard(anchor, color, category.id)).join('')}
       </div>
     </section>
   `
 }
 
 /**
- * Render a single anchor card
+ * Render a single anchor card.
+ *
+ * The optional `categoryId` argument is used to namespace the heading id
+ * used by `aria-labelledby`, since the same anchor may appear in multiple
+ * category sections (anchors can belong to more than one category) and
+ * the DOM must not contain duplicate ids.
  */
-function renderAnchorCard(anchor, categoryColor) {
+function renderAnchorCard(anchor, categoryColor, categoryId) {
   const isUmbrella = anchor.subAnchors && anchor.subAnchors.length > 0
   const umbrellaClass = isUmbrella ? ' anchor-card-umbrella' : ''
   const rolesCount = anchor.roles ? anchor.roles.length : 0
@@ -110,6 +115,8 @@ function renderAnchorCard(anchor, categoryColor) {
   const editTitle = i18n.t('card.edit')
   const copyLinkTitle = i18n.t('card.copyLink')
   const safeId = escapeHtml(anchor.id)
+  const safeCategoryId = escapeHtml(categoryId || 'uncat')
+  const cardTitleId = `anchor-card-title-${safeCategoryId}-${safeId}`
 
   return `
     <div
@@ -119,10 +126,10 @@ function renderAnchorCard(anchor, categoryColor) {
       data-tags="${escapeHtml(anchor.tags ? anchor.tags.join(',') : '')}"
       tabindex="0"
       role="button"
-      aria-labelledby="anchor-card-title-${safeId}"
+      aria-labelledby="${cardTitleId}"
     >
       <div class="anchor-card-header">
-        <h3 id="anchor-card-title-${safeId}" class="anchor-card-title">${escapeHtml(anchor.title)}</h3>
+        <h3 id="${cardTitleId}" class="anchor-card-title">${escapeHtml(anchor.title)}</h3>
         <div class="flex gap-1">
           <button
             class="anchor-copy-link-btn"
diff --git a/website/src/components/header.js b/website/src/components/header.js
index 0bda6f3a..ef2e495f 100644
--- a/website/src/components/header.js
+++ b/website/src/components/header.js
@@ -120,7 +120,8 @@ export function renderHeader() {
               <button
                 id="lang-toggle-mobile"
                 class="rounded-md px-2 py-1 text-sm font-medium text-[var(--color-text-secondary)] hover:text-[var(--color-text)] hover:bg-[var(--color-bg-secondary)] transition-colors"
-                aria-label="Toggle language"
+                aria-label="${i18n.t('header.langToggleAria')}"
+                data-i18n-aria="header.langToggleAria"
               >${langLabel}</button>
               <button
                 id="theme-toggle-mobile"
diff --git a/website/src/translations/de.json b/website/src/translations/de.json
index ec8898c1..f216fb74 100644
--- a/website/src/translations/de.json
+++ b/website/src/translations/de.json
@@ -2,7 +2,7 @@
   "app.title": "Semantic Anchors",
   "app.description": "Gemeinsames Vokabular für LLM-Kommunikation",
   "header.langToggle": "EN",
-  "header.langToggleAria": "EN — switch to English",
+  "header.langToggleAria": "EN — zu Englisch wechseln",
   "header.slogan": "Ein Wort, und die KI versteht den Rest.",
   "header.themeToggle.dark": "Zum Dunkelmodus wechseln",
   "header.themeToggle.light": "Zum Hellmodus wechseln",