from scratch, from first principles —
An open-source React component library paired with a 13-chapter guide that explains why each architectural decision is made, and what happens later if you make a different one.
Rudiment UI is a personal reference project, not a client deliverable — and that's the point. It exists because most of the component libraries I've been brought in to fix share the same root cause: architectural decisions that nobody wrote down, made in the wrong order, and now cost a quarter to untangle. Rudiment UI is the library I wish every team had started with, built deliberately, chapter by chapter, with the reasoning left in.
Step one
Component libraries rarely fail loudly. They accumulate a thousand small compromises until the thing that once felt like a system feels like a patchwork. A missing semantic token layer turns a rebrand into hundreds of manual renames. An undecided styling strategy turns a refactor into a full rewrite. Accessibility bolted on after launch always costs more than accessibility designed in from day one.
Most of these mistakes aren't expensive because they were hard to avoid. They're expensive because they were made implicitly: in a stand-up, in a PR comment, in a hurried corner of someone's sprint. Rudiment UI starts from the opposite assumption: the structural decisions come first, with no code, and every choice gets written down alongside its consequences.
That's what the guide is. Chapter 1 contains no code at all. It's the conversation a team should have had before picking a CSS strategy.
Tokens get added per-component. Styles leak into overrides. Documentation falls behind. The system stops being a system.
Token architecture shapes components. Components shape tests. Tests shape what the docs have to explain. Get the order right and the rest stops fighting you.
Step two
Most token systems collapse because they try to do two jobs in one layer: hold raw values and express design intent. Rudiment separates those jobs across three tiers, each referencing the one beneath it. A brand change touches one file. A component tweak doesn't cascade into the rest of the library.
Unopinionated primitives. No meaning, just values.
color.blue.500 = #3B82F6 Aliases that encode intent. A rebrand touches this layer, not every component.
color.brand.primary → color.blue.500 Narrow enough to tune one component without side effects elsewhere.
button.background.default → color.brand.primary Building a component library is as much an exercise in sequencing decisions as it is in writing components.
Token files use the Design Tokens Community Group format, flow
through Style Dictionary v4, and land in Tailwind CSS 4 via
@theme inline. Updating a single value propagates through every dependent
component — no hunt-and-replace, no orphans.
Step three
A single interactive component can carry an enormous accessibility
surface. A modal alone needs focus trapping, scroll locking,
escape-key handling, focus restoration, and
aria-modal
management. Rudiment doesn't rebuild that for every component. It
leans on React Aria, maintained by Adobe's design system team, to
carry the behavior layer.
React Aria owns keyboard navigation, focus management, ARIA semantics, pointer normalization, and i18n. Tailwind CSS 4 handles the visuals. The two layers stay cleanly separated — which is what lets the library re-skin without touching any behavior.
Tests then lock in that separation. Layout primitives are verified against the tokens and classes they emit. UI components are verified against their accessibility contract: keyboard activation, disabled and error states, focus behavior, loading-state ARIA, and zero axe-core violations. Tests query by role and text, never by class name, so refactors don't silently break coverage.
Step four
The guide is sequenced deliberately. You can't make sensible component decisions until the token layer is settled. You can't write useful tests until the component API is stable. You can't publish confidently until the build workflow guarantees every tier stays in sync. Each chapter earns the next one.
Every decision is explained alongside the alternatives it closes off — so you can extend the system instead of copying it.
An end-to-end library you can run, read, and pull pieces from — tokens, primitives, tests, publishing pipeline.
The expensive mistakes — shallow tokens, retrofitted a11y, drifting docs — get made visible before they compound.
A repository without explanation gives you a working system. Explaining the trade-offs at each step gives you the judgment to extend it.
Step five
Rudiment ships as two deployed sites, and you can open both right now. The guide walks through the architectural decisions and trade-offs, chapter by chapter. The Storybook is the working library those decisions produced — every primitive, every component, every variant, in your browser.
rudiment-guide.netlify.app
A sequenced, decision-by-decision walkthrough — from an empty directory to a published, token-driven, accessible React library. Every choice is shown alongside the alternatives it closed off.
rudiment-ui.netlify.app
The deployed component library as an interactive reference — layout primitives, form controls, overlays, and every variant the guide produces, with controls and docs on each story.
Read a chapter, then open the matching story — the guide and the library are meant to be used side by side.
Score your current system in 10 minutes, or grab 30 on my calendar to talk through where things are drifting.