DEV Community: Jenny Akhi

tl.extend — Register Custom CSS Variants Anywhere in Your Codebase, No Central Config Required

Jenny Akhi — Tue, 23 Jun 2026 03:16:38 +0000

Every atomic-CSS system eventually hits the same wall: the built-in breakpoints and pseudo-classes are great — until the day you need something they never shipped with. A brand-specific selector. A retina-display query. A tablet breakpoint that doesn't match any of the defaults. Most tools force you to crack open one central config file, edit it, and hope you don't step on a teammate's PR.

traceless-style solves this differently with tl.extend — and the way it solves it is the most interesting part.

What `tl.extend` actually does

tl.extend registers custom variants. The key detail: both the runtime and the compiler discover them automatically. At build time, a first pass scans every file in the project for tl.extend({ variants: {...} }) calls and merges everything it finds into a single map. A second pass then uses that merged map whenever it transforms a tl.create call.

The practical result: there is no central registry file to maintain. You can define a custom variant in the same component file where you use it, in a shared theme.ts, or scattered across a dozen files — the compiler finds all of them and treats them as one unified vocabulary.

Signature

function extend(options: ExtendOptions): TracelessStyleInstance;

interface ExtendOptions {
  variants: Record<string, string>;
  prefix?:  string;
}

interface TracelessStyleInstance {
  create:   typeof create;
  merge:    typeof merge;
  cx:       typeof cx;
  variants: FlatVariants;
  errors:   VariantValidationError[];
}

variants is a flat map of variant-key → selector-string. The returned TracelessStyleInstance isn't just metadata — it's a fully working instance, with create, merge, and cx already bound to your new variants, plus a variants map and an errors array for anything that failed validation.

Example 1 — Simple custom variants

import { tl } from "traceless-style";

tl.extend({
  variants: {
    _tablet:    "@media (min-width: 900px)",
    _retina:    "@media (-webkit-min-device-pixel-ratio: 2)",
    _brand:     ".my-brand &",
    _hoverDark: ":is(.dark *):hover",
  },
});

// Use anywhere:
const $ = tl.create({
  card: {
    padding: "1rem",
    _tablet: { padding: "2rem" },
    _brand:  { color: "gold" },
  },
});

Once _tablet and _brand are registered, they behave exactly like any built-in variant key (_hover, _focus, etc.) inside any tl.create call, in any file, for the rest of the project.

Example 2 — Using the returned instance

const $$ = tl.extend({ variants: { _tablet: "@media (min-width: 900px)" } });

// Both global and returned forms work — variants are registered in one place.
$$.create({ card: { _tablet: { padding: "2rem" } } });
tl.create({ card: { _tablet: { padding: "2rem" } } });    // also works

This matters for larger codebases: you're never forced to choose between "import the global tl" and "use a scoped instance." Registration happens once, globally, and both access patterns stay in sync.

Example 3 — Validation errors

const result = tl.extend({
  variants: {
    "1bad": "...",       // invalid identifier
    foo:    "color: red; }", // CSS-injection
  },
});
console.log(result.errors);
// [
//   { key: "1bad", message: "Variant key must be a valid identifier" },
//   { key: "foo",  message: "Invalid selector: contains '}' or ';'" },
// ]

Instead of silently swallowing a bad key or letting a malformed selector leak raw CSS-injection characters into the generated stylesheet, tl.extend returns a structured errors array you can inspect programmatically. The docs also note these same errors are surfaced as console.warn at runtime, so you get a heads-up even if you never check .errors directly.

Selector forms

Form	Example	Compiled to
Pseudo-class	`_xyz: ":xyz"`	`.tl<hash>:xyz { … }`
Pseudo-element	`_xyz: "::xyz"`	`.tl<hash>::xyz { … }`
&-anchored ancestor	`_xyz: ".parent &"`	`.parent .tl<hash> { … }`
&-anchored sibling	`_xyz: ".peer ~ &"`	`.peer ~ .tl<hash> { … }`
Media query	`_xyz: "@media …"`	`@media … { .tl<hash> { … } }`
Container query	`_xyz: "@container …"`	`@container … { .tl<hash> { … } }`
Supports query	`_xyz: "@supports …"`	`@supports … { .tl<hash> { … } }`

