A Design System of Three CSS Files, No Build Step
The problem that produced this design system wasn’t aesthetic. It was topological. Three of the house’s products render HTML in ways that are mutually incompatible. One is a site in Astro with Tailwind 4. Another is an app that serves static CSS from Fastify. The third is an operations panel whose HTML is assembled as a string in Python, with charts drawn in Pillow. The same brand had to cross all three.
The industry’s reflex answer, a component library, dies in the problem statement: components of what? An Astro component doesn’t run on Fastify. Web Components would run everywhere, but at the cost of introducing third-party JavaScript into pages that today ship zero JS. The only technology that crosses all three front-ends while demanding nothing from any of them is the oldest one available: CSS custom properties, variables declared in the CSS itself.
The result is three files and no build step for consumers. A handful of decisions are worth the field note: each has a measured reason, and two of them contradict instinct.
Three files because there are three layers of sharing
The structure isn’t “three files for tidiness”. It’s a thesis about what actually gets shared between products of the same house:
tokens.css (~400 lines): custom properties only, the brand’s named values. Surface and text colors, the accent, a severity scale, typography, spacing, shape, motion. This house’s domain is risk, so low/elevated/high are first-class tokens. Sharing: 100%. It’s where the brand lives.
primitives.css (~185 lines): about 20 classes, such as .btn, .chip, .card, .callout, .field, .table and .prose. All of them reference tokens; none has a literal color. Sharing is total, but with a deliberate restriction: a primitive is a CSS class, not a component. The reason is that <button class="btn"> comes out the same from an Astro template, a static HTML file and a Python f-string.
Compositions: zero sharing, on purpose. One product’s report screen, another’s dashboard: each lives in its own product’s CSS and does not enter the design system. That boundary wasn’t decreed, it was measured. The most mature product’s stylesheet has 256 classes, of which only ~20 are generic. Roughly 92% of that CSS is that screen, and shouldn’t be shared with anyone. A design system that tried to absorb it would become the repository of everything, and “the repository of everything” is how design systems die.
The rule that closes the layer: a token only one product uses lives in that product’s CSS. One product’s redaction bar and a specific badge stayed out of the system by recorded decision. The system carries what belongs to the house, not what belongs to someone.
The counter-intuitive decisions
Aliases with duplicated literal values, and a script that audits the duplication
The canonical tokens follow Tailwind v4 naming: --color-bg, --text-2xl, --radius-lg. The reason is pragmatic. With those names, the same file becomes utilities in the Astro project, via @theme, and remains an ordinary custom property for everyone who doesn’t use Tailwind.
But the file also defines short aliases: --bg, --text, --accent, --low, --high. And here comes the heresy: the aliases repeat the literal value rather than doing var(--color-bg). The reason is human reading, because var() is only resolved by the browser. Whoever opens the file to look up a hex, in a code review, in a Python script or in a grep, reads the first block and stops. An alias pointing at another alias turns a lookup into a hunt.
The duplication is the cost. A verification script (aliases.mjs --ci, in the repo’s tests) enforces that the two copies never diverge. Audited duplication is different from duplication: the first is a reading format, the second is a bomb.
The aliases had a second role: migration without a rewrite. The originating product had thousands of lines of CSS using the short names. Adopting the system required editing none of them. And the adoption diff tells the whole story: a single token value changed. When extracting a design system out of a product changes one value, the system came from the right place.
The dark theme enters through two doors, and it is not inverted light
The dark block is defined twice: in @media (prefers-color-scheme: dark) guarded by :root:not([data-theme="light"]), and again in :root[data-theme="dark"]. That’s what lets a theme toggle win in both directions: forcing light under a dark system and forcing dark under a light system. And with no JavaScript beyond writing the attribute. The maintenance rule that holds it up: no color has its only definition inside a theme block. Light is the baseline on :root, and dark redefines.
Two content choices, not mechanics. The dark background is neither black nor neutral gray: it leans slightly toward the accent’s green, because a mathematically inverted dark theme looks like someone else’s brand. And the accent lightens in the dark (teal-700 → teal-400), because the same color that has contrast on white doesn’t have it on near-black.
And a bug that became a rule: color-scheme is a contract, not a garnish. During one product’s migration the declaration got lost. The dark page got a light scrollbar, because scrollbars are painted by the browser, and the browser only knows about your theme if the CSS declares it. It cost one commit and joined the list of things the preview checks.
The Tailwind file is generated, because of a namespace collision
theme.css is the @theme block Tailwind 4 consumes. It is generated from tokens.css by a 92-line script, and the generator cuts the aliases: only the canonical half goes in. It’s not purism. In Tailwind v4, --text-* is the font-size namespace, that is, a prefix the tool has already reserved. A --text-muted: #5a625e leaking into @theme would generate a text-muted utility applying a hex as a font size.
The collision between “our naming convention” and “the tool’s convention” is the kind of thing a human forgets and a generator doesn’t. The generator’s --check runs in the tests, so a stale theme.css fails the suite.
The same pipeline generates tokens.py, the tokens as a Python dictionary, for the front-end that assembles HTML as strings and draws PNGs with Pillow. The design system doesn’t ask what the consumer uses. It delivers the same data in the format each one reads.
Adoption by versioned copy, not by dependency
No consumer installs the design system. Each keeps a versioned copy in its own repository. In one product that is a block pasted between markers in the CSS. In another, a cp of theme.css. In the third, a copied Python module. Alongside it goes a --check command that compares the copy against the source, declaration by declaration. Comments and whitespace do not count as divergence.
The check’s contract has two fine points:
- Silent when the source isn’t checked out next door. Whoever clones a product without cloning the design system breaks neither CI nor their machine: the check prints “skipping” and exits 0. The verification is for whoever has both repositories. The absence of one must not punish whoever needs only one.
- Running inside the consumers’
npm test. A divergent copy fails the suite along with any other test. (Footnote confession: of the three consumers, one has the check outside CI. It is the kind of gap this note exists to shame until someone closes it.)
Why copy and not an npm package? Three reasons, in order of honesty. The first: the system’s repository is private, and one consumer’s docker image has no credential to clone it. “A versioned 80-line file is more honest than a build secret.” The second: one of the consumers isn’t even Node. The third: a copy with a check gives you the real benefit of a lockfile, with explicit change and visible diff, without registry overhead.
And why pasted rather than @import in the most performance-sensitive consumer? An @import at the top of a stylesheet blocks rendering until the second file arrives, and that stylesheet is on the critical path of every public page. A pasted block costs zero requests.
Contrast is a test, not an opinion
The system’s repository has a script that runs WCAG 2.1, the accessibility standard, over 46 foreground/background pairs, in both themes, in CI. It’s not theater: it has already failed two colors that “looked fine”. One was a control border at 2.89:1 on a sunken surface, where the non-text minimum is 3:1. The other was the secondary button’s border, at 1.74:1. A new color enters the system through the same gate as any code: with verification that can say no.
The generalizable summary
- Share by measured layer, not by ambition. Tokens: everything. Primitives: as classes, the minimum all three emit identically. Compositions: nothing. Measure the ratio in your own CSS before disagreeing (here it came out ~92% screen-specific).
- The right sharing technology is what your poorest consumer can read. Here, custom properties, because one of the consumers is a Python f-string.
- Audited duplication is a reading format. An alias with a literal value plus a comparison script beats indirection only the browser can resolve.
- Generate what has namespace collisions; verify what is generated.
--checkin CI for everything copied or derived. - Dark theme: two doors, baseline outside the blocks,
color-schemealways. - Versioned copy with a silent-when-alone check is a legitimate distribution mechanism. For three heterogeneous consumers, it is more honest than a package.
- Contrast in CI. If accessibility can’t fail a merge, it’s an intention, not a property.
Need a custom technical project?
Architecture, TypeScript, APIs and automation, from prototype to production. The person answering your email is the one writing the code, and the deadline I promise is the one I can meet.
Send me a message →