Reusing Button Styles in Stylus with Argumented Mixins

The Problem of Button Duplication

In a growing front‑end project you’ll often see dozens of .btn-primary, .btn-secondary, .btn-danger classes that all share the same border, padding, or hover logic. Each class adds a new block of CSS, inflating the stylesheet and making it hard to keep visual consistency. When a design change is required—say, a new border radius—you must hunt down every button class and edit it.

Argumented Mixins: The Solution

Stylus mixins are functions that emit CSS rules during compilation. By passing arguments you can generate many variations from a single definition. The mixin stays in one place, so a change to the base logic automatically propagates to all button instances.

Because mixins are resolved at compile time, there’s no runtime cost and no need to worry about browser support. The resulting CSS is plain, predictable, and can be inspected in the final file.

Practical Example

Below is a minimal buttons.styl file that defines a button() mixin. It accepts three parameters: background color, text color, and border radius.

/* buttons.styl */
// Mixin definition
button($bg, $color, $radius = 4px)
  background: $bg
  color: $color
  padding: 0.5rem 1rem
  border: none
  border-radius: $radius
  cursor: pointer
  transition: background 0.2s

  &:hover
    background: darken($bg, 10%)

// Usage examples
.btn-primary
  button(#0052cc, #fff, 6px)

.btn-secondary
  button(#6c757d, #fff)

.btn-danger
  button(#dc3545, #fff, 8px)

Compile the file with:

stylus buttons.styl -o dist/buttons.css

Open dist/buttons.css to confirm that each .btn‑* class contains the expected rules. Inspect an element in the browser dev‑tools to ensure the background, color, and radius match the arguments you supplied.

Trade‑offs and Limitations

• Debugging Complexity: Since the mixin expands during compilation, the source of a rule may not be obvious in the final CSS. Inspect the compiled file or use stylus --watch to keep the mapping clear.
• Parameter Explosion: Adding too many optional parameters (e.g., shadow, font-size, padding) can make the mixin call unreadable. Keep the interface simple and document each argument.
• Maintainability vs. Flexibility: A single mixin guarantees consistency, but it may restrict designers who want bespoke styles. Consider exposing a small set of common variants as separate mixins if needed.

Actionable Take‑away

1. Define a single button() mixin in a shared _mixins.styl file.
2. Use the mixin in every button class, passing only the values that differ.
3. When a design change is required, edit the mixin once and recompile.
4. Document each argument’s purpose so new developers can use the mixin without guessing.
5. Keep the number of parameters to a minimum; for more complex variations create separate mixins.

By centralizing button styles in a parameterised mixin you reduce duplication, simplify maintenance, and keep your CSS clean and predictable.