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

#3335 · open · 1 comments

View on GitHub ↗

Vidminas

### Prerequisites - [x] I have [searched](https://github.com/HugoBlox/kit/issues?q=is%3Aissue) for duplicate or closed feature requests - [x] I am mindful of the project [scope](https://github.com/HugoBlox/kit/blob/main/CONTRIBUTING.md#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.

Comments

github-actions[bot]

This issue is stale because it has not had any recent activity. The resources of the project maintainers are limited, and so we are asking for your help. If this is a **bug** and you can still reproduce this error on the <code>main</code> branch, consider contributing a Pull Request with a fix. If this is a **feature request**, and you feel that it is still relevant and valuable, consider contributing a Pull Request for review. This issue will automatically close soon if no further activity occurs. Thank you for your contributions.