Skip to main content

Rudiment UI

Open-source project · Design systems

An accessible component library that any team can brand

Rudiment UI is an accessible React component library built on React Aria and design tokens. I designed its components, tokens, and brand, and wrote its docs and tests. To check it on a real screen, I built a demo app from library components only, and each place the app had to work around the library became a fix in the library.

GAP LOG · VITREA DEMO <RudiHeading … style={{ margin: 0 }}> <RudiHeading level={3} size={5}> Data table Added Field borders at 1.3:1 Fixed Fixed in the library, not the app
476 → 0
inline styles needed to build a screenDemo pages before, Vitrea after
741
unit tests, including axe accessibility checksAcross 63 test files
My role
Design and front-end engineering
Owned
Component APIs, tokens and themes, brand, docs, tests, the Vitrea demo
Team
Solo project
Built with
React 19, TypeScript, React Aria, Style Dictionary, Storybook, Vitest

Project summary

A component library can pass every test in Storybook and still fail on a real screen. Building 26 demo pages with Rudiment UI took about 476 inline styles. A working app then found keyboard, contrast, and narrow-screen bugs that had passed every unit, axe, and story test.

The decision
I chose to build behavior on React Aria and every visual value on design tokens, so a team gets accessible components and brings its own brand. To test that on a real screen, I built a demo app from library components only and fixed each gap in the library instead of in the app.
The result
The library ships 741 unit tests with axe checks and eight themes that change only token values. The demo app, Vitrea, uses 905 library components and no inline styles. Building it added a data table, forms, date pickers, toasts, and app chrome to the library, and fixed about 30 bugs the tests had missed.

Audience

Rudiment UI is an accessible React component library. React Aria handles keyboard, focus, and screen reader behavior. Design tokens handle every color, size, and font, so a team can bring its own brand. It ships as an npm package with Storybook docs.

A library is judged twice: by the team building with it, and by the people using what that team builds. I checked each decision against both groups below.

  • Product teams

    Engineers and designers who need accessible, on-brand screens without staffing a design-system team of their own. More and more of them write the first draft with a coding agent.

    • Build a whole screen from library parts
    • Apply their own brand without forking
    • Keep the rest of their app’s CSS intact
    • An API an agent can look up
  • The people using those apps

    Staff who spend the day in an internal tool, by mouse, keyboard, or screen reader, in a wide window or a narrow one. They never see the library, only whether the screen works.

    • Every control usable by keyboard
    • Errors announced where they happen
    • Fields and borders they can see
    • Screens that hold up in a narrow window

Research

Requirements gathering

Rudiment UI has no client, so I wrote the brief myself: make it simple for developers to build a wide variety of production-grade front ends. I tracked the work in the repo, in a gap log, a changelog, and a task list. With no one to sign off, every change had to meet a written definition of done before it shipped.

I found the gaps by building with the library and logging every place the code had to leave it. The first round was 26 demo pages across four made-up products: a biotech marketing site, a CRM, a storefront, and a project tracker. I audited each page for raw HTML where a component should exist, inline styles, class overrides, hardcoded colors, local helper components, and imports from the libraries Rudiment wraps.

476

inline styles across 26 demo pages

and 0 class overrides, so the components needed more props

4 of 4

demo products rebuilt their own app shell

header, sidebar, and page header, each written by hand

The typography components caused the most workarounds: every product added an inline margin reset to almost every heading. Filling a select meant importing from React Stately, and menus exposed internal class names. None of the four had a data table, so each built its own.

Fixing those removed the workarounds, but demo pages still only showed how components look. So the second round was a working app, Vitrea, and it turned up a different kind of bug: a checkbox group that never passed its value down, text fields in tables that lost their arrow keys, field borders at 1.3:1 contrast, and a kanban board that announced every move twice by an internal id.

“Every one of the bugs above passed the existing unit, axe and story tests.”
The gap log, after the list of bugs Vitrea found

The pattern behind both rounds: a component can pass every test on its own and still fail on a real screen. Demo pages test how a component looks. Only a working app tests how it behaves when someone types, scrolls, narrows the window, or listens with a screen reader.

