From 9ed11d4f5519e45c0ea3de735951f27d13aee2f9 Mon Sep 17 00:00:00 2001
From: JakeSCahill <jake@redpanda.com>
Date: Wed, 11 Mar 2026 09:15:47 +0000
Subject: [PATCH 1/2] Improve homepage semantic HTML and accessibility for AI
 crawlers

- Add <main> landmark wrapper to homepage template
- Fix mismatched heading tags (<h3> closing with </h2>)
- Use <article> elements for feature cards instead of <div>
- Add aria-labelledby attributes to sections
- Add visually-hidden label for chat textarea (WCAG 1.3.1, 3.3.2, 4.1.2)
- Add autocomplete attribute to chat input
- Add .visually-hidden CSS class for accessibility
- Support optional home-ai-summary and home-image-alt attributes
- Wrap tertiary links in <nav> element

Addresses AI audit findings for docs.redpanda.com homepage including
semantic ratio, form accessibility, and content structure issues.
---
 src/css/home.css                          | 13 +++++
 src/js/react/components/ChatInterface.jsx |  4 ++
 src/partials/component-home-v2.hbs        | 60 +++++++++++++----------
 3 files changed, 52 insertions(+), 25 deletions(-)

diff --git a/src/css/home.css b/src/css/home.css
index f7ec1f09..a785c4cf 100644
--- a/src/css/home.css
+++ b/src/css/home.css
@@ -793,3 +793,16 @@ main.article.labs footer.footer .footer__social-link:hover {
     flex-direction: column;
   }
 }
