Headless UI for Accessible Interfaces: Unstyled Components & Tailwind

When building complex interfaces, accessibility issues often arise: screen readers fail to detect dynamic elements, focus is not trapped, and keyboard users get stuck in modals. This leads to poor audit scores and loss of users with disabilities. We solve this with Headless UI—a library of unstyled components from Tailwind CSS. It handles WAI-ARIA implementation, letting you focus solely on styling. Based on our data, Headless UI cuts development time for typical components by 30% compared to hand-rolling.

Headless UI supports React and Vue. Its components (Menu, Disclosure, Dialog, Combobox, Listbox, and more) are fully accessible out of the box. It's not just another library—it saves up to 30% of time on common elements. For instance, a dropdown menu with keyboard navigation requires just a few lines of code, whereas manual implementation takes hours.

Our experience: 5+ years with Tailwind CSS, over 20 commercial projects on Headless UI. We guarantee a 15-20% LCP improvement due to optimized bundle. Contact us to discuss your project—we'll select the right components and help with adoption.

Problems Headless UI Solves

• Accessibility. Each component implements correct ARIA attributes: Listbox uses role="listbox" with aria-selected, Dialog uses role="dialog" with aria-modal and focus trap, Tabs use role="tablist". You get this for free without manual management.
• Styling. Components have no default styles. You apply any design via className (React) or Tailwind classes. No cascade fighting.
• Portability. Headless UI is UI-framework agnostic. Works with any CSS approach—Tailwind, CSS Modules, Styled Components.

Why Headless UI Is the Best Choice for Accessible Interfaces

Headless UI beats Radix UI and Reakit on three fronts: simpler Tailwind integration, built-in Vue support, and less boilerplate. For example, creating a dropdown menu in Radix requires wrapping each link in DropdownMenu.Item and adding data-attributes. In Headless UI, it's just Menu.Item with className. By our measurements, Headless UI is 2x faster than Radix UI in development speed for common components.

Headless UI vs Radix UI Comparison

Headless UI is easier to start with, but for complex interfaces with custom patterns, Radix provides more low-level primitives.

How Headless UI Improves Accessibility

Every component implements WAI-ARIA down to details: Disclosure.Button manages aria-expanded, Listbox adds aria-activedescendant, FocusTrap intercepts Tab. We verify this at all stages using axe-core and Lighthouse.

Example with Menu:

import { Menu } from '@headlessui/react';

<Menu as="div" className="relative">
  <Menu.Button className="flex items-center gap-2 px-4 py-2 rounded-md bg-white border">
    Options <ChevronDownIcon className="w-4 h-4" />
  </Menu.Button>

  <Menu.Items className="absolute right-0 mt-1 w-48 bg-white rounded-md shadow-lg ring-1 ring-black/5 focus:outline-none z-10">
    <Menu.Item>
      {({ active }) => (
        <a href="#" className={`block px-4 py-2 text-sm ${active ? 'bg-blue-50 text-blue-700' : 'text-gray-700'}`}>
          Edit
        </a>
      )}
    </Menu.Item>
    <Menu.Item disabled>
      {({ disabled }) => (
        <span className={`block px-4 py-2 text-sm ${disabled ? 'text-gray-400 cursor-not-allowed' : 'text-gray-700'}`}>
          Delete
        </span>
      )}
    </Menu.Item>
  </Menu.Items>
</Menu>

How We Do It: Stack and a Real Case

We use Headless UI with React 18, Next.js 14, TypeScript, and Tailwind CSS. Key patterns:

• Render props for state customization (active, disabled, open).
• as prop—swap the HTML element to any other.
• Transition for animations.

Case: Corporate portal with an admin panel. Required 25+ interactive components: menus, modals, tabs, autocomplete. Used Headless UI + Tailwind. Result: development time reduced by 40% compared to a previous Radix UI project, and Core Web Vitals improved—LCP dropped from 2.1s to 1.4s.

Process

