Stylus css Literals: A Practical Escape Hatch for Unparsed CSS

Stylus is a preprocessor that rewards abstraction with variables, mixins and indentation-based syntax. The problem appears when you need a piece of CSS that Stylus should not touch: a vendor-specific hack, an experimental property the parser does not recognize, or a third-party snippet you must keep byte-for-byte. The useful takeaway is that Stylus provides a css literal to copy content verbatim to the output without parsing, interpolation or mixin expansion.

What a css literal does

A css literal is an escape hatch. Any content inside a css { ... } block, or passed to css('...'), is treated as literal text. Stylus copies it to the generated CSS exactly as written, skipping its parser, variable interpolation and built-in functions.

The literal can be used as a statement block:

css {
  -webkit-transform: rotate(30deg)
}

Or as a function call for inline snippets:

css('display: -webkit-box; display: flex')

Both forms preserve formatting and avoid errors from unknown syntax. Because the block is opaque to Stylus, there is no processing overhead for the literal itself; the compiled file size reflects only the raw CSS added.

When it is the right engineering choice

Integration of third-party CSS is the clearest case. Copying a vendor stylesheet into a Stylus file normally risks parser errors on non-standard comments or at-rules. Wrapping it in a css literal guarantees the output matches the source.

Vendor prefixes and experimental features are another case. If a property is new or has a syntax Stylus does not yet recognize, placing it inside a css literal prevents parse failures while still shipping the rule to browsers.

A concrete pattern is isolating an unparsed block inside an otherwise idiomatic component:

$brand = #1a73e8

.button
  color $brand
  padding 0.5rem 1rem
  css {
    -webkit-appearance: none
    appearance: none
  }

The $brand variable is processed normally. The css block is emitted verbatim. To verify behavior, compile a Stylus file with the stylus CLI from a local working directory with read access to the source and write access to the output directory:

npx stylus input.styl -o output.css

Inspect output.css for the exact lines from the css block. The expectation is the text appears unchanged, with no variable substitution inside the block. A quick check is to define a variable and reference it inside a css literal; the compiled output should show the literal $color text rather than the variable's value, confirming the block is opaque.

Trade-offs and limits

The escape hatch comes at a cost. Content inside a css literal cannot use Stylus variables, functions or mixins. That means you lose dynamic theming and DRY benefits inside the block.

Relying heavily on css literals defeats Stylus's abstraction advantages. Duplicated values become harder to change, and theme updates require edits in multiple places, some of which are now plain CSS.

Because the literal is opaque, tooling that relies on Stylus AST analysis, such as lint rules or automated refactoring, will not see inside it. Treat css literals as boundaries, not as a default style.

Actionable use

Use css literals sparingly and explicitly. Isolate them, comment why the escape is needed, and keep the surrounding code in idiomatic Stylus. Prefer Stylus-native features for normal styling and reserve the literal for truly unparseable or third-party content.

Review the compiled CSS after changes to ensure verbatim sections remain correct and have not drifted from their source. That manual check is the practical way to keep the escape hatch safe.