Two rules govern the & token: if your selector is a multi-step selector that uses & (like .parent &), the & gets replaced by the unique generated class. If it's a parent-style selector with no & at all (like :is(.dark *)), it's used exactly as written.

Validation rules

Custom variant selectors are validated by validateVariant() (src/compiler/variants.ts), enforcing:

The selector must be a non-empty string.
The variant key must be a valid JS identifier (or quoted with ").
The selector cannot contain raw ;, }, or other CSS-injection characters.
@media / @container / @supports rules are explicitly recognized as at-rules.

Why this fits the bigger traceless-style picture

tl.extend's "no central config" design isn't a one-off trick — it's the same philosophy running through the entire library. traceless-style is a zero-runtime atomic CSS toolkit for React, Next.js, Vite, Remix, Astro, SvelteKit, Qwik, and Solid, built around build-time extraction instead of a runtime CSS-in-JS engine — no Tailwind dependency, no Babel plugin required.

npm install traceless-style
npx traceless-style init

init detects your framework, wires the bundler plugin, and generates your CSS entry — the same two-pass compiler that scans for tl.extend calls is also what powers:

WCAG 2.1 + 2.2 contrast validation on every build — AA 4.5:1 / AAA 7:1 / UI 3:1 / focus 3:1 enforced before CSS ever hits disk, with an APCA Lc readout in every diagnostic and an interactive --fix-contrast prompt.
Auto dark mode — every color you write gets a derived dark variant via <TracelessRoot />, with pair-aware contrast preservation, overridable per-block via _dark.
Auto RTL — physical properties like marginLeft rewrite to logical equivalents like marginInlineStart at build time, so one stylesheet serves every script direction.
Strict-by-default lint — inline styles, string classNames, CSS Modules, and Tailwind utilities are blocked outright, backed by a property allowlist and value-injection guards.
Diagnostic codes — every error and warning carries a stable TLS#### identifier you can grep and link to docs.
Two parsers — a zero-native-deps scanner for smaller projects, and an SWC-backed AST extractor that's nearly 2× faster on 500-file codebases, with auto picking the right one for you.

How it stacks up against the usual suspects, straight from the project's own comparison:

	Tailwind	styled-components	CSS Modules	traceless-style
Zero runtime	✓	✗	✓	✓
Type-safe styles	✗	partial	partial	✓
Atomic dedup	✓	✗	✗	✓
WCAG contrast at build time	✗	✗	✗	✓
Auto dark mode	✗	manual	manual	✓
Auto RTL (logical properties)	✗	manual	manual	✓
No bundler plugin to install	✗	✓	✓	✓ (zero-config init)

There's also tooling around all of this: a VS Code extension (autocomplete across 280+ properties, inline color swatches, hover docs, quick-fix diagnostics) and a DevTools browser extension for live class inspection and cascade conflict warnings.

Wrap-up

tl.extend is a small API with an outsized consequence: it lets a design system's vocabulary grow the same way the codebase does — organically, file by file — instead of forcing every new breakpoint or brand selector through a single config bottleneck. Combined with the validation layer catching bad identifiers and injection attempts before they reach your stylesheet, it's a genuinely safe way to extend an atomic CSS system at scale.

Full docs: https://github.com/sparkgoldentech/traceless-style

tl.merge — The Last-Wins Conflict Resolver That Makes Atomic CSS Composition Actually Safe

Jenny Akhi — Mon, 22 Jun 2026 13:38:45 +0000

If you've ever written a reusable component and accepted a className prop from the outside world, you already know the quiet horror that follows: which class wins? You append it, you prepend it, you cross your fingers — and depending on CSS specificity, source order, or sheer luck, the wrong color shows up in production.

traceless-style solves this with one small, sharply-defined function: tl.merge. Let's take it apart piece by piece.

What `tl.merge` actually is

Per the official docs, tl.merge is described as:

