`. Form controls are real `` / `

` elements. See [Philosophy](/philosophy#semantic-html-then-everything-else) for the full argument.
- **Composition over re-implementation.** Where the platform doesn't ship a primitive (combobox, dialog, tabs), we wrap a vetted unstyled library — we never re-implement keyboard or ARIA logic from scratch.
- **Progressive enhancement.** CSS-failure and no-JS rendering should still produce a usable page where possible. The skip link, semantic landmarks, and form constraint validation all work without script.
- **High contrast and reduced motion are not opt-ins.** Themes ship with high-contrast variants and animations respect `prefers-reduced-motion`.

## Required app-level setup

For full accessibility, an app embedding mantle must:

1. Mount [`<ThemeProvider>`](/components/theme), [`<TooltipProvider>`](/components/tooltip), and [`<Toaster>`](/components/toast) at the root of the document tree.
2. Place [`<SkipToMainLink />`](/components/skip-to-main-link) as the very first focusable element in `<body>`, paired with a [`<Main>`](/components/main) landmark wrapping the page's primary content.
3. Render a single `<h1>` per page that names the page.
4. Use real form elements with associated [`<Label>`](/components/label)s.
5. Provide accessible names on icon-only controls — [`IconButton`](/components/icon-button) requires `aria-label`.

## Skip-to-main and landmarks

Every page should be navigable by landmarks. The minimum structure:

```tsx
import { SkipToMainLink } from "@ngrok/mantle/skip-to-main-link";
import { Main } from "@ngrok/mantle/main";

