DEV Community: Denis Omerovic

WCAG Color Contrast: Meeting AA & AAA Without Killing Design

Denis Omerovic — Sun, 20 Sep 2026 21:14:26 +0000

Originally published at AccessGuard.

Color contrast is the most common accessibility failure

If there's one accessibility issue that appears on nearly every website, it's insufficient color contrast. The WebAIM Million study found low contrast text on 83.9% of the home pages it tested in 2026, which makes it the single most widespread WCAG failure on the web.

The reason is straightforward: designers choose colors that look good on their own high-resolution monitors in well-lit offices. For anyone with low vision, a color vision deficiency or age-related sight changes, those subtle grays and trendy pastels can render text unreadable.

This guide explains the WCAG contrast requirements, identifies the most common problem areas, and shows you how to maintain beautiful design while meeting accessibility standards.

Understanding contrast ratios

WCAG measures color contrast as a ratio between the luminance (perceived brightness) of the foreground color and the background color. The scale runs from 1:1 (no contrast - same color on same color) to 21:1 (maximum contrast - black on white).

The standard defines three threshold levels:

WCAG AA - The practical minimum

Normal text (under 18pt / 24px, or under 14pt / 18.5px bold): minimum 4.5:1
Large text (18pt+ / 24px+, or 14pt+ / 18.5px+ bold): minimum 3:1
UI components and graphical objects (icons, form borders, focus indicators): minimum 3:1

Level AA is the standard most laws require and the level you should target for compliance.

WCAG AAA - The gold standard

Normal text: minimum 7:1
Large text: minimum 4.5:1

Level AAA isn't required by most regulations, but meeting it where feasible improves readability for everyone - not just users with disabilities.

What counts as "large text"?

WCAG defines large text as 18pt (24px) or larger at regular weight, or 14pt (18.5px) or larger at bold weight. Large text gets a lower contrast threshold because its size makes it inherently easier to read. But be careful - 18px, a common body font size in modern design, is not large text by WCAG standards. You need 24px or larger.

Common contrast problem areas

Certain design patterns consistently fail contrast requirements. Knowing where to look saves time during audits.

Light gray text on white

This is the most common offender. Designers use light gray for "secondary" text - timestamps, captions, metadata - to create visual hierarchy. But the result often fails contrast standards.

