Hey lovely readers,
Welcome back to the series on European law for .NET developers. In the first part we looked at the GDPR. This time it's the European Accessibility Act, or the EAA for short.
The GDPR has been around since 2018, but the EAA is still pretty new. Its rules started to apply on 28 June 2025, and a lot of teams only started taking action for it very recently.
Accessibility is a topic that's very close to my heart. I've given talks about the EAA at .NET conferences and JS conferences, and this post is the written version of that story for .NET developers. Less Vue, more Razor and Blazor.
Before we start: I'm a developer, not a lawyer. I've done a lot of research on the EAA, but I don't have a law degree. If your company sells a lot to consumers in the EU, or you're not sure if the law applies to you, talk to a legal professional or an accessibility auditor.
What is the EAA?
The EAA (Directive (EU) 2019/882) is a European law that makes sure people with disabilities can use the same products and services as everyone else. Think webshops, banking apps, e-books, ticket machines and the website of your internet provider.
Because it's a directive, every EU country turned it into its own national law. That also means every country has its own regulator. In the Netherlands, for example, the ACM keeps an eye on webshops and electronic communication services. If a company doesn't follow the rules, the regulator can give a warning or a fine, and the exact amounts differ per country.
Why should you care?
Let me start with the question I always ask in my talks: how many people live with a permanent disability? The answer is about 1 in 6. That's not a small edge case. That's a big part of your users.
And it's not only about permanent disabilities. Someone with a broken arm, someone holding a baby, or someone reading their phone in bright sunlight all run into the same or similar issues, even though it's only temporary.
Still, a lot of us build for what I call the "super user":
- Technically very smart. Knows where to click and when.
- Learns fast. "They will figure it out."
- Has no disabilities. Uses a mouse, a big screen and perfect eyesight.
That person doesn't exist, or atleast it's not true for most of our users. And it shows. In March 2026 the ACM shared the results of testing about 100 of the largest Dutch webshops: 61 percent of them were not digitally accessible.
Does it apply to me?
The EAA is about consumers. It covers products and services that are sold to regular people, not business-to-business tools. For us as developers, these are the services that matter most:
- E-commerce: webshops, but also anything where people buy or book something online.
- Banking and consumer financial services.
- E-books and the software to read them.
- Passenger transport: websites, apps and e-tickets for planes, trains, buses and boats.
- Electronic communication services, like phone and internet providers.
- Services that give access to audiovisual media, like streaming.
There's one big exception. A microenterprise doesn't have to follow the EAA for its services. That's a company with fewer than 10 employees and a yearly turnover (total sales) or balance sheet total of at most 2 million euro. You need to meet both conditions, not just one.
Oh, and being outside of the EU doesn't get you out of it. If you sell to consumers in the EU, the EAA applies to you.
A small webshop
Let's say you build a webshop for a candle maker. They have 4 employees and sell for about 300,000 euro a year.
- In scope? No. This is a microenterprise, so the EAA doesn't apply to the webshop.
- Should you still care? Yes. Every customer who can't finish their order is a lost sale. And once the company grows past the limits, the rules apply right away.
A booking app for a gym chain
Now you build a Blazor app where people book and pay for classes at a gym chain with 40 employees.
- In scope? Yes. People book and pay online, and the company is too big to be a microenterprise.
- What's needed: The app needs to meet the accessibility requirements, there needs to be an accessibility statement, and support needs to be reachable in an accessible way.
A dashboard for logistics companies
You build a planning dashboard that a SaaS company sells to transport companies.
- In scope? No. This is B2B, and the EAA is about consumers.
- But: Larger customers and governments often ask for accessibility anyway when they buy software. So don't ignore it.
The rule of thumb
If consumers can buy, book or sign a contract through what you build, and the company isn't a microenterprise, assume the EAA applies. If you're in doubt, check with someone who knows the law in your country.
The EAA is more than code
Just like with the GDPR, it's tempting to open your IDE right away. But a few things need to happen around the code too. Here's the order I'd go in.
Step 1: Find out if you're in scope
Use the rule of thumb above. Is it for consumers, is it in one of the covered sectors, and is the company bigger than a microenterprise? Write the answer down, including why.
Step 2: Find out where you stand
You can't fix what you don't know about. There are three ways to find your issues:
- Research with a panel. Real users with disabilities test your app. This gives you the most honest feedback.
- An external audit. An accessibility expert checks your app against the standard and gives you a report.
- Doing it yourself. With the checks in "Test it yourself" later in this post, you can find a lot on your own.
The best results come from a mix. Start yourself, and bring in experts for the parts that matter most.
Step 3: Write an accessibility statement
The EAA asks service providers to explain how their service meets the accessibility requirements. Most companies do this with an accessibility statement, on its own page or as part of the terms and conditions. It says which standard you follow, what doesn't work yet, and how people can reach you. And yes, that page needs to be accessible too.
Step 4: Make your support accessible
If someone runs into a problem, they need a way to tell you. Your support needs to be reachable in an accessible way, and your support team needs to be able to answer questions about accessibility. A chat widget that only works with a mouse doesn't count.
Step 5: Keep it that way
Accessibility isn't a one-time project. Every new feature, every redesign and every third-party component can break it again. Think about your cookie banner, your payment provider or that fancy date picker from a component library.
Where this meets your code
Your accessibility statement is a promise. If it says you meet the standard, your code has to keep that promise with every release. That's where we come in as developers. The rest of this post is about how to do exactly that.
WCAG: what you actually build against
Here's something that confuses a lot of people: the EAA itself doesn't tell you how to build an accessible website. It describes goals. The technical details live in a European standard called EN 301 549, and for websites and apps that standard points to WCAG, the Web Content Accessibility Guidelines.
WCAG is built on four principles. Your app needs to be:
- Perceivable. People can see or hear the content, for example through alt text and enough contrast.
- Operable. People can use it, also without a mouse.
- Understandable. Labels, errors and instructions make sense.
- Robust. It works with assistive technology like screen readers.
Every guideline has a level: A, AA or AAA. A is the bare minimum, AAA is the gold standard. The level you're expected to meet is AA.
2.1 or 2.2?
The version of EN 301 549 most teams work with right now (v3.2.1) uses WCAG 2.1 level AA. On 2 September 2026 a new version came out, v4.1.1, which moves to WCAG 2.2 level AA. It's published, but it isn't the official reference yet. That only happens once the EU cites it in its Official Journal, which is expected somewhere between the end of November and mid-December 2026.
My advice: build against WCAG 2.2 AA now. It's everything from 2.1, plus six new A and AA criteria.
The most common mistakes
Every year WebAIM checks the home pages of the top one million websites. In the 2026 report they found 56.1 errors per page on average, up from 51 the year before. And 95.9 percent of the pages had at least one WCAG error that a tool could find.
The most common errors have been the same six for years:
- Low contrast text, on 83.9 percent of the pages.
- Images without alt text.
- Form inputs without labels.
- Empty links.
- Empty buttons.
- A missing page language.
Want to know what to check first in your own app? Take a look at the WebAIM Million report. It's updated every year and shows the most common issues, how often they show up, and even how different platforms and frameworks score.
Here's the good news: all six are things we can fix in code. So let's do that.
Start with semantic HTML
It doesn't matter if you use Razor Pages, MVC or Blazor. In the end, the browser gets HTML, and a screen reader only knows what that HTML tells it. So the most important accessibility tool you have is choosing the right element.
Here's something I see a lot in Blazor apps:
<div class="btn" @onclick="AddToCart">Add to cart</div>
It looks like a button and it works with a mouse. But you can't reach it with the Tab key, Enter doesn't do anything, and a screen reader doesn't announce it as a button. Let's fix that:
<button type="button" class="btn" @onclick="AddToCart">Add to cart</button>
That's it. The browser now gives you focus, keyboard support and the right role for free.
Give your layout landmarks
Screen reader users often jump between parts of a page, like the navigation and the main content. That only works if those parts exist in your HTML. Here's a MainLayout.razor that has them:
@inherits LayoutComponentBase
<a class="skip-link" href="#main-content">Skip to main content</a>
<header>
<a href="/">Candle Corner</a>
</header>
<nav aria-label="Main">
<NavMenu />
</nav>
<main id="main-content">
@Body
</main>
<footer>
<a href="/accessibility">Accessibility statement</a>
</footer>
The skip link lets keyboard users jump over the navigation, so they don't have to tab through every menu item on every page. You can hide it until it gets focus with a bit of CSS.
And while you're at it, check your headings. One <h1> per page, and don't skip levels just because an <h4> looks nicer. Style it with CSS instead.
Set the page language
Remember the missing page language from the top six? The Blazor template already has <html lang="en"> in App.razor. If your site is in Dutch, change it to nl, or a screen reader will read your Dutch text with an English accent. If your app supports more languages, you can set it from the current culture:
@using System.Globalization
<html lang="@CultureInfo.CurrentUICulture.TwoLetterISOLanguageName">
Every input needs a label
Unlabeled form fields are on half of the top one million home pages. For a sighted user, a placeholder like "Email" might feel like enough. A screen reader user just hears "edit text" and has to guess.
The rule is simple: every <input> gets a <label> with a for that matches the input's id. A placeholder is not a label, because it disappears the moment you start typing.
Here's a checkout form in Blazor that gets it right:
<EditForm Model="Order" OnValidSubmit="PlaceOrder" FormName="checkout">
<DataAnnotationsValidator />
<div>
<label for="full-name">Full name</label>
<InputText id="full-name" @bind-Value="Order.FullName" autocomplete="name" />
<ValidationMessage For="() => Order.FullName" />
</div>
<div>
<label for="email">Email address</label>
<InputText id="email" type="email" @bind-Value="Order.Email" autocomplete="email" />
<ValidationMessage For="() => Order.Email" />
</div>
<button type="submit">Place order</button>
</EditForm>
A few things are happening here:
- Every input has a label. Clicking the label also puts the focus in the input, which helps people with motor disabilities too.
-
The
autocompleteattribute. This tells the browser what kind of data the field expects, so it can fill it in. That's a WCAG AA requirement, and it saves everyone a lot of typing. -
Blazor helps you out. The input components add
aria-invalid="true"when a field has a validation error, so a screen reader knows something is wrong.
Write errors people understand
The default validation message for a required field is something like "The Email field is required." That's okay, but we can do better. Let's tell people what to do instead:
public class CheckoutOrder
{
[Required(ErrorMessage = "Please enter your full name.")]
public string FullName { get; set; } = string.Empty;
[Required(ErrorMessage = "Please enter your email address, so we can send you the receipt.")]
[EmailAddress(ErrorMessage = "This doesn't look like an email address. Check if it has an @ in it.")]
public string Email { get; set; } = string.Empty;
}
And don't only use color to show an error. A red border means nothing to someone who's color blind. The text of the message is what counts.
Images need alt text
Alt text is what a screen reader reads instead of the image. What you write depends on what the image does:
-
Decorative? Use an empty
alt="". The screen reader skips it, which is exactly what you want. - Functional? If the image is a link or a button, describe the action, like "Go to your cart".
- Informative? Give a short description of the information, like "Cat sitting on a doorstep".
- Complex? For a chart or a diagram, give a short alt text and put the full explanation in the text nearby.
A few tips that make your alt text better:
- Keep it short and keep it in context.
- Skip "picture of" or "image of". The screen reader already says it's an image.
- Write it in the language of the page.
Alt text is data
In most .NET apps, images don't live in your Razor files. They come from a database or a CMS. That means the alt text has to live there too. Let's add it to the model and make it required, so nobody can upload a product image without one:
public class ProductImage
{
public int Id { get; set; }
[Required]
public string Url { get; set; } = string.Empty;
[Required(ErrorMessage = "Describe the image for people who can't see it.")]
[MaxLength(150)]
public string AltText { get; set; } = string.Empty;
}
And you use it like this. Decorative images, like a divider line, usually live in your design and not in your database, so those get an empty alt right in the markup:
<img src="@image.Url" alt="@image.AltText" />
<img src="/images/divider.svg" alt="" />
A small change in your model, and the people who manage the content can't forget it anymore.
Fix your silent controls
Empty links and empty buttons are also in the top six. I call them "silent controls": a screen reader finds them, but has nothing to say about them. They're almost always icon-only buttons, like a trash can or a little heart.
This is where ARIA comes in. ARIA stands for Accessible Rich Internet Applications, and it's a set of attributes that give extra information to assistive technology.
Give icon-only buttons a name
Here's a remove button in a shopping cart:
<button type="button" class="icon-button" @onclick="() => RemoveFromCart(item.Id)">
<span class="icon-trash"></span>
</button>
A screen reader user hears "button", and that's it. Remove what? Let's fix that:
<button type="button"
class="icon-button"
aria-label="@($"Remove {item.Name} from cart")"
@onclick="() => RemoveFromCart(item.Id)">
<span class="icon-trash" aria-hidden="true"></span>
</button>
The aria-label gives the button a name, and because it's built from the product name, every remove button in the list sounds different. The aria-hidden="true" on the icon makes sure the screen reader doesn't try to read it.
Tell people when something changes
Blazor updates the page without reloading it. That feels great if you can see it. But if you add something to your cart and the counter goes from 2 to 3, a screen reader user doesn't notice a thing.
A live region solves that. Anything that changes inside it gets read out loud:
<div role="status">
@statusMessage
</div>
@code {
private string statusMessage = string.Empty;
private async Task AddToCart(Product product)
{
await CartService.AddAsync(product.Id);
statusMessage = $"{product.Name} was added to your cart.";
}
}
Make sure the div with role="status" is already on the page when it loads, and only change the text inside it. If you render the whole element at the same time as the message, most screen readers miss it.
The first rule of ARIA
Before you add ARIA everywhere: the first rule of ARIA is to not use ARIA if a normal HTML element can do the job. A <button> is always better than a <div role="button">. The WebAIM report backs this up. Pages that used ARIA had more errors on average (59.1) than pages without it (42). So use ARIA with care, and only where you need it.
Keyboard, focus and page titles
A lot of people don't use a mouse. Some use only a keyboard, some use a switch device, and some use voice control. They all depend on focus: the element that's currently "selected" on the page.
Don't hide the focus
This one line of CSS breaks your app for keyboard users:
*:focus {
outline: none;
}
If you don't like the default focus ring, replace it with your own instead of removing it. :focus-visible only shows it when someone uses the keyboard:
:focus-visible {
outline: 3px solid #1a5fb4;
outline-offset: 2px;
}
Give every page a title
The page title is the first thing a screen reader reads after navigating. In Blazor, you set it with the PageTitle component:
@page "/checkout"
<PageTitle>Checkout - Candle Corner</PageTitle>
<h1>Checkout</h1>
Keep FocusOnNavigate in your router
With client-side navigation, the page doesn't reload. So where does the focus go? Blazor solves that with FocusOnNavigate, which is already in Routes.razor when you create a new project:
<Router AppAssembly="typeof(Program).Assembly">
<Found Context="routeData">
<RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
<FocusOnNavigate RouteData="routeData" Selector="h1" />
</Found>
</Router>
After every navigation, the focus moves to the <h1>, and the screen reader announces the new page. Please don't remove it because you don't know what it does. Now you do.
Move the focus when the page changes a lot
Sometimes a big part of the page changes without a navigation. Think about a checkout form that turns into a confirmation message. Let's move the focus to that message, so a screen reader user knows it worked:
@if (orderPlaced)
{
<h2 tabindex="-1" @ref="confirmationHeading">Thanks for your order!</h2>
}
@code {
private ElementReference confirmationHeading;
private bool orderPlaced;
private bool moveFocus;
private async Task PlaceOrder()
{
await OrderService.PlaceAsync(Order);
orderPlaced = true;
moveFocus = true;
}
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (moveFocus)
{
moveFocus = false;
await confirmationHeading.FocusAsync();
}
}
}
The tabindex="-1" makes the heading focusable from code, without adding it to the Tab order. And you focus it in OnAfterRenderAsync, because the heading doesn't exist before the render. This needs an interactive render mode, since FocusAsync uses JavaScript interop.
Test it yourself
You can't promise accessibility in a statement if you never check it. The good news: you don't need an expensive audit to find most of your problems. Here are four ways to test your app yourself from quick and free to fully automated.
Tab and Enter through your app
The best keyboard test is simple. Put your mouse away and try to finish the most important flow in your app with only the keyboard:
- Tab moves to the next link, button or input. Shift+Tab goes back.
- Enter follows a link or presses a button. Space also presses buttons and ticks checkboxes.
- Arrow keys move inside menus, radio buttons and select lists.
- Escape closes dialogs and menus.
While you do this, ask yourself:
- Can you always see where the focus is?
- Does the focus move in a logical order, from top to bottom and left to right?
- Can you reach, open and close every menu and dialog?
- Do you ever get stuck, so that Tab doesn't take you any further?
If it's hard for you, it's hard for your users too.
Use a screen reader and block your vision
Next, try your app the way a blind user would. NVDA is free on Windows, and VoiceOver is built into macOS and iOS. Learn a few basic commands first:
- NVDA: press H to jump between headings, D to jump between landmarks, and NVDA+F7 for a list of all links and headings.
- VoiceOver: turn it on with Cmd+F5, and open the rotor with Ctrl+Option+U to jump between headings, links and landmarks.
Then block your vision. Close your eyes, turn off your screen, or tape a piece of paper over it. Now try to place an order, disconnect your mouse and use your keyboard again. Do the buttons have names that make sense? Do you hear it when something is added to your cart? Can you tell what went wrong when a form doesn't submit?
It feels weird at first, but after 15 minutes you'll never look at your app the same way. Just remember that experienced screen reader users are a lot faster than you, and use shortcuts you don't know yet. Nothing beats watching someone who uses assistive technology every day try your app.
One more quick check while you're at it: zoom your browser to 200 percent. Does everything still fit, or does text overlap and disappear?
Browser extensions
The quickest automated check is a browser extension. They scan the page you're on and show you what's wrong:
- WAVE puts the problems as icons right on top of your page, so you can see where they are.
- axe DevTools lists the problems in your developer tools, with a link that explains how to fix each one.
- Lighthouse is built into the Chrome developer tools and gives your page an accessibility score.
They're great for a first look, but you have to remember to run them. And a score of 100 doesn't mean your page is accessible. It only means the tool couldn't find anything.
Extra checks in your tests and CI/CD
The last step is making sure nobody breaks it again. If you already use Playwright for .NET, adding accessibility checks is easy. Deque, the company behind axe, has a NuGet package for it:
dotnet add package Microsoft.Playwright.NUnit
dotnet add package Deque.AxeCore.Playwright
Here's a test that scans the checkout page for WCAG A and AA problems:
using Deque.AxeCore.Commons;
using Deque.AxeCore.Playwright;
using Microsoft.Playwright.NUnit;
[TestFixture]
public class AccessibilityTests : PageTest
{
[Test]
public async Task CheckoutPage_HasNoDetectableAccessibilityIssues()
{
await Page.GotoAsync("http://localhost:5000/checkout");
var options = new AxeRunOptions
{
RunOnly = new RunOnlyOptions
{
Type = "tag",
Values = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"]
}
};
AxeResult result = await Page.RunAxe(options);
Assert.That(result.Violations, Is.Empty,
string.Join(Environment.NewLine, result.Violations.Select(v => $"{v.Id}: {v.Help}")));
}
}
The RunOnly part tells axe to only check the WCAG A and AA rules, which is what the EAA is about. And the message in the assert lists every problem it found, so a failing build tells you what to fix.
You can also scan one part of the page, for example after opening a dialog:
AxeResult result = await Page.Locator("dialog").RunAxe();
Now let's make these tests run on every pull request. Here's a GitHub Actions workflow that starts the app, installs the Playwright browsers and runs the tests:
name: Accessibility tests
on: [pull_request]
jobs:
accessibility:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.0.x'
- run: dotnet build
- name: Start the app
run: dotnet run --project src/CandleCorner --no-build --urls http://localhost:5000 &
- name: Wait until the app is up
run: curl --retry 15 --retry-delay 2 --retry-connrefused --silent --output /dev/null http://localhost:5000
- name: Install Playwright browsers
run: pwsh tests/AccessibilityTests/bin/Debug/net10.0/playwright.ps1 install --with-deps chromium
- name: Run accessibility tests
run: dotnet test tests/AccessibilityTests --no-build
The same steps work in Azure DevOps or any other pipeline. Make the check required for merging, and a missing label never reaches production again.
Automation only finds part of it
Here's the catch: automated tools can't find everything. They can tell you an image has no alt text, but not that the alt text says "image123.png". They can't tell you if your focus order makes sense, or if a flow is confusing. That's why the first two checks in this section matter just as much as the last two.
What about outside of Europe?
The EAA isn't the only accessibility law out there. And the good news is that almost all of them come back to WCAG. So if you build for the EAA, you're in good shape in a lot of other places too.
| Where | Law | Good to know |
|---|---|---|
| United States | Americans with Disabilities Act (ADA) | Thousands of web accessibility lawsuits are filed every year. State and local governments have to meet WCAG 2.1 AA, with deadlines now in April 2027 and April 2028. |
| United Kingdom | Equality Act 2010 | Companies must make reasonable adjustments for disabled people. Public sector websites follow separate rules based on WCAG 2.2 AA. |
| Canada | Accessible Canada Act, AODA (Ontario) | In Ontario, larger organizations must meet WCAG 2.0 AA. |
| Australia | Disability Discrimination Act 1992 | Doesn't name WCAG, but WCAG is what courts and the government use to judge it. |
| Israel | Equal Rights for Persons with Disabilities regulations | Israeli Standard 5568 is based on WCAG and applies to most business websites. |
| Japan | Act for Eliminating Discrimination against Persons with Disabilities | Since April 2024, private companies must provide reasonable accommodation. The standard JIS X 8341-3 lines up with WCAG. |
Your EAA checklist
- Check if you're in scope: is it for consumers, in a covered sector, and bigger than a microenterprise?
- Build against WCAG 2.2 AA, even though 2.1 AA is still the official baseline for a little while.
- Use semantic HTML in your Razor and Blazor components, and only reach for ARIA when HTML can't do the job.
- Give every input a label, and write error messages that tell people what to do.
- Treat alt text as data: store it, require it, and keep it short.
- Make sure everything works with only a keyboard, and that people can always see where the focus is.
- Add axe checks to your Playwright tests, and still test by hand with a keyboard and a screen reader.
- Publish an accessibility statement, and keep it true with every release.
That's a wrap!
I know, this was a lot. But don't let it scare you. You don't have to fix your whole app this weekend. Pick one important flow, like your checkout or your login. Run axe on it, fix the top six, and try it with only your keyboard. You'll be surprised how much you can fix in one afternoon.
And remember why we're doing this. It's not about avoiding a fine. It's about the 1 in 6 people who want to order those candles too.
In the next and last part of this series, we'll look at the AI Act and what it means for the .NET apps that use AI.
If you have any questions or want to share how your team handles accessibility, leave a comment or find me on my socials.
See ya!
Top comments (1)
Thanks for the clarifications!