Fixing Common Issues

#Common tips

Here's a quick rundown of some of the most common accessibility issues we run into with tenant websites. There are the obvious ones — alt tags on img tags, meaningful heading tags — but these are some of the less common tips you may want to keep in mind as you work on accessibility.

Once the Scanner has given you a score, this is the page that tells you what to do about it. See A11y Max for how scanning and scoring work.

#Contrast Issues

The most common issue you will run into will be contrast errors, and here are a few tips to help you out.

#Image and video backgrounds

<!-- Bad: Most likely to cause a contrast error -->
<div class="relative bg-[url('/hero.jpg')] bg-cover">
  <h1 class="text-white text-4xl font-bold p-8">Welcome</h1>
</div>

<!-- Good: Setting a background color on the parent div will significantly help with accessibility -->
<section class="bg-black">
  <div class="relative bg-[url('/hero.jpg')] bg-cover">
    <h1 class="relative text-white text-4xl font-bold p-8">Welcome</h1>
  </div>
</section>

<!-- Even better: Adding an overlay will help the accessibility even more -->
<section class="bg-black">
  <div class="relative bg-[url('/hero.jpg')] bg-cover">
    <div class="absolute inset-0 bg-black/50"></div>
    <h1 class="relative text-white text-4xl font-bold p-8">Welcome</h1>
  </div>
</section>

Tip: The font weight of the text will also help — making it bolder will help increase the contrast. You may also want to consider a text shadow.

#Text opacity

Try to stay away from adding opacity on text elements.

/* Bad: contrast depends on the background */
.muted { opacity: 0.6; }

/* Good: a real color, measurable ratio */
.muted { color: #595959; } /* passes 4.5:1 on white */

#Empty buttons need an accessible name

Every button without visible text needs either an aria-label or visually hidden text with sr-only.

<!-- Bad: screen reader just says "button" -->
<button>
  <svg>...</svg>
</button>

<!-- Good: aria-label -->
<button aria-label="Close menu">
  <svg aria-hidden="true">>...</svg>
</button>

<!-- Also good: sr-only text -->
<button>
  <svg aria-hidden="true">>...</svg>
  <span class="sr-only">Close menu</span>
</button>

Tip: Be sure to put aria-hidden="true" on the icon/SVG itself so it doesn't get announced as random noise.

By the way, this same rule applies to icon-only links: <a><svg ...></a>.

#Small interactive elements

The latest accessibility standard specifies a minimum target size of 24×24 CSS pixels for any interactive element. Tiny icon buttons, cramped pagination links, and little close "X"s in the corner tend to fail at this — and because it's a newer rule, most older tenant sites have never been checked against it at all.

If a target is visually small, give it padding (or an invisible larger hit area) so the actual clickable region clears 24×24.

/* Small icon, but a comfortable hit area */
.icon-btn {
  min-width: 24px;
  min-height: 24px;
  padding: 8px;
}

Important: This one especially matters on mobile — your fat-fingered friends will thank you.

#A few bonus tips

Some of these apply to forms and buttons and may not be as relevant when adding or editing content in N1ed, but they're still good to know.

#Placeholder text is not a label

Every input needs a real <label>. If the design truly can't show one, use aria-label — but a visible label is better.

<!-- Bad -->
<input type="email" placeholder="Email address">

<!-- Good -->
<label for="email">Email address</label>
<input type="email" id="email" placeholder="you@example.com">

If the label has to be hidden, hide it visually with sr-only — never with aria-hidden, which takes it away from the screen reader that needs it most.

<!-- Good: visible to screen readers, invisible on screen -->
<label for="search" class="sr-only">Search products</label>
<input type="search" id="search" placeholder="Search…">

#Focus states

Someone sees the default browser focus ring, thinks it's ugly, slaps outline: none on everything, and now keyboard users have no idea where they are on the page. They're tabbing blind.

If you remove the default outline, you owe a replacement — and it needs its own visible contrast (3:1) against the adjacent colors.

/* Bad */
button:focus { outline: none; }

/* Good: custom but clearly visible */
button:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

Use :focus-visible so the ring shows for keyboard users without popping up on every mouse click.

#No clickable <div>s

A <div> with an onclick is invisible to assistive tech. It's not focusable, you can't operate it with the keyboard, and it announces as nothing. If it does something when you click it, it should be a real <button> or <a>.

<!-- Bad -->
<div onclick="doThing()">Save</div>

<!-- Good -->
<button onclick="doThing()">Save</button>

Feel free to add any more you think would be helpful to add to this list.