Personas

  • Kenji Mori

    The product engineer

    “If I have to remove the margin from every heading in every card, the library isn’t saving me time.”

    Builds screens on a small product team with no design-system group, often with a coding agent writing the first draft.

    Needs
    • Build a whole screen, tables and forms included, from library parts
    • Keyboard and screen reader behavior without wiring it up
    • An API reference a coding agent can read instead of guessing props
    Frustrations
    • Libraries that look finished in Storybook and break on a real page
    • Inline styles and third-party imports to make a component work
    • A package whose CSS restyles the rest of the app

    A working persona based on the gaps logged while building the demo pages and Vitrea. No outside engineers were interviewed.

  • Sofia Lindqvist

    The brand designer

    “I want to change the brand in one place, not file a ticket against every component.”

    Owns how a product looks and needs a shared library to carry her brand in light and dark.

    Needs
    • Rebrand by changing tokens, not component code
    • Light and dark themes that both pass contrast
    • Controls that line up and match in every theme
    Frustrations
    • Themes that depend on overrides inside component stylesheets
    • Field borders too faint to see
    • Two border colors and two heights in one row of controls

    A working persona based on rebranding Vitrea through tokens alone. No outside designers were interviewed.

  • Ruth Adeyemi

    The person using the finished app

    “When I move a card, I need to hear where it went, once.”

    Coordinates shipments at a clinic lab. She works mostly from the keyboard and uses a screen reader for long tables.

    Needs
    • Every control reachable and usable by keyboard
    • Errors announced and tied to their fields
    • Screens that still work in a narrow window
    Frustrations
    • Text fields in a table that lose their arrow keys
    • Each move announced twice, by an internal id
    • A form that takes focus away while she types

    A working persona based on the accessibility bugs Vitrea found. No screen reader users were interviewed or tested with.

Persona names and photos are illustrative, as are quotes without a named source.

Adoption journey map

  1. Reads the docs

    Activity

    A team decides whether the library is worth adopting.

    Problem

    Component stories show each part working alone, not a whole product.

    Design response
    Storybook opens with what the library is for, and links to a working app to try.
  2. Installs the package

    Activity

    An engineer adds the package to an existing app.

    Problem

    A library’s CSS can reset or restyle the rest of the app.

    Design response
    No reset and no bare element selectors, with React Aria kept out of the bundle so the app’s one copy is used.
  3. Applies the brand

    Activity

    A designer makes the components look like their product.

    Problem

    Earlier brand themes needed overrides inside component stylesheets.

    Design response
    Every theme is a set of token values, and Vitrea’s whole brand is one stylesheet.
  4. Builds real screens

    Activity

    Engineers, often with a coding agent, build tables, forms, and dashboards.

    Problem

    An agent that can’t look up the API guesses at props or falls back to raw markup.

    Design response
    The package ships its full API in files and a server that coding agents can read.
  5. People use the app

    Activity

    Staff use the finished screens all day, by mouse, keyboard, and screen reader.

    Problem

    Bugs in typing, focus, and narrow layouts passed every unit, axe, and story test.

    Design response
    A working app built only from library parts, with each bug fixed in the library.

Themes that change only tokens

Earlier versions shipped two brand themes that depended on overrides written into the component stylesheets, so a new brand meant editing components. I removed them and deleted every theme override from eleven stylesheets. A theme is now nothing but a different set of token values.

Every visual value is a --rudi- custom property in one of three tiers. A theme overrides token values in any tier, and the components follow. The library ships eight themes, including dark, Roomy, Soft, and Compressed, and a theme can be set on any element.

Token tiers

  • Primitive

    Raw values with no meaning, such as color.neutral.900. The semantic tier gives them a job.

  • Semantic

    What a value is for, such as color.brand.primary. Most themes and rebrands change only this tier.

  • Component

    One component’s values, such as component.button.primary-bg, so one component can change without touching the rest.

