Skip to content

Add server-rendered h1 to root page for accessibility compliance#38

Draft
Copilot wants to merge 4 commits intomainfrom
copilot/fix-accessibility-level-one-heading
Draft

Add server-rendered h1 to root page for accessibility compliance#38
Copilot wants to merge 4 commits intomainfrom
copilot/fix-accessibility-level-one-heading

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Feb 1, 2026 •
edited
Loading

Accessibility scanners flagged missing level-one heading on / because the h1 was only rendered client-side inside a client:only="react" component, placing it in a <template> tag inaccessible to a11y tools.

Changes

  • Added server-rendered h1 in DefaultLayout.astro outside the Shell component

    • Uses page title from frontmatter when available
    • Falls back to "DB UX Design System" for root page

  • Added .sr-only utility in global.css for visually hidden but accessible content

<body>
  <!-- Accessible to screen readers and a11y scanners, hidden visually -->
  {(frontmatter.title || currentPath === '/') && (
    <h1 class="sr-only">{frontmatter.title || 'DB UX Design System'}</h1>
  )}
  <Shell client:only="react" ...>
    <!-- Page content -->
  </Shell>
</body>

The h1 is now in the initial HTML DOM before JavaScript loads, making it immediately accessible while maintaining the visual design.

Screenshot

Homepage with accessibility fix

Page displays unchanged - the sr-only h1 is accessible but not visible.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • telemetry.astro.build
    • Triggering command: /usr/local/bin/node node /home/REDACTED/work/db-ux-design-system.github.io/db-ux-design-system.github.io/node_modules/.bin/astro build (dns block)
    • Triggering command: /usr/local/bin/node node /home/REDACTED/work/db-ux-design-system.github.io/db-ux-design-system.github.io/node_modules/.bin/astro build ep/bin/linux-x641 (dns block)
    • Triggering command: /usr/local/bin/node node /home/REDACTED/work/db-ux-design-system.github.io/db-ux-design-system.github.io/node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

This section details on the original issue you should resolve

<issue_title>Accessibility issue: Page should contain a level-one heading on /</issue_title>
<issue_description>## What
An accessibility scan flagged the element <html lang="en"> on https://design-system.deutschebahn.com/ because page should contain a level-one heading. Learn more about why this was flagged by visiting https://dequeuniversity.com/rules/axe/4.11/page-has-heading-one?application=playwright.

To fix this, ensure that the page, or at least one of its frames contains a level-one heading.

Specifically:

Fix all of the following:

  • Page must have a level-one heading

Acceptance Criteria

  • The specific axe violation reported in this issue is no longer reproducible.
  • The fix MUST meet WCAG 2.1 guidelines OR the accessibility standards specified by the repository or organization.
  • A test SHOULD be added to ensure this specific axe violation does not regress.
  • This PR MUST NOT introduce any new accessibility issues or regressions.

</issue_description>

Comments on the Issue (you are @copilot in this section)

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 3 commits February 1, 2026 06:09
@mfranzke
Initial plan for accessibility fix: add h1 to root page
4053d9e 
Co-authored-by: mfranzke <787658+mfranzke@users.noreply.github.com>
@mfranzke
Add server-rendered h1 for accessibility compliance on root page
7e1c9f7 
Co-authored-by: mfranzke <787658+mfranzke@users.noreply.github.com>
@mfranzke
Simplify conditional logic for h1 heading
62f62d9 
Co-authored-by: mfranzke <787658+mfranzke@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix accessibility issue: add level-one heading on page Add server-rendered h1 to root page for accessibility compliance Feb 1, 2026
Copilot AI requested a review from mfranzke February 1, 2026 06:16
@mfranzke
Copy link
Copy Markdown
Contributor

mfranzke commented Feb 1, 2026

instead we should question why that headlines needs to get rendered client side.

@michaelmkraus michaelmkraus changed the title Add server-rendered h1 to root page for accessibility compliance [X] - Add server-rendered h1 to root page for accessibility compliance Mar 19, 2026
@mfranzke mfranzke changed the title [X] - Add server-rendered h1 to root page for accessibility compliance Add server-rendered h1 to root page for accessibility compliance Mar 27, 2026
@michaelmkraus
Copy link
Copy Markdown
Contributor

michaelmkraus commented Apr 2, 2026

All pages with a headline in the frontmatter correctly render an <h1>, as both MainContent.astro and DocumentationContent.astro use a default headlineLevel of 1. The demo-b2b/index.astro and demo-b2c/index.astro pages are the exceptions; they don't use a standard layout or PageHero, so the existence of an <h1> there depends entirely on the DemoShell content.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mfranzke mfranzke Awaiting requested review from mfranzke

At least 1 approving review is required to merge this pull request.

Assignees

@mfranzke mfranzke

Copilot code review Copilot

Labels

nice to have

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Accessibility issue: Page should contain a level-one heading on /

3 participants

@mfranzke @michaelmkraus