1. Analysis—identify common components (Dropdown, Dialog, Combobox), check layouts for accessibility.
2. Design—choose the appropriate Headless UI component, design API (props, slots).
3. Implementation—markup with Tailwind, integrate transition animations.
4. Testing—verify with axe-core, user scenarios with NVDA and VoiceOver.
5. Deploy—merge with existing code, optimize bundle (tree-shaking).

What’s Included

• Component selection for your tasks.
• Custom styling with Tailwind CSS.
• Transition animation integration.
• Accessibility testing (axe-core, Lighthouse).
• Usage documentation.
• Source code and build handover.

Timeline Estimate

A set of 5–7 components (menu, modal, tabs, accordion, select) takes 2 to 4 days. Complex scenarios with custom logic may take up to 8 days. Pricing is determined individually after analyzing your project.

Common Mistakes with Headless UI

• Forgetting the as prop. By default, components render non-semantic elements; always specify as="nav" or as="div".
• Overriding styles with !important. Headless UI doesn't use layers—regular Tailwind works fine.
• Ignoring FocusTrap. In modals or popups, always wrap content in <FocusTrap>.

Additional Features: Transition and Tailwind UI

Headless UI includes the Transition component for smooth animations:

<Transition
  show={isOpen}
  enter="transition ease-out duration-100"
  enterFrom="transform opacity-0 scale-95"
  enterTo="transform opacity-100 scale-100"
  leave="transition ease-in duration-75"
  leaveFrom="transform opacity-100 scale-100"
  leaveTo="transform opacity-0 scale-95"
>
  <Menu.Items>...</Menu.Items>
</Transition>

The official paid Tailwind UI templates are built on Headless UI. Purchasing Tailwind UI gives you 500+ ready-made components—a great starting point for commercial projects. Contact us to discuss your project and get advice on headless UI adoption.

Website Accessibility: WCAG, Screen Readers, Keyboard Navigation

On a major bank's website, the "Submit Application" button was marked up as <div class="btn" onclick="...">. The NVDA screen reader did not announce it, Tab skipped it, Enter didn't work. For thousands of blind users, this bank simply did not exist as an online service. We see such problems every day in dozens of projects — and developing accessible websites according to WCAG 2.2 AA has become the only way to avoid discrimination and legal risks. Fines for non-accessibility for legal entities can reach substantial amounts, and lawsuits millions.

In this card — how we make web accessibility a11y work, based on real cases, with a specific tech stack and numbers. No generic phrases.

Why is Semantic Markup the Foundation of Web Accessibility (a11y)?

Most accessibility problems are solved by correct HTML, not additional ARIA attributes. <button> instead of <div onclick>, <nav> instead of <div class="navigation">, <h1>–<h6> in proper hierarchy, <label for="field-id"> instead of <div class="label">. This is the basic level, but in practice, every second form in Russian online stores does not have correct <label> tags.

ARIA is needed where native HTML falls short: custom components — dropdown menus, tooltips, modal windows, tabs, accordions. And here the complexity begins.

A typical mistake in custom dropdowns: the screen reader does not know it is a combobox, does not announce the number of options, does not say which one is selected, focus does not move to the list when opened. Proper implementation:

• role="combobox" on the input
• aria-expanded="true/false" when opened/closed
• aria-controls="listbox-id" points to the list
• aria-activedescendant — ID of the currently selected item
• role="option" and aria-selected on each option

This is not theory; it is tested with a screen reader. NVDA + Chrome or VoiceOver + Safari is a mandatory part of QA.

<div role="combobox" aria-expanded="false" aria-controls="listbox-1" aria-activedescendant="" tabindex="0">
  <label for="input-1">Select city</label>
  <input id="input-1" type="text" role="combobox" aria-autocomplete="list" />
  <ul id="listbox-1" role="listbox" aria-label="Cities">
    <li role="option" aria-selected="false" id="opt-1">Moscow</li>
    <li role="option" aria-selected="false" id="opt-2">St. Petersburg</li>
  </ul>
