DEV Community: 7onic

Design to Code #8: The Cosmetics of Modularity

7onic — Tue, 26 May 2026 07:39:56 +0000

It was sometime in early April. Version 0.1.0 had been sitting on npm for maybe twenty-four hours. I was clicking through the documentation site I'd just deployed, riding that brief, fragile wave of pride you get right before you discover a critical bug.

The Card component page featured a standard "Copy" button on the code block. Out of pure habit, I clicked it, flipped over to a scratch test project, and ran npm install @7onic-ui/react. The installation finished cleanly. Then, the development server lit up bright red.

Module not found: Can't resolve '@7onic-ui/react/card'

The code block on my own documentation site was instructing developers to import from a path that literally did not exist in the package they had just installed. It wasn't a typo. It wasn't a missing dependency. It was a path that had never existed and was never going to exist, simply because I had never written a package.json exports map to support it.

Anyone who copied that snippet on day one ran straight into a module-resolution error on line one.

Where the Lie Came From

The Card documentation page relied on a helper function called generateCode() to render the Playground's live preview snippets. Somewhere deep in that utility, I had written a line that looked roughly like this:

const importPath = `@7onic-ui/react/${componentName.toLowerCase()}`

It feels entirely right when you write it. It's very shadcn-style. It looks clean, professional, and mimics the architecture of a massive, modular enterprise package. The string interpolated perfectly, the syntax highlighter mapped it beautifully, and the page rendered with zero console warnings.

The only problem was that it had absolutely zero relationship to what was actually sitting inside the compiled dist/ directory.

In reality, I had built the package with a single root entry point — one lone index.ts file that re-exported every component. The package.json had "main" and "module" and "types" all pointing strictly to that one file, and that was it. There was no "exports" map, no subpaths, nothing. The npm package and the documentation site were completely misaligned, and the docs site was writing checks that the package couldn't cash.

What I Did Instead of Managing 42 Subpaths

My initial, knee-jerk instinct was to fix the documentation site by making the underlying package match its claims. I figured I'd just build the subpath infrastructure: write out the exports map — "./card": "./dist/card.js", "./button": "./dist/button.js" — and repeat that for all forty-two components. I'd configure tsup to emit every single one of them as an isolated entry point, and then commit to maintaining that list for the rest of my life.

I actually started doing this, but I stopped about four components into the refactor. The sheer volume of package.json plumbing required per component was non-trivial. Every single new component added down the line would mean another entry to write, another build target to track, and another vector for human error if I forgot to map it.

So, I decided to look at how mature UI libraries actually solve this.

shadcn/ui wasn't a valid architectural comparison because it doesn't ship via an npm registry; you're copying raw source files directly into your project. But when I looked at libraries like Mantine, Chakra UI, and Radix Themes, they all import directly from a single root: import { Button } from '@mantine/core'. Not @mantine/core/button. The packages I had been quietly romanticizing in my head weren't even doing what my documentation claimed I was doing.

Furthermore, the bundle-size argument didn't hold water. Running tsup with splitting: true ensures that tree-shaking handles dead code elimination gracefully at the named-export level. If a consumer imports { Button } and nothing else, the rest of the library doesn't get shipped to the client anyway.

The subpath import was entirely cosmetic. It was a vibe. It was the aesthetic of a modular architecture, not actual modularity.

I formalized this decision in an Architecture Decision Record — NO-SUBPATH-EXPORTS.md — mostly to stop future-me from having this exact same argument with himself. I established very clear re-evaluation criteria in the document: I would only revisit subpath exports if the library grew past 50 components, if a single root import began ballooning the bundle size past 100KB, or if actual production users explicitly demanded it. Right now, none of those conditions are true. We have 42 components, tree-shaking works flawlessly, and nobody has complained.

Once the ADR was settled, I fixed generateCode() to emit @7onic-ui/react and absolutely nothing else. I cleared the build cache, reloaded the documentation page, clicked Copy, and pasted it. It worked seamlessly. It was the first time my documentation had actually agreed with my compiled package.

The One Exception (Which Arrived Three Days Later)

Of course there is an exception. There is always an exception.

On 2026-04-08 I shipped v0.2.0 and the Chart component rolled out with its own dedicated subpath: @7onic-ui/react/chart. The ADR covering this deviation is titled CHART-SUBPATH-EXPORT.md, and it's a direct response to a real dependency bottleneck.

The Chart component relies heavily on recharts. recharts is a massive package, and most developers pulling in a core design system like 7onic don't need visualization tools right out of the gate. To accommodate this, I marked recharts as an optional peer dependency, adding it to peerDependenciesMeta with optional: true.

Here is the JavaScript module quirk I didn't anticipate: if an optional library like recharts lives anywhere within the main entry point's import graph, importing literally anything from that main entry — a Button, an Input, a Badge — will instantly crash the application if recharts isn't installed in the consumer's project.

Module resolution hits the application before tree-shaking even gets a vote. The bundler parses the dependency chain, spots import { LineChart } from 'recharts', immediately goes hunting for it in node_modules, fails to locate it, and brings the entire application crashing down.

The only real fix was to completely isolate the Chart component into its own independent entry point. This required two distinct tsup build configurations: index (ensuring no recharts code touched the primary graph) and chart (treating recharts as an explicit external dependency). I mapped two separate entries in the package.json exports map, and thus, a single subpath earned its place by solving a tangible structural failure.

The rule here isn't "never use subpaths." The rule is "no subpaths for vibes." If a subpath exists to isolate a heavy, optional dependency that would otherwise break the primary entry point, it earns its keep. If it exists simply to make the import line look more modular than it actually is, it gets cut.

What the DX Improvement Actually Looked Like

When developers ask for subpath imports, what they are usually chasing is a sense of visual intentionality. They like seeing import { CardHeader } from '@7onic-ui/react/card' because it provides immediate, spatial context that CardHeader is tightly coupled to the Card component ecosystem.

v0.3.0 solved that psychological need without the overhead of subpaths. Every subcomponent is now exposed as a flat, named export right at the root entry point:

import { Card, CardHeader, CardTitle, CardContent } from '@7onic-ui/react'

You get a single, clean import line with all subcomponents explicitly declared. The contextual grouping shifts from the file path to the editor's autocomplete panel and the names themselves — Card, CardHeader, CardTitle. As you read the code from left to right, the structural relationship is entirely obvious.

An added benefit is that you only ever need exactly one import statement per component family, no matter how many nested subcomponents your layout requires. I actually find myself copying and pasting far fewer import lines now than I did when I was pretending the library utilized subpath directories.

What's Still Bothering Me

The reality I keep coming back to is that generateCode() spent a non-trivial amount of time serving a complete fiction to early adopters, and I have no real way of knowing how many people copied it before I pushed the fix. Granted, v0.1.0 didn't hit massive installation numbers, but those early users existed.

The resulting terminal error message is completely unambiguous, so anyone who tried it would have figured out the fix immediately. But they also would have known, on day one, that the maintainer didn't bother to test his own basic copy-paste documentation flow before executing a production release.

