Skip to content
Tutorials Center
My learning

Topics

Lesson 96 of 132 ยท Ecosystem

UI Libraries and Design Systems

Compare React component libraries (MUI, Chakra, shadcn/ui, Radix, Headless UI), learn design tokens, theming and headless components, and build a tiny accessible design system.

Nearly every real application needs the same dozen widgets: buttons, text fields, selects, tabs, dialogs, menus, tooltips, toasts. Writing each of them well is much harder than it looks. A good dialog traps focus, restores it on close, closes on Escape, locks background scrolling and announces itself to screen readers. Most teams therefore do not write these from scratch. They pick a UI library, or they build a small design system of their own on top of a few well-tested primitives.

This lesson gives you a map of the options, explains the three ideas that every library is built on (design tokens, theming and headless components), and then builds a miniature design system you can run right here. You will use the styling techniques and component design rules from earlier lessons, and you will see why accessibility is the main reason to reach for a library at all.

Three kinds of library

Component libraries differ mostly in how much they decide for you. It helps to sort them into three groups.

Kind You get Examples Trade-off
Styled Finished, themed components MUI (Material UI), Chakra UI, Ant Design, Mantine Fastest start; the look is opinionated and customizing deeply can be a fight
Headless Behavior and accessibility, no visuals Radix Primitives, React Aria, Headless UI, Ark UI You write all the styling; you keep full control of the design
Copy-in kits Source code you own, built on headless parts shadcn/ui No dependency to upgrade for the visual layer, but you maintain the copied code

None of these is "the best". The right choice depends on how unique your design must be, how large your team is, and how long the product will live.

The names above are real, widely used projects, but this editor has no npm packages installed. Snippets that import them are read-only and labelled as such. The runnable examples on this page are hand-written stand-ins that show the same ideas.

Styled libraries

A styled library such as MUI gives you components that already look finished and follow a design language. You import them, configure a theme object, and use them:

JSX
// Read-only: needs the npm package @mui/material.
import { Button, TextField, ThemeProvider, createTheme } from '@mui/material';

const theme = createTheme({
  palette: { primary: { main: '#4f46e5' } },
});

function SignUp() {
  return (
    <ThemeProvider theme={theme}>
      <TextField label="Email" type="email" />
      <Button variant="contained">Create account</Button>
    </ThemeProvider>
  );
}

