DEV Community

xg704863664
xg704863664

Posted on

Making 52 reference pages accessible without a framework

#css #html #webdev #a11y

Reference sites are mostly tables, and tables are where accessibility quietly breaks. Here is what I fixed across 52 static pages, in the order that mattered.

1. Real <th>, not bolded <td>

The most common shortcut is styling a cell to look like a header:

<tr><td><strong>Depth</strong></td><td><strong>What grows</strong></td></tr>
Enter fullscreen mode Exit fullscreen mode

Visually identical to a header row. To a screen reader it is two data cells, so every subsequent cell is announced without its column context. Compare:

<thead><tr><th>Depth</th><th>What grows</th></tr></thead>
<tbody><tr><td>30 cm</td><td>Carrots, peppers</td></tr></tbody>
Enter fullscreen mode Exit fullscreen mode

Now a cell is announced as "30 cm, Depth" rather than a bare number. This is a five-minute fix per page and I had to go back through twenty pages to apply it — see the raised bed depth chart for the corrected version.

2. Do not shrink the font to fit a phone

A 700px table on a 390px screen makes the entire page scroll sideways. The lazy fix is font-size: 0.7rem, which produces text nobody can read.

Wrap the table instead and let one element scroll:

<div class="table-scroll"><table>…</table></div>
Enter fullscreen mode Exit fullscreen mode 
.table-scroll { overflow-x: auto; -webkit-overflow-scrolling: touch; }
Enter fullscreen mode Exit fullscreen mode

Scrolling one container is fine. Scrolling the page is not. The food storage lookup has a five-column table that would be unusable on a phone without this.

3. Progressive enhancement is an accessibility feature too

My three calculators all work with JavaScript disabled, because the content underneath is real markup:

  • The soil calculator page contains the formula and a full explanation of the ratios in prose
  • The coop calculator contains the space standards as a readable table
  • The storage lookup is a complete 24-row table; the search box only filters it

If JS fails, the page is still a reference document. That matters more for accessibility than any ARIA attribute I could add.

4. aria-live on computed output

When a calculator updates a result, a screen reader user gets no announcement unless you ask for one:

<div id="out" class="calc-out" aria-live="polite"></div>
Enter fullscreen mode Exit fullscreen mode

polite rather than assertive — the user is still typing, and interrupting them mid-word is worse than a short delay.

5. Links that describe their destination

"Click here" and "read more" are invisible out of context. Screen reader users often navigate by pulling up a list of links on the page, where a list of twelve "read more" entries is useless.

Every internal link on my site names its destination: how deep should a raised bed be, how long dried herbs last, how to make a herbal salve.

6. Colour contrast in dark mode

I added prefers-color-scheme: dark and immediately broke my own contrast. The fix was defining the palette as custom properties and checking each one against its background rather than eyeballing it:

:root { --ink: #1e2328; --bg: #fbfaf6; }
@media (prefers-color-scheme: dark) {
  :root { --ink: #e9e7e1; --bg: #16181a; }
}
Enter fullscreen mode Exit fullscreen mode

The trap: a muted grey that passes on white will not pass on near-black. Both values need checking separately.

7. Skip link and landmark

Two lines that cost nothing:

<a class="skip" href="#main">Skip to content</a>
<main id="main">…</main>
Enter fullscreen mode Exit fullscreen mode

Keyboard users should not have to tab through a nav on every page.

What I would do first if starting over

Add <thead> and <th> from the beginning. Everything else on this list is additive; that one is a retrofit across every page you have already written, and retrofits are where mistakes happen.

The companion planting chart is the page where I got it right the first time — three columns, real headers, scroll wrapper from day one.

Top comments (0)