Skip to content

Feature request (docs): note accessibility caveats in the customisation / theming guide #3335

Description

@Vidminas

Prerequisites

  • I have searched for duplicate or closed feature requests
  • I am mindful of the project scope

Proposal

Add a short "keep it accessible" callout to the customisation docs, so users don't silently
regress the built-in accessibility when they override layouts or add custom CSS. Two concrete
pitfalls (both were defects in the theme before my recent PRs, so they're easy to
reintroduce):

  • Overriding baseof.html — the skip-to-content link and the <main id="main-content">
    landmark live there. A custom baseof.html that predates them (or is copied from an old version)
    drops both. Note: keep the skip link as the first focusable element and keep the <main> wrapper.
  • Custom CSS that hides focus outlines — a rule like outline: none / focus:outline-none on
    links or buttons removes the keyboard focus indicator (WCAG 2.4.7). Recommend pairing any such
    reset with a :focus-visible outline (show a ring for keyboard focus, not on mouse click).
  • (Optional, if the docs cover custom block/section markup:) when restyling section titles, keep
    them as headings (<h2>…) rather than styled <div>s so the heading outline stays intact.

A few sentences + a code snippet in the relevant customisation page would help.

Motivation and context

This theme is meant to be easy to customise, but it's easy to regress accessibility by doing this if not careful. A brief callout in the customisation docs would help draw attention to this.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions