Forem: 7onic

Design to Code #4: Why I Chose Radix Over Custom Primitives

7onic — Fri, 24 Apr 2026 13:34:50 +0000

I spent an entire afternoon trying to write a focus trap from scratch.

The requirement seemed dead simple: when a modal is open, the Tab key should cycle through elements inside it—and nowhere else. When the modal closes, focus should snap back to whatever triggered it. I'd seen this in production apps a thousand times. How hard could it be? I sat down, cracked my knuckles, and started coding.

The first version worked... until I tested it with a portal. Since the modal was rendering outside the main DOM tree, my trap simply missed it. Fixed that. Then, Tab landed on a contenteditable element inside the modal, which my focusable query hadn't accounted for. Fixed that. Then I realized I'd completely ignored Shift+Tab. Fixed it. Finally, I fired up Safari with VoiceOver, and the screen reader didn't even acknowledge the thing was a modal—the ARIA was a mess.

At that point, I stopped fixing things and started asking myself if I was even the right person to be fixing them.

I deleted the file and looked up Radix UI.

The accessibility argument is real, but...

Saying "Radix handles accessibility" is technically true, but it's also the kind of thing people say when they want to end a conversation.

The real story is more nuanced. Focus management in overlays isn't the kind of "hard" where you find the right answer once and you're done. It's the kind where combinations of browsers, assistive technologies, and OS versions behave in wildly inconsistent ways. The only way to find what's broken is to test it—systematically, on actual devices, with actual screen readers.

The Radix team has been shipping this since 2020. Their Dialog handles focus locks in portals. Select and RadioGroup implement roving tabindex so arrow keys work exactly how screen reader users expect. Toast doesn't scream duplicate announcements into the ARIA live region. These behaviors didn't appear by magic; they're the result of years of iteration and real-world bug reports.

I'm one person building a system with 42 components. Spending my hours on focus management in overlays is a poor use of time. It wasn't about checking a "Radix handles A11y" box—it was realizing that a dedicated team had already solved a class of problem I wasn't equipped to handle as well as they were.

The other reason: truly zero styles

What people often understate is that Radix ships with genuinely zero CSS. Not "easy to override" or "CSS-variable-based." Just... nothing. You bring the design tokens; Radix brings the interaction semantics.

This is a massive win when you're building on a token system. 7onic generates CSS custom properties, Tailwind v3 presets, Tailwind v4 @theme blocks, and TypeScript types from a single figma-tokens.json. The last thing that pipeline needs is a component library with hardcoded opinions about what "primary" looks like or what a dropdown's border radius should be.

Radix doesn't have those opinions. It's a skeleton I put skin on. Because there's no overlap between the token system and the component library, they can't contradict each other.

Radix is not perfect

There was one specific behavior that took me way too long to figure out.

When you select an option in a Select or close a DropdownMenu with a mouse click, Radix calls .focus() on the trigger element as it closes. This is correct for keyboard users—after navigating a menu with arrow keys and hitting Enter, focus should return to the trigger so they can keep tabbing through the page.

The catch? If you used arrow keys at any point inside the dropdown before clicking with your mouse, the browser remembers that as "keyboard modality." So when Radix calls .focus() programmatically, the browser applies :focus-visible to the trigger. Result: you click with a mouse, the menu closes, and the trigger suddenly gets a focus ring for no reason.

It looks like a visual glitch. I spent ages thinking it was a CSS bug in my token output. It wasn't.

The fix is calling e.preventDefault() in the onCloseAutoFocus handler:

onCloseAutoFocus={(e) => {
  e.preventDefault()
  onCloseAutoFocus?.(e)
}}

The tradeoff is that after a keyboard-close, focus no longer returns to the trigger—Tab will land on whatever comes next in the DOM. For most use cases, this is fine. For specific keyboard workflows, it might not be. I documented the decision, shipped it, and moved on.

That's what using Radix actually feels like: you delegate the hard problems, only to discover that "delegated" doesn't mean "invisible." The quirks are real, but they're localized and workable—which is a much better place to be than owning the entire problem yourself.

The path not taken

I looked at Headless UI. Similar philosophy, but at the time, their API leaned more toward render props and transitions. For a system where I'm defining the component APIs anyway, Radix's compositional model (Select.Content, Select.Item) was much easier to keep consistent across 42 components.

React Aria from Adobe was also on the table. It's more comprehensive but also significantly more complex. Their hook-based API offers more granular control, but requires a lot more wiring per component. For a design system where I need a solid baseline but aren't shipping a low-level primitive library, it was more control than I actually needed.

Building from scratch? That was off the table after my afternoon with the focus trap. Some problems are solved well enough that trying to re-solve them is just stubbornness.

Where things stand

All the interactive components in 7onic—Dialog, Select, Tabs, Accordion, and the rest—use Radix under the hood. The presentational ones like Skeleton or Spinner don't touch it because there's nothing to delegate.

The decision has held up. I've shipped components I wouldn't have trusted myself to build alone, and the accessibility baseline is higher than anything I could have achieved on my own. Some of that is Radix; some of it is that committing to Radix early forced me to think about keyboard behavior and ARIA patterns before I otherwise would have.

I still don't have a professional screen reader testing setup. I do basic VoiceOver checks, but "doesn't sound broken to me" isn't a substitute for "correct." It's on the list. It keeps getting pushed down the list.

That's probably the most honest thing I can say about accessibility in a solo-built design system: the foundation is better than it would be without Radix, but it's still not as thorough as it should be. Both things are true.

Next: 42 components, and every interactive one has at least five size variants. The smallest is 28px. Here's why it's not 24px, and what WCAG 2.5.8 actually says about touch targets.

About 7onic — An open-source React design system where design and code never drift. Free, MIT licensed. Docs and interactive playground at 7onic.design. Source code on GitHub — stars appreciated. More posts in this series at blog.7onic.design. Follow updates on X at @7onicHQ.

Design to Code #3: Copy-Paste vs npm Install

7onic — Fri, 24 Apr 2026 11:33:09 +0000

The first thing I did after publishing @7onic-ui/react@0.1.0 was install it in a test project.

It worked. Imports resolved, buttons rendered, and Tailwind classes applied perfectly. I sat there for a moment feeling good about this. Then I wanted to double-check the focus ring behavior, so I went to inspect the source.

What I found was node_modules/@7onic-ui/react/dist/index.mjs—a bundled, transformed mess with variable names half-mangled by the build step. I could see the output, but I couldn't truly read it. For most packages, that's the whole point. But for a design system, it felt wrong. The entire premise of this project was transparency, yet my code was hidden behind a build artifact.

What I shipped vs. what I should have shipped

The npm package made sense at the time. If you want a Button, you npm install @7onic-ui/react, import { Button }, and you're done. It's the standard approach, it genuinely works, and it's still live for those who prefer it.

But the problem wasn't a bug; it was the abstraction model.

A utility library like lodash benefits from being a black box. You don't care how _.debounce is implemented as long as it debounces. You import it, use it, and update it. Component libraries are different. When a button doesn't look quite right in your layout, you need to see the source. When you need a prop that doesn't exist, you need to modify it. When your TypeScript config is stricter than mine, a compiled .js file won't help you debug why your build is failing.

A design system is something you should own. The traditional package model says "I maintain this, you consume it." That's the wrong relationship.

Five days later

@7onic-ui/react@0.1.0 went live on April 4th. By April 9th, I was already building a CLI.

The idea was simple: instead of importing from a compiled package, you run npx 7onic add button and the actual .tsx source code is copied directly into your project. It lands in src/components/ui/button.tsx—readable, and entirely yours. No node_modules involved. The exact file living in the 7onic repo is what ends up in your codebase.

I wasn't inventing this—shadcn/ui had been doing it for a while. But I hadn't fully appreciated why until I spent a few days trying to be a consumer of my own npm package.

The registry approach works like this: the CLI bundles all 40 component source files (~456KB) and when you run add, it writes them directly to your disk. No transformation, no obfuscation. You can open it, change it, or even break it.

npx 7onic add button input select

It also handles dependencies automatically. add input realizes it needs a field wrapper and pulls that in too. add button-group knows to fetch button if it's missing. Building the topological sort for this was a rabbit hole in itself. (Writing tests for dependency resolution is as boring as it sounds.)

What this actually enables

The obvious benefit is customization. You can modify button.tsx directly—add a custom variant or tweak a default class—without forking a repo or waiting for a PR to merge.

But there was a less obvious win regarding TypeScript.

Vite's default template sets noUnusedLocals: true in tsconfig.app.json. In my initial card.tsx, I had a sizePaddingMap object intended for future use but not yet wired up. In my own dev environment, eslint-disable handled it fine. But in a user's Vite project, tsc would simply fail the build.

In a compiled npm package, that's a "wait for a fix" situation — I'd need to publish, users would need to update. With source files, the user can see the issue and fix it instantly. And once I pushed the official fix—deleting the unused object—the registry updated so the next npx 7onic add gets the clean version. The friction of a version dependency became just a file in your project.

There's also an AI angle I hadn't anticipated. When source code is buried in node_modules, tools like Claude or Copilot can't easily see it without explicit context. When it lives in src/components/ui/, it's part of your codebase. "Modify the Button component" becomes a direct, actionable instruction instead of something that requires explaining what's in the package first.

The trade-off

Nothing is free.

When I update button.tsx with a bug fix or a new variant, users who copied the file don't get it automatically. They have to run npx 7onic add button --overwrite, which many won't do. The code copied in April is the code they'll likely be running in October.

With an npm package, npm update @7onic-ui/react handles that.

It's a trade-off between convenience and ownership. If you want to stay in sync with upstream, use the package. If you want to own your UI and treat it as a snapshot in time, the CLI is the way to go.

I don't think one is always right. But the copy-paste model better matches how developers actually treat design systems. Nobody updates their component library every week. The files get copied, maybe tweaked, and then just sit there doing their job. At least with the source approach, what's sitting in your folder is human-readable.

The package still exists

I still publish @7onic-ui/react with every release. My GitHub Actions workflow publishes the npm package and regenerates the CLI registry simultaneously.

There are teams with strict policies about what lives in src/, or monorepos that prefer package boundaries. For them, import { Button } from '@7onic-ui/react' is still the right call.

I just don't think it's the default anymore.

The CLI launched five days after the first npm release. That wasn't a planned timeline — it was a reaction. I wrote the install instructions for the package, tried to follow them myself, and spent the rest of the week building an alternative. Sometimes the fastest way to realize what's wrong with what you've built is to use it as if you didn't build it.

Next: 42 components in, there are patterns I'd never go back on — and at least three I'd design completely differently.

Tailwind Guides #1: Supporting Tailwind v3 and v4 Was Brutal

7onic — Fri, 17 Apr 2026 11:02:03 +0000

I was halfway through shipping a component update when v4 dropped. My design system, 7onic, has to work with both Tailwind v3 and v4 — same components, same token source, two different output formats. So my reaction to the v4 announcement was less "exciting new features" and more "great, another output target to maintain."

I read the migration guide. It covered the syntax changes fine. What it didn't cover was that three of those changes would silently break things in ways that produced zero error messages and took hours to track down.

The Config File Moved Into CSS

You've probably heard this one. tailwind.config.js becomes CSS. In v3, I had this big JavaScript preset mapping tokens to Tailwind's config:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: 'rgb(var(--color-primary-rgb) / <alpha-value>)',
          hover: 'rgb(var(--color-primary-hover-rgb) / <alpha-value>)',
        },
      },
      borderRadius: {
        sm: 'var(--radius-sm)',
        lg: 'var(--radius-lg)',
      },
    },
  },
}

In v4:

@theme {
  --color-primary: #15A0AC;
  --color-primary-hover: #107A84;
  --radius-sm: 2px;
  --radius-lg: 8px;
}

The nice part is bg-primary/50 just works now — v4 uses color-mix() internally, so you don't need the rgb() channel hack anymore. But what I actually appreciate more is the debugging. When a utility doesn't work in v3, I have to trace through JavaScript config merging logic. In v4, I open a CSS file and read it. Sounds small. It's not.

@theme inline Killed My Dark Mode

OK so this is the one I'm still kind of mad about.

I used @theme inline because the docs said it avoids variable name collisions. Sounded reasonable. Everything worked in light mode. I toggled dark mode and the page just... stayed light.

I checked everything. .dark class on html — yes. CSS variables updating in DevTools — yes. Dark stylesheet loaded — yes. I even slapped a background: red !important rule inside my dark block just to prove the file was being read. It was. Variables were changing. But the actual page colors didn't move.

I wish I could say I figured it out quickly. I didn't. I spent an entire afternoon going in circles before I finally opened the compiled CSS and saw this:

/* What I assumed Tailwind was generating */
.bg-primary { background-color: var(--color-primary); }

/* What @theme inline ACTUALLY generated */
.bg-primary { background-color: #15A0AC; }

@theme inline resolves everything at build time. It takes your CSS variables and replaces them with literal hex values in the output. So at runtime, your dark mode variables update correctly — but the utility classes aren't looking at variables anymore. They have hardcoded light-mode colors baked in.

The fix was just removing the word inline. Build size went up by 8.5KB (0.8KB gzipped). I cannot stress enough how little I care about that tradeoff.

What bugs me is the naming. "inline" sounds like a performance optimization or a scoping strategy. It doesn't sound like "we will throw away all your CSS variables and hardcode the resolved values." If the flag were called @theme static or @theme resolved, I would have caught this in five minutes instead of five hours. But it is what it is.

Plugins Became @utility

Not much to say here honestly. v3 plugins become @utility blocks in CSS. I generate about 50 custom utilities (icon sizes, durations, z-index layers, focus rings) and the migration was completely mechanical. The v4 version is easier to read. Moving on.

@source Failed Without Telling Me

The content array is now @source in CSS:

@source "../src/**/*.{ts,tsx}";

I wrote the path relative to the project root because that's what content used. Tailwind generated an empty stylesheet. No error, no warning, nothing in the terminal. I spent twenty minutes convinced my PostCSS setup was broken before I realized: @source paths are relative to the CSS file, not the project root.

This is the kind of bug where you feel stupid once you figure it out, but also — a warning would be nice? "Hey, that glob matched zero files" would save a lot of people a lot of time.

Variant Stacking Order Reversed

This one's painful if you support both versions.

v3 stacks variant selectors right-to-left. v4 stacks left-to-right. Same words, different order, different result:

// v3 — innermost first
className="[&_div]:data-[state=checked]:bg-primary"

// v4 — outermost first
className="data-[state=checked]:[&_div]:bg-primary"

I found this in the Switch component. The toggle track styled correctly in v3, silently didn't apply in v4. No error — the generated CSS was valid, it just didn't match the DOM.

I don't have a great answer for this. My component code avoids complex variant stacking and the docs show v3/v4 examples side by side. It works, but it's not elegant.

Dark Mode: Three Selectors for One Job

v3 dark mode was darkMode: 'class' and you're done. v4 defaults to prefers-color-scheme, which follows the OS. That's a better default until your user wants to force light mode while their OS is set to dark — because you can't override a media query from JavaScript.

I ended up with this:

/* Follow OS, unless user explicitly chose light */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-background: var(--color-gray-900);
    --color-text: var(--color-gray-100);
  }
}

/* Manual override */
:root[data-theme="dark"],
:root.dark {
  --color-background: var(--color-gray-900);
  --color-text: var(--color-gray-100);
}

The :not([data-theme="light"]) is what makes "force light" possible. The .dark class is v3 compat. Three selectors for the same variable declarations feels wrong, but each one handles a scenario the others can't, and I couldn't find a way to collapse them.

The Outline Flash

Oh, this one. Tailwind v4 added outline-color to transition-colors. Inputs with focus rings now animate the outline appearing, which looks like a brief flash. I didn't notice for weeks — only caught it during unrelated side-by-side v3/v4 testing.

Fix: outline-transparent on the base state. One class. Applied it to Input, Textarea, and Select. The kind of thing nobody would file a bug about — you'd just feel like something was slightly off.

Opacity Modifiers Got Good

In v3, bg-primary/50 with CSS variables required decomposing every color into RGB channels. I generated 135 extra --*-rgb variables for this. Every new color token meant two more CSS variables. It worked, but it was a hack that I maintained grudgingly.

v4 uses color-mix():

background-color: color-mix(in srgb, var(--color-primary) 50%, transparent);

That's it. Any color format. No channel decomposition. I still generate the -rgb variables for v3 users, but the day I drop v3 support, an entire pipeline stage disappears.

Honestly this might be my favorite v4 change, even though it's the least dramatic. Removing a hack you've been carrying around for months feels disproportionately good.

If you're about to migrate: check dark mode first. Not "does it toggle" — check that every color you expect to change actually changes. That's where @theme inline hides, that's where the media query vs class assumption lives, and that's where I wasted the most time.

The rest is mostly find-and-replace. Dark mode is where your v3 instincts will lie to you.