Vitrea was the test of that claim. It doesn’t change any library source. Its whole brand is one stylesheet of token overrides: a green-gray neutral ramp, a spruce brand color, Instrument Sans, and shadows tinted with the brand ink. Where tokens couldn’t reach, the library gained one, such as a display font token and a shared control height, so every field and medium button lines up at 38px in every theme.

  • The Vitrea shipment page in the Light theme: white cards with soft borders on a pale canvas, a spruce-green chain-of-custody stepper, and a red temperature alert.
    Light

    Vitrea’s own light theme: spruce green, pill buttons, and a display face for titles.

  • The same shipment page in the Compact theme: tight spacing, square corners, and the stops and full details list visible without scrolling.
    Compact

    Compact changes only spacing and radius, so more of the shipment fits on screen.

An API reference that coding agents can read

Teams increasingly ask a coding agent for the first draft of a screen. An agent that can’t look up a library’s API guesses at props, or falls back to raw markup and inline styles, which brings back the exact workarounds the gap log was removing.

I chose to generate the reference from the source over writing separate docs for agents, which would drift. Every build writes the full API to files in the package, and a small MCP server ships with it. It answers from the version installed in the project, with no network access and no account.

What ships in the package

  • llms.txt and llms-full.txt

    The library’s conventions, an index, and the full prop reference, generated from the TypeScript source on every build.

  • components.json

    Every component, compound part, prop, default, and inherited React Aria prop, as data.

  • An MCP server

    get_conventions, list_components, get_component, and search, answered from the version installed in the project.

  • Documented by test

    JSDoc on every export. A unit test fails on an undocumented export or a @default that doesn’t match the code.

A brand built from three primitives

Storybook was the first thing a team would see, and it looked like every other Storybook. A rudiment is a first principle, and in drumming it’s a basic pattern that bigger pieces are built from. The mark makes that literal: a lowercase r built from a bar, an arc, and a point on a 32-unit grid. With the point, it reads as “r.”, which echoes the headline “Build from the rudiments.”

Persimmon is the only accent, used once in each view. It fails text contrast, so it’s used only as a fill, and a deeper persimmon at 5.7:1 carries selected states and link underlines. Geist sets the headings and Geist Mono the labels.

The brand dresses only the docs. Components never read it, so a team’s own brand never has to fight mine. It’s in the repo but not yet on the public Storybook.

A library tested on a working app

More demo pages would have shown more components looking right. I built Vitrea instead: a demo shipping app for fertility clinics, where clinics book frozen-specimen transport and follow each shipment’s temperature from pickup to delivery. It has 14 screens, including shipments, booking, a shipment page with a live temperature trace, an address book, a dashboard, an ops board, and admin screens. The data lives in the browser, and a Demo controls dialog moves a simulated clock so readings and alerts play out.

The rule is that every element is a library component. When the library can’t do something, the fix goes into the library, not into a stand-in in the app, because a stand-in hides the gap. Vitrea installs the published npm package, so every fix had to ship in a release before the app could use it.

What Vitrea added to the library

  • A data table

    RudiTable with sorting, linked rows, and an empty state drawn inside the table, so the column headers stay in place.

  • Forms

    RudiForm with an error summary, plus a combo box, date pickers, a number field, and radio buttons.

  • App chrome

    App shell, top bar, page header, and section header, exported once a real app needed them.

  • Status and detail

    Toasts, an action slot on alerts, a sparkline for the probe temperature, and a description list for shipment details.

Bugs it found that the tests had missed

  • Keyboard

    Text fields inside table cells keep their arrow keys, and the form no longer takes focus away while someone types.

  • Contrast

    Form-control borders went from 1.3:1 to about 4.7:1, and chart legends no longer set their text in the series colors.

  • Screen readers

    Group errors are tied to their groups, and a kanban move is announced once, by the card’s label instead of its id.

  • Narrow screens

    Tab lists, hidden labels, and kanban columns no longer push the page wider than a 375px screen.

A Storybook docs page for the old CRM demo: a Top customers card listing five accounts with revenue and Healthy or At risk tags, above its source code, which wraps the page in a local CrmShell and PageHeader around RudiStack, RudiButton, and RudiGrid.
A demo page and its source