The lightest gray that passes 4.5:1 against pure white (#FFFFFF) is #767676, at 4.54:1. Anything lighter fails. That popular #999999 many designers reach for? It only achieves 2.85:1, well below the minimum.

Placeholder text in forms

Browser default placeholder colors typically fail contrast requirements. Chrome's default placeholder color on a white input is approximately #757575, which barely passes at 4.61:1. But if your input has a light gray background, even that might fail. Custom-styled placeholders in lighter shades almost always fail.

Remember that placeholder text should never replace labels, but when you do use it, it still needs to be readable.

Text overlaid on images

Hero banners and cards with text over photographs are a contrast minefield. The contrast varies depending on the image content beneath the text - it might pass in one area and fail in another.

Solutions include:

Adding a semi-transparent overlay between the image and text
Using a solid background behind the text area
Adding a text shadow for additional separation (though this alone may not be sufficient)
Choosing images with consistent dark or light areas where text is placed

Colored buttons and links

Brand-colored buttons often fail when light brand colors are used with white text, or dark brand colors with dark text. A medium blue button with white text might look fine but fail the 4.5:1 threshold.

Links that rely solely on color to distinguish them from surrounding text have an additional requirement: the color difference between the link and the surrounding text must be at least 3:1 (or the link must have a non-color indicator like an underline).

Disabled and inactive states

WCAG technically exempts "inactive" UI components from contrast requirements, so disabled buttons and inputs don't need to meet the 4.5:1 threshold. However, users still need to perceive that a control exists and is disabled. Using extremely low contrast for disabled states can make them invisible, confusing users about what options are available.

Maintaining your brand while meeting standards

A common concern from design teams is that accessibility requirements will force them to abandon their brand colors. In practice, this is rarely the case. Here are strategies that work:

Darken, don't replace

Most brand colors that fail contrast can be adjusted by darkening the shade slightly. If your brand blue is #4A90D9 (3.34:1 against white), shifting to #2A6AB5 (5.49:1) keeps the same hue while passing AA. Most users will not notice the difference. Users with low vision will notice the improvement.

Use color strategically

You can still use your lighter brand colors in places where contrast requirements are less strict: large headings (3:1 threshold), decorative elements (no contrast requirement), backgrounds, and borders. Reserve your darkened accessible variants for body text, buttons, and form elements.

Test early in the design process

Checking contrast after the design is "done" leads to frustrating last-minute changes. Build contrast checking into your design workflow from the start. Many design tools have built-in or plugin-based contrast checkers that give you real-time feedback as you choose colors.

Tools for checking contrast

You don't need to calculate contrast ratios by hand. These tools make checking quick and easy:

Browser DevTools - Chrome, Firefox, and Edge all show contrast ratios when you inspect text elements. Chrome's color picker also suggests colors that would meet AA and AAA thresholds.
WebAIM Contrast Checker - A simple web tool where you enter foreground and background hex codes and see the resulting ratio.
Stark - A popular plugin for Figma, Sketch, and Adobe XD that checks contrast within your design tool.
Operating system tools - macOS includes a Digital Color Meter and accessibility inspector. Windows has the Accessibility Insights tool from Microsoft.

How AccessGuard helps with color contrast

Checking individual color pairs works well during design, but a live site may have hundreds of text elements across dozens of pages. AccessGuard runs automated WCAG 2.2 AA checks in a real browser and flags every text element that falls below the threshold for its size.

Each contrast issue comes with the two colors found, the calculated ratio, the ratio required at that text size, and the WCAG criterion it fails, so your design team gets the exact pair to change rather than a page to go hunting through. Reports can go out as white-label PDFs under your agency's name.

Contrast is one of the failures automated checks are genuinely good at, because the ratio is arithmetic. Text over photographs is the exception: a tool can only measure against the pixels it samples, so hero images still need a human eye. Automated checks find many problems but cannot confirm conformance.

Next steps for your team

Set the accessible variants of your brand colors as design tokens, so nobody has to remember which blue passes.
Check every new color pair at design time, not at QA.
Give focus indicators and form borders their own 3:1 check. They are the ones teams forget.
Scan the live templates after each release, because a CSS change can undo a fix quietly.
Review text over images by hand on the breakpoints you support.

See what a scan reports for one of your pages with the color contrast checker, or run a free scan on a client page. For the wider audit, read how to audit a website for accessibility and the most common accessibility issues and how to fix them.

Most Common WCAG Violations (With Code Fixes for Each)

Denis Omerovic — Fri, 18 Sep 2026 07:16:55 +0000

Originally published at AccessGuard.

The same issues keep showing up

Every year, the WebAIM Million study analyzes the top one million websites for accessibility. And every year, the results tell a remarkably consistent story: a small set of issues accounts for the vast majority of failures.

In the 2026 report, 95.9% of home pages had detected WCAG 2 failures, at an average of 56.1 errors per page, and 96% of all detected errors fell into just six categories: low contrast text, missing alt text, missing form input labels, empty links, empty buttons and missing document language. That means a handful of common problems account for nearly all of what an automated scan will find. It also means the count went the wrong way this year: WebAIM records a 10.1% rise in detected errors per page since its 2025 analysis.

This post walks through the most common accessibility issues found in real-world scans, explains why each one matters, and gives you the exact code to fix it.

1. Missing image alt text

Why it matters

When an image lacks alt text, screen reader users hear something like "image" or the file name - "DSC_0492.jpg" - which conveys no meaning. For users who rely on screen readers, images without alt text are invisible at best and confusing at worst.

Missing alt text violates WCAG 1.1.1 Non-text Content (Level A), the most fundamental accessibility requirement.

How to fix it

Every image needs an alt attribute. What you put in it depends on the image's purpose:

Informational images - describe what the image conveys:

<img src="team-photo.jpg" alt="The AccessGuard team at our 2024 company retreat">

Functional images (like icons inside links or buttons) - describe the action:

<a href="/search"><img src="search-icon.svg" alt="Search"></a>

Decorative images that add no information - use an empty alt attribute so screen readers skip them entirely:

<img src="decorative-swoosh.svg" alt="">

The key principle: alt text should convey the purpose of the image, not just describe its appearance. "Photo of a woman" is rarely useful. "CEO Maria Lopez presenting quarterly results" tells the user what they need to know.

2. Low color contrast

Why it matters

Low contrast text is difficult or impossible to read for people with low vision, color blindness, or anyone using a screen in bright sunlight. It's one of the most common accessibility failures - the 2026 WebAIM Million found it on 83.9% of home pages, which makes it the single most common failure type.

Low contrast violates WCAG 1.4.3 Contrast Minimum (Level AA).

The required ratios

WCAG defines minimum contrast ratios between text color and its background:

Normal text (under 18pt, or under 14pt bold): minimum 4.5:1 ratio
Large text (18pt+, or 14pt+ bold): minimum 3:1 ratio
UI components and graphical objects: minimum 3:1 ratio

How to fix it

First, check your current contrast ratios. You can use browser DevTools - Chrome's color picker shows the contrast ratio directly. You can also use online tools like the WebAIM Contrast Checker.

Common problem areas to audit:

Light gray text on white backgrounds - a frequent design choice that almost always fails. color: #767676 is the lightest gray that passes 4.5:1 against white
Placeholder text in form fields - browser default placeholder color often fails contrast requirements
Text overlaid on images - without a solid background or text shadow, contrast varies by the underlying image content
Links that are only distinguished by color - if links aren't underlined, the color difference from surrounding text must meet a 3:1 ratio

When adjusting colors, you don't need to abandon your brand palette. Often, using a slightly darker shade of the same hue is enough to pass. For example, if your brand blue is #5B9FD6, it fails against white at 2.85:1. Darkening it to #2B6CA3 gives 5.56:1, which clears 4.5:1 with room to spare and keeps the same feel. Our color contrast checker explains how the ratio is calculated, and meeting AA without killing the design covers the palette work in more detail.

3. Missing form labels

Why it matters

When a form input doesn't have a properly associated label, screen reader users don't know what information to enter. They hear "edit text" with no context - is it asking for their name, email, or credit card number? This creates a guessing game that makes forms unusable.

Missing form labels violate WCAG 1.3.1 Info and Relationships (Level A) and WCAG 4.1.2 Name, Role, Value (Level A).

How to fix it

Every form input needs a programmatically associated label. The most reliable method is the <label> element with a for attribute that matches the input's id:

<label for="email">Email address</label>
<input type="email" id="email" name="email">

Alternatively, you can wrap the input inside the label:

<label>Email address <input type="email" name="email"></label>

Common mistakes to avoid

Using placeholder as a label. Placeholder text disappears when the user starts typing, removing the only indication of what the field is for. It also typically fails contrast requirements. Always use a visible <label> in addition to any placeholder.
Using aria-label instead of a visible label. While aria-label is announced by screen readers, sighted users who rely on the label for context (including people with cognitive disabilities) won't benefit. Prefer visible labels whenever possible.
Forgetting labels on select, textarea, and checkbox elements. Every form control needs a label - not just text inputs.

4. Broken heading hierarchy

Why it matters

Headings aren't just visual formatting - they create a structural outline of your page. Screen reader users rely heavily on headings to navigate: most screen readers let users jump between headings with a single keystroke, and many users scan headings first to find the section they need, just like sighted users scan visual hierarchy.

Skipping heading levels (jumping from <h1> to <h4>) or using headings purely for styling (making something an <h3> because you want smaller bold text) breaks this navigation and violates WCAG 1.3.1 Info and Relationships (Level A).

How to fix it

Follow these rules for a correct heading structure:

One <h1> per page - this should be the main topic or title of the page
Don't skip levels - an <h2> should be followed by <h2> or <h3>, never <h4>
Use headings for structure, not styling - if you want smaller bold text, use CSS instead of a lower heading level

A correct heading outline looks like this:

<h1>Page Title</h1>
  <h2>Main Section</h2>
    <h3>Subsection</h3>
    <h3>Subsection</h3>
  <h2>Another Main Section</h2>

Think of headings like a table of contents. If the outline doesn't make sense when listed on its own, your heading structure needs work.

5. Missing document language

Why it matters

When the <html> element doesn't include a lang attribute, screen readers don't know what language to use for pronunciation. A French screen reader user visiting an English page might hear English words pronounced with French phonetics - rendering the content incomprehensible.

This is arguably the easiest accessibility fix, yet the 2026 WebAIM Million found it missing on 13.5% of home pages. It violates WCAG 3.1.1 Language of Page (Level A).

How to fix it

Add a lang attribute to your <html> element:

<html lang="en">

Use the appropriate IETF language tag for your content's primary language. Common values include:

en - English
es - Spanish
fr - French
de - German
zh - Chinese
ja - Japanese

If your page contains sections in a different language, add a lang attribute to those sections as well:

<p>The French word <span lang="fr">accessibilité</span> translates to accessibility.</p>

This one-line fix takes seconds to implement and immediately helps every screen reader user who visits your site.

The pattern behind these issues

Notice something these five issues have in common? Four of the five are Level A failures, the most basic tier of WCAG, and low contrast is Level AA. They are also all straightforward to fix, often needing a single line of HTML. For the ones that need more than that, accessible forms and how to write alt text go deeper.

The gap between inaccessible and accessible isn't a chasm of complexity. It's a collection of small, fixable oversights - missing attributes, forgotten labels, unchecked contrast. The barrier to meaningful improvement is awareness, not difficulty.

How AccessGuard helps you find and fix these issues

You could audit every page by hand, but on a growing site that stops being practical. AccessGuard runs automated WCAG 2.2 AA checks in a real browser and flags every instance of these common problems and many more. You can try it on any page with a free accessibility scan.

Each issue in the report names the WCAG criterion it fails, its severity, and the exact element on the page. On paid plans it also writes the fix. Reports go out white-labelled under your agency's name, and every client site sits in one account so you can see what broke and what got fixed since the last scan.

What a scan cannot do is tell you the site conforms. Automated checks find many real problems, and whether alt text is accurate, whether focus order makes sense in a real flow and whether an error message actually helps still need a person. The check pages set out what each test covers, for example the alt text checker and the form labels checker, and the accessibility audit checklist covers the manual steps that go around the scan.

What Is WCAG? A Plain-English Guide to 2.0, 2.1 and 2.2

Denis Omerovic — Wed, 16 Sep 2026 07:13:18 +0000

Originally published at AccessGuard.

WCAG doesn't have to be intimidating

If you've ever looked into web accessibility, you've probably encountered the acronym WCAG - and then promptly felt overwhelmed. The Web Content Accessibility Guidelines are the global standard for accessible web design, referenced by laws and regulations in dozens of countries. But reading the actual specification can feel like deciphering legal code written by engineers.

The good news? You don't need to memorize every success criterion. Once you understand the structure and principles behind WCAG, the standard becomes a practical tool rather than an intimidating document. This post breaks it all down in plain language.

What is WCAG?

The Web Content Accessibility Guidelines (WCAG) are a set of recommendations for making web content more accessible to people with disabilities. They're developed and maintained by the Web Accessibility Initiative (WAI), which is part of the World Wide Web Consortium (W3C) - the same organization that develops HTML, CSS, and other core web standards.

WCAG has evolved through several versions:

WCAG 1.0 (1999) - The original guidelines, now largely obsolete. They were tied to specific HTML techniques and didn't age well.
WCAG 2.0 (2008) - A major rewrite that introduced technology-agnostic principles. Still widely referenced and forms the foundation of most accessibility laws.
WCAG 2.1 (2018) - Added 17 new success criteria addressing mobile accessibility, low vision, and cognitive disabilities. This is the version most commonly required today.
WCAG 2.2 (2023) - The latest release, adding 9 new criteria focused on users with cognitive disabilities, low vision, and mobile devices.

Each new version builds on the previous one - all WCAG 2.0 criteria still apply in 2.1, and all 2.1 criteria still apply in 2.2. Think of it as additive, not replacing.

The four principles: POUR

At its heart, WCAG is organized around four principles. Every success criterion falls under one of these. They spell out the acronym POUR, and they answer a simple question: what does a user need from web content?

1. Perceivable

Users must be able to perceive the information being presented. Content can't be invisible to all of a user's senses.

In practice, this means:

Images need alt text so screen reader users know what they depict
Videos need captions so deaf and hard-of-hearing users can follow along
Text needs sufficient color contrast against its background so low-vision users can read it
Content shouldn't rely on color alone to convey meaning (e.g., "fields marked in red are required" fails if someone can't see red)