Next: I mentioned the rgb() channel hack for v3 opacity modifiers. That hack is part of a bigger story — how CSS variables and Tailwind actually interact, and why most guides get the setup wrong.

Solo Builder #1: What Nobody Tells You

7onic — Fri, 17 Apr 2026 04:43:31 +0000

Before I started building 7onic, I googled one very specific phrase:

solo design system

I expected at least a few useful battle stories.

Instead, I found conference talks from teams of twenty, blog posts about "scaling component libraries," and articles that casually assumed I had designers, engineers, PMs, reviewers, and someone named Alex who owned tokens.

I had none of those people.

It was just me.

So I learned what building a design system alone actually looks like the hard way.

Here's what I wish I'd known.

You will make every decision, every day

On a team, decisions get distributed.

Someone owns tokens.
Someone owns components.
Someone owns docs.
Someone owns accessibility.
Someone joins the meeting late and disagrees with everything.

That structure can be slow, but it spreads the mental load.

When you're solo, every open question lands on your desk.

Should the border radius be 6px or 8px?
Do we support RTL now or later?
What happens when someone passes both variant and className?
Should defaults be strict or forgiving?

None of these questions are difficult on their own.

But answer fifty of them in a day — while writing code, docs, release notes, CLI tooling, and fixing one mysterious TypeScript issue — and it becomes draining in a way I didn't expect.

For the first month, I kept a decision log.

Then I stopped.

Because logging every decision introduced a new decision:

Is this decision worth logging?

What finally helped was a simpler rule:

Decide once. Document briefly. Move on.

Not every choice deserves a framework.
Most choices deserve ten seconds and a code comment.

Nobody will catch your mistakes

This hit me around the third component.

I had built a Button with five size variants:

xs, sm, md, default, lg

Beautiful API. Typed props. Looked clean.

Two weeks later I realized md and default were visually identical.

Both were 36px.

I had duplicated a token value by accident.

Which meant I had:

written the bug
reviewed the bug
approved the bug
shipped the bug

All personally.

There's no pull request where a teammate says:

Wait... why do two sizes look exactly the same?

That moment taught me something important:

When you build solo, your QA process is just future-you.

And future-you is inconsistent.

I've shipped duplicate variants.
Exported components with the wrong display name.
Published a version where dark mode didn't work because I tested in light mode and called it done.

I still don't have a perfect solution.

What helps a little:

visual regression checklists
writing changelog notes before release
opening docs as if I were a new user
forcing one final pass when I'm already tired and want to skip it

None of this is glamorous.

But neither is debugging yourself.

Scope creep has no natural predator

On a product team, eventually someone says:

That's out of scope.

A PM says it.
A tech lead says it.
A deadline says it.

Solo builders often have none of those voices.

Which means every idea feels valid and immediately actionable.

I originally planned to build a CLI that installs components.

Somehow that turned into:

typo suggestions using Dice coefficient similarity
package manager auto-detection from lockfiles
Tailwind v4 auto-injection
JSON schema support for IDE autocomplete

Each feature was reasonable.

Each feature improved the product.

Together, they delayed launch by two months.

That's the trap:

When you're solo, scope creep rarely feels like scope creep.

It feels like craftsmanship.

And sometimes it is.

But sometimes the right feature is shipping.

Now before I add anything, I write one sentence:

What problem does this solve for someone installing 7onic today?

If I have to stretch to answer it, the feature waits.

Momentum gets weird in open source

Shipping internally gives immediate feedback.

Someone uses it tomorrow.
Someone complains by lunch.
Someone asks for a new prop by Friday.

The loop is fast.

Shipping to open source can feel very different.

You release something you spent three weeks building.

The next morning looks exactly the same as yesterday.

No dashboard spike.
No coworker message.
No usage report.

Maybe a few GitHub stars trickle in — and I'm genuinely grateful for every one — but early open source has a kind of silence to it.

You need a different feedback loop.

For me, writing helped.

Not for traffic. There wasn't much.

But because explaining a decision to an imaginary reader forces clarity.

Whenever I couldn't explain why I built something a certain way, that was usually a sign the decision wasn't solid yet.

This blog became part of the product process.

The hidden half of the work

People see components.

They don't see the rest.

Building components might be half the job.

The other half is:

figuring out why TypeScript generated nonsense types
debugging CI that works locally but fails remotely
rewriting docs for the third time because the API changed again
setting up smoke tests
maintaining release notes
answering occasional issues
cleaning scripts no one will ever praise

None of it is dramatic.

All of it consumes time.

And when you're solo, all of that time belongs to you.

Some weeks the components barely move because infrastructure needed attention first.

That used to frustrate me.

Now I see it more clearly:

The product is one system.
The tooling is another.
Both need maintenance.

The upside people explain badly

Everything above is true.

But it's incomplete.

There's a benefit to working alone that's harder to describe:

Coherence.

Not freedom.
Not control.
Not "being your own boss."

Coherence.

The whole system fits in your head.

If I want to change dark mode, I know exactly where to go.
If I add a token, I know the full path from figma-tokens.json to runtime output.
If something feels inconsistent, I usually know why.

No handoff.
No ownership map.
No "let me check with the person who manages that."
No waiting.

Just change it.

Teams optimize for coordination.

Solo builders can optimize for consistency.

Those are different advantages.

And for a design system — where consistency is the product — that matters more than people admit.

I didn't expect to like it this much

Working alone is tiring in all the ways I described.

It can be repetitive, lonely, slow, and mentally noisy.

But it's also deeply satisfying in ways I didn't predict.

There's something special about seeing a system become cleaner because you touched every layer of it.

I still wouldn't romanticize solo building.

But I also wouldn't dismiss it.

Sometimes one person with enough stubbornness can build something surprisingly coherent.

Next: I don't do code reviews in the traditional sense. Here's what I do instead — and what I've learned to catch by forcing myself through it.

Design to Code #2: One JSON, Eleven Outputs

7onic — Fri, 17 Apr 2026 01:55:04 +0000

The entire 7onic design system runs on a single JSON file.

It's 1,847 lines long.

Colors live there as hex values like #6B21A8. Spacing is stored as plain numbers like 16. Border radius uses the same format. Animations are defined as keyframe objects. If you've ever exported tokens from Figma Token Studio, it would look instantly familiar.

Because that's exactly what it is.

The file is called figma-tokens.json, and it's the only place in the codebase where design values are allowed to exist.

Everything else is generated from it.

One command reads that file and spits out 11 distribution files in about 200 milliseconds. Change a color. Run the script. Ship it.

That's the whole pipeline.

Getting there, however, was a lot messier.

Why one file somehow became eleven

At first glance, eleven output files sounds excessive.

Why not just generate one universal token file and call it a day?

Because different environments want completely different things.

A Tailwind v3 project expects a preset. Tailwind v4 wants @theme. A developer writing vanilla CSS doesn't care about either of those — they just want CSS variables. Someone building outside React may only need TypeScript types. Another team may want raw JSON for internal tooling.

Same source. Different consumers.

So the pipeline produces:

css/variables.css — primitive CSS variables
css/themes/light.css — semantic light theme
css/themes/dark.css — semantic dark theme
css/all.css — bundled CSS
tailwind/v3-preset.js
tailwind/v4-theme.css
tailwind/v4.css
js/index.js — CommonJS
js/index.mjs — ESM
types/index.d.ts — TypeScript declarations
json/tokens.json — processed token output

Most of these were straightforward.

A few of them absolutely were not.

The day `bg-primary/50` broke everything

The first version of the pipeline was beautifully naive.

Read JSON. Loop tokens. Generate CSS variables. Generate Tailwind config. Done.

Then I tried:

<div class="bg-primary/50">

And nothing happened.

Turns out Tailwind's opacity modifiers need access to the actual color channels so they can inject alpha values. That works fine with hex colors.

It does not work with this:

var(--color-primary)

To Tailwind, a CSS variable is just a string. It can't crack it open, inspect the hex, and rebuild it with opacity.

So I had to generate a second version of every color token:

--color-primary: #6B21A8;
--color-primary-rgb: 107, 33, 168;

Now Tailwind v3 can do this:

rgb(var(--color-primary-rgb) / <alpha-value>)

Which means these finally work:

bg-primary/50
border-border/40
text-foreground/80

So yes, every color now ships twice: once as hex, once as RGB channels.

Elegant? Debatable. Effective? Absolutely.

Tailwind v4 made this easier later thanks to native color-mix(), but v3 made me earn it first.

Dark mode: where simple ideas go to die

Dark mode starts innocently.