Before Vitrea: an old CRM demo page above its source, wrapped in a CrmShell and PageHeader written by hand for this one product.

A Vitrea shipment page in the Soft theme: a breadcrumb, the reference REF-24109 with Active, Premium Ground, and package badges; a red alert saying the shipment is reading too warm with a See the temperature log button; From and To cards; a probe temperature card with a sparkline crossing a dashed threshold; tabs; a four-step chain-of-custody stepper; and a details list.
Shipment page

The alert, sparkline, custody stepper, and details list are all library parts that Vitrea asked for.

Engineering

React Aria provides the behavior and Rudiment provides the look and the API. The sections below show the code behind each design decision, with the reason it was made.

Definition of done

  • One folder per component

    The component, its BEM stylesheet on component tokens, its stories, and a test file with render, keyboard, state, and axe checks.

  • Tokens with dark values

    New component tokens in the token file, with dark-theme values wherever color is involved, built and committed.

  • Docs and changelog

    The component guidelines updated, a changelog entry, and the gap log row marked done.

  • Green checks

    Type checks and the unit suite pass before a change ships to npm.

Themes are token values

A checkbox’s border starts as a primitive gray, neutral.500. The semantic tier names it the control border, and the component tier hands it to the checkbox. The stylesheet reads only the component token.

Why tokens only. The themes this replaced kept their focus rings inside the component stylesheets, under a selector for each theme, so every new brand meant editing components. Eleven stylesheets carried those overrides. Now a brand is a file of values, and the components don’t change.

Before: in 11 stylesheets

src/components/Checkbox/checkbox.css (before, removed in 7882c9e) css
[data-theme='teal'] .rudi-checkbox__input:focus-visible + .rudi-checkbox__control,
[data-theme='teal-dark'] .rudi-checkbox__input:focus-visible + .rudi-checkbox__control {
  outline: none;
}

[data-theme='teal'] .rudi-checkbox__input:focus-visible + .rudi-checkbox__control {
  box-shadow:
    0 0 0 2px var(--rudi-color-neutral-0),
    0 0 0 4px var(--rudi-color-border-focus),
    …;
}
…

After: one value through the tiers