Last-wins conflict-aware class joining. Reads compile-time-injected metadata to deterministically pick the latest input that sets each property.

That single sentence is doing a lot of work, so let's unpack the two halves separately:

"Last-wins" — when two classes you pass in both touch the same CSS property, the one that appears later in the argument list is the one that survives.
"Conflict-aware" — it doesn't just dedupe strings. It actually knows which property each class controls, so it can tell that color: white and color: red are fighting over the same thing, even though they look like two unrelated tokens.

The signature

function merge(
  ...inputs: (string | undefined | null | false | 0)[]
): string;

A few things worth noticing immediately:

It's a variadic function — pass as many class strings as you want.
The accepted types aren't just string. undefined, null, false, and 0 are all valid inputs too — which is the first clue that this function is designed to sit directly inside conditional JSX expressions like isActive && $.active.
It always returns a single string, ready to drop straight into a className attribute.

How it behaves, step by step

The behavior section of the docs lays out a very precise, deterministic algorithm:

Falsy inputs are silently dropped. undefined, null, false, 0, and "" simply vanish — no errors, no "false" strings leaking into your markup.
Each non-empty input is split on whitespace. So if one of your inputs is actually several space-separated classes, they're treated individually, not as one atomic blob.
For each individual class, tl.merge looks up __TRACELESS_STYLE_META__[class] to find out which property key that specific class controls.
The last class for each property key wins. Not the last input — the last individual class, once everything has been split apart.
Classes that aren't found in the meta map are preserved as-is, in input order. So unknown/foreign classes (think: a class from a totally different library) are never dropped — they're just not part of the conflict-resolution logic.
The final result is a single space-joined string.

That fourth point is the heart of the whole function. It's not "last argument wins" — it's "last property-setter wins", which matters once you start composing several style objects together.

Example 1 — Basic conflict resolution

const base   = tl.create({ b: { color: "white", padding: "8px" } });
const danger = tl.create({ d: { color: "red"                   } });

tl.merge(base.b, danger.d);
// → "tl tl"   (color:white dropped)

Here, base.b sets two properties: color and padding. danger.d only sets color. Since danger.d comes after base.b in the argument list, its color: red overrides base.b's color: white. The padding: 8px from base.b is untouched because nothing later in the call touches padding at all. Notice the white color class doesn't just get "deprioritized" — it's gone entirely from the output.

Example 2 — Conditional override

const $ = tl.create({
  base:   { color: "black", padding: "8px" },
  active: { color: "blue" },
  error:  { color: "red"  },
});

tl.merge($.base, isActive && $.active, isError && $.error);
// only the LAST truthy color wins

This is where the falsy-input handling really shines. If isActive is false, that argument collapses to false and is dropped before the merge logic even runs. If both isActive and isError are true, then $.error's color: red wins simply because it's evaluated last in the list — $.active's blue never makes it into the final string. You get a single, predictable rule for "which state's color shows up," no matter how many boolean flags you're juggling.

Example 3 — Component prop forwarding

function Card({ className, children }: {
  className?: string;
  children: React.ReactNode;
}) {
  const $ = tl.create({ card: { padding: "1rem", background: "white" } });
  return (

      {children}

  );
}

// Caller's className wins on any conflicting property:

This is the pattern most component libraries desperately need and rarely get right: a component defines its own default styles (padding, background), but if the caller passes a className that also sets background, the caller's value wins — because it's the last argument to tl.merge. The component's padding survives untouched since the caller never mentioned it. No specificity wars, no !important, no guessing about CSS source order.

Why `__TRACELESS_STYLE_META__` matters

This is arguably the most important section in the whole page, because it explains why tl.merge can be this reliable in the first place.

Without that compile-time meta map, tl.merge would have no way of knowing that two differently-named classes both control color. It could only fall back to set-deduplication — removing exact duplicate strings, but leaving genuine property conflicts sitting right there in the output:

// With meta:    "tl tl"
// Without meta: "tl tl tl"
//                ↑ kept, even though it's overridden — last in HTML wins,
//                  which works for this trivial case but is unreliable
//                  with raw selector overrides.

