Getting started

Accessibility

What the components handle for you (focus, keyboard, labels, motion, transparency, contrast) and what stays your responsibility.

Interactive components are built on bits-ui, which provides the ARIA roles, keyboard handling and focus management of each pattern. The package adds tokens, motion and touch rules on top, and every component is tested with axe in a real browser.

What you get

Motion

When the user prefers reduced motion, --ca-duration-fast, --ca-duration-base and --ca-duration-slow become 0ms, so every token-driven transition is instant. Components with JavaScript-driven motion check the reducedMotion store: Sheet disables its swipe spring and SegmentedControl turns off its indicator animation.

import { reducedMotion, reducedTransparency } from "@codeatlasdev/ui";

reducedMotion.init();       // start following the media query (returns cleanup)
reducedMotion.value;        // boolean, reactive
reducedTransparency.value;  // prefers-reduced-transparency

Use the duration tokens in your own CSS and your animations respect the setting for free:

.panel {
  transition: transform var(--ca-duration-base) var(--ca-ease-standard);
}

Skip link and landmarks

SkipLink is the first tab stop of every page shell. It is hidden until focused, then jumps to #main and moves focus there (tabindex="-1", no focus ring on the container).

Never put a second id="main" or a second <main> on a page. When a shell is embedded in a page that already has a skip link (a framed demo, a preview), pass skipLink={false} to AppShellLayout.

<AppShellLayout {modules} {pathname}>
  <!-- content region is the skip target; use <main> only with mainId={null} -->
  <PageShell title="Users">…</PageShell>
</AppShellLayout>

Announcements

announce(message, politeness) speaks a message through one shared, lazily created live region (a polite role="status" and an assertive role="alert" pair appended to <body>). Several components talking through separate regions step on each other; one region keeps messages ordered.

import { announce } from "@codeatlasdev/ui";

announce("3 results");                 // polite (default)
announce("Payment failed", "assertive");

In SvelteKit, mount RouteAnnouncer once in the root layout to announce client-side navigations (the new document.title, or the page <h1>):

<script>
  import { RouteAnnouncer } from "@codeatlasdev/ui/kit";
</script>

<RouteAnnouncer />

Forced colors and increased contrast

Windows High Contrast and other forced-color modes replace author colors with system colors. The package removes backdrop-filter, translucent tints and shadows there, draws surfaces with a 1px CanvasText border and uses Highlight for the focus ring, so nothing depends on a glass blur to be visible.

prefers-contrast: more raises the neutral tokens instead: text-secondary and text-hint to at least 7:1 and outlines to at least 3:1 on every surface, with a thicker focus ring. The values are generated per preset (built-in and brand presets from defineTheme), tinted with the preset hue.

Reduced transparency

With prefers-reduced-transparency: reduce, every glass material (glass-regular, glass-chrome, overlays, panels, upload zones and glass buttons) drops backdrop-filter and renders on an opaque tint. Browsers without backdrop-filter support get the same near-opaque fallback, so text never sits on raw page content.

Color contrast

Text tokens are tuned per preset and scheme:

• --ca-text-primary and --ca-text-secondary for body text.
• --ca-text-hint is the lowest readable tier and keeps 4.5:1. Use it for captions and helper text.
• --ca-text-disabled is for inactive controls only, never for information.
• --ca-brand-text is brand-colored text that keeps contrast on the surface. Use --ca-brand-fill with --ca-brand-contrast for filled brand elements.

Brand presets generated from a hex color use the same generator, so they keep these relationships. Semantic colors (success, warning, error, info) are separated from the brand by luminance, not only hue, and should always be paired with an icon or text: color alone is never the only signal. Alert and Toast already include an icon.

Writing accessible pages

• Give every page one <h1> and keep heading levels in order.
• Provide a skip link and a single <main id="main" tabindex="-1"> landmark. AppShellLayout, DocsShell and AuthLayout already do (see Skip link and landmarks); use SkipLink in shells you build.
• Label icon-only controls (IconButton enforces it) and give Dialog, Sheet and Drawer a title. Use chromeless dialogs with a title so the accessible name remains.
• Give Select, Combobox and the other fields a label prop. Without one, the control has no visible or programmatic name. For a Combobox with no visible label, pass ariaLabel.
• Do not put will-change: transform on glass surfaces. It breaks blur rendering, which also removes the contrast the tint was tuned for.
• Make clickable non-button elements real <button> or <a> elements.

Testing

Components are tested with vitest-browser-svelte and axe-core. The helper in packages/ui/tests/a11y.ts provides checkA11y and a toHaveNoViolations matcher (this is the pattern used inside the repo):

import { render } from "vitest-browser-svelte";
import { checkA11y } from "../../../tests/a11y";

it("has no axe violations", async () => {
  const screen = await render(MyComponent);
  expect(await checkA11y(screen.container)).toHaveNoViolations();
});

In your app, run axe on your routes in light and dark, and with an overlay open, using Playwright with @axe-core/playwright. Also test with a keyboard only and with a screen reader on at least one platform.