Put light values on :root. Put dark values on .dark. Toggle a class on <html>.

Classic. Reliable. Works great in Tailwind v3.

Then Tailwind v4 arrived with a different philosophy: use system preferences.

@media (prefers-color-scheme: dark)

Also reasonable.

Until a real user wants this:

"My OS is dark, but I want your site in light mode."

That's where things get awkward.

If your entire dark mode strategy depends on prefers-color-scheme, overriding it cleanly becomes surprisingly annoying.

So the final system uses three strategies at once:

Follow OS preference by default
Respect explicit data-theme="dark"
Support legacy .dark class toggles

And there's one important escape hatch:

<html data-theme="light">

That blocks OS dark mode and forces light mode.

Which sounds simple now.

It was not simple then.

The Tailwind v4 trap no one warns you about

This one was painful because I discovered it after shipping.

I used:

@theme inline

Seems harmless.

What it actually does is bake your token values directly into generated utilities.

So instead of:

background-color: var(--color-primary);

You get:

background-color: #6B21A8;

Looks identical in light mode.

Then you switch to dark mode... and nothing updates.

Because CSS variables can change. Hardcoded hex values cannot.

Dark mode didn't fail loudly.

It failed politely.

The fix was deleting one word:

@theme

No inline.

That tiny difference now lives in script comments and architecture notes because future-me absolutely would have broken it again.

TypeScript types, because eventually someone asks

The pipeline also generates declarations like:

export declare const colorPrimary: string;
export declare const spacingMd: string;

Most of the time you won't need them.

But when you're wiring tokens into charts, runtime themes, config systems, or anything dynamic, typed access becomes very convenient.

And once generation is automated, adding it costs almost nothing.

The only part that really matters

All of this is interesting engineering trivia.

But none of it is the real win.

The real win is this:

Before

Design values lived in Figma
Code values lived in the codebase
Keeping them aligned required human discipline
Human discipline eventually lost

After

Values live in one file
Everything else is derived
Drift becomes structurally impossible

That's it.

The 11 outputs, RGB channels, dark mode logic, Tailwind quirks — those are implementation details.

The actual product is a system where design and code no longer argue about reality.

Next: I launched 7onic as a standard npm package. Then I added a CLI that copies source files directly into your project. Here's why I made that shift — and what it actually costs.

Design to Code #1: Why I Built 7onic

7onic — Thu, 16 Apr 2026 10:47:03 +0000

I remember the exact moment I gave up on handoffs.

A developer had implemented a card component I designed. The spacing was off by 2 pixels. The border radius was 8px instead of 6px. The shadow was close but not quite right — they'd grabbed a Tailwind default instead of the value in the Figma file. Individually, none of these were worth a ticket. Together, the whole thing just looked... slightly wrong.

I left a Figma comment. It got fixed in the next sprint. Then the same thing happened on the next component. And the next one. For ten years.

I'm a designer. I've also been writing frontend code for most of those ten years, which means I've been on both sides of this handoff. I know why the developer used rounded-md — it's right there in Tailwind, it's close enough, and who has time to check whether 6px rounds to rounded-md or rounded or something else entirely. (It doesn't map cleanly to either, by the way.)

At some point the Figma comments stopped feeling productive and I just started writing the components myself.

It's not a people problem

I want to be clear: the developers I worked with weren't sloppy. Most of them were better engineers than me. The issue was that design values lived in Figma and code values lived in... wherever the last developer put them.

Someone builds a button. They eyeball the Figma file, pick bg-gray-900 because it looks right, move on. Next month, someone else builds a card header. They look at the button, assume that's the canonical dark color, copy it. Except the Figma file actually specified #1a1a1a, which is close to gray-900 but not the same. Now you've got two slightly different "dark" colors in production and nobody remembers which one is correct.

Multiply that by every color, every spacing value, every radius, every shadow. Across dozens of components, over months. The drift is slow and constant.

The actual problem is obvious in hindsight: there was no shared source of truth. The designer had one (Figma). The codebase had another (whatever was already in the code). Keeping them in sync was manual, which means it was nobody's job, which means it didn't happen.

I tried all the "normal" solutions first

Before building anything, I did what you'd expect.

Exported tokens from Figma manually, dropped them into the Tailwind config. Worked great for about three weeks until the Figma file got updated and nobody remembered to sync the code. Back to drift.