tokens/semantic.json (semantic) json
"border": {
  "default": { "$value": "{color.neutral.200}" },
  "control": { "$value": "{color.neutral.500}" },
  …
tokens/components.json (component) json
"checkbox": {
  "control-size": { "$value": "1rem" },
  "control-border": { "$value": "{color.border.control}" },
  …
src/components/Checkbox/checkbox.css css
width: var(--rudi-component-checkbox-control-size);
height: var(--rudi-component-checkbox-control-size);
border: 1px solid var(--rudi-component-checkbox-control-border);
border-radius: var(--rudi-component-checkbox-control-radius);
background-color: var(--rudi-component-checkbox-control-bg);

One height for every control

Fields were 35px tall while a medium button was 39px, so no theme lined them up, and a field in a grid row grew taller when a neighbor had help text.

Why a token. Fields and medium buttons read one value, so a form row lines up in every theme, and a theme changes it in one place: 44px in Roomy, 32px in Compressed.

tokens/components.json json
"button": {
  …
  "height-md": { "$value": "{component.input.height}" },
  …
"input": {
  …
  "height": { "$value": "2.375rem" },
src/components/Input/input.css · src/components/Button/button.css css
/* input.css */
min-block-size: var(--rudi-component-input-height);

/* button.css */
min-block-size: var(--rudi-component-button-height-md);

Behavior from React Aria, API from Rudiment

Each component wraps React Aria’s hooks for keyboard, focus, and screen reader behavior, and exposes props of its own.

Why this API. React Aria’s press events cover mouse, touch, and keyboard, so buttons take onPress instead of onClick. onChange hands back the value, such as a string or a boolean, so a form stores it without unpacking an event. Behavior tests find elements by role and name, the way a screen reader user would.

src/components/Checkbox/CheckboxGroup.tsx tsx
import { useCheckboxGroup } from 'react-aria'
import { useCheckboxGroupState } from 'react-stately'
…
  /** Called with the full array of checked values (not an event) whenever one changes. */
  onChange?: (value: string[]) => void
…
export function RudiCheckboxGroup(props: RudiCheckboxGroupProps) {
  // isInvalid links the error message to the group and marks it invalid for assistive tech.
  const ariaProps = { ...props, isInvalid: !!props.errorMessage }
  const state = useCheckboxGroupState(ariaProps)
  const { groupProps, labelProps, descriptionProps, errorMessageProps } =
    useCheckboxGroup(ariaProps, state)
  …
    <CheckboxGroupContext.Provider value={state}>
    <div
      {...groupProps}
      className={cn('rudi-checkbox-group', props.className)}
src/components/Checkbox/CheckboxGroup.test.tsx tsx
render(<Tissues />)
expect(screen.getByRole('checkbox', { name: 'Embryos' })).toBeChecked()
expect(screen.getByRole('checkbox', { name: 'Eggs' })).not.toBeChecked()
await userEvent.click(screen.getByText('Eggs'))
expect(onChange).toHaveBeenLastCalledWith(['embryos', 'eggs'])
expect(screen.getByRole('checkbox', { name: 'Eggs' })).toBeChecked()
The test came with the fix for a group that never passed its value to its checkboxes, a bug the earlier tests missed.

A package that stays out of the app’s way

Why. React Aria’s context breaks when an app ends up with two copies, so the build leaves every dependency for the app to resolve once. One 'use client' line at the top marks every export for the Next.js App Router. And the stylesheet skips Tailwind, whose reset would restyle the host app.

vite.config.ts ts
rollupOptions: {
  // Externalize every bare specifier. All runtime imports are declared in
  // `dependencies`, so consumers resolve their own copies — critical for
  // react-aria-components, whose React context breaks across duplicates.
  // `@/` is our own source alias and must stay bundled.
  external: (id) =>
    !id.startsWith('.') && !id.startsWith('@/') && !path.isAbsolute(id),
  output: {
    // Single ES output, so one directive at the top marks every export as a
    // client component for the Next.js App Router.
    banner: "'use client';",
  },
},
src/styles.css css
/*
 * Deliberately does NOT import Tailwind. Components use plain BEM classes and
 * custom properties only, so pulling in Tailwind would ship a preflight reset
 * that clobbers consumer styles for no benefit. …
 */

An API reference generated from the source

Every build turns the JSDoc on each component and prop into three files in the package, and the MCP server answers from them.

Why generated. Docs written separately for agents would drift. Generated from the source, the reference always matches the installed version, and a unit test fails when an export or prop is undocumented.

scripts/component-docs.mjs js
const api = buildManifest()
fs.mkdirSync(outDir, { recursive: true })
fs.writeFileSync(path.join(outDir, 'components.json'), JSON.stringify(api, null, 2) + '\n')
fs.writeFileSync(path.join(outDir, 'llms.txt'), renderMarkdown(api, { full: false }))
fs.writeFileSync(path.join(outDir, 'llms-full.txt'), renderMarkdown(api))
dist/llms-full.txt (generated) md
### RudiCheckboxGroup

A labelled set of `RudiCheckbox` options whose selection is a string array. `label` is required. Each child
checkbox must have a `value`.
…
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` *(required)* | `string` |  | Group legend and accessible name. Required. |
| `children` *(required)* | `React.ReactNode` |  | The `RudiCheckbox` elements. Each needs a `value`. |
| `description` | `string` |  | Help text under the group. Hidden while `errorMessage` is shown. |
…
Terminal bash
npm install rudiment-ui
claude mcp add rudiment-ui -- npx --no rudiment-ui-mcp
Setup for Claude Code. The README covers Cursor, VS Code, Codex, and Claude Desktop.

Internal parts out of the public API

To style a menu item, the demo pages imported parts from React Aria and passed the menu’s internal class names.

Why. Once app code depends on an internal class name, that name can’t change without breaking apps. A menu item now takes an icon and a label, and the separator is a component of its own.

Before

src/components/Menu/Menu.stories.tsx (before) tsx
import { Separator, SubmenuTrigger, Text } from 'react-aria-components'
…
<RudiMenuItem id="rename" textValue="Rename">
  <RudiIcon icon="lucide:pencil" className="rudi-menu__item-icon" />
  <Text slot="label">Rename</Text>
</RudiMenuItem>
…
<Separator className="rudi-menu__separator" />

After

src/components/Menu/Menu.stories.tsx (after) tsx
import { RudiMenuSeparator } from './MenuSeparator'
…
<RudiMenuItem id="rename" icon="lucide:pencil" label="Rename" />
…
<RudiMenuSeparator />

A bug only a real screen found

In a table, a text field lost its arrow keys: the grid took them to move between cells. Now the grid hands the keys to a focused text field, and Tab still leaves.

Why it mattered. The bug passed every unit, axe, and story test. Only typing into a form inside a table showed it, which is why the library was tested by building an app with it.

src/components/Table/TableCell.tsx tsx
// While a text field in this cell has focus, switch the grid into React Aria's
// edit mode (the one column resizing uses): arrow keys, Home/End and type-to-select
// stay with the field instead of moving focus between cells and rows. Tab still leaves.
const setEditing = (e: FocusEvent, editing: boolean) => {
  if (isTextEntry(e.target)) state?.setKeyboardNavigationDisabled(editing)
}
return (
  <div
    className="rudi-table__cell-content"
    data-align={resolved ?? 'start'}
    onFocus={(e) => setEditing(e, true)}
    onBlur={(e) => setEditing(e, false)}
  >

A screen built from library components

This card from the demo app is two library components, with no app styles.

Shipment summary card tsx
<RudiStatCard
  label="Probe temperature"
  value={formatTemperature(summary.latest)}
  delta={`${summary.excursions} readings above ${formatTemperature(setPoint)}`}
  trend={summary.excursions ? 'down' : 'up'}
>
  <RudiSparkline
    label={`Probe temperature trace, alert threshold ${formatTemperature(setPoint)}`}
    data={trace}
    threshold={setPoint}
    tone={summary.excursions ? 'error' : 'brand'}
    showEndpoint
  />
</RudiStatCard>
The probe temperature card is two library components. The threshold draws the dashed alert line, and the tone turns to error once readings cross it.

Results

Measured against my own builds and review, not outside teams.

476 → 0

inline styles needed to build a screen

26 demo pages before, Vitrea’s 14 screens after

905

library components in Vitrea’s screens

of 72 kinds; the only raw markup is the logo

For engineers like Kenji

  • A data table, forms, date pickers, toasts, and app chrome
  • No third-party imports or internal class names to make a component work
  • The full API in files and a server coding agents can read

For people like Ruth using the apps

  • Text fields in tables keep their keys
  • Kanban moves announced once
  • Field borders that meet WCAG 3:1
  • Screens that hold at 375px

For designers like Sofia

  • A whole brand in one stylesheet of token overrides
  • Eight themes with no theme code in any component
  • One control height across every field and button

Limitations

  • No outside team yet

    I wrote the library and Vitrea, so the gaps found are the ones I ran into. The README still calls it beta. The next test is a team other than me building a real screen with it.

  • Section themes stop at overlays

    A theme set on one section doesn’t reach dialogs and menus drawn at the page root, so Vitrea sets its theme on the whole page. Brand overrides also have to be repeated for each theme.

  • Checked by tools, not by screen reader users

    Axe runs in the library’s tests, and Vitrea passed axe on 13 pages in light and dark. No one who relies on a screen reader has used it, and Vitrea’s own tests don’t run axe yet.

  • One large bundle

    Vitrea’s build was a single 1.16 MB chunk, 336 KB gzipped. Per-component entry points would let an app load only the parts it uses.

More screens

More screens from Vitrea, the demo app built only from Rudiment UI components.

See all 4 in the gallery