Issue card

The teaching unit: a problem, mapped standards, Bad/Good/Code tabs and fix steps.

Issue card

Icon-only button has no accessible name

WCAG 2.2A EN 301 549 Section 508

A button containing only an icon, with no text and no aria-label, is announced as just "button". Users relying on a screen reader cannot tell what it does. This maps to SC 4.1.2 Name, Role, Value.

  • Bad

    Demonstration only — shown as escaped code, never as live markup.

    bad.html Copied 
    <button>
  <svg viewBox="0 0 24 24"><path d="M3 6h18..."/></svg>
</button>
<!-- Announced only as "button": no name -->

  • Good

    A visually hidden label gives the button a clear accessible name while keeping the compact icon-only appearance:

  • Code

    good.html Copied 
    <button class="ewa-btn ewa-btn--icon ewa-btn--secondary" type="button">
  <svg viewBox="0 0 24 24" aria-hidden="true"><path d="..."/></svg>
  <span class="visually-hidden">Delete row</span>
</button>

How to fix

  1. Add a <span class="visually-hidden"> with a concise action label.
  2. Mark the decorative icon aria-hidden="true" so it is not announced.
  3. Confirm the control still meets the 24×24 minimum target size.

Using the issue card accessibly

Reach for an issue card when you teach one specific failure: pair the problem statement with the standards it maps to, the Bad/Good/Code tabs, and concrete fix steps.

Do

  • Show the broken example as escaped code so it can never break the surrounding page.
  • Name the exact success criterion, such as SC 4.1.2 Name, Role, Value.
  • Keep the nested tabs, badges, code and callout fully operable.

Don't

  • Don't render the bad markup as live DOM, where its defect can leak into the real page.
  • Don't reuse an id from the live demo, creating duplicate id values.
  • Don't skip heading levels just to make the card look denser.

Build it right

  • Compose tabs, badges, code and callout without overriding their roles, labels or keyboard behaviour.
  • Render the Bad example as escaped text inside <pre><code>, never as live broken markup.
  • Prefix every new id (for example issue-usage-) so nothing collides with the demo above.
  • Keep a logical heading order: this h2 sits beside the demo's, with h3 below.
  • Map each issue to a real WCAG success criterion and the matching EN 301 549 / Section 508 reference.

The source CSS for this component lives in assets/css/components/issue-card.css.