# Merid

> Merid is an accessible React component library (`@meridui/react`) built on plain CSS, cascade layers and `--mrd-*` design tokens: 1px hairlines, one cool accent, soft grey trays and calm motion. React 18 and 19, server components, light and dark themes.

Install with `npm i @meridui/react` and import `@meridui/react/styles.css` once at the app entry, or run `npx @meridui/cli init`. Every component is imported from the package root.

Write Merid code with semantic `--mrd-*` tokens only: no raw hex colours, arbitrary spacing or inline styles. Compose existing components before creating new ones. The full rules are in [Using Merid with AI](https://meridui.dev/docs/ai.md) and at the top of [llms-full.txt](https://meridui.dev/llms-full.txt).

MCP server for coding agents: `npx -y @meridui/mcp` (tools: list_components, get_component, search_docs, get_tokens, get_design_contract, get_pattern, get_setup).

## Getting started

- [Introduction](https://meridui.dev/docs/introduction.md): What Merid is, what it is for, and the ideas it is built on.
- [Installation](https://meridui.dev/docs/installation.md): Install @meridui/react with npm, pnpm or Yarn, and set it up in Next.js or Vite.
- [CLI](https://meridui.dev/docs/cli.md): npx @meridui/cli: set up Merid in a Next.js, Vite or React Router project, add AI rules and MCP config, and copy page patterns.
- [Using Merid with AI](https://meridui.dev/docs/ai.md): Give Claude Code, Cursor, VS Code and Windsurf the Merid docs: an MCP server, llms.txt and an official rules file.
- [Usage](https://meridui.dev/docs/usage.md): Import components, pass variants through props, and compose them with your own markup.
- [Styling and CSS layers](https://meridui.dev/docs/styling.md): How Merid's cascade layers work and how to override tokens and components without !important.
- [Server components](https://meridui.dev/docs/server-components.md): Which Merid components render on the server and how interactive components behave in the App Router.
- [Accessibility](https://meridui.dev/docs/accessibility.md): Merid's accessibility statement: the standard it targets, how it is tested, and known limitations.
- [FAQ](https://meridui.dev/docs/faq.md): Answers to common questions about Merid.

## Foundations

- [Design tokens](https://meridui.dev/docs/foundations.md): How Merid's design tokens are named, tiered and consumed.
- [Color](https://meridui.dev/docs/foundations/color.md): Merid's colour tokens in light and dark, their roles and measured contrast ratios.
- [Dark mode](https://meridui.dev/docs/foundations/dark-mode.md): How Merid switches between light and dark, and how to control it per page or subtree.
- [Typography](https://meridui.dev/docs/foundations/typography.md): Merid's typeface, type scale, weights and typesetting rules.
- [Spacing](https://meridui.dev/docs/foundations/spacing.md): The spacing scale and layout widths used across Merid.
- [Radius](https://meridui.dev/docs/foundations/radius.md): Corner radius tokens and how radius steps down as surfaces nest.
- [Elevation](https://meridui.dev/docs/foundations/elevation.md): Shadow tokens, surface layering and the focus halo.
- [Motion](https://meridui.dev/docs/foundations/motion.md): Durations, easing and the interaction patterns that use them.
- [Breakpoints and layers](https://meridui.dev/docs/foundations/layout.md): Merid's two breakpoints, coarse-pointer sizing and the z-index scale.
- [Principles](https://meridui.dev/docs/foundations/principles.md): The ten rules every Merid component and page is held to.

## Components

- [Overview](https://meridui.dev/docs/components.md): Every Merid component, grouped by purpose, with its current status.
- [Accordion](https://meridui.dev/docs/components/accordion.md): Stacked disclosure sections that show one or more panels at a time.
- [Alert](https://meridui.dev/docs/components/alert.md): An inline notice on a tinted surface for info, success, warning and error messages.
- [AlertDialog](https://meridui.dev/docs/components/alert-dialog.md): A modal confirmation that interrupts and requires a response.
- [Avatar](https://meridui.dev/docs/components/avatar.md): A circular image or initials that represents a person or organisation.
- [Badge](https://meridui.dev/docs/components/badge.md): A small, non-interactive pill for status and counts.
- [Breadcrumb](https://meridui.dev/docs/components/breadcrumb.md): Shows where the current page sits in a hierarchy, with links to each ancestor.
- [Button](https://meridui.dev/docs/components/button.md): Triggers an action: submit a form, open a dialog, save a change.
- [Calendar](https://meridui.dev/docs/components/calendar.md): A month grid for picking a day or a range, with keyboard navigation and Intl locales.
- [Card](https://meridui.dev/docs/components/card.md): A content container that separates by surface, not border.
- [Checkbox](https://meridui.dev/docs/components/checkbox.md): A native checkbox for independent on/off choices and multi-select lists.
- [Code](https://meridui.dev/docs/components/code.md): Monospace code, inline in a tray chip or as a multi-line block.
- [Collapsible](https://meridui.dev/docs/components/collapsible.md): A button that shows and hides one region.
- [Combobox](https://meridui.dev/docs/components/combobox.md): A searchable select: type to filter, pick one or many, load options asynchronously.
- [Command](https://meridui.dev/docs/components/command.md): A searchable command menu with groups, keyboard navigation and shortcuts; opens as a ⌘K palette.
- [Container](https://meridui.dev/docs/components/container.md): Centres content, caps its width and adds the responsive side gutter.
- [ContextMenu](https://meridui.dev/docs/components/context-menu.md): A menu of actions opened at the pointer with a right-click.
- [DataTable](https://meridui.dev/docs/components/data-table.md): Sorting, filtering, pagination, row selection and column visibility on top of Table.
- [DatePicker](https://meridui.dev/docs/components/date-picker.md): A date field you can type into, with a calendar popover for a single day or a range.
- [Dialog](https://meridui.dev/docs/components/dialog.md): A modal window for a focused task, with focus trap, scroll lock and dismiss handling.
- [Drawer](https://meridui.dev/docs/components/drawer.md): A modal side sheet that slides in from the left or right edge.
- [DropdownMenu](https://meridui.dev/docs/components/dropdown-menu.md): A list of actions or toggles opened from a button.
- [EmptyState](https://meridui.dev/docs/components/empty-state.md): A centred placeholder for empty lists, searches with no results and first-run screens.
- [Field](https://meridui.dev/docs/components/field.md): Label, control, helper text and error message wired together with ids and ARIA.
- [FileUpload](https://meridui.dev/docs/components/file-upload.md): An accessible file picker with a drag-and-drop zone, validation and a file list.
- [Grid](https://meridui.dev/docs/components/grid.md): Two-dimensional grid layout with fixed or auto-fit columns.
- [Heading](https://meridui.dev/docs/components/heading.md): Semantic h1–h6 with Merid's tight, balanced heading scale, size independent of level.
- [HoverCard](https://meridui.dev/docs/components/hover-card.md): A preview card shown when pointing at or focusing a link.
- [IconButton](https://meridui.dev/docs/components/icon-button.md): A square, icon-only button with a required accessible label.
- [Input](https://meridui.dev/docs/components/input.md): Single-line text input with sizes, leading and trailing addons, and Field wiring.
- [Kbd](https://meridui.dev/docs/components/kbd.md): A keyboard key cap for documenting shortcuts.
- [Label](https://meridui.dev/docs/components/label.md): A form label with optional required marker and disabled styling.
- [Link](https://meridui.dev/docs/components/link.md): A styled anchor for navigation, inline or standalone.
- [NativeSelect](https://meridui.dev/docs/components/native-select.md): The platform select element with Merid styling, native keyboard and mobile pickers.
- [NavigationMenu](https://meridui.dev/docs/components/navigation-menu.md): A site's top navigation with drop-down and mega-menu panels of links.
- [NumberInput](https://meridui.dev/docs/components/number-input.md): A numeric field with increment and decrement buttons, min, max, step and Intl.NumberFormat.
- [Pagination](https://meridui.dev/docs/components/pagination.md): Moves between pages of results, with previous and next controls and a compact page range.
- [PinInput](https://meridui.dev/docs/components/pin-input.md): One-time code and PIN entry with one cell per character, paste and autofill.
- [Popover](https://meridui.dev/docs/components/popover.md): A non-modal floating panel anchored to a trigger.
- [Portal](https://meridui.dev/docs/components/portal.md): Renders its children into document.body, or another element, outside the parent DOM tree.
- [Progress](https://meridui.dev/docs/components/progress.md): A linear progress bar for determinate and indeterminate tasks.
- [Radio](https://meridui.dev/docs/components/radio.md): Native radios in a RadioGroup for choosing exactly one option from a small set.
- [ScrollArea](https://meridui.dev/docs/components/scroll-area.md): A native scroll container with thin, themed scrollbars.
- [Section](https://meridui.dev/docs/components/section.md): A full-bleed page band with Merid's vertical rhythm and an optional tray background.
- [SegmentedControl](https://meridui.dev/docs/components/segmented-control.md): A pill-shaped single-select toggle for switching views or ranges.
- [Select](https://meridui.dev/docs/components/select.md): Choose one option from a styled list.
- [Separator](https://meridui.dev/docs/components/separator.md): A 1px hairline that divides content, horizontally or vertically.
- [Shortcut](https://meridui.dev/docs/components/shortcut.md): A platform-aware key combination built from Kbd key caps.
- [SidebarNav](https://meridui.dev/docs/components/sidebar-nav.md): Vertical navigation for application sidebars, with groups, icons and trailing counts.
- [Skeleton](https://meridui.dev/docs/components/skeleton.md): A shimmering placeholder that holds the shape of content while it loads.
- [Slider](https://meridui.dev/docs/components/slider.md): Pick a value, or a range with two thumbs, on a horizontal track.
- [Spinner](https://meridui.dev/docs/components/spinner.md): An indeterminate loading indicator that inherits the current text colour.
- [Stack](https://meridui.dev/docs/components/stack.md): One-dimensional flex layout with gaps from the spacing scale.
- [Stepper](https://meridui.dev/docs/components/stepper.md): A read-only display of progress through a multi-step flow.
- [Switch](https://meridui.dev/docs/components/switch.md): An on/off toggle for settings that take effect immediately.
- [Table](https://meridui.dev/docs/components/table.md): Styled table primitives for tabular data in a hairline, horizontally scrollable frame.
- [Tabs](https://meridui.dev/docs/components/tabs.md): Line tabs for switching between related panels.
- [Text](https://meridui.dev/docs/components/text.md): Body text on Merid's type scale, with tone and weight for hierarchy.
- [Textarea](https://meridui.dev/docs/components/textarea.md): Multi-line text input with resize control and Field wiring.
- [Toast](https://meridui.dev/docs/components/toast.md): Brief, non-blocking notifications stacked in the corner of the screen.
- [ToggleGroup](https://meridui.dev/docs/components/toggle-group.md): Two-state toggle buttons, alone (Toggle) or as a single- or multiple-choice set.
- [Toolbar](https://meridui.dev/docs/components/toolbar.md): A row of related controls that is a single Tab stop.
- [Tooltip](https://meridui.dev/docs/components/tooltip.md): A short text label shown on hover and focus.
- [VisuallyHidden](https://meridui.dev/docs/components/visually-hidden.md): Hides content visually while keeping it available to screen readers.

## Integrations

- [React Hook Form](https://meridui.dev/docs/integrations/react-hook-form.md): Use Merid form controls with React Hook Form: register for native inputs, Controller for Select, RadioGroup and Switch.
- [Validation with Zod](https://meridui.dev/docs/integrations/zod.md): Validate Merid forms with a Zod schema, through React Hook Form or with plain FormData and server actions.
- [Next.js](https://meridui.dev/docs/integrations/nextjs.md): Use Merid with the Next.js App Router: stylesheet, server components, routing links, fonts and metadata.
- [React Router and TanStack](https://meridui.dev/docs/integrations/routers.md): Render Merid navigation components as React Router or TanStack Router links.
- [Vite](https://meridui.dev/docs/integrations/vite.md): Set up Merid in a Vite + React app: stylesheet order, fonts and dark mode.
- [Tailwind CSS](https://meridui.dev/docs/integrations/tailwind.md): Use Merid alongside Tailwind CSS v4: layer order, Preflight, and Merid tokens as Tailwind theme values.
- [Icons](https://meridui.dev/docs/integrations/icons.md): Use lucide-react (or any SVG icon set) with Merid: sizes, stroke width and where icons go.
- [Figma and Style Dictionary](https://meridui.dev/docs/integrations/design-tokens.md): Use @meridui/tokens to bring Merid's design tokens into Figma (Tokens Studio), Style Dictionary and JavaScript.
- [Plain HTML and CSS](https://meridui.dev/docs/integrations/html.md): Use Merid's stylesheet without React: which components work with classes and data attributes, with markup to copy.
- [Subtree attributes](https://meridui.dev/docs/integrations/subtree-attributes.md): Theme, accent and density on any element with data-theme, data-accent and data-density. They nest.
- [Theming a brand](https://meridui.dev/docs/integrations/theming.md): Give Merid your brand colour by overriding the accent tokens, in light and dark, for the whole app or one subtree.
- [Dark mode strategies](https://meridui.dev/docs/integrations/dark-mode.md): Follow the system, add a toggle without a flash, or theme a single subtree with data-theme.
- [Internationalization and RTL](https://meridui.dev/docs/integrations/rtl.md): What Merid does and does not do for right-to-left languages, translated labels and locale formatting.

## Patterns

- [Forms](https://meridui.dev/docs/patterns/forms.md): Form layout, validation timing, error summaries and submit states with Merid components.
- [Empty and loading states](https://meridui.dev/docs/patterns/empty-and-loading.md): Skeletons, spinners, empty states and error states for lists and panels.
- [Confirmations](https://meridui.dev/docs/patterns/confirmations.md): When to confirm, when to offer undo, and how to build a typed confirmation with AlertDialog.
- [Data tables](https://meridui.dev/docs/patterns/data-tables.md): Sorting, filtering, row selection with bulk actions, and pagination built from Table, Checkbox and Pagination.
- [Settings pages](https://meridui.dev/docs/patterns/settings.md): Sectioned settings with a side nav, explicit save, toggles that apply immediately, and a danger zone.
- [Authentication](https://meridui.dev/docs/patterns/authentication.md): Sign-in and verification-code screens with correct autocomplete, error handling and loading states.
- [Navigation layouts](https://meridui.dev/docs/patterns/app-shell.md): A sidebar app shell with a top bar, breadcrumbs and an account menu that collapses into a drawer on small screens.

## Optional

- [Browser support](https://meridui.dev/docs/browser-support.md): The browsers Merid supports and the CSS features it relies on.
- [Versioning](https://meridui.dev/docs/versioning.md): How Merid versions releases and deprecates APIs.
- [Changelog](https://meridui.dev/docs/changelog.md): Release notes for every published version of @meridui/react.
- [Roadmap](https://meridui.dev/docs/roadmap.md): What is planned for Merid and in what order.
- [Contributing](https://meridui.dev/docs/contributing.md): How to set up the repository, propose changes and get a pull request merged.
- [Logo and usage](https://meridui.dev/docs/brand.md): The Merid mark and wordmark, clear space, colour versions and what to avoid.
- [Design contract](https://meridui.dev/design.md): Binding rules for colour, radius, shadow, typography and naming