The key idea: if someone can't perceive your content through at least one sense, it doesn't exist for them.

2. Operable

Users must be able to operate the interface. Every interactive element must be usable regardless of how someone navigates.

In practice, this means:

Everything that works with a mouse must also work with a keyboard
Users must have enough time to read and interact with content - no auto-advancing carousels that move too fast
Content should not flash in ways that could trigger seizures
Users need clear navigation mechanisms - skip links, descriptive page titles, logical focus order

The key idea: a beautiful interface is useless if someone can't actually use it.

3. Understandable

Users must be able to understand both the information and how the interface works. Content should be readable, and the site should behave predictably.

In practice, this means:

The language of the page is identified in the HTML (so screen readers use the correct pronunciation)
Navigation is consistent across pages
Form inputs have clear labels and error messages that explain what went wrong and how to fix it
Unusual words or abbreviations are defined

The key idea: clarity isn't just good writing - it's an accessibility requirement.

4. Robust

Content must be robust enough to be interpreted reliably by a wide range of technologies, including assistive technologies like screen readers.

In practice, this means:

HTML is well-formed and valid - proper opening and closing tags, unique IDs
Custom components use appropriate ARIA roles and properties so assistive technologies can understand them
Status messages are programmatically communicated without requiring focus changes

The key idea: your content should work not just in today's browsers, but with the assistive technologies your users actually rely on.