To prevent this from happening again, I wrote a verification script that executes an npm pack into a temporary directory and programmatically attempts to import components from the exact paths exposed by the documentation site. It exists purely because I no longer trust myself to remember to check manually. I shipped that script in the exact same release as the chart subpath — v0.2.0 — which feels poetically correct. Both implementations emerged from the exact same architectural realization: the npm package and the documentation site are two completely separate artifacts, and nothing forces them to agree unless you sit down and write the code that forces them to agree.

I should probably write an automated end-to-end test that scrapes every single generateCode() output across the entire live docs site, packs the library, and runs an isolated import test on each snippet. I haven't written it yet. It's on the list.

Next: 42 components, one developer, no design review. What the patterns looked like after a year of building and what I'd do differently if I started over.

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 #7: How CVA Scaffolding Turned Into Dead Code

7onic — Tue, 26 May 2026 07:09:53 +0000

The lint config had been sitting in the repo for a week, untouched, when I finally ran it across src/components/ui/ on the afternoon of April 4th. I was expecting maybe a stray console.log, a forgotten TODO — the kind of trivialities you hunt down right before any first publish. What I got back instead was a list of five files where VariantProps was imported but never used: breadcrumb, divider, drawer, pagination, and toast. Fine. Dead imports. Delete them and move on.

But then I opened breadcrumb.tsx and noticed something worse: the cva call itself was also completely unused. Not just the type import — the entire const breadcrumbVariants = cva(...) block was sitting there, fully defined, exported in spirit, and referenced by absolutely nothing. The component rendered its classes via cn() directly. The CVA scaffolding was pure decoration.

I had written that file. Yet I had no memory of writing the CVA part of it, because I had not written it deliberately. I had simply pasted the boilerplate shape of a 7onic component and filled in the middle.

Why CVA Earns Its Slot Elsewhere

Before getting into why removing it from breadcrumb was the right move, it helps to look at why that dependency is everywhere else in the first place.

class-variance-authority is one of the four core packages the 7onic add CLI auto-installs alongside @7onic-ui/tokens, clsx, and tailwind-merge. Four dependencies. That is the absolute floor of this design system. If you install a single 7onic component, all four show up in your node_modules, and CVA is the only one that isn't either a pure utility (clsx, tailwind-merge) or the design token layer itself.

It earns that real estate mostly on components like Button.

The Button component has, in its current form, four variants (solid, outline, ghost, link), six sizes (xs, sm, md, default, lg, icon), nine radius values (none through full), and a fullWidth boolean. Multiply that out and you get something north of four hundred valid combinations, every single one of which needs to produce the exact right Tailwind class string. Without CVA, the alternative is a long, miserable staircase of nested ternaries and template literals, or some homegrown lookup map that re-implements the same idea worse. The CVA call collapses that entire matrix into a single declarative object:

const buttonVariants = cva(
  'inline-flex items-center justify-center whitespace-nowrap transition-all duration-micro focus-visible:focus-ring disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: { solid: 'font-semibold', outline: 'border border-border bg-background text-foreground hover:bg-background-muted', ghost: '...', link: '...' },
      size: { xs: 'h-7', sm: 'h-8', md: 'h-9', default: 'h-10', lg: 'h-12', icon: 'h-10 w-10' },
      radius: { none: '...', /* ...nine total */ full: '...' },
      fullWidth: { true: 'w-full' },
    },
    defaultVariants: { variant: 'solid', size: 'default', radius: 'default', fullWidth: false },
  }
)

But handling class strings is only the smaller half of what CVA actually does for the library.

The Part That Isn't About Classes

The real reason CVA is worth a dedicated dependency slot is the line immediately following that cva call:

type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
  VariantProps<typeof buttonVariants> & { /* ... */ }

VariantProps<typeof buttonVariants> reads the variants object and infers the prop types directly from it. variant automatically becomes 'solid' | 'outline' | 'ghost' | 'link'. size becomes 'xs' | 'sm' | 'md' | 'default' | 'lg' | 'icon'. If I add a new size next month, the type system updates without me ever touching the props interface. If I rename solid to filled, every consumer site gets a red compile error the moment they pull the updated version.

You can easily build the class-string concatenation machinery yourself in twenty lines of code and tree-shake your way out of the dependency. What you cannot easily replicate yourself is this bidirectional link between the configuration object and the TypeScript types. CVA's true value lives inside the type system; the runtime class composition is just along for the ride.

Which is exactly what made the breadcrumb situation slightly ridiculous. Breadcrumb had a cva call with variants: {} — empty object, no variants — and it still had VariantProps imported at the top of the file. VariantProps<typeof breadcrumbVariants> resolves to {}. Zero props. The entire setup was a circle whose circumference was exactly zero.

When Variants Aren't Enough

The other thing worth knowing about CVA, before addressing the problem with defaults, is that it has a known soft edge. CVA fundamentally expects each variant to be orthogonal — meaning size should be independent of variant, which should be independent of radius. The exact moment you introduce a prop that only makes sense in tight combination with another prop, you step outside the comfortable middle of the library.

Button's color prop is the clearest example. It accepts default, primary, secondary, or destructive, and it only actually does anything when variant === 'solid'. An outline button doesn't have a solid fill color in the same way; a ghost button doesn't either. If I were to put color inside the main CVA variants object, it would show up in the TypeScript types for all variants. Consumers could legally write <Button variant="ghost" color="destructive" /> and get something that compiles cleanly but produces incoherent runtime styling.

So color lives outside CVA as a plain JavaScript lookup map:

const solidColorMap = {
  default: '...',
  primary: '...',
  secondary: '...',
  destructive: '...',
}

And the final class assembly looks like this:

cn(
  buttonVariants({ variant, size, radius, fullWidth }),
  variant === 'solid' && solidColorMap[color],
  className
)

The variant === 'solid' && ... line is load-bearing. CVA hands back the base utility classes; the conditional hands back the contextual color, but only when it is strictly relevant; cn flattens everything out while resolving any Tailwind utility conflicts. It's not exceptionally beautiful, but it's an architectural seam. CVA handles the clean, rectangular center of the design space and the conditional patches the corners.

For a long time I wanted to push color back into CVA via compoundVariants — the specific API designed for cross-prop interactions. I never found a way to express "this prop only exists when this other prop has this specific value" through compoundVariants. It can apply extra utility classes when two variants combine, but it cannot make a prop conditionally part of the TypeScript type interface itself. So the escape hatch remains.

Where compoundVariants Does Pull Its Weight

Five of the 42 components use compoundVariants: divider, tabs, segmented, textarea, and input. These are the components where the cross-prop logic isn't "should this prop exist?" but rather "what specific class combination does this intersection produce?"

The clearest use case is Input, which maps out three entries:

compoundVariants: [
  { focusRing: true, className: 'focus-visible:shadow-[0_0_0_2px_var(--color-focus-ring)]' },
  { variant: 'default', focusRing: false, className: 'focus:border-border-strong' },
  { variant: 'filled', state: 'error', className: 'border-transparent ... bg-[var(--color-error-bg)]' },
]