+
+/* Visually hidden but accessible to screen readers */
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
diff --git a/src/js/react/components/ChatInterface.jsx b/src/js/react/components/ChatInterface.jsx
index 55d5d0d9..25c1be7d 100644
--- a/src/js/react/components/ChatInterface.jsx
+++ b/src/js/react/components/ChatInterface.jsx
@@ -478,11 +478,15 @@ export default function ChatInterface() {
           <form onSubmit={handleSubmit}>
             <div className="chat-card">
               <div className="chat-content">
+              <label htmlFor="chat-message" className="visually-hidden">
+                Ask a question about Redpanda
+              </label>
               <textarea
                 ref={textareaRef}
                 id="chat-message"
                 name="chat-message"
                 className="chat-input"
+                autoComplete="off"
                 placeholder="How can we help you with Redpanda today?"
                 value={message}
                 onChange={(e) => {
diff --git a/src/partials/component-home-v2.hbs b/src/partials/component-home-v2.hbs
index 1db03110..8a676ae5 100644
--- a/src/partials/component-home-v2.hbs
+++ b/src/partials/component-home-v2.hbs
@@ -1,25 +1,34 @@
-<div id="preamble">
+<main class="home-content">
+<section id="preamble" aria-labelledby="home-overview">
   <div class="sectionbody">
     <div class="paragraph home-intro">
+      {{#with page.attributes.home-overview-title}}
+        <h2 id="home-overview">{{{this}}}</h2>
+      {{else}}
+        <h2 id="home-overview">Overview</h2>
+      {{/with}}
       <p>{{{page.attributes.home-intro}}} {{#with page.attributes.home-intro-learn-more}}<a href="{{{relativize (resolve-resource this)}}}">Learn more</a>{{/with}}
       </p>
+      {{#if page.attributes.home-ai-summary}}
+        <p class="home-ai-summary">{{{page.attributes.home-ai-summary}}}</p>
+      {{/if}}
       {{#if page.attributes.home-image}}
-      <img style="max-height: 150px;min-height: 120px;" src="../_images/{{page.attributes.home-image}}" alt="{{{page.title}}}" loading="lazy"/>
+      <img style="max-height: 150px;min-height: 120px;" src="../_images/{{page.attributes.home-image}}" alt="{{#if page.attributes.home-image-alt}}{{{page.attributes.home-image-alt}}}{{else}}{{{page.title}}}{{/if}}" loading="lazy"/>
       {{/if}}
     </div>
   </div>
-</div>
-<section class="sect1 features">
+</section>
+<section class="sect1 features" aria-labelledby="home-primary-title">
   {{#with page.attributes.home-primary-row-title}}
-    <h2 id="{{{this}}}">{{{this}}}<a class="anchor" href="#{{{this}}}"></a></h2>
+    <h2 id="home-primary-title">{{{this}}}<a class="anchor" href="#home-primary-title"></a></h2>
   {{/with}}
-  <div class='sectionbody container'>
+  <div class="sectionbody container">
     <div class="grid-primary boxes">
       {{#each page.attributes.home-primary-row}}
-      <a href="{{{relativize (resolve-resource  url)}}}" class="feature-link">
-        <div class="feature-box">
+      <article class="feature-box">
+        <a href="{{{relativize (resolve-resource url)}}}" class="feature-link">
           <div class="feature-text">
-            <h3 id="{{{title}}}" class="feature-title">{{{title}}}</h2>
+            <h3 class="feature-title">{{{title}}}</h3>
             {{#if description}}
               <p class="feature-description">{{{description}}}</p>
             {{/if}}
@@ -27,23 +36,23 @@
               <p class="feature-link-text get-started">{{{link-text}}}</p>
             {{/if}}
           </div>
-        </div>
-      </a>
+        </a>
+      </article>
       {{/each}}
     </div>
   </div>
 </section>
-<section class="sect1 features">
+<section class="sect1 features" aria-labelledby="home-secondary-title">
   {{#with page.attributes.home-secondary-row-title}}
-    <h2 id="{{{this}}}">{{{this}}}<a class="anchor" href="#{{{this}}}"></a></h2>
+    <h2 id="home-secondary-title">{{{this}}}<a class="anchor" href="#home-secondary-title"></a></h2>
   {{/with}}
-  <div class='sectionbody container'>
+  <div class="sectionbody container">
     <div class="grid-secondary boxes">
       {{#each page.attributes.home-secondary-row}}
-      <a href="{{{relativize (resolve-resource  url)}}}" class="feature-link">
-        <div class="feature-box">
+      <article class="feature-box">
+        <a href="{{{relativize (resolve-resource url)}}}" class="feature-link">
           <div class="feature-text">
-            <h3 id="{{{title}}}" class="feature-title">{{{title}}}</h2>
+            <h3 class="feature-title">{{{title}}}</h3>
             {{#if description}}
               <p class="feature-description">{{{description}}}</p>
             {{/if}}
@@ -51,25 +60,26 @@
               <p class="feature-link-text">{{{link-text}}}</p>
             {{/if}}
           </div>
-        </div>
-      </a>
+        </a>
+      </article>
       {{/each}}
     </div>
   </div>
 </section>
-<section class="sect1 features">
+<section class="sect1 features" aria-labelledby="home-tertiary-title">
   {{#with page.attributes.home-tertiary-row-title}}
-    <h2 id="{{{this}}}">{{{this}}}<a class="anchor" href="#{{{this}}}"></a></h2>
+    <h2 id="home-tertiary-title">{{{this}}}<a class="anchor" href="#home-tertiary-title"></a></h2>
   {{/with}}
-  <div class='sectionbody container'>
-    <div>
+  <div class="sectionbody container">
+    <nav aria-label="Additional resources">
       <ul class="grid-tertiary">
       {{#each page.attributes.home-tertiary-row}}
       <li>
-      <a href="{{{relativize (resolve-resource  url)}}}">{{{title}}}</a>
+      <a href="{{{relativize (resolve-resource url)}}}">{{{title}}}</a>
       </li>
       {{/each}}
       </ul>
-    </div>
+    </nav>
   </div>
 </section>
+</main>

From b20634ba04a6cafcd2d9af2e86ec7c8b108ad7be Mon Sep 17 00:00:00 2001
From: JakeSCahill <jake@redpanda.com>
Date: Wed, 11 Mar 2026 09:41:11 +0000
Subject: [PATCH 2/2] Fix review findings: clip-path, aria-labelledby
 fallbacks, alt escaping

- Replace deprecated clip: rect() with clip-path: inset(50%) in .visually-hidden
- Add fallback h2 headings for aria-labelledby references when titles are absent
- Use double-stash escaping for alt attribute values to prevent injection
---
 src/css/home.css                   | 2 +-
 src/partials/component-home-v2.hbs | 8 +++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/css/home.css b/src/css/home.css
index a785c4cf..2b683971 100644
--- a/src/css/home.css
+++ b/src/css/home.css
@@ -802,7 +802,7 @@ main.article.labs footer.footer .footer__social-link:hover {
   padding: 0;
   margin: -1px;
   overflow: hidden;
-  clip: rect(0, 0, 0, 0);
+  clip-path: inset(50%);
   white-space: nowrap;
   border: 0;
 }
diff --git a/src/partials/component-home-v2.hbs b/src/partials/component-home-v2.hbs
index 8a676ae5..379750fc 100644
--- a/src/partials/component-home-v2.hbs
+++ b/src/partials/component-home-v2.hbs
@@ -13,7 +13,7 @@
         <p class="home-ai-summary">{{{page.attributes.home-ai-summary}}}</p>
       {{/if}}
       {{#if page.attributes.home-image}}
-      <img style="max-height: 150px;min-height: 120px;" src="../_images/{{page.attributes.home-image}}" alt="{{#if page.attributes.home-image-alt}}{{{page.attributes.home-image-alt}}}{{else}}{{{page.title}}}{{/if}}" loading="lazy"/>
+      <img style="max-height: 150px;min-height: 120px;" src="../_images/{{page.attributes.home-image}}" alt="{{#if page.attributes.home-image-alt}}{{page.attributes.home-image-alt}}{{else}}{{page.title}}{{/if}}" loading="lazy"/>
       {{/if}}
     </div>
   </div>
@@ -21,6 +21,8 @@
 <section class="sect1 features" aria-labelledby="home-primary-title">
   {{#with page.attributes.home-primary-row-title}}
     <h2 id="home-primary-title">{{{this}}}<a class="anchor" href="#home-primary-title"></a></h2>
+  {{else}}
+    <h2 id="home-primary-title" class="visually-hidden">Featured content</h2>
   {{/with}}
   <div class="sectionbody container">
     <div class="grid-primary boxes">
@@ -45,6 +47,8 @@
 <section class="sect1 features" aria-labelledby="home-secondary-title">
   {{#with page.attributes.home-secondary-row-title}}
     <h2 id="home-secondary-title">{{{this}}}<a class="anchor" href="#home-secondary-title"></a></h2>
+  {{else}}
+    <h2 id="home-secondary-title" class="visually-hidden">More resources</h2>
   {{/with}}
   <div class="sectionbody container">
     <div class="grid-secondary boxes">
@@ -69,6 +73,8 @@
 <section class="sect1 features" aria-labelledby="home-tertiary-title">
   {{#with page.attributes.home-tertiary-row-title}}
     <h2 id="home-tertiary-title">{{{this}}}<a class="anchor" href="#home-tertiary-title"></a></h2>
+  {{else}}
+    <h2 id="home-tertiary-title" class="visually-hidden">Additional links</h2>
   {{/with}}
   <div class="sectionbody container">
     <nav aria-label="Additional resources">