export default function App() {
	return (
		<>
			<SkipToMainLink />
			<header>{/* nav */}</header>
			<Main>
				<h1>Page title</h1>
				{/* primary content */}
			</Main>
			<footer>{/* … */}</footer>
		</>
	);
}
```

`SkipToMainLink` is visually hidden until focused and uses the History API directly so it works in any framework. `Main` renders `<main id="main" tabIndex={-1}>` so the skip link can deliver focus without leaving a visible focus ring on the region itself.

## Keyboard interactions per component

The table below summarizes the keyboard contract for the most common interactive components. Underlying primitives (Radix, Ariakit) implement the full WAI-ARIA pattern — these are the keys consumers most often need to remember.

| Component                                                                                                 | Keys                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Button](/components/button) / [IconButton](/components/icon-button)                                      | `Tab` to focus, `Enter` or `Space` to activate.                                                                                                   |
| [Anchor](/components/anchor)                                                                              | `Tab` to focus, `Enter` to follow.                                                                                                                |
| [Checkbox](/components/checkbox) / [Switch](/components/switch)                                           | `Tab` to focus, `Space` to toggle.                                                                                                                |
| [RadioGroup](/components/radio-group)                                                                     | `Tab` to enter the group, `Arrow` keys to move and select within the group.                                                                       |
| [Tabs](/components/tabs)                                                                                  | `Tab` to enter the tab list, `Arrow Left`/`Right` to move, `Home`/`End` to jump, `Enter`/`Space` to activate.                                     |
| [Dialog](/components/dialog) / [AlertDialog](/components/alert-dialog)                                    | Focus is trapped inside while open, `Esc` closes (Dialog only — AlertDialog requires explicit confirmation), `Tab`/`Shift+Tab` cycles focus.      |
| [Sheet](/components/sheet)                                                                                | Same as Dialog.                                                                                                                                   |
| [Popover](/components/popover) / [HoverCard](/components/hover-card)                                      | `Esc` closes; `Tab` cycles focusable content. HoverCard opens on hover/focus and is non-essential.                                                |
| [DropdownMenu](/components/dropdown-menu) / [Command](/components/command)                                | `Arrow Up`/`Down` to navigate items, `Enter` to select, `Esc` to close, type-ahead jumps to matching items.                                       |
| [Combobox](/components/combobox) / [MultiSelect](/components/multi-select) / [Select](/components/select) | `Arrow Up`/`Down` through options, `Enter` selects, type filters, `Esc` closes.                                                                   |
| [Slider](/components/slider)                                                                              | `Arrow Left`/`Right` (or `Up`/`Down`) increment/decrement, `Home`/`End` jump to min/max, `PageUp`/`PageDown` for larger steps.                    |
| [DataTable](/components/data-table)                                                                       | Row click handlers respond to `Enter` when used with `asChild` rendering of an `<a>` or `<button>`. Header sort buttons follow Button keys above. |
| [Toast](/components/toast)                                                                                | Auto-dismissing toasts respect `prefers-reduced-motion`; `F8` (browser default) cycles to the toast region.                                       |

## Focus management

- **Trap on modal surfaces.** `Dialog`, `AlertDialog`, and `Sheet` trap focus while open and restore it to the trigger on close.
- **Don't trap on non-modal surfaces.** `Popover` and `HoverCard` allow focus to escape — that's intentional.
- **Programmatic focus is fine.** When a route changes, focus the page's `<h1>` (or the `<Main>` landmark via `document.getElementById("main")?.focus()`) so screen reader users hear the page change.
- **Visible focus rings.** Mantle uses `:focus-visible` so focus styles appear for keyboard users without distracting mouse users. Don't override `outline` without providing an equivalent ring.

## ARIA roles and labels

Mantle components emit appropriate roles automatically. Consumers need to add:

- `aria-label` on [`IconButton`](/components/icon-button), and any [`Button`](/components/button) whose label is icon-only.
- `aria-label` or visually-hidden text on [`Kbd`](/components/kbd) when the visible glyph is a symbol (e.g. `⌘`).
- `aria-describedby` linking error/help text to form controls. [`Input`](/components/input) and friends do this for you when you use the validation prop, but custom messages should be wired manually.
- `aria-current="page"` on the active item in primary navigation (use react-router's `NavLink` for this).
- Live-region semantics — use [`Toast`](/components/toast) for transient announcements; use the [`Alert`](/components/alert) component with `role="alert"` for inline warnings.

## Color contrast and themes

- Color tokens (`text-strong`, `text-muted`, `bg-form`, `border-accent-600`, etc.) target WCAG AA contrast in both light and dark themes.
- High-contrast variants are provided via dedicated stylesheets — import [`@ngrok/mantle/mantle-light-high-contrast.css`](https://www.npmjs.com/package/@ngrok/mantle?activeTab=code) or `@ngrok/mantle/mantle-dark-high-contrast.css` to opt in.
- Don't communicate state by color alone. Use color **and** a label, icon, or copy. `Badge` and `Alert` do this by default; custom components should follow suit.

## Reduced motion

Animations across mantle (toasts, transitions, the password-input eye blink) honor `prefers-reduced-motion`. Custom animations should too:

```css
@media (prefers-reduced-motion: reduce) {
	.my-animation {
		animation: none;
	}
}
```

## Testing

Manual smoke checks per page or PR:

1. **Keyboard-only.** Hide your mouse. `Tab` from the top of the page. You should be able to reach every interactive element, see focus on each, activate it with the appropriate key, and never get stuck.
2. **Skip link.** First `Tab` from the top of the page should reveal the skip link; activating it should land focus inside `<Main>`.
3. **Screen reader.** A quick pass with VoiceOver (Mac, `Cmd+F5`) or NVDA (Windows) — every interactive element should announce its role and accessible name.
4. **Reduced motion.** In OS settings, enable Reduce Motion. Repeat any animated flow.
5. **High contrast.** Switch the imported theme to `*-high-contrast.css`. Confirm legibility.
6. **Zoom.** Zoom to 200% in Chrome — content should reflow without horizontal scroll.

For automated testing, [`axe-core`](https://github.com/dequelabs/axe-core) integrated via Playwright catches the bulk of WCAG issues. Mantle does not ship a custom axe runner, but the conventions in `CONVENTIONS.md` favor structures that pass it.

## When you can't fix the accessibility issue

If a third-party widget or constraint makes a component temporarily inaccessible:

1. Document it in a code comment that explains the *why* and links to the tracking issue.
2. Communicate the limitation to the user — don't ship invisible inaccessibility.
3. Provide a fallback path (e.g. a plain `<a>` with the same target) so keyboard and screen-reader users are not blocked.

The goal isn't perfect compliance forever — it's making the right choice the default and surfacing the exceptions honestly.

---

---
title: Breakpoints
description: Responsive breakpoints for building adaptive layouts in the mantle design system
---

# Breakpoints

Responsive breakpoints for building adaptive layouts.

## Live Demo

## Breakpoint Values

There are seven breakpoints by default, inspired by common device resolutions:

| Breakpoint prefix | Minimum width   | CSS                                 |
| ----------------- | --------------- | ----------------------------------- |
| `default`         | 0rem (0px)      | No media query                      |
| `2xs`             | 22.5rem (360px) | `@media (width >= 22.5rem) { ... }` |
| `xs`              | 30rem (480px)   | `@media (width >= 30rem) { ... }`   |
| `sm`              | 40rem (640px)   | `@media (width >= 40rem) { ... }`   |
| `md`              | 48rem (768px)   | `@media (width >= 48rem) { ... }`   |
| `lg`              | 64rem (1024px)  | `@media (width >= 64rem) { ... }`   |
| `xl`              | 80rem (1280px)  | `@media (width >= 80rem) { ... }`   |
| `2xl`             | 96rem (1536px)  | `@media (width >= 96rem) { ... }`   |

## useBreakpoint Hook

The `useBreakpoint` hook returns the current breakpoint based on the viewport width. It efficiently tracks all breakpoints and returns the largest one that currently matches.

```tsx
import { useBreakpoint } from "@ngrok/mantle/hooks";