The third entry is the interesting one. variant: 'filled' and state: 'error' are both perfectly legal in isolation. A filled input without an error renders with a subtle gray background. An outline input with an error renders with a stark red border. But the combination of filled and errored needs its own custom treatment — a transparent border (because there is no outline to color) and a red-tinted background instead of the standard gray. Without compoundVariants you would either need a third state value (filled-error?) or lift the conditional outside CVA, creating the exact same seam I had to build for Button's color.

Divider's compoundVariants block is less complex but significantly more dense — ten entries covering the cross product of orientation (horizontal/vertical) with spacing (sm/md/default/lg). Each combination produces the correct margin utility and border direction. horizontal + default yields border-t my-4. vertical + sm yields border-l mx-2. The entire matrix laid out with zero conditionals at the call site.

These are the exact use cases CVA was actually engineered for.

What the Lint Sweep Was Actually Saying

So, the tally stood at five files with unused VariantProps. Four of them — divider, drawer, pagination, and toast — were using CVA productively but had simply forgotten to clean up the type import lines after a previous refactoring pass. An easy delete.

The fifth file, breadcrumb, was the one where I had to admit something to myself. Breadcrumb genuinely does not have variants. It has a rigid structure — a list of items separated by a visual separator — and the only thing that changes between instances is the literal content. There is no size prop because the size is inherited from the surrounding text context. There is no variant prop because there is only one way to render a breadcrumb in this system. The component is a thin, sensible wrapper around <nav> and <ol>.

Yet I had still given it a full cva call. With a completely empty variants object. Simply because every other file in the library had one.

That is the part worth writing down. The CLI installs CVA. The component templates start with CVA. Forty-two components use CVA. So when I sat down to author the breadcrumb file, my hands typed import { cva, type VariantProps } from 'class-variance-authority' before my brain ever caught up with the fact that there were no variants to manage. The lint sweep wasn't merely catching dead code; it was catching the underlying assumption that the pattern itself is the point.

The final result, after the cleanup: 0 errors, 0 warnings. Five files lighter on unused imports. One file lighter on an entire unused cva block. And a small, sobering note left in the ADR: "Pattern boilerplate vs deliberate use: not the same thing."

I think about that note more than I want to. The whole appeal of building a component library, from the inside, is that you stop having to make tiny, repetitive decisions. You reach for the established template, fill in the middle, and ship. The hidden cost is that you eventually stop noticing when the template is making the decisions for you. CVA inside the breadcrumb wasn't a load-bearing tool. It was just a habit wearing the costume of one.

Next: 7onic ships one entry point. No @7onic-ui/react/button subpath imports. The reason is embarrassingly specific to one incident where generateCode() sent users to an import path that didn't exist.

Design to Code #6: When @theme inline Killed My Dark Mode

7onic — Tue, 26 May 2026 06:24:28 +0000

I was in test-v4 that morning, clicking the theme toggle for the fifteenth time, and the card background just kept staying white.

The toggle itself worked. I could watch data-theme="dark" flip on <html> in DevTools. Text color changed. Border color changed. But the surface underneath stayed #ffffff, smug and immovable, as if it had personally decided that dark mode was a phase I was going through.

This was 7onic — my own library — on a fresh install of the v4 build I'd just shipped. The Tailwind v3 test page two tabs over worked fine. Same components, same tokens, same toggle. So the bug lived somewhere in the slice of CSS that only Tailwind v4 users would ever touch, which was exactly the slice I'd rewritten the week before, following the official migration guide step by step like a good citizen.

Three selectors, no JavaScript

Before I get to what I broke, it helps to know what dark mode in 7onic is actually made of, because the answer is: very little.

There's no useTheme hook in the library. No context provider, no <ThemeProvider> you have to drop into your root layout. The whole mechanism is three CSS selectors:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) { /* dark tokens */ }
}

:root[data-theme="dark"] { /* dark tokens */ }

:root.dark { /* dark tokens */ }

The first says: if the OS is dark, go dark — unless the user explicitly set data-theme="light". The second is for apps that want a manual toggle without touching prefers-color-scheme. The third is there because Tailwind v3 projects flip .dark on <html>, and I'm not in the business of fighting that habit.

Each block redefines a handful of CSS custom properties — --color-background, --color-foreground, --color-border, the usual suspects. The components don't know any of this exists. A <Card> just sets background-color: var(--color-background) and trusts whichever block is currently winning the cascade to fill in the right value. The whole thing rests on one slight assumption: the utilities reference variables, not hex literals.

Spoiler: in v4, mine didn't.

What `@theme inline` actually compiles to

If you've followed Tailwind's v4 migration guide, you've probably seen this snippet:

@theme inline {
  --color-background: var(--color-background);
  --color-primary: var(--color-primary);
  /* ... */
}

It looks innocent. It's documented. The Tailwind team recommends it for exactly the setup I have — design tokens defined elsewhere, Tailwind utilities that need to know about them. So I copy-pasted the pattern, ran the build, shipped the version, and went to bed feeling productive.

Here's what @theme inline does that the docs don't quite shout at you: it resolves the values at compile time and bakes them into the utility classes as literals.

So when my dev-mode tokens looked like this:

