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

Open Beginner friendly
#3,335 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
70/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
css, html
Domain
accessibility, documentation

Research direction

Start with the customisation/theming guide and locate the section covering baseof.html overrides and custom CSS. Add the accessibility callout and a focused code snippet covering the skip link, main landmark, keyboard focus indicators, and heading semantics where relevant. Done means the guidance is present on the relevant customisation page and clearly warns against these regressions.

Written by the indexing model from the issue text.

Description

proposal stale
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.

Dominant language
HTML
Stars
9.7k
Forks
3k
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from HugoBlox/kit

All issues in HugoBlox/kit

Similar issues

More Accessibility issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.