DEV Community: Dawid Ryczko

WCAG - Links and accessible text

Dawid Ryczko — Thu, 19 Mar 2026 21:08:53 +0000

Descriptive Link Text

Link text should clearly describe the destination or function of the link. Avoid generic terms like "click here", "read
more", or "more info".

Bad example:

<p>To learn more about our services, <a href="/services">click here</a>.</p>

Good example:

<p>To learn more, see our <a href="/services">services page</a>.</p>

Links in Context

If the link text is not descriptive on its own, its purpose must be clear from the surrounding text (Success Criterion
2.4.4).

Example (List context):


<ul>
  <li>
    Introduction to WCAG
    <a href="intro.html">PDF</a>,
    <a href="intro.doc">Word</a>
  </li>
</ul>

Distinctive Links (Use of Color)

Color should not be the only visual means of conveying that a piece of text is a link (Success Criterion 1.4.1).

Links should be distinguishable from surrounding text by something other than color (e.g., underlines, bolding, or icons).
If only color is used, the contrast ratio between the link and the surrounding text must be at least 3:1, and a non-color visual indicator (like an underline) must appear on focus or hover.

Focus Visible

Any keyboard-operable user interface must have a mode of operation where the keyboard focus indicator is visible (
Success Criterion 2.4.7).

Never remove the default focus outline (outline: none) without providing a clear, high-contrast alternative.

Good Practices

Identify File Types: If a link leads to a file (like PDF or DOCX), include the file type and size in the link text.

  <a href="report.pdf">Annual Report 2024 (PDF, 2MB)</a>

Identify External Links: Let users know if a link opens a new window or leads to an external site.

  <a href="https://example.com" target="_blank">Example Site (opens in new window)</a>

Avoid Redundancy: Don't start link text with "Link to..." or "Go to...". Screen readers already announce that it is a link.
Consistent Identification: Links with the same destination should have the same link text across the website.
Skip Links: Provide a "Skip to Content" link at the very beginning of the page to allow keyboard users to bypass navigation.
Image Links: If an image is a link, its alt text must describe the destination, not the image itself.

References

Link Purpose (In Context)

Link Purpose (Link Only)

Use of Color

Focus Visible

Techniques for descriptive link text

WCAG - image and alternative text

Dawid Ryczko — Wed, 18 Feb 2026 17:01:12 +0000

Definitions

Decorative Image: doesn't add information to the content of a page (visual separators, background images)
Informative Image: conveys a simple concept or information
Functional Image: conveys a function or action (buttons, links, icons)
Complex Image: conveys complex information (charts, infographics, maps, illustrations)

Rules

Decorative Images

Should have informative alternative text and give the context about the image (product photo, informative banners,
screenshots)

should have alt attribute (preferred)

<img src="image.jpg" alt="" />

disable by aria-hidden="true"

<img src="image.jpg" aria-hidden="true" />

disable by role="presentation"

<img src="image.jpg" role="presentation" />

disable by role="none"

<img src="image.jpg" role="none" />

Informative Images:

Should have informative alternative text and give the context abut the image (product photo, informative banners,
screenshots)

should have alt attribute

<img src="graph-q1-results.png" alt="Bar chart showing Q1 sales increased by 20%" />
<img src="banner-promo-text.png" alt="Winter Sale: 50% off all jackets" />
<img src="menu-hamburger.png" alt="Open menu" />

SVG Images

loaded via an <img>, it behaves like a standard image. You need to add alt attribute (empty or with text)

<img src="settings.svg" alt="Open settings" /> 
<img src="icon.svg" alt="" />

for inline accessible SVG you need to add role="img" and aria-label


<svg role="img" aria-label="Menu" viewBox="...">
  <path d="..." />
</svg>

another solution for accessible SVG is to use <title>


<svg aria-labelledby="menu1" viewBox="...">
  <title id="menu1">Menu</title>
  <path d="..." />
</svg>

you can hide decorative SVG:


<svg aria-hidden="true" focusable="false">
  <path d="..." />
</svg>

Functional Images

Like informative images, should have informative alternative text. The text should describe the action of the image.

search button (icon only)


<button type="button">
  <!-- The alt text tells the user what clicking will DO -->
  <img src="icons/search.svg" alt="Search website" />
</button>

file download

<a href="/files/report-2025.pdf">
  <!-- The user knows exactly what happens when they click -->
  <img src="icons/pdf-icon.svg" alt="Download Annual Report (PDF)" />
</a>

social media link

<a href="https://instagram.com/yourprofile">
  <img src="icons/ig.svg" alt="Follow us on Instagram" />
</a>

Complex Images

Complex Images require more explanation and context. There are some techniques we can use to make them accessible.

provide a link to a page with more information or description

<img src="infographic.png" alt="Infographic about Design Thinking" />
<br />
<a href="design-thinking.html">Text description about the infographic.</a>

add aria-describedby attribute to the image with the id of the description (the description can be hidden if needed)

<img src="infographic.png" alt="Infographic about Design Thinking" aria-describedby="infographic-description" />
<p id="infographic-description">The infographic shows.....</p>

add <figure> element with <figcaption> to describe the image


