Mixed Parameter Default Values in the Stylus Guide

In Stylus CSS preprocessor, the use of variables significantly enhances code reusability and maintainability. However, when dealing with multiple source files or complex inheritance relationships, defining and passing parameter default values becomes a critical challenge. The concept of "mixed parameter default values" refers to setting initial values (i.e., defaults) for variables within a specific scope while allowing those values to be explicitly overridden by parameters at higher levels or in specific contexts. This design pattern not only simplifies the creation of base style files but also enhances component flexibility, enabling developers to start projects with "zero configuration" and perform precise customization when needed.

Stylus natively supports the var = value syntax for assigning default values during variable declaration. When you define a variable in a file without explicitly passing parameters at the call site, the preprocessor automatically uses the default value defined within that file. This mechanism is similar to function parameter defaults in JavaScript or custom properties (Custom Properties) in CSS. Its core value lies in reducing cognitive load: developers do not need to remember specific configuration items required for each component; they only need to focus on the business logic itself.
The first step to mastering mixed parameters is understanding how they are defined within a single scope. In Stylus, you can bind default values to variables using the var = value form. If the corresponding parameter name or value is not provided during a subsequent call, the system will backtrack and apply this preset value. This approach is particularly suitable for component scenarios that have standard behaviors but allow flexible extension.

Below is a typical single-file example demonstrating how to define a set of variables with default values:

// Basic style component: Card container
card-bg = #ffffff
border-radius = 8px
shadow-offset = 2px
text-color = #333333

.card-styles(var) when var is not defined
    background: card-bg
    border-radius: border-radius
    box-shadow: (var - shadow-offset) px solid rgba(0, 0, 0, 0.1)
    color: text-color

In the code above, the card-styles function receives an optional parameter var. If the caller does not pass this parameter (e.g., by writing .card {} directly), Stylus will automatically use the default value defined at the top of the file; conversely, if a specific numeric value is specified during the call (such as card-styles(10px)), it will prioritize the explicitly passed parameter. This mechanism ensures a balance between "out-of-the-box usability" and "high customization."

Parameter Inheritance and Override Strategies in Multi-File Collaboration

In actual large-scale projects, styles are often distributed across different files. At this point, "mixed parameter default values" need to collaborate across multiple scopes. Stylus's scope resolution rules determine that explicit definitions in child files take precedence over parent file or global defaults, unless specific module export mechanisms impose restrictions. This feature allows us to build a "Core Library + Theme Plugin" structure.

Assume we have a core core.styl file and a specific project configuration theme.styl. In core.styl, define the base variables:

// core.styl - Core style library
primary-color = #007bff
font-size-base = 16px
spacing-unit = 8px

.button(var) when var is not defined
    background: primary-color
    font-size: font-size-base + spacing-unit

In theme.styl (the project theme file), we can directly modify these variables or define new parameters to override the defaults:

// theme.styl - Specific theme configuration
primary-color = #e34a25 // Explicitly override the core library's default value
font-size-base = 18px   // Adjust base font size

.button(var) when var is not defined
    background: primary-color
    font-size: font-size-base + spacing-unit

The key here is that the variable definitions in theme.styl effectively become the "new defaults" within that scope. When the button() function is called within the theme file, it automatically applies primary-color = #e34a2a and font-size-base = 18px. This mechanism allows us to change component behavior by simply passing parameters or overriding scopes without modifying the core library source code.

Advanced Techniques: Dynamic Defaults and Conditional Logic

In addition to static numeric assignments, "mixed parameter default values" can be combined with Stylus's conditional compilation features (such as when, if) to implement more complex logic judgments as part of the default strategy. This allows variables not only to provide fallback data but also to automatically select optimal configurations based on the environment.

For example, we can define an intelligent spacing variable that has different default behaviors in development and production environments:

// utils.styl - Utility function library
is-dev = true // Assume this is a boolean flag

spacing-scale(var) when var is not defined and !dev-mode
    return spacing-unit * (var || 1.5) # Use larger multiplier for design preview
    
spacing-scale(var) when var is not defined and dev-mode
    return spacing-unit * (var || 0.8) # Compact layout for production

// Actual usage example
.container()
    padding: spacing-scale(4px) // Automatically calculates default value based on current mode

In this example, the logic inside the spacing-scale() function dynamically decides its "default" calculation formula based on is-dev (or a similar flag). If no parameter is passed externally, it still outputs a reasonable value consistent with the current environment expectations. This advanced usage elevates parameter flexibility to an algorithmic level, greatly enriching Stylus's expressiveness when handling complex style systems.

Summary and Best Practice Recommendations

In summary, "mixed parameter default values" are the cornerstone of building modular, maintainable CSS architectures. By reasonably utilizing the var = value syntax combined with scope override mechanisms, developers can create style component libraries that are both stable and flexible. During implementation, please adhere to the following principles:

Explicit Documentation: Write clear comments for each function or variable with default values, explaining their purpose and which parameters can override them.
Avoid Over-Reliance: While defaults are convenient, do not allow all users to ignore the opportunity to pass explicit parameters; encourage customized configuration for key style items.
Layered Design: Place basic logic in the core layer (containing universal defaults), and place specific requirements in the theme layer for overriding, maintaining clear code structure and decoupling.

Mastering this mechanism will enable you to write more robust, collaborative-friendly frontend engineering code, allowing Stylus to truly leverage its potential as a modern CSS preprocessor.