Improve homepage semantic HTML and accessibility for AI crawlers

[JakeSCahill]

Summary

• Adds <main> landmark wrapper to homepage template for better semantic structure
• Fixes mismatched heading tags (<h3> closing with </h2>)
• Uses <article> elements for feature cards instead of generic <div>
• Adds aria-labelledby attributes to all sections
• Adds visually-hidden label for chat textarea (WCAG 1.3.1, 3.3.2, 4.1.2)
• Adds autocomplete="off" attribute to chat input
• Adds .visually-hidden CSS class for screen reader accessibility
• Supports optional home-ai-summary and home-image-alt page attributes
• Wraps tertiary links in <nav> element

Context

Addresses AI audit findings for docs.redpanda.com homepage:

• Semantic ratio: Was 2% due to heavy use of <div> elements
• Form accessibility: Chat textarea missing label and autocomplete
• Content structure: Missing proper semantic landmarks

Test plan

• Run gulp preview and verify homepage renders correctly at http://localhost:5252/home.html
• Verify chat input is accessible (label present for screen readers)
• Verify page structure in browser dev tools shows <main>, <section>, <article>, <nav> elements
• Run gulp lint to ensure no linting errors

[netlify]

✅ Deploy Preview for docs-ui ready!

Name	Link
🔨 Latest commit	b20634b
🔍 Latest deploy log	https://app.netlify.com/projects/docs-ui/deploys/69b138e858128e00081f96cb
😎 Deploy Preview	https://deploy-preview-369--docs-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 37 (🔴 down 1 from production) Accessibility: 93 (no change from production) Best Practices: 83 (🔴 down 17 from production) SEO: 89 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d4e855bc-e16a-4aaf-9251-46f4b2478ca7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request enhances accessibility and semantic structure across three files. A new .visually-hidden CSS utility class is added to hide content visually while preserving screen reader access. The React ChatInterface component receives an associated accessibility label and autocomplete protection on its textarea input. The home component template undergoes structural refactoring: the wrapper becomes a semantic main element with properly labeled sections, feature items transition from anchor-wrapped divs to article elements, and tertiary navigation wraps resources in a nav element. ARIA labels and fixed element IDs are introduced throughout to establish clear semantic relationships.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• paulohtb6
• Feediver1

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main objective of the changeset: improving semantic HTML and accessibility on the homepage through structural changes and WCAG compliance.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The pull request description clearly relates to the changeset, detailing specific accessibility improvements and semantic HTML changes across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/ai-audit-homepage-accessibility

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/css/home.css`:
- Around line 797-808: The .visually-hidden rule uses the deprecated property
clip; replace that property with the modern equivalent clip-path: inset(50%)
while keeping the rest of the declarations intact (position, width, height,
padding, margin, overflow, white-space, border) so the element remains visually
hidden but accessible; update the selector .visually-hidden in src/css/home.css
(the rule block shown) to remove clip(...) and add clip-path: inset(50%) to
satisfy Stylelint.

In `@src/partials/component-home-v2.hbs`:
- Around line 21-24: The section element currently hardcodes aria-labelledby
while the referenced heading is inside {{`#with`
page.attributes.home-primary-row-title}} (the h2 with id "home-primary-title"),
which can create a broken reference if the title is absent; update the template
so either the section's aria-labelledby is added only when
page.attributes.home-primary-row-title exists, or always render a fallback h2
(visually hidden or default text) with id "home-primary-title" when the
attribute is missing. Apply the same fix to the other two occurrences that use
the same pattern (the blocks around lines 45-48 and 69-72) so no section points
to a non-existent heading.
- Around line 15-16: The alt attribute uses unescaped triple-stash values
({{{page.attributes.home-image-alt}}} and {{{page.title}}}) which can break the
attribute or inject markup; update the <img> template in component-home-v2.hbs
to use normal Handlebars escaping ({{page.attributes.home-image-alt}} and
{{page.title}}) for the alt fallback so both home-image-alt and page.title are
HTML-escaped before insertion and cannot close the attribute or inject
attributes into the <img>.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: aae4b6ef-0029-49a3-86ef-06d33dfe2d49

📥 Commits

Reviewing files that changed from the base of the PR and between 889537e and 9ed11d4.

📒 Files selected for processing (3)

• src/css/home.css
• src/js/react/components/ChatInterface.jsx
• src/partials/component-home-v2.hbs

[Feediver1]

lgtm