Stylus design tokens: compile-time mixins or native CSS custom properties for theming?

Recommendation: custom properties for your constraints

Given your two hard requirements — a dark-mode variant and per-brand overrides — native CSS custom properties are the better fit. They let one compiled stylesheet serve every theme by redefining values on a root or scoped selector, while mixins force a separate compiled stylesheet per theme. The size question also favors custom properties once tokens are referenced hundreds of times.

Output size with hundreds of references

A compile-time mixin expands the token's full value into every rule. If a token is used 500 times, its value appears 500 times in the output. Custom properties emit the value once and 500 short var(--token) references. For typical token values (hex colors, rem sizes), the custom-property output is smaller, and the gap widens as values get longer. Verify with your own token set rather than trusting a rule of thumb:

stylus tokens-mixins.styl -o mixins.css
stylus tokens-props.styl -o props.css
gzip -c mixins.css | wc -c
gzip -c props.css | wc -c

Gzip narrows the difference because repeated mixin expansions compress well, so compare gzipped sizes, not raw.

Runtime theming vs recompilation

With custom properties, dark mode is a selector, not a build:

:root
  --bg: #ffffff
  --fg: #111111

html[data-theme="dark"]
  --bg: #111111
  --fg: #eeeeee

body
  background var(--bg)
  color var(--fg)

Toggling data-theme on <html> switches the theme with no recompilation. Stylus 0.64.x (current stable line — confirm with stylus --version) compiles this without extra tooling, and @media (prefers-color-scheme: dark) works the same way. With mixins, each theme is a separate build artifact and switching requires shipping and swapping stylesheets.

The arithmetic pitfall you asked about

This is the real trap. Stylus variables resolve at compile time; var(--space) is an opaque string to Stylus. If a mixin does Stylus-level math on it, the multiplication runs against the literal string and produces invalid CSS:

// BAD: Stylus tries to compute var(--space) * 2 at compile time
double($s)
  padding $s * 2

// GOOD: arithmetic deferred to the browser via calc()
double($s)
  padding calc(%s * 2 % $s)

The safe rule: treat custom properties as opaque values inside Stylus and keep all arithmetic inside CSS calc(). Related pitfall: interpolation like --color: #{$brand} resolves $brand at compile time, so the custom property gets a static color, not a live reference to another token.

Scoping: two precedence systems

Your concern is correct. Stylus variables follow lexical/hierarchical override at build time; custom properties follow CSS cascade and inheritance at runtime. They are independent: overriding a Stylus variable never affects a custom property of the same name, and Stylus block scoping does not isolate custom properties — they inherit through the DOM unless shadowed by a nearer ancestor. To avoid confusion, pick one layer for each job: Stylus variables for build-time constants (breakpoints, file paths), custom properties for anything theme-dependent. Never mirror the same token in both.

When mixins still win

If you must support browsers without custom-property support (IE11, legacy Edge), mixins or a polyfill are mandatory — check your browser matrix against current support data before committing. Mixins also suit values that must feed compile-time logic (loops, conditionals, math) that genuinely cannot move into calc().

Uncertainty

Exact size savings depend on your token values and reference count — run the gzip comparison above. Stylus behavior described here assumes the 0.64 stable line; verify version-specific syntax against the installed release's documentation.