Stylus Transparent Mixins: Reusable CSS That Reads Like Plain CSS

You need vendor-prefixed border-radius in forty places. In Sass, that means forty @include border-radius(5px) lines — visually distinct from every normal declaration around them, and painful to revert if you later drop the mixin. Stylus takes a different route: its transparent mixins let a call site look exactly like an ordinary CSS declaration, so border-radius 5px can be either a real property or a function call, and nobody reading the file has to care which.

That transparency is the whole point of this piece. Used deliberately, it lets you introduce and retire abstractions without touching call sites. Used carelessly, it hides behavior from your teammates. Here's how to get the first outcome.

What a transparent mixin actually is

In Stylus, a mixin is defined with the same syntax as a function — a name followed by parameters — but it's invoked without any call keyword. There's no @mixin/@include pair. You define it once, then "declare" it anywhere:

// Define once
border-radius(n)
  -webkit-border-radius n
  -moz-border-radius n
  border-radius n

// Invoke like a normal declaration
.card
  border-radius 5px

.avatar
  border-radius 50%

Compiled output (Stylus 0.5x line; pin your exact version, since behavior can drift between releases):

.card {
  -webkit-border-radius: 5px;
  -moz-border-radius: 5px;
  border-radius: 5px;
}
.avatar {
  -webkit-border-radius: 50%;
  -moz-border-radius: 50%;
  border-radius: 50%;
}

Note the invocation: border-radius 5px with a space, no colon, no parentheses. Stylus also accepts border-radius(5px) if you prefer explicit call syntax — both resolve to the same mixin.

Why the transparency matters in practice

The engineering payoff shows up over a stylesheet's lifetime, not on day one:

• Swap a property for a mixin without rewriting call sites. Your file already says border-radius 5px everywhere as a plain property. When you decide you need prefixed output, you add the mixin definition — and every existing declaration silently upgrades. Delete the mixin later and the same lines fall back to plain CSS.
• Gradual adoption. Stylus is whitespace-flexible: braces, colons, and semicolons are optional. A team migrating an existing CSS file can paste it in nearly as-is and introduce mixins incrementally, rather than converting everything to a new syntax up front.
• Defaults and rest arguments. Mixins support default parameter values (shadow(x, y = 2px, blur = 4px)) and the arguments local variable, so helpers like multi-value transition prefixes are easy to write.

Running it in a build

Stylus is a Node.js package, so transparent mixins slot into standard pipelines. From your project root, with Node installed:

npm install --save-dev stylus@^0.59.0
npx stylus --watch src/styles --out dist/css

The --watch flag recompiles on save. For a bundler or custom script, the JavaScript API works too: require('stylus').render(source, callback). Pin the version in package.json — built-in functions and error messages have varied across releases, and a floating version is an invitation to a surprise diff in generated CSS. Before upgrading, compile your full source with both the old and new versions and diff the output; it's a five-minute check that catches version-sensitive behavior.

The shadowing trade-off you must manage

Transparency cuts both ways. If you name a mixin overflow or display, every genuine use of that property in the file now routes through your function. A reader — or a linter, or a new hire — sees standard CSS and gets nonstandard behavior. This is the most common real-world complaint about the feature.

Practical guardrails:

1. Only shadow properties you're intentionally enhancing. border-radius is the classic case because the mixin emits the standard property last, so behavior is a superset of the real thing.
2. Prefer explicit call syntax for anything non-obvious. Writing ellipsis(true) with parentheses signals "this is a function" while keeping the definition transparent-capable.
3. Enforce one formatting style. Because punctuation is optional, mixed styles across files can produce subtle parse differences. Pick indented or CSS-like syntax and hold the line in code review.

A caveat on the project itself

Stylus development has slowed considerably compared with Sass and the PostCSS ecosystem. The feature described here is long-established and stable, but before adopting Stylus for a new long-lived project, check the package's npm page and repository for recent release activity and open-issue volume. For an existing Stylus codebase, transparent mixins remain a perfectly sound tool — the risk calculus is about future maintenance, not current correctness.

Try it in ten minutes

Create a file with the border-radius mixin above, compile it with npx stylus, and confirm the output contains all three expanded properties. Then rename the mixin to overflow, add a real overflow hidden declaration somewhere, and recompile — watching how Stylus resolves the collision will teach you more about the shadowing risk than any documentation. If the output surprises you, that's your cue to adopt the explicit-parentheses convention before the codebase grows.