Calm software, built to last.
Most systems drift. Every new screen reinvents its own buttons, spacing, and color until the product feels like a patchwork. Agents make that worse: they reach for hex values and one-off divs because nothing stops them. This system is the opposite, a single quiet, content-first aesthetic you can adopt in minutes, re-skin from one variable, and keep on-system by construction.
The problem
Design systems fail quietly.
shadcn solved ownership: copy the code, it is yours, not a dependency you cannot inspect. But ownership alone does not stop drift. A team adds a green button here, a shadow there, a zinc palette on the next feature. Six months later the Figma file and the codebase disagree, and nobody can say when it happened.
Now add an agent to the loop. It does not remember your last code review. It does not feel the inconsistency. It will happily write text-[#333] because it worked in the last project. byronwade/ui treats that as a solvable engineering problem: one aesthetic, one token base, one definition of on-system, enforced everywhere code gets written.
How we build
Design engineer principles.
Adapted from Vercel's Design Engineer Principles, tailored for a registry where agents write most of the UI. Visual tenets describe what the system looks like; these describe how we work — encoding lessons into components, tokens, lint, and the shipped AI rule so the next screen and the next agent start from better defaults.
Bias toward usefulness
- Fix problems users and teammates actually hit.
- Make the useful path obvious and frictionless.
Own outcomes end-to-end
- Span product, interface, and implementation.
- Ship docs, examples, and tests when the outcome needs them.
- Sweat every state, word, edge case, and interaction.
Find the binding constraint
- Read user needs, product goals, codebase, and business limits together.
- Know what actually binds before you commit to an approach.
Design for the full audience
- Skill levels, abilities, devices, and contexts.
- Offer depth without forcing it — defaults work, power is reachable.
Ship craft, not volume
- Scope small enough to finish with care.
- Challenge work when clarity, craft, performance, or trust slips.
- Leave surfaces cleaner than you found them.
Raise the team's floor
- Kind, direct, low ego — share early with specific feedback.
- Encode lessons as registry patterns, lint, examples, and the shipped rule.
Ten convictions
What the system believes.
Warm, never stark
A warm paper canvas and warm near-black ink, never pure white, never pure black. Clinical neutrals keep you at arm's length; a little warmth invites you to stay and read. The hue is structural, baked into the foundation tokens, not a skin you swap later.
One accent
Every emphatic thing, rings, charts, success, active states, derives from a single brand token. One voltage, used sparingly, reads as confidence; a rainbow reads as noise. Override --brand once and the whole accent family follows, in light and dark.
Tokens, never raw color
Nothing is hardcoded. Every surface, text color, and state resolves through a semantic token, so dark mode and a full re-skin come for free. Change one variable, not a hundred call sites. If a value cannot be expressed as a token, it probably does not belong in the system.
Depth is a hairline
No drop shadows. A single inset edge gives a surface just enough presence to sit into its background. Flatness, executed with care, reads as quality. Borders are for separators between regions, not for boxing every card.
Restraint in type
Hierarchy comes from size, tracking, and the typeface, not heavy weights or color. Three families, each with one job: sans for interface, mono for data, serif for reading. Display and section headings stay font-normal or font-medium. Bold is reserved for genuinely urgent emphasis inside body copy.
Compose, don't reinvent
Primitives become composites become whole pages. A status pill is a status dot plus a chip. A page header is typography plus optional actions. Consistency is not enforced by a linter alone; it is the natural byproduct of always reaching for what already exists.
Every page earns a hero
No generic, repeated card grids. Each surface gets one signature moment that belongs only to it: the catalog index, the token swatch wall, the type specimen, the skin gallery. Documentation should feel designed, not templated.
Yours to own
Installed via the shadcn registry, the code is copied into your repo. No runtime dependency, no lock-in, no version skew between your app and a package you cannot see inside. Fork a component, rename a token, ship it. The system is source, not a black box.
Dark mode for free
Because every color is a token, dark mode is not a second stylesheet you maintain in parallel. Flip the variable values under .dark and the entire product re-renders correctly. Accessibility states, focus rings, and status colors all inherit the same logic.
light
Warm paper
dark
Warm ink
On-system, provably
The next era of UI is written with agents, and agents drift the moment they reach for bg-[#f7f7f4] instead of your token. This system ships the rule, the lint, and the MCP server from one source of truth, so on-system is a definition you can enforce in CI, not a hope.
What we turn away from
Taste is a constraint.
Philosophy is as much about refusal as preference. These patterns are not banned because they are ugly; they are banned because they break the guarantees the system makes about warmth, re-skinning, and agent-reviewable output.
Cold zinc neutrals
They signal developer-tool, not product. Warmth is structural here.
Shadow stacks
Depth comes from the edge hairline. Shadows age fast and fight dark mode.
font-bold heroes
Editorial hierarchy uses size and tracking. Bold headings read as shouting.
Rainbow accents
One brand variable. Charts and status have fixed semantic roles.
Bespoke one-offs
If it looks like UI, it should compose from an existing primitive.
Raw hex in components
Hardcoded color breaks re-skinning and makes agent output unreviewable.
“Good design gets out of the way. The system stays quiet so your product can be the loudest thing in the room.”
Agent-native
Built for the way code gets written now.
A design system that only exists in Figma is already obsolete. This one ships the AI rule, the enforcement, and the live registry access as first-class artifacts, all generated from the same registry.json, so the agent is never told to install a component that does not exist.
Design rules
An installable rule file teaches your agent the component catalog, token vocabulary, and editorial constraints before it writes a line.
Read moreOn-system lint
The same definition of on-system runs in ESLint and CI. Raw colors, off-token spacing, and hand-rolled shadows fail the build.
Read moreMCP server
Agents query the live registry, fetch source, and self-check generations before they land in your repo.
Read moreLiving chrome
Navigation that blooms, not teleports.
Most design systems treat navigation as static chrome: a sidebar, a top bar, done. Here, floating docks and toolbars morph in place, growing from a compact pill into a full panel on a tuned curve, then shrinking cleanly back. It is not decoration; it is a primitive (use-chrome-morph, morph-dock) you compose like any other component.
Motion respects reduced-motion preferences. Esc and click-away close panels. The dock reads from pure --dock tokens so it re-skins with everything else.
morph-dock · collapsed → open
In practice
The same instinct, every time.
When in doubt, reach for the token or the primitive. The lint catches what habit misses.
bg-brand text-brand-foregroundbg-[#22c55e] text-whitefont-medium tracking-tight text-4xlfont-bold text-green-600rounded-xl edge bg-cardrounded-lg edge<Button variant="outline"><button className="px-4 py-2 border…">shadcn lineage, byronwade convictions.
The install model is the same: a namespaced registry, the shadcn CLI, code copied into your project. What changes is everything around it: warm editorial aesthetics, a single accent variable, morphing chrome primitives, and an agent toolchain that keeps output reviewable. You get the ownership model everyone already trusts, plus a system that still looks like yours six months from now.
Start to finish