Rudiment UI
Open-source project · Design systemsAn 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.
- 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.
inline styles across 26 demo pages
and 0 class overrides, so the components needed more props
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 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
-
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. -
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. -
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. -
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. -
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.
-
LightVitrea’s own light theme: spruce green, pill buttons, and a display face for titles.
-
CompactCompact 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, andsearch, 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
@defaultthat 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
RudiTablewith sorting, linked rows, and an empty state drawn inside the table, so the column headers stay in place. -
Forms
RudiFormwith 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.
Before Vitrea: an old CRM demo page above its source, wrapped in a CrmShell and PageHeader written by hand for this one product.
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
[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
"border": {
"default": { "$value": "{color.neutral.200}" },
"control": { "$value": "{color.neutral.500}" },
… "checkbox": {
"control-size": { "$value": "1rem" },
"control-border": { "$value": "{color.border.control}" },
… 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.
"button": {
…
"height-md": { "$value": "{component.input.height}" },
…
"input": {
…
"height": { "$value": "2.375rem" }, /* 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.
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)} 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() 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.
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';",
},
}, /*
* 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.
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)) ### 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. |
… npm install rudiment-ui
claude mcp add rudiment-ui -- npx --no rudiment-ui-mcp 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
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
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.
// 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.
<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> Results
Measured against my own builds and review, not outside teams.
inline styles needed to build a screen
26 demo pages before, Vitrea’s 14 screens after
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