Conformance levels: A, AA, and AAA

Each WCAG success criterion is assigned one of three conformance levels. These indicate the impact and difficulty of meeting the requirement:

Level A - The baseline

These are the most fundamental requirements. Failing Level A means your site has serious barriers that will completely block some users. Examples include providing alt text for images and ensuring all functionality is available via keyboard.

Level AA - The practical standard

Level AA addresses the most common barriers people with disabilities encounter. This is the level referenced by most laws and regulations worldwide - including the ADA, the European Accessibility Act, and Section 508. Examples include meeting minimum color contrast ratios (4.5:1 for normal text) and providing visible focus indicators.

If you're aiming for one level, aim for AA. It's the sweet spot between meaningful impact and practical feasibility.

Level AAA - The gold standard

Level AAA represents the highest level of accessibility. These criteria are often difficult to achieve for all types of content - for example, requiring a contrast ratio of 7:1 or providing sign language interpretation for all video. W3C itself states that it's not recommended to require AAA conformance as a general policy, because it's not always possible.

That said, meeting individual AAA criteria where feasible (like enhanced contrast) is excellent practice.

How to read a success criterion

Each WCAG success criterion follows a consistent structure. Let's break down a real example:

1.4.3 Contrast (Minimum) - Level AA

Here's what each part tells you:

1 - The principle (1 = Perceivable)
4 - The guideline within that principle (1.4 = Distinguishable)
3 - The specific success criterion number
Contrast (Minimum) - The human-readable name
Level AA - The conformance level

The criterion itself states: "The visual presentation of text and images of text has a contrast ratio of at least 4.5:1" (with exceptions for large text, incidental text, and logotypes).

Beyond the criterion text, WCAG provides techniques - specific implementation approaches that satisfy the requirement. Techniques are categorized as "sufficient" (guaranteed to pass), "advisory" (recommended but not required), and "failures" (guaranteed to fail). This layered structure means you can understand both what to achieve and how to achieve it.

WCAG 2.1 vs. 2.2: What changed?

If you're already working toward WCAG 2.1 compliance, you're in good shape. WCAG 2.2 adds a targeted set of improvements, mostly benefiting users with cognitive disabilities, low vision, and mobile device users:

Key additions in WCAG 2.2

Focus Appearance (2.4.13, AA) - Focus indicators must meet minimum size and contrast requirements, ending the era of invisible or barely-visible outlines
Dragging Movements (2.5.7, AA) - Any action that requires dragging must also have a non-dragging alternative (like click-to-move), helping users with motor impairments
Accessible Authentication (3.3.8, AA) - Login flows cannot require cognitive function tests (like remembering a password or solving a puzzle) without providing alternatives like password managers or biometric options
Consistent Help (3.2.6, A) - If a help mechanism (like a chat widget or contact link) appears on multiple pages, it must be in the same relative location
Redundant Entry (3.3.7, A) - Information a user has already entered in a process should be auto-populated or available to select, rather than requiring them to re-enter it

One notable change: 4.1.1 Parsing was removed in WCAG 2.2. Modern browsers and assistive technologies have become robust enough at handling markup errors that this criterion is no longer considered necessary.

How AccessGuard maps to WCAG

Understanding WCAG is valuable, but manually checking your site against dozens of success criteria is time-consuming and error-prone. This is where automated scanning becomes essential.

AccessGuard scans your website and maps every issue it finds to a specific WCAG success criterion. Each issue includes:

The criterion number and name (e.g., 1.4.3 Contrast Minimum)
The conformance level (A, AA, or AAA)
A severity rating - error, warning, or notice - so you can prioritize what to fix first
AI-written fix suggestions on paid plans, explaining what to change in your code

This means you don't need to cross-reference the WCAG specification yourself. AccessGuard connects the dots between the issue on your page and the standard it violates, then tells you how to fix it.

Now that you understand the structure behind WCAG, you can read your scan results with confidence and make informed decisions about which issues to address first. Automated checks find many problems but cannot confirm conformance, so pair every scan with a manual pass over each template.

Run a free scan on a client page to see the criteria in context, or start with the most common accessibility issues and how to fix them and how to audit a website for accessibility.

What Is Web Accessibility? Definition and Why It Matters

Denis Omerovic — Mon, 14 Sep 2026 19:23:01 +0000

Originally published at AccessGuard.

The web was built for everyone

When Tim Berners-Lee created the World Wide Web, he envisioned a universal space: "The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect."

Yet today, the vast majority of websites fail to meet basic accessibility standards. A 2026 WebAIM Million found that 95.9% of the top one million home pages had detected WCAG 2 failures - meaning almost every site on the internet creates barriers for people with disabilities.

Web accessibility is the practice of designing and developing websites so that people with disabilities can perceive, understand, navigate, and interact with them. But it goes far beyond compliance checkboxes - it's about building a web that works for everyone.

Accessibility benefits more people than you think

When most people hear "accessibility," they think of screen readers and wheelchair ramps. But the reality is much broader. Accessibility improvements help:

People with permanent disabilities - including visual, auditory, motor, and cognitive impairments affecting over 1.3 billion people worldwide
People with temporary impairments - a broken arm, an eye infection, or recovering from surgery
People in situational limitations - using a phone in bright sunlight, watching a video in a noisy café without headphones, or navigating with one hand while holding a child
Aging populations - declining vision, hearing, motor control, and memory affect most people as they age
People with slow connections - accessible sites tend to be lighter and more performant

Microsoft's inclusive design framework estimates that for every person with a permanent disability, there are many more with temporary or situational impairments who benefit from the same design solutions. A captioned video helps someone who is deaf, someone in a loud airport, and someone learning a new language.

