Variable Declaration and Usage in Stylus: `$variable

In the Stylus preprocessor, variables form the foundation for building complex, maintainable style systems. They allow developers to encapsulate reusable values such as colors, dimensions, fonts, etc., thereby avoiding hard-coded magic numbers and strings. Stylus uses the $ symbol as a prefix for variable declaration, which is highly similar to Sass (SCSS) syntax; however, it also supports JavaScript-style const and let keywords, providing greater flexibility. Mastering the rules of declaring and using variables is the first step toward deeply understanding the Stylus compilation mechanism.
Stylus supports two primary methods for variable declaration: the traditional $variable_name syntax and the modern const/let syntax.

Traditional `$` Syntax

This is the most basic method of declaration, applicable to all types of values. Variable names follow identifier naming conventions, typically using lowercase letters, numbers, and underscores, but cannot start with a number.

// Declare a color variable
$primary-color = #3498db
$secondary-color = #2ecc71

// Declare a dimension variable
$spacing-unit = 8px
$container-width = 1200px

// Use variables in rules
body
  background $primary-color
  padding $spacing-unit

.container
  width $container-width

`const` and `let` Syntax

Stylus allows the use of JavaScript's const and let keywords to declare variables, which is very useful when handling more complex logic or distinguishing between constants and temporary values.

// const used for declaring immutable constants
const $brand-color = #e74c3c
const $max-width = 100%

// let used for declaring mutable variables (in Stylus, mainly used inside loops or functions)
let $counter = 0

body
  counter: (count++)

Variable Assignment and Type Conversion

Stylus variables are not merely simple string replacements; they support arithmetic operations and implicit type conversion. When you perform mathematical operations on variables in Stylus, it automatically converts relevant values to numbers or pixel units.

Numerical Operations

You can directly use operators such as addition, subtraction, multiplication, and division within variable expressions.

$base-size = 10px
$double-size = $base-size * 2
$incremented = $base-size + 5px

div
  font-size $double-size
  margin-top $incremented

Mixed String and Numerical Operations

Stylus allows assigning variables to other variables even if the source value contains a string part; it will attempt to parse numerical values within them.

$base = "10px"
$calculated = $base * 2 // Result automatically converts to "20px"

p
  padding $calculated

Nested Variables and Reference Mechanisms

Variables in Stylus support nested references, meaning you can use other variables to define new values. This feature greatly enhances code reusability, especially when dealing with color palettes or design systems.

Chained Assignment Example

Through chained referencing, you can build hierarchical style logic.

$base-color = #ffffff
$dark-text = $base-color + "30%" // Assuming mixing operations are supported; actual support depends on compiler version
// Or directly use the calculated color value
$accent-color = lighten($base-color, 20%)

header
  background $accent-color
  color $dark-text

Please note that some advanced color mixing operations may require specific plugins (such as cssmix) to work properly. Without a plugin, simple numerical addition and subtraction are universally supported.

Best Practices and Considerations

Following certain conventions when using Stylus variables can significantly improve code readability and maintenance efficiency.

Naming Conventions: It is recommended to use snake_case naming (lowercase letters combined with underscores), avoiding special characters or reserved words.
Scope Management: Although global variables in Stylus are very powerful, it is advisable to manage variables through module isolation in large projects to prevent name conflicts.
Type Checking: While Stylus performs automatic type conversion, it is recommended to explicitly define the expected type of a variable (such as px, %, or rgb()) at declaration time to avoid unexpected behavior.
Avoid Hardcoding: Minimize writing color values or dimensions directly in CSS rules; prefer referencing variables instead.

// Recommended practice
$border-radius = 4px
.card
  border-radius $border-radius

// Not recommended practice
.card
  border-radius 4px // Magic number, difficult to maintain

By mastering the declaration, assignment, and operation rules of variables, developers can utilize Stylus to build more elegant and logically clear style code. Whether it is simple theme switching or complex responsive layout design, variables are an indispensable cornerstone.