function ResponsiveComponent() {
	const breakpoint = useBreakpoint();

return (
		<div>
			<p>Current breakpoint: {breakpoint}</p>
			{breakpoint === "lg" && <p>This only shows on large screens and above!</p>}
		</div>
	);
}
```

### Features

- **Performance optimized:** Uses a single subscription for all breakpoint changes
- **SSR compatible:** Returns `default` during server-side rendering
- **Real-time updates:** Automatically updates when the viewport size changes
- **TypeScript support:** Fully typed with autocompletion for all breakpoints

### Return Value

Returns a `Breakpoint` type that can be one of: `"default"`, `"2xs"`, `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"2xl"`.

## useIsBelowBreakpoint Hook

The `useIsBelowBreakpoint` hook returns `true` if the current viewport width is below the specified breakpoint. Perfect for mobile-first responsive design patterns.

```tsx
import { useIsBelowBreakpoint } from "@ngrok/mantle/hooks";

function ResponsiveSidebar() {
	const isMobile = useIsBelowBreakpoint("md");

return (
		<aside className={isMobile ? "mobile-sidebar" : "desktop-sidebar"}>
			{isMobile ? <MobileNav /> : <DesktopNav />}
		</aside>
	);
}
```

### Parameters

Accepts a `TailwindBreakpoint` which can be one of: `"2xs"`, `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"2xl"`.

### Common Use Cases

- **Mobile detection:** `useIsBelowBreakpoint("md")` for mobile-first layouts
- **Conditional rendering:** Show/hide components based on screen size
- **Dynamic styling:** Apply different CSS classes for mobile vs desktop
- **Component adaptation:** Switch between mobile and desktop component variants

---

---
title: Colors
description: Color system for the mantle design system with automatic dark and high contrast mode support
---

# Colors

Colors are a key component of any design system. They are used to convey meaning, attract
attention, and provide feedback. Mantle's color system is designed to be accessible
and flexible with dark and high contrast modes.

## Tailwind

Mantle uses Tailwind under the hood for all its CSS styling. However, we differ from
Tailwind when it comes to colors. Mantle provides a full color library that automatically
provides dark and high contrast modes. This is different from standard Tailwind usage
that *requires* dark class variations. By simply specifying light colors provided
by Mantle, you'll get dark and high contrast modes for free. If you require
additional customization, you can provide dark variant classes as an override.

## Variables

Mantle's colors are delivered as CSS variables via Tailwind's API e.g.
`.text-blue-500`. They can be directly accessed via `var(--color-blue-500)` and use `oklch()` color space.

## Black and White Color Variables

Mantle overrides what "black" and "white" mean depending on the theme. We transformed
these colors to be semantic colors instead of literal colors. For dark modes, we swap them
so that white is actually black and vice versa. Pay attention to the example below when
swapping between our themes!

## Overrides

Most colors should appropriately swap for sensible values in dark and high contrast modes.
However, there are often cases where you'll need to specify an override. The
`dark:` variant is well-documented on [Tailwind's website](https://tailwindcss.com/docs/dark-mode).
Mantle provides additional variants for high contrast and dark high contrast mode with
`high-contrast:` and `dark-high-contrast:` respectively.

## Functional Colors

Mantle generally limits its color choices to the following functional colors for primary
actions, and various states like danger and warnings.

### Neutral