The legal landscape is tightening

Accessibility isn't just good practice - it's increasingly a legal requirement. Here's what you need to know:

United States: ADA and Section 508

The Americans with Disabilities Act (ADA) has been consistently interpreted by courts to apply to websites. The Department of Justice's guidance on web accessibility and the ADA says the ADA's requirements apply to the web services of state and local governments and of businesses open to the public. ADA-related web accessibility lawsuits have surged, with thousands filed each year targeting businesses of all sizes.

Section 508 requires federal agencies and their contractors to make electronic and information technology accessible. If you do business with the U.S. government, compliance is mandatory.

European Union: European Accessibility Act

The European Accessibility Act (EAA), which has applied to products and services placed on the market since 28 June 2025, requires a wide range of products and services - including e-commerce, banking, and media - to be accessible. It applies to businesses selling to EU consumers, regardless of where the business is based.

Beyond these: A global trend

Canada (ACA), the UK (Equality Act), Australia (DDA), and dozens of other countries have accessibility laws on the books. The global direction is clear: web accessibility is becoming a legal baseline, not a nice-to-have.

The business case for accessibility

Even setting aside legal risk, accessibility makes good business sense:

Reach a larger audience

The World Health Organization estimates that 1.3 billion people, 16% of the world's population or one in six of us, experience significant disability. That's a market segment larger than any single country except China or India. An inaccessible website simply locks out potential customers.

Improve SEO

Accessibility and SEO share significant overlap. Proper heading hierarchy, descriptive alt text, semantic HTML, clear link text, and well-structured content all help search engines understand your pages. Google has explicitly stated that many accessibility best practices improve search rankings.

Reduce legal risk

Defending an accessibility complaint costs money and time that fixing the site up front does not. The failures that end up in a complaint are usually the ones an audit would have listed first, which is the practical argument: the order of the work matters more than any settlement figure.

Build brand trust

Consumers increasingly care about inclusivity. Demonstrating a commitment to accessibility signals that your brand values all of its customers - a powerful differentiator in competitive markets.

Five quick wins to improve accessibility today

You don't need to overhaul your entire site overnight. Start with these high-impact changes:

Add alt text to all images. Every informational image should have a concise, descriptive alt attribute. Decorative images should have an empty alt (alt="") so screen readers skip them.
Check your color contrast. Text should have a contrast ratio of at least 4.5:1 against its background (3:1 for large text). Use a contrast checker tool to verify.
Use proper heading hierarchy. Start with a single <h1>, followed by <h2>, <h3>, and so on. Never skip heading levels for styling purposes.
Label all form fields. Every input needs an associated <label> element. Placeholder text is not a substitute for labels.
Test with your keyboard. Navigate your entire site using only the Tab, Enter, and Arrow keys. Can you reach every interactive element? Can you always see where the focus is?

How AccessGuard helps

Finding accessibility issues by hand is slow and easy to get wrong. AccessGuard runs automated WCAG 2.2 AA checks in a real browser and groups what it finds by category: color contrast, alt text, ARIA attributes, keyboard and focus, headings, forms and more.

Each issue names the WCAG success criterion behind it and its severity, and paid plans add AI-written fixes, so a team can act on the list without being accessibility experts first. Automated checks find many problems but cannot confirm conformance, so the keyboard and screen reader passes still belong to a person.

Accessibility is a practice, not a destination. The first step is knowing where a site stands, so run a free accessibility scan of one representative page, then read the guide to WCAG for what the standard asks of you and the audit checklist for the manual pass.

Accessibility Overlays Won't Save You From an ADA Lawsuit

Denis Omerovic — Mon, 06 Jul 2026 15:13:52 +0000

If your accessibility strategy is "we added the widget," here's a stat worth sitting with: 22.64% of 2025 ADA website lawsuits — 456 cases — targeted sites that already had an accessibility overlay installed. Paying for the tool didn't stop the demand letter.

This post digs into why: what overlays actually do at the code level (patch the rendered DOM after the page loads), why that timing means screen readers and plaintiffs' scans often never see the patch, and the FTC's April 2025 order that put a $1M fine and a 20-year restriction on one overlay vendor's compliance claims.

There's a code comparison showing the real difference between a div an overlay tries to patch into a fake button, and an actual <button> element that's accessible by default — plus what we've found actually moves the needle on legal exposure: fixing violations in your source HTML, prioritized by which ones show up most often in real lawsuits.

Full post (cross-posted from the AccessGuard blog) → https://getaccessguard.com/posts/accessibility-overlays-lawsuit-risk

Accordions vs Tabs: Why These Two ARIA Patterns Are Not Interchangeable

Denis Omerovic — Mon, 29 Jun 2026 06:16:58 +0000

Most component libraries implement accordions and tabs the same way. They shouldn't.

Both patterns show a trigger and a panel of content. But the keyboard contract, ARIA roles and screen reader behavior are completely different for each — and mixing them up is one of the most common accessibility bugs I see in audits.

Here's the short version:

Accordions

Multiple panels can be open at once
Tab key focuses each trigger, Enter/Space toggles it
Native <details>/<summary> handles this with zero JavaScript
Full ARIA fallback: <button aria-expanded> inside a heading + aria-controls pointing to role="region"

Tabs

Only one panel visible at a time
Arrow keys navigate between tabs — NOT the Tab key
Every inactive tab needs tabindex="-1" (roving tabindex) or keyboard users get stuck
ARIA: role="tablist" > role="tab" + aria-selected > role="tabpanel"

Wire up the wrong keyboard pattern and keyboard users either can't access the content or have to fight through the component to get there.

I wrote the full breakdown — with the broken markup and the correct fix for each pattern — on the AccessGuard blog:

→ Accessible Accordions and Tabs: ARIA + Keyboard Patterns

It covers the exact WCAG criteria, when to use each pattern and which attributes most implementations get wrong. Happy to discuss any of it in the comments.

Accessible Accordions and Tabs: The Two Patterns Everyone Confuses

Denis Omerovic — Thu, 30 Apr 2026 07:35:54 +0000

