Prerequisites
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.
Prerequisites
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):
baseof.html— the skip-to-content link and the<main id="main-content">landmark live there. A custom
baseof.htmlthat 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.outline: none/focus:outline-noneonlinks or buttons removes the keyboard focus indicator (WCAG 2.4.7). Recommend pairing any such
reset with a
:focus-visibleoutline (show a ring for keyboard focus, not on mouse click).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.