This is the quickest way to a consistent admin dashboard or internal tool. The cost is bundle size, a styling system you have to learn (in MUI's case a CSS-in-JS engine and a sx prop), and a design that looks recognisably "Material" unless you invest in theming.

Headless libraries

A headless component implements behavior (state, keyboard handling, ARIA attributes, focus management) and leaves the markup and styles to you. Radix Primitives, for example, offers a Dialog made of parts you assemble:

JSX
// Read-only: needs the npm package @radix-ui/react-dialog.
import * as Dialog from '@radix-ui/react-dialog';

function ConfirmDelete({ onConfirm }) {
  return (
    <Dialog.Root>
      <Dialog.Trigger className="btn">Delete</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="overlay" />
        <Dialog.Content className="dialog">
          <Dialog.Title>Delete this project?</Dialog.Title>
          <Dialog.Description>This cannot be undone.</Dialog.Description>
          <Dialog.Close className="btn">Cancel</Dialog.Close>
          <button type="button" className="btn danger" onClick={onConfirm}>Delete</button>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Everything difficult is handled for you: the content is rendered in a portal, focus moves into it and returns to the trigger on close, Escape and clicking the overlay close it, and the title and description are wired to aria-labelledby and aria-describedby. Your CSS decides how it looks.

Copy-in kits

shadcn/ui is a different distribution model. A command-line tool copies component source files (built on Radix and styled with Tailwind CSS) into your repository. There is no shadcn-ui package to upgrade; the files become yours to edit. That removes the "I cannot change this one detail" problem, at the price of owning the code and applying upstream fixes by hand.

Design tokens

Every library, and every design system you build, starts with design tokens: named values for the decisions a designer makes once. Instead of writing #4f46e5 in forty places, you name it --color-primary and refer to the name.

Tokens usually cover:

  • Color: brand, text, background, border, danger, success.
  • Spacing: a scale such as 4, 8, 12, 16, 24, 32 pixels.
  • Typography: font families, sizes, weights, line heights.
  • Radius, shadow, motion: corner rounding, elevation, durations.

On the web the most practical token format is CSS custom properties. They cascade, so a subtree can override them, and they update live without re-rendering React. That makes theming almost free: switch a data-theme attribute, and every component that reads the variables changes.

Design tokens and a theme switch

Notice that the React state holds only the name of the theme. The actual colors live in CSS, and the browser repaints without React re-rendering anything below the attribute change. That is also why a CSS-variable theme is cheaper than passing colors through context as JavaScript values.

Use two layers of tokens. Primitive tokens name raw values (--blue-600). Semantic tokens say what a value is for (--color-primary: var(--blue-600)). Components read only semantic tokens, so a rebrand or a dark theme changes the mapping in one place.

Theming in the library world

Styled libraries expose the same idea through a ThemeProvider. You pass a theme object, and the provider uses context to make it available to every component below. Under the hood, MUI and Chakra turn many theme values into CSS variables or generated class names, because reading a context value in every styled component is more work than letting the browser resolve a variable.

A few rules apply whichever library you use:

  1. Keep one source of truth. Tokens live in one file or one stylesheet, not scattered across components.
  2. Respect the user's system setting. Read prefers-color-scheme (a media query) for the default theme, and let the user override it.
  3. Persist the choice. In a real app you would store the theme in localStorage or a cookie. Our sandboxed editor has no storage, so the demos keep it in memory.
  4. Avoid a flash of the wrong theme. On a server-rendered page, set the data-theme attribute before the first paint, usually with a tiny inline script in the document head.

Headless components, by hand

The best way to understand a headless library is to build one small piece. A switch (an on/off toggle) looks trivial, but the accessible version needs a role, a state attribute, a label, and keyboard support. A native <button> gives you focus and Space/Enter activation for free, so we build on it:

A headless Switch with ARIA

Tab to a switch and press Space: it toggles, because the element is a real button. A screen reader announces "Notifications, switch, on". The component knows nothing about green or grey; those come from data-state selectors in CSS. That split is exactly what Radix and React Aria do at larger scale. Note that the component is controlled: the parent owns checked, the same pattern as a controlled input from controlled and uncontrolled components.

Composite widgets need more. Tabs follow the WAI-ARIA pattern called roving tabindex: only the selected tab is in the Tab order, and the arrow keys move between tabs. This is the sort of detail a headless library gets right once, for everyone.

Headless Tabs with arrow keys

Click inside the tab list, then press the right arrow: selection and focus move together, and wrap around at the end. Only one tab has tabIndex={0}, so pressing Tab from the list jumps straight to the panel instead of walking through every tab.

Building a tiny design system

A design system is not a package you must install; it is a layer of your own components that apply your tokens and decisions, so product code never repeats them. Product code writes <Button tone="danger">, not twenty lines of classes.

Good small-system habits:

  • Constrain the API. Offer tone and size props with a few allowed values rather than accepting arbitrary colors.
  • Forward the rest. Spread unknown props onto the root element so onClick, disabled, aria-* and data-* keep working.
  • Accept className and merge it with yours, as an escape hatch.
  • Use ref as a regular prop in React 19, so consumers can focus the element. No forwardRef is needed.
A mini design system: Button and Field

Try typing a complete address: the error disappears, the hint takes its place and Save becomes enabled. The Field component links its message to the input with aria-describedby, so screen readers read the error after the label. useId generates the unique id (its exact text is an implementation detail; never depend on it).

Accessibility baseline

If you adopt a library, the accessibility work it saves is worth more than the visuals. Whatever you choose, check these:

  • Native elements first. Buttons for actions, links for navigation, <label> for inputs. ARIA roles only fill gaps native HTML cannot.
  • Keyboard access. Every control reachable with Tab, activated with Enter or Space, and a visible focus ring (:focus-visible). Composite widgets (tabs, menus, listboxes) also use arrow keys.
  • Names and states. Every control has an accessible name; toggles expose aria-pressed, aria-checked or aria-expanded.
  • Focus management for dialogs and popovers: move focus in, trap it, restore it.
  • Contrast. Text needs roughly 4.5:1 against its background, in every theme.
  • Do not rely on color alone to show an error or status.

A beautiful library does not make your app accessible. Props are still your responsibility: an icon-only button needs an aria-label, an image needs alt, and a form needs real labels. Test with the keyboard alone and with a screen reader. The lesson on accessibility goes deeper.

Choosing, and what to check before adopting

Ask these questions before you commit:

  1. How custom is the design? A marketing site with a strong brand points to headless or copy-in. An internal tool with tight deadlines points to styled.
  2. How is it styled? Libraries that depend on runtime CSS-in-JS can conflict with Server Components and add JavaScript cost. Check that the library supports your rendering model.
  3. Is it maintained and accessible? Look at recent releases, open issues, and whether keyboard and screen-reader behavior is documented and tested.
  4. What does it cost in bytes? Check whether it is tree-shakeable and how much a single button adds to your bundle (see code splitting).
  5. Can you leave? Wrapping library components in your own Button, Dialog, Select means a future swap touches one folder instead of the whole app. That wrapper layer is your design system.

Building everything yourself rarely pays off, and adopting a heavy library for two buttons rarely does either. A common sweet spot is a headless library for the hard widgets (dialog, menu, combobox) plus your own tokens and thin wrappers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a headless UI component?

    Headless components such as Radix primitives or React Aria hooks implement state, keyboard handling, focus and ARIA, while you decide how they look.
  2. 2. Why are CSS custom properties a good fit for theming?

    Variables resolve in the browser. Changing a data-theme attribute switches every component that reads the variables, with no JavaScript passing colors around.
  3. 3. What is the main distribution difference of shadcn/ui compared with MUI?

    With shadcn/ui you own the copied files and edit them freely; with MUI you import from a package and customize through its theme and props.
  4. 4. Which is the best first choice for a clickable on/off toggle?

    A native button already supports focus and keyboard activation. Adding role="switch" and aria-checked tells assistive technology what it does.
  5. 5. Why wrap a third-party Button inside your own Button component?

    A thin wrapper layer is the core of a design system: it fixes your tokens and prop names and hides the library behind one boundary.

Summary

  • Component libraries come in three flavors: styled (MUI, Chakra, Ant Design, Mantine), headless (Radix, React Aria, Headless UI) and copy-in kits (shadcn/ui).
  • Design tokens name your design decisions; CSS custom properties make them cheap to theme, including dark mode.
  • Use primitive tokens for raw values and semantic tokens for purpose, and let components read only semantic ones.
  • Headless components own behavior and ARIA; you own the styling. A native element with the right role is the foundation.
  • A design system is a thin layer of your own components with constrained props that forwards the rest, so libraries can change behind it.
  • Always verify keyboard access, names, focus management and contrast; a library helps but does not guarantee accessibility.

Next: The React Ecosystem Map