Look closely at that second line: tl<color-white> is still in the string. In the simplest cases, "last class in the HTML wins" happens to produce the right visual result by coincidence of CSS cascade order. But the docs are explicit that this is unreliable with raw selector overrides — meaning the moment something more complex than basic cascade order is in play, that leftover dead class becomes a real bug waiting to happen, not just visual noise.

This is exactly what the meta map prevents: it lets tl.merge actually remove the loser instead of hoping the browser's cascade rules paper over it.

Where the meta map comes from

The docs note that the Webpack/Next.js plugin injects the meta map automatically via DefinePlugin — so in a normal bundled app, you never touch this yourself.

But for test environments running outside the bundler, the docs show this escape hatch:

import { __setMeta } from "traceless-style";
__setMeta({ "tla1b2c3d4": "color", /* ... */ });

This is a small but crucial detail for anyone writing unit tests for components that use tl.merge — without calling __setMeta first, your tests would be exercising the "no meta" fallback path, not the real production behavior.

Putting it all together

What happens
|

|

If there's a single sentence to walk away with, it's this: tl.merge resolves conflicts by property, not by string identity — and that distinction is only possible because of the compile-time metadata sitting behind it.

My CSS workflow: 🧑‍💻

Jenny Akhi — Fri, 19 Jun 2026 04:06:57 +0000

Write 3 lines of clean CSS.
Everything looks perfect.
Add border-radius: 5px; -> Entire layout collapses and disappears into another dimension.
Who relates? 😂 👇

Stop Bloating Your JS Bundle: Mastering Zero-Runtime CSS with traceless-style ⚡

Jenny Akhi — Thu, 18 Jun 2026 20:32:10 +0000

Let's cut the fluff. If you are still shipping massive JavaScript bundles just to calculate CSS styles in the browser, you are bottlenecking your Core Web Vitals. Let's look at how to handle styling at compile time, completely stripping out the runtime overhead.

The entry point for this architecture in traceless-style is the tl.create API. It accepts a single argument: an object where the keys are arbitrary names you choose, and the values are literal style definitions.
Here is exactly what defining a component looks like:

javascript

