Accessibility

Our approach

Accessibility is not an afterthought in Lumeo. Every component is designed from the start with proper semantic markup, ARIA attributes, keyboard interactions, and focus management. Our goal is to make it easy to build inclusive applications without requiring accessibility expertise from every developer on your team.

Lumeo components follow the WAI-ARIA Authoring Practices Guide for interaction patterns, and use native HTML semantics wherever possible. When ARIA roles are necessary, they are applied automatically so you do not need to add them manually.

Accessibility is continuous work, not a checkbox: the automated audits below run on an ongoing basis, and what they find flows straight back into the library as fixes — most recently keyboard navigation for the FileManager folder tree and popup semantics on the Cascader trigger, both found by the screen-reader audit described below.

Keyboard navigation

All interactive components in Lumeo are fully operable via keyboard. The library follows standard keyboard conventions so users who rely on keyboard navigation will find familiar interaction patterns.

Focus management

Proper focus management is critical for keyboard and screen reader users. Lumeo handles focus automatically in overlay components so you do not need to manage it manually.

Screen reader support

Lumeo components use semantic HTML elements and ARIA attributes to provide a meaningful experience for screen reader users. Roles, states, and properties are applied automatically.

Color and contrast

Lumeo uses CSS custom properties for all colors, which means color contrast can be controlled at the theme level rather than per component.

• No hardcoded colors. Every color in Lumeo is a CSS variable (--foreground, --primary, --muted, etc.). Swapping the theme swaps all colors at once.
• Dark mode via variable swaps. Dark mode is handled entirely through CSS variable overrides. There are no dark: Tailwind prefixes anywhere in the library, ensuring a consistent and clean approach.
• Foreground / background pairing. Every background color variable has a matching foreground variable (e.g. --primary paired with --primary-foreground) to maintain readable contrast ratios.
• Built-in themes tested for contrast. The 7 built-in color themes (Zinc, Blue, Green, Rose, Violet, Amber, Teal) are designed with sufficient contrast between foreground and background in both light and dark modes.
• Muted text uses proper contrast. The --muted-foreground variable is calibrated to provide readable secondary text without disappearing against the background.

Per-component test matrix

This is a status report, not a marketing claim. The table below is generated at runtime from registry.json, which Lumeo.RegistryGen produces directly from the real test sources — so it cannot drift from what is actually tested. It reflects the state of the suite, not aspiration.

134/165 components have automated a11y assertions · 104/165 have keyboard interaction tests · 17/165 have E2E coverage.

Axe-core audit results

scripts/a11y-audit runs an axe-core WCAG A/AA sweep of every /components/<slug> docs route (all 164), scoped to each page's <main> content so shared app-shell chrome doesn't spam every report with the same findings. It runs weekly and on-demand in CI, gated against a committed baseline of accepted-but-not-yet-fixed findings — a pull request fails the gate only if it introduces a new (component, rule) violation, so the backlog can only shrink, never silently grow.

Last triage: 2026-07-12. Tool: axe-core 4.12.1 · rules: wcag2a, wcag2aa, best-practice. See scripts/a11y-audit/README.md for how to run the sweep locally and how the baseline/exclusions gate works.

Best practices for your app

While Lumeo handles component-level accessibility, there are application-level practices you should follow to ensure a fully accessible experience.

• Use Label with form inputs. Always pair Input, Select, Checkbox, Radio Group, Switch, and other form controls with a <Label> component. This creates an accessible name for screen readers.
• Provide meaningful text. Avoid icon-only buttons without an aria-label. If a button only has an icon, pass aria-label="Description" via AdditionalAttributes.
• Use semantic headings. Use the <Heading> component with appropriate Level values (1 through 6) to create a logical heading hierarchy. Screen readers use headings to navigate page structure.
• Test with keyboard only. Try navigating your application using only the keyboard. Every action should be reachable without a mouse.
• Test with a screen reader. Run through key flows with NVDA (Windows), VoiceOver (macOS), or Narrator (Windows) to verify the experience.
• Respect user preferences. Lumeo supports prefers-color-scheme for automatic dark mode. Avoid overriding user system preferences without offering a toggle.