Accordions and tabs look almost identical when you squint, but they're not the same pattern. Different ARIA roles, different keyboard contracts, different reasons to exist — and one of the fastest ways to ship a broken component is to build one with the rules for the other.

I wrote up the full breakdown on the AccessGuard blog: how to pick the right pattern, the WCAG criteria each one touches, the exact markup that makes them accessible, and the bugs that show up most often in real-world scans.

Read the full post here 👉 https://getaccessguard.com/posts/accessible-accordions-and-tabs-two-patterns-everyone-confuses

Quick teaser of what's covered:

When to use an accordion vs a tabset (it's structural, not visual)
Accordion: real <button> inside a real heading, aria-expanded, aria-controls, and the hidden attribute
Tabset: role="tab", roving tabindex, and the Arrow / Home / End keyboard model that nothing else on the web uses
Why mobile "tabset that collapses into an accordion" needs a markup swap, not just a CSS swap
A 5-minute keyboard test you can run before shipping

If you maintain a component library or you're about to reach for an accordion in your next sprint, this one's for you.

How to Build Accessible Custom Dropdowns (Comboboxes) That Actually Work

Denis Omerovic — Thu, 23 Apr 2026 09:20:57 +0000

Originally published on the AccessGuard blog.

After our post on accessible modals resonated with so many of you, we wanted to tackle another notoriously tricky pattern: the custom dropdown, or combobox. Native select elements are accessible out of the box, but the moment you need custom styling, searchable options, multi-select, or grouped items, you end up reimplementing a lot of browser behavior — and that is where accessibility usually breaks.

This post walks through the pieces you need to get right: semantics, keyboard support, focus management, and announcements. By the end you will have a mental checklist you can apply to any dropdown in your codebase.

Step 1: Start with the right roles

A combobox is not just a styled button. The WAI-ARIA Authoring Practices define a specific role structure: a combobox element (usually a button or input) with aria-haspopup="listbox", aria-expanded reflecting open state, and aria-controls pointing to the listbox id. The popup itself uses role="listbox" and each option uses role="option" with aria-selected on the active option. If you only remember one thing: roles must match behavior. Do not slap role="listbox" on a div that behaves like a menu.

Step 2: Make the trigger reachable and descriptive

The trigger must be a real focusable element — either a native button or an input with tabindex="0". Give it an accessible name using a visible label, aria-label, or aria-labelledby. Announce the current value so screen reader users hear "Country, combobox, United States" and not just "combobox, collapsed."

Step 3: Keyboard support is non-negotiable

This is where most custom dropdowns fail. At a minimum you need: Enter or Space to open the listbox, Arrow Down to open and move to the first or selected option, Arrow Up and Arrow Down to move between options, Home and End to jump to the first and last option, Escape to close and return focus to the trigger, Tab to close and move to the next focusable element, and typeahead so pressing a letter jumps to the next matching option.

Step 4: Manage focus, not just visual highlight

Here is the subtle part. In a listbox pattern, DOM focus stays on the combobox trigger. You do not move focus into the list. Instead, you track the active option with aria-activedescendant, pointing at the id of the currently highlighted option. This keeps typeahead and keyboard handlers on the trigger while still telling assistive tech which option is active. Moving real focus into the list is a common mistake that breaks typeahead and confuses screen readers.

Step 5: Announce changes without being noisy

When the listbox opens, screen readers should announce the expanded state and the active option. You get this for free if aria-expanded and aria-activedescendant are wired up correctly. Avoid adding extra aria-live regions that duplicate this — double announcements are worse than none.

Step 6: Do not forget the close behaviors

Close the listbox on Escape, on outside click, and on blur of the combobox. When closing via Escape, restore focus to the trigger. When a user selects an option, update the trigger's visible text and its accessible name, close the listbox, and return focus to the trigger.

A quick testing checklist

Can you open, navigate, select, and close using only the keyboard?
Does VoiceOver or NVDA announce the role, state, and active option?
Does typeahead work?
Does Escape always return focus to the trigger?
Do touch users on mobile get a usable experience? (hint: test with TalkBack and VoiceOver on iOS)

If you can answer yes to all of these, you are ahead of 90% of the custom dropdowns on the web.

When to skip all of this

Honestly? Use the native select element whenever you can. It is accessible, it works on every platform, and mobile browsers give you a great picker for free. Only build a custom combobox when you genuinely need features native select cannot provide — searchable options, rich option content, or async loading. The best accessible component is often the one you did not have to build.

We will follow this up with a post on accessible autocompletes, which add another layer of complexity on top of this pattern. If there is a tricky component you would like us to cover next, let us know.

Read more from AccessGuard at getaccessguard.com.

[Boost]

Denis Omerovic — Sat, 18 Apr 2026 21:30:06 +0000

Denis Omerovic

Apr 18

I'm building a flat-priced alternative to Churnkey for SaaS doing $3k-$30k MRR

#saas #buildinpublic #indiehackers #startup

2 min read

I'm building a flat-priced alternative to Churnkey for SaaS doing $3k-$30k MRR

Denis Omerovic — Sat, 18 Apr 2026 21:29:34 +0000

The problem, with real numbers

If you run a Stripe-native SaaS between roughly $3k and $30k MRR, somewhere between 5% and 10% of your monthly revenue quietly disappears to failed cards. Expired cards, insufficient funds, the usual. On $10k MRR that's $500-$1,000 a month walking out the door before you even notice.

The fix is known: smarter retries based on the decline code, plus a hosted page where the customer can update their card in 30 seconds. That second piece recovers more than retry timing ever will.

Why the existing options don't fit this band

Churnkey is genuinely good, but the floor is about $3k a year and they take 1-3% of every recovered dollar on top. That math only works once you're past $30k MRR. Stunning is cheaper but the UX feels frozen in 2017 and the config is scattered. ProfitWell Retain killed its free tier. Baremetrics Recover has been coasting for years. If you're below $30k MRR you basically write your own retry cron job and hope.

What I'm building

Nanokept. Flat pricing: $49, $149, or $349 a month by your MRR band. Never a percent of recovered revenue.

What's in the box:

Stripe Connect OAuth install, read-only, about 90 seconds
Decline-code-aware retries: soft declines retry on day 1/3/5/7/14, hard declines stop auto-retrying and trigger a branded customer email
Hosted card-update page per failed invoice
Idempotency keys on every Invoice.pay call so a network hiccup never double-charges anyone
Works against the Stripe sandbox from day one, which I was surprised to find most competitors still don't

Rails 8, SolidQueue for the retry jobs, EU-hosted on Hetzner with Cloudflare in front. I'm solo, based in Bosnia, and billing through Lemon Squeezy as merchant of record since I can't take Stripe directly from here. Previous project was AccessGuard (getaccessguard.com).

Status

Landing page and waitlist are live at nanokept.com. Product is mid-build, targeting end of May 2026 for the first paying cohort.

What I'd like from you

Two questions for anyone running a Stripe SaaS in this MRR band:

What's your actual recovery rate right now, and do you even measure it?
If you've looked at dunning tools and bounced off them, what was the dealbreaker: the price floor, the revenue share, the setup time, or something else?

Link: https://nanokept.com. Happy to answer anything in the comments.

6 Accessibility Checks Most Scanners Miss (And How AccessGuard Catches Them)

Denis Omerovic — Thu, 16 Apr 2026 20:54:14 +0000

axe, WAVE, Lighthouse, Pa11y, and Siteimprove share a rules-engine lineage and share its soft spots. Here are six checks where that baseline tends to under-report, over-report, or punt to manual review, with notes on how we approached each one.

Where scanners agree, and where they stop

Most popular accessibility scanners share a foundation — either axe-core directly or a similar rules engine that reads the static HTML. That gives them fast, reliable coverage of the obvious issues: missing alt text, empty links, heading order, deterministic ARIA misuse. It also means they all share the same blind spots.

We audited what slips through, then built detection for six of the most common gaps. This post walks through each one, explains why it is hard, and shows what a real fix looks like. If you are using any of the major scanners, use this as a checklist for what to double-check by hand.

Run the same page through axe-core, WAVE, Lighthouse, Pa11y, and Siteimprove and you will get broadly similar results for the deterministic rules. That is not a bad thing — the shared baseline catches real problems and catches them fast. What the shared baseline does not catch is anything that requires one of three things: actual browser behavior (not just the DOM), computed state that is not expressed in HTML attributes, or visual geometry that only exists after layout. That is where every scanner has gaps, and it is where we focused this round of work.

1. onclick handlers attached through JavaScript (2.1.1 Keyboard)

The problem: A common pattern in React, Vue, Svelte, and vanilla JS apps: a <div> with a click handler attached via addEventListener. The HTML looks like this:

<div class="card" data-id="42">Open</div>

No onclick attribute, no role, no tabindex — but in the browser, clicking it runs a handler and so does pressing Enter (if the framework wired up a keydown listener too).

Why static scanners miss it: axe, WAVE, and the rest read the HTML as it arrives from the DOM. They can see onclick="..." as an inline attribute, but they cannot see listeners attached with element.addEventListener("click", ...) because those live in JavaScript state, not the attribute set. So they either miss the problem entirely (no flag on a mouse-only div) or over-report (flag every div with a keydown-less onclick even when the framework attached a keydown listener dynamically).

What we do: Before the page script runs, we inject a small shim that wraps EventTarget.prototype.addEventListener. Every call to attach a click, keydown, keyup, or keypress handler gets recorded in a WeakMap keyed by the target element. After the page finishes loading, we query that map and tell the scanner which elements actually received keyboard handlers. The onclick-without-keyboard warning only fires on elements that truly have no keyboard path.

2. Pseudo-element text contrast (1.4.3 Contrast)

The problem: CSS ::before and ::after with a content property render real text to the screen, and that text is subject to the same contrast requirements as any other text. Examples: icon labels, counter numbers, status badges, the "Required" asterisk on form labels.

.badge::before {
  content: "New";
  color: #e0e0e0;
  background: #ffffff;
}

That is 1.13:1 contrast. Invisible. A screen reader will not read it, but the visible rendering still fails WCAG 1.4.3.

Why static scanners miss it: axe-core has attempted pseudo-element contrast since 2022, but the implementation has documented gaps: pseudo-elements without position: absolute are frequently missed, and icon-style pseudo-elements often produce false positives that teams waive. WAVE, Lighthouse (which uses axe), and Pa11y inherit the same behavior.

What we do: While we are in the browser computing styles for every element, we also call getComputedStyle(el, "::before") and getComputedStyle(el, "::after"). If the resulting content is a non-empty string literal, we capture the pseudo-element's color, background, and font size as a separate entry. The contrast checker then evaluates those entries with the same logic it uses for real elements.

3. Contrast over transparent backgrounds and background images (1.4.3 Contrast)

The problem: Modern layouts use transparent backgrounds constantly. A card inside a section inside the body. A header overlay on a hero image. A navigation bar with a semi-transparent background.

axe-core walks the element stack using document.elementsFromPoint to find the effective background, but the approach has documented edge cases: translucent overlays on modals are included incorrectly, opacity on ancestors is handled inconsistently, and when the effective background is a gradient or image the check either errors out or flags it as needs-review.

Why this is hard: There is no single correct answer. The "real" background behind transparent text is whatever happens to be rendered at that pixel, which depends on layout, scroll position, and z-order. For images and gradients, contrast varies across the image.

What we do: For transparent backgrounds, we walk up the DOM tree until we find an ancestor with a non-transparent background color. Between 98% and 100% of pages have a reachable opaque ancestor. For background images or gradients, we emit an honest notice instead of pretending we know the answer — the notice tells you the element sits over a background image and that contrast cannot be reliably computed, with a suggestion to verify manually.

4. Real 320px reflow at an actual viewport (1.4.10 Reflow)

The problem: WCAG 1.4.10 requires content to reflow to 320 CSS pixels without horizontal scrolling. The usual offenders: fixed-width containers, min-width greater than 320px, tables with no responsive wrapper, wide images without max-width: 100%.

Why static checks fall short: You can write static heuristics — look for inline width: 1200px, flag overflow-x: scroll on the body. But a lot of reflow failures only manifest when you actually narrow the viewport: a grid that does not collapse, a flex row that does not wrap, content hidden inside a wrapper whose child has a fixed aspect ratio that exceeds the viewport.

What we do: We run a second browser pass at 320x640 after the main scan. The viewport is resized, layout re-runs, and we query document.documentElement.scrollWidth versus clientWidth. If the page requires horizontal scrolling at 320px, it fails 1.4.10. We also enumerate the first 20 elements whose getBoundingClientRect().right exceeds 320px, so you know exactly which containers are the culprits.

5. Sectioning-aware heading hierarchy (1.3.1 Info and Relationships)

The problem: WCAG 1.3.1 requires a logical heading hierarchy. In practice, scanners flag "skipped heading levels" whenever the next heading is more than one level below the previous one — h1 followed by h3, for example. That rule is correct at the document level. It is wrong inside sectioning content. A page that has an <article> with its own <h1>, or a card layout with independent heading outlines, is following the HTML5 sectioning spec. Flagging every one of those produces 10 to 30 false positives on any page with multiple articles, sidebars, or modal dialogs.

Why most scanners get this wrong: A flat walk over all headings is easy to write. Tracking sectioning context is harder, so most engines do not bother. axe-core does not reset hierarchy at sectioning boundaries. Neither does WAVE.

What we do: We group headings by their nearest sectioning ancestor — <article>, <section>, <aside>, role="article", role="region" — before running the hierarchy check. Each sectioning root gets its own starting heading level, and skips are evaluated within that scope. We also filter out hidden headings so invisible elements do not pollute the hierarchy.

6. Framework-aware severity (2.1.1 Keyboard)

The problem: An onclick handler on a plain <div> without any keyboard path is a real bug. An onclick handler on a <div role="button" tabindex="0"> probably is not — that is a standard pattern where the framework has wired up Enter and Space key handlers. Most scanners give both cases the same severity. You end up with a dashboard full of "errors" that are often framework false positives.

What we do: Severity depends on signal strength. If a div has role="button", it is already announced as interactive — we skip it. If a div has tabindex="0" and an onclick but no explicit keyboard handler, we demote it from error to notice. If neither role nor tabindex is present, we keep it as a warning because we genuinely cannot be sure there is no keyboard path. Combined with the addEventListener tracking from item 1, the false-positive rate on this specific check drops close to zero on modern framework sites.

What to do with this

If you are evaluating accessibility scanners, ask the vendor how they handle each of the six cases above. Not because those are the only things that matter — most scanners cover the deterministic baseline, and they all matter more than these edge cases — but because how a vendor answers tells you how seriously they have thought about the long tail of real-world accessibility.

If you are just trying to make your own site accessible, the short version is:

Run any scanner. The shared baseline catches most real issues.
Hand-check the categories above on a few representative pages, especially if you use a modern JS framework, CSS pseudo-elements, or card-heavy layouts.
Treat scanner notices as signals to investigate, not as failures. Especially for 1.4.3 (contrast) and 1.4.10 (reflow), the "unknown" cases are often where real problems hide.

Originally published on the AccessGuard blog.

Accessibility Lawsuits Surged 27% in 2025. Here's Why Developers Should Care About 2026.

Denis Omerovic — Wed, 15 Apr 2026 20:26:35 +0000

Federal courts saw 3,117 website accessibility lawsuits in 2025 — a 27% jump from 2024. That spike wiped out two years of decline, and 69% of those lawsuits targeted e-commerce businesses.

If you're building websites or web apps, this matters. Here's what's driving the surge and why 2026 will be even worse.

AI Is Making It Ridiculously Easy to Sue

40% of federal ADA Title III filings in 2025 came from pro se plaintiffs — people filing lawsuits without a lawyer. AI tools now let someone generate a legal complaint in minutes. No $5,000 retainer. No attorney consultations.

Plaintiff's law firms are also using AI to scan hundreds of websites at once, flagging accessibility violations automatically, then filing batches of complaints.

The European Accessibility Act Is Now Live

The EAA took effect on June 28, 2025 across all 27 EU member states. Penalties vary but they're painful — up to €100,000 per violation in Germany and Italy, and up to 4% of annual revenue in France.

If your site has EU customers, the EAA applies to you regardless of where your business is based. Unlike the ADA, the EAA explicitly requires WCAG compliance.

The April 2026 Title II Deadline Changes Everything

The new ADA Title II web accessibility rule solidifies WCAG 2.1 Level AA as the benchmark courts reference. This makes it easier for plaintiffs to argue their case against any business.

Overlays Won't Save You

25% of all ADA lawsuits in 2024 targeted websites that already had accessibility overlays installed. The FTC reached a $1 million settlement with an overlay provider for misleading compliance claims.

Overlays don't fix your code. They add a layer on top of broken HTML. Courts aren't buying it, and plaintiff's lawyers specifically look for overlay widgets as targets.

What Developers Should Do

94.8% of websites fail basic accessibility checks. The most common issues are things developers can fix:

Missing alt text on images — the #1 issue cited in lawsuits
Broken keyboard navigation — dropdowns, modals, and cart flows are common failures
Poor color contrast — easy to fix, constantly flagged
Missing form labels — screen reader users can't complete purchases without them

The Bottom Line

Accessibility lawsuits jumped 27% last year. AI is making them cheaper to file. The EU is actively enforcing. Overlays are being exposed. Every trend points to more lawsuits, targeting more businesses, in more places.

If you're a developer, accessibility isn't optional — it's a legal requirement that's getting enforced more aggressively every year.

Read the full breakdown with all the data: Website Accessibility Lawsuits Surged 27% in 2025. Here's Why 2026 Will Be Even Worse.