import { tl } from "traceless-style"; const $ = tl.create({ card: { display: "flex", flexDirection: "column", padding: "1rem", background: "#ffffff", borderRadius: "8px", boxShadow: "0 1px 3px rgba(0,0,0,0.1)", _hover: { boxShadow: "0 4px 12px rgba(0,0,0,0.15)", },

title: {
fontSize: "1.25rem",
fontWeight: 600,
marginBottom: "0.5rem"

What makes this powerful is what happens next. A strict literal-only AST parser locates the tl.create call at build time, validates properties against a strict allowlist, and hashes each property-value pair into an 8-character base36 class name.
After compilation, the object above is entirely stripped from your bundle and replaced with pure string hashes:`

javascript

// After compilation: const $ = { card: "tl12abcd34 tl56efgh78 tl9ab0c1d2 tl3e4f5g6h tl7i8j9k0l tlmnopqrst tluvwxyz12", title: "tl34567890 tlabcdefgh tlijklmnop", };Because the compiler needs to know every value at compile time to emit the matching CSS rule, dynamic variables are strictly rejected. If you try to pass color: myColor or use a template literal, the parser will throw a ParseError. If you need dynamic values, you use compile-time resolved design tokens (tl.defineTokens), not runtime JavaScript.
You also get full composition and built-in variants as standard object keys. Pseudo-classes, breakpoints, and dark mode overrides are handled instantly:

javascript

tl.create({ myStyle: { color: "white", _hover: { color: "lightblue" }, sm: { padding: "0.5rem" }, // breakpoint _dark: { background: "black" }, // dark mode override "&:nth-child(odd)": { background: "#f0f0f0" }, // raw selector pass-through }, });Pre-compile it, hash it, and ship zero runtime. Have you migrated your frontend stack to strict build-time styling yet?

https://github.com/sparkgoldentech/traceless-style/blob/main/docs/api/create.md

Why are we still shipping CSS parser code to the browser?

Jenny Akhi — Thu, 18 Jun 2026 03:26:27 +0000

Serious question to all frontend developers: Why do we still accept bundle bloat and LCP lag just for dynamic styling?
If we can achieve the exact same dynamic flexibility using a 10ms build-time scanner with 0ms runtime architecture, why hasn't zero-runtime become the absolute industry standard yet?
What are the actual trade-offs that keep you using heavy runtime CSS-in-JS libraries in 2026? Let’s discuss.

traceless-style vs Tailwind vs StyleX vs styled-components — an honest comparison

Jenny Akhi — Wed, 17 Jun 2026 10:46:31 +0000

Every CSS-in-JS and atomic CSS library makes different tradeoffs. This post compares traceless-style, Tailwind, StyleX, and styled-components across the dimensions that matter for a real project.

All information below is drawn from the official documentation of each library.

The comparison

Feature	traceless-style	StyleX	Tailwind	styled-components
Runtime cost	None (fallback hash only)	None	None	High (hash + insertRule per render)
Atomic CSS	Yes	Yes	Yes	No
Build-time deduplication	Yes	Yes	n/a	No
Babel plugin required	No	Yes	n/a	n/a
Arbitrary CSS values	Yes	Yes	No (config-only)	Yes
Built-in WCAG contrast validation	Yes (build-time, halts build)	No	No	No
Auto dark mode derivation	Yes (WCAG-compliant)	No	Plugin-based	No
Auto RTL (compile-time)	Yes	No	Plugin-based	No
Design tokens + TypeScript safety	Yes	Yes	Yes (config)	Partial
Server Components	Yes	Yes	Yes	Partially
VS Code extension	Yes	Yes	Yes	Partial
WCAG 2.2 §2.4.13 focus checks	Yes	No	No	No

What traceless-style is not

The docs are explicit about this and it matters:

Not a Tailwind replacement. Tailwind ships a fixed utility vocabulary (bg-red-500, px-4). traceless-style accepts arbitrary CSS values (background: "red", padding: "1rem"). There is no shorthand utility syntax.
Not a styled-components replacement. There is no template-tag DSL, no styled.button API. Styles attach to elements via className= only.
Not a CSS-in-JS library in the traditional sense. Nothing runs at render time except a deterministic hash used as a runtime fallback for SSR and non-bundled test environments.

When traceless-style is the right choice

You have an accessibility compliance requirement (Section 508, EN 301 549) and want to automate WCAG enforcement instead of relying on manual audits.
You want zero runtime cost and don't want a Babel plugin in your build chain.
You want auto dark mode and auto RTL without managing two stylesheets or writing every property twice.
You're starting a new project and want design-token TypeScript safety from day one.

Getting started

npm install traceless-style
npx traceless-style init

Docs: https://traceless-style.dev
GitHub: https://github.com/sparkgoldentech/traceless-style

DEV Community: Jenny Akhi

tl.extend — Register Custom CSS Variants Anywhere in Your Codebase, No Central Config Required

What tl.extend actually does

Signature

Example 1 — Simple custom variants

Example 2 — Using the returned instance

Example 3 — Validation errors

Selector forms

Validation rules

Why this fits the bigger traceless-style picture

Wrap-up

tl.merge — The Last-Wins Conflict Resolver That Makes Atomic CSS Composition Actually Safe

What tl.merge actually is

The signature

How it behaves, step by step

Example 1 — Basic conflict resolution

Example 2 — Conditional override

Example 3 — Component prop forwarding

Why __TRACELESS_STYLE_META__ matters

Where the meta map comes from

Putting it all together

|

See also

My CSS workflow: 🧑‍💻

Stop Bloating Your JS Bundle: Mastering Zero-Runtime CSS with traceless-style ⚡

Why are we still shipping CSS parser code to the browser?

traceless-style vs Tailwind vs StyleX vs styled-components — an honest comparison

The comparison

What traceless-style is not

When traceless-style is the right choice

Getting started

What `tl.extend` actually does

What `tl.merge` actually is

Why `__TRACELESS_STYLE_META__` matters