Tried Style Dictionary. It's genuinely powerful, but configuring it to output exactly the formats I needed — CSS variables, Tailwind v3 preset, Tailwind v4 theme, JS exports, TypeScript types — took longer than building the actual components. I spent a full weekend writing transforms and formatters and still didn't have something I trusted.

Token Studio for Figma? Good plugin. But the exported JSON needed so much massaging before it was useful in a real Tailwind project that I was basically writing a custom pipeline anyway — just with an extra abstraction layer I didn't control.

Every approach had the same gap. It handled the "get tokens out of Figma" part reasonably well, then left you alone for the "actually wire these into your codebase" part. That last-mile wiring is exactly where things break.

So yeah, I built my own thing.

One file, one command, zero drift

The rule I started with was almost naively strict: if a value isn't in the design token file, it can't exist in code. No bg-gray-500. No p-[17px]. No text-[13px]. If you need a color, there's a token for it. If there isn't, you add one to the token file first.

I realize that sounds annoying. It is, a little, at first. But it turns out that constraint is the whole point. It forces every visual decision through a single chokepoint: figma-tokens.json.

One sync-tokens command reads that file and generates everything:

CSS custom properties
Tailwind v3 preset with RGB channels (so bg-primary/50 works)
Tailwind v4 @theme with native color-mix
TypeScript types
JSON for anything else

Eleven files total. All from one source. I can change a color in the token file, run the command, and know it's updated everywhere. No searching the codebase for hardcoded hex values. No "did we update the Tailwind config too?"

On top of that token layer, I built 7onic — 42 components, all using Radix UI under the hood for accessibility, styled with CVA variants. There's a CLI too:

npx 7onic add button input select

This copies the actual source files into your project. Not a compiled package you import — the real .tsx files, in your components/ folder, fully yours to read and modify. I started with npm install — the standard approach. The CLI came later, once I understood what copy-paste actually enables. I'll write a separate post about why I made that shift, because it's a real trade-off.

Why Radix specifically

Quick detour on this because people ask.

Accessibility is the part I didn't want to get wrong and also the part I knew I would get wrong if I built it from scratch. Focus traps in dialogs, keyboard navigation in dropdowns, screen reader announcements for toasts — this stuff is brutally hard to get right across browsers and assistive technologies.

Radix handles all of that and ships completely unstyled. No CSS to override, no opinions about how things look. You bring the design tokens, Radix brings the semantics.

Could I have built primitives from scratch? Sure. Would the focus management in my dialog component be as robust as what the Radix team has iterated on for years? No. I know where my time is better spent.

The solo thing

I should mention that I built all of this alone. No team. No design review. No code review. Just me, my Figma files, and a growing collection of markdown documents where I argued with myself about naming conventions.

(Is the base button size called default or md? Does the button need 5 sizes or is 3 enough? These are the questions that keep you up at night when there's nobody else to make the call. I went with 5 sizes and default as the base, if you're curious. There's a whole doc about why.)

Building solo has one unexpected benefit: it makes the "no hardcoding" rule actually stick. On a team, someone always has a deadline and a good reason to skip the token file. "I'll clean it up later." Solo, I'm the person who has to clean it up later, and I know I won't, so I just do it right the first time. The constraint isn't aspirational — it's survival.

The downside is that a design system can grow forever. There's always one more component to add, one more variant to support, one more edge case to handle. I had to get comfortable shipping something incomplete. 7onic right now has 42 components, supports both Tailwind v3 and v4, has a CLI, and docs in three languages. It's also missing things. That's fine. Ship, iterate, repeat.

What comes next

This is the first post in a series called "Design to Code." The plan is to write about the decisions behind 7onic — not the marketing version, but the actual reasoning, including the parts where I got it wrong and had to redo things.

Some posts I'm planning:

How the token pipeline works end to end — the sync-tokens script, why I generate RGB channel variables, how Tailwind v3 and v4 support both work from the same token file
The copy-paste vs npm-import story — why I started with npm install and later built a CLI that copies source files instead
Using AI to build a design system — what llms.txt actually does, how I use Claude to write components, and where it falls apart
Lessons from 42 components — patterns that scaled, patterns that didn't, things I'd do differently if I started over

If any of that sounds interesting, stick around.

Next up: how one JSON file becomes CSS variables, Tailwind presets, and TypeScript types — and why my first three attempts at building this pipeline failed.