</div>

The cost of fixing a single Level A violation varies depending on complexity. Implementing a11y from the design stage reduces the refactoring budget by 2–3 times compared to retrofitting a finished site.

How to Properly Build Keyboard Navigation?

Tab order should match the visual order of elements. If in HTML the "Cancel" button comes before "Confirm", but CSS swaps them — the keyboard user is confused.

Focus trap in modal windows. When a modal opens, Tab should cycle only within it. When closing, return focus to the element that opened the modal. Without this, the user ends up at the top of the page after closing.

tabindex="-1" — element does not enter Tab sequence but can receive focus programmatically. Used for elements that receive focus via JavaScript (section headings after anchor navigation).

tabindex="1" and above is almost always an error. Explicit order breaks natural order and creates unpredictable behavior. Control order via DOM, not tabindex.

Skip links — a "Skip to content" link, hidden visually, visible on Tab. Allows screen reader users to skip repetitive navigation.

Color and Contrast: Requirements and Common Violations

WCAG 2.2 AA requires contrast 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold). AAA requires 7:1 and 4.5:1.

The most common violations: gray placeholder in inputs (#999 on white = 2.9:1), light gray secondary text, white text on pastel backgrounds.

Color should not be the sole indicator: "required fields are red" without an asterisk — violation for color blind users.

Testing tools: axe DevTools, WAVE, Accessibility Inspector in Chrome DevTools. axe-core integrates into Playwright tests: automatic check of 80+ rules on every deployment. Manual testing finds about 60% more errors than automated.

What Is Important About Media Content and Dynamics?

Images without alt — a common basic failure. alt should be meaningful: not alt="image_123.jpg", but a description of content relevant to context. Decorative images — alt="" (empty, not missing attribute).

Video should have captions. YouTube auto-captions are not a standard; they make mistakes. WebVTT files with correct captions for all educational and marketing video content.

Animations — a problem for users with vestibular disorders. @media (prefers-reduced-motion: reduce) — media query that disables or slows animations for users with that OS setting.

What Changed in WCAG 2.2?

Version 2.2 came into effect with new criteria:

These criteria raise the entry bar, but we already include them in our standard checklist.

Audit and Remediation

Automated tools find about 30–40% of violations. The rest is only manual testing. Minimum scenario: go through the entire critical user flow (registration, purchase, form) using only keyboard and screen reader.

Process

1. Automated audit — axe-core, Lighthouse, WAVE — outputs 80+ rules.
2. Manual testing — NVDA, VoiceOver, keyboard — 2–3 days for a typical site.
3. Violation prioritization — P1 (blocks usage), P2 (creates difficulties), P3 (enhancements).
4. Fixing — iteratively, integrate checks into CI via Playwright + axe.
5. Re-audit — close all P1/P2 before release.
6. Documentation and handover — report with results, maintenance recommendations, team training.

Results and Scope

• Full audit report with violation prioritization (PDF/HTML)
• Fixed code: semantic markup, ARIA, keyboard navigation
• Integration of axe-core into CI/CD for regression control
• Training for client developers on a11y (2-hour session)
• Access to repository with correct component examples
• Guarantee of WCAG 2.2 AA compliance at time of delivery

Timeline

Budget is calculated individually after the audit. Contact us — we will evaluate your project in 1 day. Get a consultation and free checklist when ordering an audit.

Experience and Guarantees

We have been working in web accessibility a11y for over 8 years. Completed more than 50 projects for banks, retail, and government. Certified specialists (IAAP CPACC, WAS). We guarantee passing a third-party audit or will fix for free.

WCAG 2.2 Standard — official W3C recommendation defining web content accessibility requirements.

Wikipedia: Web Content Accessibility Guidelines
Wikipedia: ARIA

— web accessibility levels a11y per version 2.2.

Order an audit now — get a checklist and preliminary estimate for free. Contact us – we will respond within an hour.