:root { --color-background: #ffffff; }
.dark { --color-background: #0a0a0a; }

Tailwind read @theme inline { --color-background: var(--color-background); }, looked up what --color-background resolved to in the :root scope at build time, found #ffffff, and emitted:

.bg-background { background-color: #ffffff; }

Not var(--color-background). Just the hex. Forever.

The .dark { --color-background: #0a0a0a } block was still sitting there in the CSS file. The variable was still being overridden at runtime. It just had nothing left to override, because no utility in the entire stylesheet was reading the variable anymore. It was the most polite kind of broken — every piece of the system looked correct in isolation, and the system as a whole did nothing.

Drop the word inline:

@theme {
  --color-background: var(--color-background);
}

…and Tailwind keeps the var() reference in the emitted utilities:

.bg-background { background-color: var(--color-background); }

Same authoring API. Completely different runtime behavior. One word.

Why I had `inline` in the first place

The honest answer: because the docs told me to, and because two weeks earlier I'd hit a different problem and inline was how I worked around it.

I'd just finished a token rename pass — REMOVE-DEFAULT-SUFFIX in the ADR, exactly as glamorous as it sounds. The old name for the brand color was --color-primary-default, and I'd decided the -default suffix was noise nobody had asked for. The new name was just --color-primary. Fine. Run the codemod, regenerate the token pipeline, move on.

Except now my Tailwind config was trying to write this:

@theme {
  --color-primary: var(--color-primary);
}

Which is, if you read it slowly, a variable defining itself in terms of itself. Tailwind liked that about as much as I did. The build either threw or it didn't throw and the value just collapsed to nothing — I don't fully remember which, because at the time I just wanted it to stop and I grabbed the first thing the docs suggested:

@theme inline {
  --color-primary: #15a0ac;
}

Hardcode the hex as a fallback. Tell @theme to resolve inline. Build went green. The brand color showed up. I committed.

What I did not notice, at that moment, was that I'd also signed every other token in the file up for the same treatment. Because @theme inline isn't a per-property switch — it's a whole-block mode. Once you put inline on the @theme block, every variable inside it gets resolved at compile time. Not just the one you were trying to rescue.

The brand color was now a hex literal in the utilities. So was the background. So was the foreground. Every border and ring and surface color in the system. All of them, frozen at whatever they resolved to in the light-mode :root. All of them, immune to .dark.

I'd built a dark mode that worked perfectly in CSS and was reached by exactly zero utility classes.

Why shadcn doesn't have this problem

While I was staring at this, I went to look at shadcn/ui's setup, because I knew they used @theme inline and their dark mode obviously worked. If the snippet was poison, surely they'd have noticed.

The trick is in the naming. Their @theme inline block looks like this:

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
}

Two different namespaces. The Tailwind utility variable is --color-background. The user-facing token they reference is --background. When @theme inline tries to resolve var(--background) at compile time, it finds… var(--background), because nothing else in the stylesheet defines that name at the :root level in a way Tailwind can statically resolve. So the var() survives into the output. The utility becomes .bg-background { background-color: var(--background); }. Dark mode overrides --background, the utility reads --background, everything works.

Mine looked like this:

@theme inline {
  --color-background: var(--color-background);
}

Same name on both sides. Because the entire 7onic token pipeline — Figma Token Studio → JSON → generated CSS → published package — uses one canonical name per token. There is no --background and --color-background. There is just --color-background, generated from figma-tokens.json, used by the utilities, overridden by the theme blocks. Single source of truth.

shadcn can afford the asymmetry because their tokens live in a hand-written globals.css that the user edits. Renaming one side is a five-second find-and-replace. I can't rename one side, because both sides are the same generated artifact. The variable name is the token name. That's the deal I made, and I'm not unmaking it for a Tailwind directive.

So @theme inline was always going to collapse the indirection on me. I just hadn't noticed yet.

Deleting one word

The fix took longer to think about than to type:

/* before */
@theme inline {
  --color-background: var(--color-background);
}

/* after */
@theme {
  --color-background: var(--color-background);
}

Then I had to solve the original self-reference problem a different way, which mostly meant putting the actual hex values directly in @theme rather than using var() references there at all. The hex values go into @layer theme { :root { ... } }. The unlayered variables.css wins the cascade. Dark mode wins inside that. Everything stays addressable through CSS variables, the whole way down.

The cost showed up in the build output. CSS went from 62.73 KB to 71.20 KB — an extra 8.47 KB, about 13.5% bigger. Gzipped, 11.51 KB to 12.34 KB, so the wire cost is 0.83 KB. The bulk of the increase is the @layer theme { :root { ... } } block that now has to ship every token as a real variable definition, plus the color-mix() expressions Tailwind generates for opacity modifiers (bg-primary/50 and friends), plus @supports fallbacks for browsers that don't yet speak color-mix(in oklab, …).

I'll pay that 0.83 KB every day of the week to have dark mode actually work.

What I keep thinking about

The thing that bothers me isn't that I wrote the wrong directive. It's that I wrote it straight from the official migration guide, the build passed, the dev server rendered, and I shipped it to npm. Every user on the v4 entry point of the package got a CSS file that ignored their dark mode overrides for as long as that version was current.

I had tests. I did not have a test that said: "the .dark selector should actually change pixel colors when applied to <html> in a real browser." I have one now. It would have caught this in five minutes.

Most of the bugs in this project end up like that. Not a missing concept — just a missing assertion of the obvious thing everyone assumed was true. inline is a single word. Dark mode worked. Then it didn't. Then it did again. The diff was four characters.

The longer postmortem is in the ADR if anyone wants it. The short version fits in a sentence: if your token names and your utility variable names are the same string, @theme inline will quietly turn your design system into a screenshot.

Next: 22 of 7onic's 42 components shipped with two different import patterns simultaneously. Both worked. One was a mistake, and I didn't find out for three releases.

Design to Code #5: Using AI to Build a Design System

7onic — Tue, 26 May 2026 05:39:21 +0000

I gave Claude the Switch component spec and pointed it at variables.css. What came back — CVA variants, Radix Primitives, forwardRef, controlled and uncontrolled both wired — was genuinely good. Better than my first draft would have been. I shipped it that afternoon without changing much.

That was sometime in March. By April, I had written three shell scripts whose entire job was to catch Claude reporting things as done when they weren't.

Not lying about the code. The code was still good.

What I Built for Claude

Before any of the problems, there's the setup. I spent more time building infrastructure for the AI workflow than I'd expected — more than I'd wanted to, honestly.

The core issue: Claude doesn't know anything about my codebase unless I tell it. And the codebase is specific in ways that matter. Custom token variables, a particular component pattern (Radix + CVA + forwardRef + named exports only), a naming convention, a list of exactly eleven distribution files that sync-tokens generates from one JSON source. None of that is in anyone's training data.

So I built llms.txt. Six variants of it, actually:

llms.txt (root) — library overview, installation, quick reference
tokens/llms.txt — token package specifics, variable names and categories
cli/llms.txt — CLI command reference, flags, dependency resolution
public/llms.txt — lightweight, for AI tools that attach context by URL
public/llms-full.txt — full component API reference with prop types
public/llms-cli.txt — CLI workflow format, import paths already converted to @/components/ui/

The last one exists because the import paths are different when you've copied the source files locally via the CLI, and I got tired of Claude giving users the wrong path in code examples. Small thing. Took a while to notice.

Beyond the llms.txt files, there's CLAUDE.md in the repo root. It loads automatically when I start a Claude Code session — the operating manual. Coding rules, token usage rules, the absolute constraints. The patterns that aren't obvious, like "use items-center always — never items-start with a mt-0.5 manual offset." Skill files for recurring workflows, so I don't re-explain the same pre-publish checklist every time. A memory directory with facts that persist across sessions — things like "don't add Co-Authored-By to public repo commits" (the repository is under my name; the ownership record matters for the MIT license).

I didn't build all of this at once. Most of it came after something went wrong.

42 Components

For component code, the workflow is genuinely useful. Given the spec, the relevant token file, and the established patterns, Claude produces something I can read, understand, and ship with maybe 10-20% editing. The CVA variant structure, the Radix primitive wiring, the TypeScript types — it handles all of that correctly when the context is set up right.

42 components in 7onic. I built most of them this way.

Where it's less reliable: anything that requires holding the full state of the codebase at once. "Does this change break anything else?" is hard for a tool that only sees what you've explicitly shown it. I learned to be specific about scope and stopped expecting it to catch cross-file implications on its own. That part I adapted to. The component code stayed good.

The problem was somewhere else entirely.

The v0.3.0 Day

The v0.3.0 release cycle is documented in an Architecture Decision Record now. I keep it not because I enjoy the reading, but because the pattern it describes keeps recurring in subtler forms and it helps to have it written down somewhere.

In one day — we were landing the breaking change migration that converted 22 compound components to named exports — I got three separate confident reports that something had been verified or completed. None of them were accurate.

The specifics varied each time. Once, Claude cited a subagent's verification results as its own without re-running the check itself. Once, the substitution count it reported didn't match what was actually in the files — it had counted text occurrences rather than checking structural correctness. Once, "technically verified" meant the code compiled, when what I needed was confirmation that the rendered output matched the expected output across modes.

Each time, the language was the same: completed, verified, all passing. Each time I believed it and found the problem after.

The ADR calls this "완료 선언 시 실측 증거 결여" — claiming completion without actual measurement. The problem wasn't that Claude was wrong. It's that it was confident and wrong in a way that looked exactly like confident and right. Nothing in the response distinguished between them.

After the third one, I closed the laptop and went for a walk. When I came back I wrote an architecture decision record, which is apparently what I do when I need to make sure I don't repeat a mistake.

What Got Built After

The first thing was a vocabulary ban. CLAUDE.md §4 now classifies words like "완료", "검증됨", "all clean", "PASS" — used without direct tool output attached — as false reports. The required format for any completion claim is:

✓ [item] — 도구: `[command]` → `[output line verbatim]`

If the command and output can't be cited, the required response is "⚠ 검증 안 함" with a stated reason. Not a failure mode to hide — just an honest "I didn't check."

The second was a gate for commits. scripts/hooks/verify-artifact-gate.sh blocks commits that touch UI source files unless a specific evidence file exists in /tmp/ — written by the live audit script, timestamped, expiring in 15 minutes. No evidence file, no commit. The hook reads the file. It doesn't read the message.

Third was scripts/hooks/hundred-percent-detector.sh, which scans incoming prompts for phrases like "100%", "전수", "완벽하게". When any appear, it forces the session into the /100-percent-verify protocol — five gated phases, each requiring actual tool output before moving forward.

The one I added last — after I realized how close I'd come to letting it happen — was scripts/hooks/manual-only-gate.sh. It blocks npm publish, gh workflow run publish, and npm dist-tag unless a one-time authorization token file exists in .claude/gates/. I was running a verification workflow and noticed that the publish step was sitting right next to the check steps, and that nothing structural prevented Claude from running it. The commands are manual-only now. That's not a constraint Claude works around; it's a file that doesn't exist until I create it.

I also flipped the document propagation model around the same time. Previously, Claude would automatically update documentation whenever I changed code. During active development, this meant docs were getting rewritten for iterations I abandoned ten minutes later. The new model is approval-based: Claude scans the git diff at commit time, proposes a propagation plan, waits for yes. Slower, but the docs stop reflecting decisions I've already reversed.

Where It Still Falls Apart

The hooks cover the specific pattern that broke v0.3.0. Other things still go wrong.

Verification is the most dangerous mode — it needs explicit forcing to produce actual tool output rather than an interpretation of it. "Check if this is correct everywhere" lands very differently than "read this file, now read this file, compare these specific values." Cross-file consistency is generally unreliable without breaking it down manually.

Long sessions are the worst. Constraints that were clearly active at the start of a session get quietly dropped by the third or fourth task, with no signal that it happened. I've ended sessions where CLAUDE.md rules followed carefully at the start were just not being applied at the end — not defiantly, just absent. The skills help here: they re-establish rules at the moment they're needed rather than depending on something established hours earlier staying live.

I still use Claude for almost everything. The component code is genuinely good, and the llms.txt infrastructure plus CLAUDE.md plus the memory system means a new session orients to the codebase fast. The maintenance overhead is real, but it's less than the alternative, which was rebuilding trust from scratch every day.

The shell hooks exist for the edge cases. I'm glad they're there. I'd be gladder if I didn't need them.

Next: How 7onic handles dark mode — no JavaScript, no documentElement.classList toggling. Just CSS, and why one strategy wasn't enough.

Build & Release #2: Five Patches for One Line of CSS

7onic — Mon, 18 May 2026 14:35:58 +0000

I was running through a quick test on April 27 when I noticed something almost funny. Light background. White-ish text. Just barely legible enough that you could tell text was supposed to be there, like a watermark someone forgot to remove.

The site was the 7onic documentation, rendered in light mode. My OS, however, was set to dark mode. The culprit? A single line in the body rule targeting --color-foreground.

I had shipped that exact line four days earlier in v0.3.1. I had already patched it once. By that morning, I was about to patch it a second time. (The third patch—the one that actually solved the mystery—wouldn't happen until v0.3.5, and certainly not because I planned it.)

All in all, it took five releases and four different values for html body { color } to fix a text color. I patched the output file three separate times without ever touching the generator script—which meant every time I ran npm run sync-tokens, my pipeline would have silently regenerated the exact bug I was trying to kill.

The Original Sin

The chaos started with v0.3.1 on April 23. I introduced tokens/css/reset.css as a brand-new distribution file, bringing our total file count from 11 to 12. Tucked neatly inside this reset was a body baseline color set to var(--color-foreground). In that same release, I added --foreground: var(--color-foreground) to variables.css as a compatibility alias for Next.js.

It blew up the exact same day.

Next.js has a @theme inline directive that emits --color-foreground: var(--foreground) on its end. Look closely at that loop: --foreground was pointing to --color-foreground, which was pointing right back to --foreground. The browser did exactly what browsers do when caught in a circular reference trap—it gave up and resolved the whole thing to unset.

Hours later, v0.3.2 went out as emergency triage. I pointed --foreground at var(--color-text) instead, deleted reset.css as a standalone file, and embedded the body baseline straight into variables.css. We were back down to 11 distribution files. I called this Approach Z because I had already burned through too many letters of the alphabet trying to make this work.

But the body color? It stayed as var(--color-foreground).

Three Days Later: Enter IACVT

April 27. White text on a white background.

The underlying mechanism took a while to see clearly, mostly because --color-foreground was defined in the codebase—it just wasn't defined in variables.css. It lived exclusively in tokens/tailwind/v4-theme.css, a file you only ever import if you are actively using Tailwind v4. If a user imported variables.css standalone, used Tailwind v3, or pulled the raw CSS into a non-Tailwind project, that variable simply didn't exist to them.

CSS has a terrifyingly specific name for what happens next: IACVT (Invalid At Computed Value Time).

The browser parses the CSS declaration perfectly fine. But at runtime, it tries to resolve var(--color-foreground), realizes it's looking at a ghost, and throws the entire color declaration away. Not the whole CSS rule—just that one property.

The cascade then fell back to a global rule I had: html:root { color-scheme: light dark }. This tells the browser, "Hey, I support both themes, pick whatever makes sense." Since my OS preference was set to dark mode, the browser obligingly picked a light text color for a dark background. Except, the actual background of the docs site was locked into light mode. Light text. Light background. Total invisibility.

The fix went out as v0.3.4. I swapped the variable from var(--color-foreground) to var(--foreground). Because --foreground is defined inside variables.css itself (within the html:root compatibility alias block), it is guaranteed to be available wherever variables.css is imported. I verified it locally, pushed, tagged, and called it a day.

Or so I thought.

I had patched the compiled output file. I had not looked at the generator.

The generator was a script named scripts/sync-tokens.ts, which automatically spits out tokens/css/variables.css. Back in v0.3.3, when I was messing around with a monospace font baseline, I had touched that generator code and hardcoded it to emit color: var(--color-foreground). I had manually hotfixed the output file, but I forgot to fix the robot that writes the file. Nobody noticed. There was no one else to notice.

The Generator Never Lies

The next day, while working on something completely unrelated, I casually ran npm run sync-tokens.

I checked the git diff. The script had proudly stripped away my manual hotfix and put var(--color-foreground) right back into production.

That was the moment.

Version 0.3.5 shipped on April 28. This time, I fixed the actual generator code to emit var(--color-text), and updated the output file to match. The first execution of the fixed script reported 1 updated, 12 unchanged. Running it a second time yielded 0 updated, 13 unchanged. Idempotent. Finally.

--color-text comes straight from our core theme files: themes/light.css (resolving to gray-900) and themes/dark.css (resolving to gray-100). No aliases. No indirection. It is defined in every single supported import permutation because it maps directly back to our Figma Single Source of Truth—the exact source this entire pipeline was built to serve.

Decoupling the Three Variables

Looking at the three variables lined up side-by-side makes the architectural hierarchy glaringly obvious:

--color-foreground is a Tailwind v4 alias. It lives strictly in v4-theme.css so Tailwind utility classes can map correctly. Outside of Tailwind v4, it does not exist.

--foreground is a Next.js compatibility alias. It lives in the html:root block of variables.css so Next.js's @theme inline compiler has something to bind to.

--color-text is the Figma token. It lives in the core theme files — named after the *-text token convention in figma-tokens.json, the same source the entire pipeline was built around.

The baseline rule inside html body is the most universal selector in the entire project. By extension, it requires the most universal variable available. That was --color-text the whole time. It had been sitting quietly in the theme files before any of this madness even started.

I had instinctively reached for the Tailwind alias because Tailwind was the immediate sandbox environment I was developing in, completely forgetting that the resulting raw CSS file would be consumed by developers who weren't using Tailwind at all.

The build generator was the only honest witness to what code I was actually shipping to production. I just wasn't bothered to ask it.

Next: 22 of the 42 components in 7onic shipped with two different import patterns at the same time. Both worked. One was a mistake.

Build & Release #1: How Apple's rsync Update Nuked My Repo

7onic — Mon, 18 May 2026 09:05:32 +0000

The sync script hadn't changed. Same flags, same paths, same output format. I'd been running it every single time I pushed a change to the public repo, and it had always been rock solid.

Until April 8th. I ran the script, and the terminal output looked perfectly normal. But when I double-checked the local public repo directory, something was missing.

No .git folder. It was just... gone.

Why There's a Script at All

A quick bit of context: 7onic lives a double life across two repositories. There's a private repo where the full project lives — the docs site, design tokens, internal tooling, the whole nine yards. And then there's the public repo (itonys/7onic) that contains only the open-source library: the core components, the CLI, and the token package.

To keep them in sync, I wrote a script that uses rsync to copy the relevant directories from private to public, filter out the internal fluff, and push the clean code.

Now, the .git folder in that public directory is what makes it a Git repository in the first place. It holds every commit, every branch, every tag, and most importantly, your remote configuration — the stuff that tells Git, "Hey, when I type git push, send this code to this exact GitHub URL." If you delete that folder, you lose your entire local history. Fortunately, the remote on GitHub stays intact, so a quick git clone will save your skin. But any local-only state? Completely vaporized.

My script explicitly included --filter='P .git'. That P stands for Protect — a standard GNU rsync flag that tells the engine, "Whatever you do, do not touch anything named .git." I had verified it. It had been working flawlessly for weeks.

What I didn't know was that macOS had quietly pulled a fast one on me. A recent OS update had swapped out the native GNU rsync binary for openrsync, Apple's own BSD-licensed re-implementation. And guess what? openrsync doesn't give a damn about --filter='P .git' the same way GNU does.

Combined with the --delete-excluded flag — which ruthlessly purges files in the destination that match an exclude rule — the public repo's .git folder was silently executed on the very next sync.

The Fix That Made It Worse

My immediate, panic-fueled instinct was: Okay, rsync needs to keep its hands off .git entirely.

The obvious move was to tweak the flags. But in my state of confusion over which flag was doing what, I made the classic mistake of changing two things at once: I ripped out the protect flag and kept the exclude.

Which meant rsync looked at the source directory — the private repo — and copied its .git folder right over to the public destination.

The public repo had a .git folder again, sure. But it was a clone of the private repo's brain. This meant:

The public directory's origin remote now pointed directly at the private GitHub repository.
Any commit made from inside the public directory would bypass the public repo and push straight to the private remote.

I didn't realize this immediately. To verify my "fix" worked, I casually ran a test commit.

That commit flew straight into the private remote. I stared at the terminal git log for a long, quiet minute.

Oh, no.

321 Files Deleted. 93,300 Lines Gone.

I managed to untangle the origin mess first — wiped the imposter .git folder, ran a fresh git clone from GitHub to restore the actual public history, and got the public repo pointing back to itself.

But now, my local working tree was a crime scene. There was a bad commit (13edc14) sitting there from the whole ordeal that needed to be reconciled. I decided to merge it.

I did not run git diff --stat first. Big mistake.

The merge took the private repo's file structure as the absolute source of truth and aggressively subtracted everything the public repo wasn't supposed to have. Which, as it turned out, was almost the entire codebase.

321 files deleted. 93,300 lines of code wiped from existence.

site.config.ts got completely overwritten with the private version. package.json followed suit. What followed was a cascade of four consecutive errors. I fixed each one blindly, treating the symptoms without looking at the larger picture, only to trigger the next error. It was that specific kind of miserable debugging session where you're chasing ghosts because you refuse to admit how deep the hole actually is.

The ultimate salvation was running git reset --hard f3453d8 — rolling back to the last clean commit before the madness started. It worked instantly and cleanly. The actual damage was luckily contained to my local working state and one embarrassing, stray commit on the private remote.

But it cost me four hours.

The Real Fix

The root problem was putting blind faith in rsync to protect a critical folder like .git. Any solution that relies on a specific CLI implementation behaving perfectly across different OS flavors is fundamentally fragile. GNU rsync and openrsync are simply not the same beast.

The new approach completely eliminates rsync from the equation of trust:

# Physically move .git completely out of rsync's line of sight
GIT_BACKUP="/tmp/.7onic-git-backup-$$"
mv "$DEST/.git" "$GIT_BACKUP"
trap 'mv "$GIT_BACKUP" "$DEST/.git" 2>/dev/null' EXIT

# rsync runs with .git physically absent from the destination
rsync -av --delete \
  --exclude='.git' \
  "$SRC/" "$DEST/"

# Restore it like nothing happened
mv "$GIT_BACKUP" "$DEST/.git"
trap - EXIT

It's a three-layer defense: physically eject .git to /tmp before rsync even initializes so there's nothing to delete, tell rsync to exclude it anyway just to be safe, and then slide it back into place afterward. The trap EXIT ensures that even if rsync crashes or the script aborts mid-run, the restore still fires. No flags to guess. No implementation quirks to worry about.

It hasn't broken once since April 8th.

Post-Mortem

The merge was the ultimate unforced error. By the time I hit that step, I had already fixed the remote origin issue — I was technically in recovery mode, not still drowning. A single git diff --stat before hitting enter on that merge would have screamed "321 DELETIONS" and I would have stopped immediately.

I didn't check because I was still trapped in "fix things fast" mode, which is historically the absolute worst mindset for carefully reviewing a git merge.

The initial script fix would have been fine too if I had just changed one thing at a time. Instead, I altered two flags simultaneously while my brain was fried, which is exactly how you end up copying a private .git directory somewhere it has absolutely no business being.

I've added one final line to the end of the sync script now: git -C "$DEST" remote -v. It prints the active origin remote after every single sync. It takes half a second. If it ever accidentally shows the private remote URL again, I'll catch it instantly before a test commit can make a fool out of me.

Next: The same week I broke the sync script, I also shipped a color bug five times in a row — each fix introducing a new way to break the same thing.

Component Anatomy #1: Perfect on Paper, Wrong in Production

7onic — Mon, 18 May 2026 08:37:27 +0000

I have an Architecture Decision Record (ADR) file sitting in my repo dated February 19, 2026. It contains three beautifully written paragraphs arguing why our xs button should be 28px instead of 24px. At the bottom of that file is a neat little table mapping out our definitive button size scale. Five rows: xs, sm, default, lg, and xl.

The xl row was set to a beefy 56px.

I deleted that entire row on March 11, 2026.

What xl Was Supposed to Do

As a list, the scale made perfect mathematical sense:

xs (28px): For tight secondary actions, toolbars, and dense data tables.
sm (32px): For compact user interfaces.
default (40px): The golden baseline.
lg (48px): For prominent primary actions that needed breathing room.
xl (56px): For... prominent hero actions? Massive landing page CTAs?

To be completely honest, I wasn't entirely sure what xl was actually for when I defined it. But man, it filled out the scale in a satisfying way. There was a comforting logic to it: each step up was roughly 8 to 12 pixels larger than the last, capping out at 56px — a number that felt solidly "large but not absurd." On paper, it was flawless.

The illusion shattered the moment I put an actual 56px button into an actual UI layout.

It looked immediately wrong. Not subtly wrong, but off-the-charts wrong. The kind of wrong where you instinctively double-check your code to see if you accidentally applied the wrong utility class, because surely this monstrosity wasn't what you intended. I tried shoving it into card footers, form submissions, modal confirmation rows, and sidebar navigations. It was a disaster everywhere. Our default (40px) already felt substantial enough in those contexts; at 56px, the button started aggressively picking fights with the section headers.

Sure, there are interfaces where a button that massive makes sense — onboarding welcome screens, app store download buttons, or aggressive marketing landing pages where the entire design exists to funnel you into a single click. But those edge cases aren't what a core design system is built for. A design system size needs to work repeatedly, across different components, in different contexts. xl never did. It was a theoretical size that looked pretty in a token file and made zero sense in a real product.

So, I took a knife to it.

The Gap I Didn't See Coming

What I didn't anticipate was that cutting xl would immediately expose a glaring flaw in the rest of the scale.

With xl gone, I was left with four remaining sizes: xs (28px), sm (32px), default (40px), and lg (48px). I stared at that list for a long time, and something felt deeply unsettling. The jump from sm (32px) to default (40px) suddenly felt like a massive chasm. Eight pixels sounds tiny on paper, until you place those two buttons side by side in a real layout. sm is tight and compact. default is chunky and substantial. There was an entire register of UI missing in between.

Think about toolbars where default feels way too heavy but sm looks like an accidental misclick. Or secondary actions in a form that need to feel slightly more important than a naked text link, but still play second fiddle to the main CTA.

I added md at 36px the exact same day I axed xl.

Now, 36 isn't a particularly magical number. It's just 4px above sm and 4px below default, which at least scratched my itch for symmetry. My actual validation process was less numerical and more vibes-based: I tried 34px and 38px first. 34px basically blurred into sm on a standard screen. 38px just felt visually illegal because it wasn't a clean multiple of 4 (I know, it's completely irrational — 7onic's spacing scale already breaks the 4px rule in plenty of places — but my brain just couldn't shake it). 36px was the only one that slipped into the layout and looked like it belonged there without causing a scene.

And just like that, the new scale was born: xs (28px) / sm (32px) / md (36px) / default (40px) / lg (48px).

Same five sizes. But a completely different five sizes.

Why 28 and Not 24

The logic behind our xs size is the one piece of this entire puzzle that remained completely untouched between February and March.

WCAG 2.5.8 sets the minimum touch target size at 24px. That's the AA criterion — the absolute floor below which your UI is officially considered inaccessible. I'd seen plenty of other design systems set their smallest buttons to 24px just to check that compliance box.

But I drew the line and set our xs to 28px.

The reasoning, as documented in our ADR, is straightforward: WCAG's 24px is a minimum, not a target goal. The Apple HIG recommends 44pt. Material Design pushes for 48dp. Every mature, battle-tested design system sits comfortably well above the WCAG floor — not out of corporate generosity, but because 24px is genuinely too small for a human finger to interact with comfortably. On a cramped mobile screen, inside a packed toolbar, with an average thumb having a clumsy day, those 4 extra pixels matter in a way that's hard to articulate but instantly felt.

There was also a dirty little practical reason: h-7 is exactly 28px in Tailwind. h-6 is 24px. While the accessibility argument absolutely came first, I won't pretend the clean alignment with Tailwind's token scale didn't put a massive smile on my face.

Back to Square One (But Better)

The ultimate irony of this whole saga is that we shipped with five sizes anyway. I deleted one in March, added one back in March, and ended up exactly where I started numerically.

It's been a few months of putting this scale through its paces in production now. Hilariously, md (36px) has turned out to be the size I reach for the most when building secondary actions — way more than sm (32px), which I initially thought would dominate that territory. Meanwhile, lg (48px) makes appearances far less often than I anticipated. And I have yet to open a component file in a real product and think, "You know what this needs? A 56px xl button."

Is this scale absolutely perfect? Honestly, I don't know. But the goal was never perfection; it was utility. We wanted a size for every context without hoarding sizes that serve no context. Right now, all five of these sizes actively earn their keep — which is a hell of a lot more than xl could ever say.

Next: 22 of the 42 components in 7onic shipped with two different import patterns at the same time — a namespace style and a named style. Both worked. One was a mistake. Here's how I figured out which.

Token Deep Dive #1: The /50 That Did Nothing

7onic — Mon, 18 May 2026 07:37:31 +0000

The other day, I noticed something funky with my accordion component's hover state.

It wasn't broken in an obvious, "error-thrown-in-console" kind of way. The background color changed when I hovered over it, sure, but the opacity was completely gone. I had explicitly coded hover:bg-background-muted/50, but instead of a nice, subtle 50% tint, I was getting a solid, opaque slap of color. Same went for my glassmorphism effects (bg-white/10) — just pure, blinding white.

At first, I went down the usual rabbit holes: Is it a specificity issue? Did I miss an import somewhere?

It took me longer than I'd like to admit to connect the dots to a change I'd pushed a few days prior: converting every single color in our 7onic Tailwind v3 preset from hardcoded HEX values to CSS var() references.

At the time, I thought I was a genius. I thought I was building the ultimate clean architecture.

Spoiler alert: I wasn't.

The "Single Source of Truth" That Betrayed Me

The dream was beautiful. I was setting up a token pipeline where figma-tokens.json was the Single Source of Truth. Run one build script, and it spits out eleven different distribution formats — CSS variables, Tailwind presets, TypeScript types, you name it.

The goal was simple: keep the Tailwind v3 preset perfectly synchronized with those Figma tokens without the nightmare of maintaining separate, duplicated HEX values in a JS file.

So I mapped every token reference to a CSS variable:

colors: {
  primary: {
    DEFAULT: 'var(--color-primary)',
  },
  background: {
    muted: 'var(--color-background-muted)',
  },
}

Look at that. Whenever a designer shifted a hex code in Figma, npm run sync-tokens would handle the rest downstream.

Except the moment this shipped, bg-primary/50 died. So did border-border/60, text-foreground/80, bg-gray-500/30. Every single opacity modifier across the entire component library silently stopped working.

The truly embarrassing part? I had literally written the documentation for this pipeline a month earlier, explicitly stating that Tailwind v3 opacity modifiers require decomposable color values. I read it. I wrote it. And then I completely ignored it because I was blinded by how clean the var() refactoring looked. Classic.

Why Tailwind v3 Chokes on CSS Variables

Here's the technical reality: Tailwind v3 handles opacity modifiers at build time.

When the JIT compiler scans your code and sees bg-primary/50, it looks up primary in your Tailwind config. It expects a raw value — like a HEX or RGB string — that it can physically decompose into individual R, G, B channels to output rgba(R, G, B, 0.5). This is all build-time string manipulation.

When you pass it var(--color-primary), the compiler hits a wall. It has no idea what RGB values that variable will resolve to, because that resolution happens at runtime in the browser. So instead of throwing an error, it just discards the /50 alpha channel entirely and outputs the base color as a solid block.

Tailwind v4 doesn't suffer from this. It delegates the heavy lifting to the browser using the native color-mix() function:

/* What bg-primary/50 compiles to in Tailwind v4 */
background-color: color-mix(in srgb, var(--color-primary) 50%, transparent);

Since the browser handles the blending at runtime, v4 doesn't need to know the raw RGB channels at build time. But when I was building this, forcing everyone onto v4 wasn't an option — and the 7onic token package had to support both v3 and v4.

The Three-Tier Compromise

Fixing the static, primitive colors like gray-500 was easy. I swallowed my pride and reverted them back to raw HEX strings: gray-500: '#78787C'. These core palette shades never change based on the active theme anyway, so hardcoding them in the JS preset was fine, and it instantly brought opacity modifiers back to life.

Semantic colors were a different problem. background-muted needs to resolve to a light gray in light mode and a dark charcoal in dark mode. It has to be a CSS variable at runtime to handle theme toggling — but it also needs to be decomposable at build time for Tailwind v3.

Tailwind v3 has a built-in escape hatch for exactly this dilemma. Instead of 'var(--color-background-muted)', you write 'rgb(var(--color-background-muted-rgb) / <alpha-value>)'. The <alpha-value> is a special placeholder Tailwind swaps out with the actual opacity percentage during compilation. The catch: you need a companion CSS variable that holds only the space-separated R G B numbers, not a full HEX code.

The three-tier breakdown:

Type	Preset format	Reason
Primitive colors (gray-500, primary-400…)	HEX directly	Static values, `/50` works out of the box
Semantic colors (primary, background…)	`rgb(var(--*-rgb) / <alpha-value>)`	Theme-aware at runtime + alpha at build time
Non-color tokens (spacing, radius…)	`var()`	Opacity doesn't apply here

The preset ends up looking like this:

colors: {
  primary: {
    DEFAULT: 'rgb(var(--color-primary-rgb) / <alpha-value>)',
  },
  background: {
    muted: 'rgb(var(--color-background-muted-rgb) / <alpha-value>)',
  },
}

And the theme CSS files expose those raw companion variables:

--color-background-muted: var(--color-gray-100);
--color-background-muted-rgb: 244 244 246;

--color-background-muted: var(--color-gray-700);
--color-background-muted-rgb: 60 60 60;

When the theme changes, the browser swaps the underlying RGB numbers. Tailwind's pre-baked alpha placeholder handles the transparency. hover:bg-background-muted/50 works correctly in both modes.

Automating 135 Companion Variables Because I Value My Sanity

I had 82 primitive color tokens and 53 semantic colors per theme. Calculating and writing those -rgb channel variables by hand was not happening — it's tedious and drifts the moment a token value changes.

So I hooked it into sync-tokens.ts. A hexToRgb helper converts #F4F4F6 → "244 244 246" (space-separated, which is what modern CSS color syntax expects):

function hexToRgb(hex: string): string | null {
  const match = hex.replace('#', '').match(/^([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i)
  if (!match) return null
  return `${parseInt(match[1], 16)} ${parseInt(match[2], 16)} ${parseInt(match[3], 16)}`
}

Now every time the build pipeline runs, the script reads the original HEX values from figma-tokens.json, extracts the raw channels, and outputs both variables side by side. The source file stays clean. The -rgb values are derived, not stored — generated automatically, never manually maintained.

For semantic tokens, the script resolves the full reference chain (semantic → primitive → final HEX) for both light and dark modes, emitting the correct channel values per theme.

The One Gotcha That Still Trips People Up

If you're using @7onic-ui/tokens in a Tailwind v3 project and opacity modifiers suddenly vanish, 9 times out of 10 it's a missing theme import.

Importing just variables.css isn't enough. Because semantic -rgb variables have different values per theme, they live inside light.css and dark.css. If those theme files aren't imported, the -rgb variables are undefined — and bg-background-muted/50 either renders transparent or drops the background entirely, depending on the browser.

It's documented right there in the getting started guide. Some lessons are best learned by breaking it first.

Next: v3 and v4 dual support from one token source — how the two presets stay in sync and why the v3 format necessarily does more work.

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.

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.