Variants

A variant is a name that maps to a CSS selector or @-rule. Inside a tl.create style group, an object keyed by a variant name represents conditional styles:

tl.create({
  btn: {
    background:    "blue",
    _hover:    { background: "darkblue" },     // variant: pseudo-class
    sm:        { padding: "0.5rem" },          // variant: breakpoint
    _dark:     { background: "white" },        // variant: parent selector
    _disabled: { opacity: 0.5 },
  },
});

Variants stack — combine them by nesting:

tl.create({
  btn: {
    color: "white",
    _hover: {
      color: "lightblue",
      _dark: { color: "yellow" },               // dark + hover
    },
    sm: {
      _hover: { color: "darkblue" },            // small-screen hover
    },
  },
});

Built-in variants

There are 76 built-in variants in five categories. Source of truth: src/compiler/variants.ts BUILT_IN_VARIANTS.

Pseudo-classes (23)

Pseudo-elements (11)

Parent / ancestor selectors (10)

Responsive breakpoints (5)

Container queries (3)

Special media queries (10)

Custom variants

Add your own variants with tl.extend({ variants: ... }). Both runtime and compiler discover them — at build time, Pass 1 scans every file for tl.extend({ variants: {...} }) calls, merges them into a single map, and Pass 2 uses that map when transforming tl.create calls. No central config required.

// app/variants.ts
import { tl } from "traceless-style";

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

// app/Card.tsx
const $ = tl.create({
  card: {
    padding: "1rem",
    _tablet: { padding: "2rem" },     // ✓ resolves to @media (min-width: 900px)
    _brand:  { color: "gold" },       // ✓ resolves to .my-brand & { color: gold }
  },
});

If your variant uses a multi-step selector with &, the & is replaced by a unique class. If it uses a parent-style selector with no & (like :is(.dark *)), it's used as-is.

Validation rules for custom variants

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

• Selector must be a non-empty string.
• Variant key must be a valid JS identifier (or quoted with ").
• Selector cannot contain raw ;, }, or other CSS-injection chars.
• @media / @container / @supports rules are recognized as at-rules and emitted at the top level.

Any validation failure becomes a build error pointing at the tl.extend call site.

Stacking variants

Variants can be nested inside one another. Each level extends the selector of the parent:

tl.create({
  btn: {
    background: "blue",
    _hover:  { background: "darkblue",
      _dark: { background: "black"  },     // → :is(.dark *):hover
    },
    sm: {                                  // → @media (min-width: 640px) { … }
      _hover: { background: "navy" },      // → @media (min-width: 640px) { :hover { … } }
    },
  },
});

Order doesn't matter for the compiled CSS — each unique (property, value, selector) combination becomes one rule, regardless of where it appeared in the source tree.

Variants vs. raw selectors

Sometimes you need a one-off selector that isn't worth defining as a custom variant. Any object key starting with :, &, [, ., @, or > is treated as a raw selector pass-through:

tl.create({
  list: {
    listStyle: "none",
    "& > li:not(:first-child)": { borderTop: "1px solid #eee" },
    "@media (min-resolution: 2dppx)": { borderWidth: "0.5px" },
  },
});

Raw selectors are still validated for injection-safety, but they are not stored in the variant registry.

Continue to 6. Design tokens & themes.