<figure>
  <img src="infographic.png" alt="Infographic about Design Thinking" />
  <figcaption>The infographic shows.....</figcaption>
</figure>

Good practices

The Phone Test: Describe the image as if you are explaining the page to a friend over the phone.
Be Concise: Keep text short. Put the most important information first.
Decorative Images: If an image has no meaning (like a background pattern), use alt="". Do not put a space inside the quotes.
No Redundancy: Never start with words like "Image of," "Picture of," or "Icon." The screen reader already says this.
Punctuation Matters: End your text with a period so the screen reader pauses correctly.

References

Alt text, tips and tricks

WCAG - contrast requirements

Dawid Ryczko — Thu, 12 Feb 2026 09:12:10 +0000

Definitions

Normal Text: Less than 24px or less than 18.7px if bold.
Large-Scale Text: At least 24px or at least 18.7px with bold weight (typically 700+).

Rules

Normal Text & Images of Text: Minimum contrast ratio of 4.5:1.
Large-Scale Text & Images of Large-Scale Text: Minimum contrast ratio of 3:1.
User Interface Components & Graphical Objects: Minimum contrast ratio of 3:1. This includes:
- Icons: Meaningful icons
- Buttons: The visual boundaries (states) of the button.
- Form Input Borders: Visual boundaries of text inputs, radio buttons, and checkboxes.
- Focus Indicators: The "outline" that appears when navigating via keyboard.

Exceptions

The following elements do not have to meet contrast requirements:

Logotypes: Text that is part of a logo or brand name.
Incidental/Decorative Text: Text used for pure decoration.
Inactive Elements: Disabled buttons or form fields.

Tools

WebAIM Contrast Checker

TPGi Colour Contrast Analyser (CCA)

Leonardo Color

Reference

1.4.3 Contrast

1.4.11 Non-text Contrast

Learning notes about WCAG Compliance

Dawid Ryczko — Sun, 08 Feb 2026 12:20:38 +0000

In my entire carrier it was very rare situation when WCAG Compliance was a serious topic. Few years ago nobody care about it (my experience). Today it almost standard for serious pages and "must have".

I decided to learn more about WCAG and started some courses on Coursera.org.

The first course is WCAG Compliance: Web Accessibility Best Practices

Unfortunately, the course wasn't about coding with the WCAG rules but more about methodology how to audit, fix and introduce WCAG compliance into project.

But I was in the middle of the course when I realize it.

I decided to finish it anyway. I gathered some good tips and added a new certificate to my CV. It is only 4 hours, worth it.

Here are my #LearningNotes from this journey:

This is my summary of the course:

1. Understanding WCAG Principles

Explores the WCAG principles and success criteria for making content perceivable, operable, understandable, and robust - POUR
Emphasizes the importance of accessibility as an ongoing journey rather than a one-time project.

2. Conducting Accessibility Audits

Teaches how to run automated checks using tools like Wave, Lighthouse, and Axe, along with manual techniques to identify high-impact barriers.
Provides a structured compliance roadmap and breaks down tasks into achievable milestones for effective implementation.

3. Engaging Stakeholders and Continuous Improvement

Encourages hosting workshops to highlight the business and UX benefits of accessibility and assigning ownership for ongoing tasks.
Stresses the importance of staying updated on WCAG evolution and connecting with the accessibility community for shared insights and best practices.

WCAG Tools

WAVE – A browser extension that shows you WCAG errors directly on your page. Very visual and easy to use.
Lighthouse – Built into Chrome. It’s my go-to for a quick check on Performance, SEO, and Accessibility.
Axe-core – The engine behind many testing tools. You can use it for automated tests.
Accessibility Insights for Web – A powerful extension for deep manual checks.

Methodology

POUR Principles – A great way to understand WCAG. It stands for: Perceivable, Operable, Understandable, and Robust.

Frameworks & Guidelines

If you want to see how the big players do it, check out BBC GEL (Global Experience Language).

GEL Foundations – Solid guidance for developers on how to build accessible websites.
GEL Test Docs – Real-world test scenarios you can use in your own projects.
Official Guidelines – The complete philosophy of their design system.

Most Common Mistakes

Missing alt text – Images without descriptions are invisible to screen readers.
Low contrast – If the text color is too close to the background color, many people won't be able to read it.
Empty labels – Form inputs without tags. Screen readers need to know what the user should type.
Skipped heading levels – Jumping from <h1> straight to <h3>. It breaks the structure of the page.

Pro-tip

You don't have to test everything manually. You can add WCAG checks to your CI/CD pipeline (using tools like Axe-core) to catch bugs before they go live.

What is your favorite tool for accessibility? Let me know!

My Learning Notes

Dawid Ryczko — Sat, 07 Feb 2026 16:19:18 +0000

I’ve been programming for 11 years. Mostly web but I touch backend, mobile, devops, ai and almost everything else you can imagine ;)

I still often feel like I know nothing. For every interview I need learn basic and remember myself what is the difference between var, const and let. Do you remember?

I decided to start these #LearningNotes to document what I know, what I’ve just learned, and what I’ve already forgotten (again).

Let's be honest together, what basic thing you forgot last time?