Variable and Mixin Priority in the Stylus Guide

Stylus is renowned for its unique syntax and powerful capabilities within the realm of CSS preprocessors. Within this ecosystem, "variables" serve to centrally manage reusable resources such as colors and fonts, while "mixins" enable developers to encapsulate blocks of code and invoke them multiple times. However, when both variables and mixins coexist within the same scope, determining their execution order and priority relationships often confuses beginners. Mastering this mechanism is crucial for constructing modular and maintainable CSS architectures.

Stylus adheres to a "Top-Down" processing principle regarding the definition and invocation of variables and mixins. This implies that during parsing, the preprocessor processes instructions sequentially based on their order of appearance in the source code. If a variable or mixin block is defined within a specific scope before being referenced, that definition must be completed prior to its usage; conversely, referencing an identifier defined later but not yet declared will result in a compilation error.
Variables in Stylus are declared using the $ symbol. Their lifecycle and scope depend on their placement within the file and whether they are isolated using @mixin or similar scoping modifiers. Typically, global variables defined at the top level of the file are visible to all code blocks. However, when a local variable is defined inside a specific mixin, its scope is limited strictly to the execution context of that mixin block.

For instance, if we aim to reuse a color value within a complex graphical transformation, declaring $color globally or in a parent mixin is considered best practice:

$primary = #3498db
$text = #ecf0f1

@mixin button($size)
  background: $primary
  color: $text
  
  if $size is 'large'
    font-size: 24px

In the example above, code inside @mixin button can directly access $primary and $text. This is because variables are parsed and stored immediately upon declaration; when the mixin executes, it reads these pre-existing values. Attempting to define a global variable with the same name inside a mixin (e.g., var $name = value) will cause Stylus to treat it as a new local scope or replace the existing one depending on the specific version behavior, which is usually not the intended outcome.

Invocation and Parameter Passing Logic of Mixins

Mixins are the core tool for code reuse, allowing us to modularize complex CSS rules and apply them repeatedly. When using mixins, the order of parameter passing and the mechanism for default values are also constrained by the "Top-Down" rule. When invoking a mixin with multiple parameters, arguments must be provided strictly in the order defined in the parameter list; if necessary parameters are missing and no defaults are set, the compiler will throw an error.

Notably, Stylus mixins support nesting, but this does not imply simple recursive execution. When a variable is declared or another mixin is invoked inside a mixin block, the inner logic takes precedence over the outer one unless an explicit reference to the outer identifier is made. This feature of scope isolation allows us to safely share data across different mixin levels without conflicts.

@mixin card($bg-color, $text-color)
  background: $bg-color
  color: $text-color
  
  @mixin title()
    font-weight: bold
    
  // Internal variables do not affect the external scope unless explicitly referenced
  padding: 10px + ($bg-color is 'white' ? 5 : 2)

.card($red, $black).title()

In this example, the logic inside @mixin title() is completely independent of the $bg-color variable passed to the .card mixin. Even if a new color variable is defined within title, it will not automatically override parameters passed from the parent unless we perform an explicit assignment operation or rely on specific scope lifting rules.

Priority Conflicts and Resolution Strategies

When the same identifier (whether a variable name or a parameter name) is redefined in multiple mixin blocks, there is a risk of namespace pollution. Stylus does not automatically perform closure lookup to resolve external variable values like JavaScript does; instead, it tends to establish new scope bindings based on declaration order. Therefore, if $x is defined in mixin A and then redefined in mixin B (which is invoked by A), the definition in mixin B will shadow the former, resulting in the newly defined variable being accessed within mixin B.

To avoid such confusion and enhance code readability, it is recommended to follow these strategies:

  1. Avoid Duplicate Naming: Ensure that mixin blocks at different levels use distinct prefixes or namespaces to distinguish variables (e.g., $card-bg vs $global-theme).
  2. Utilize Default Parameters: Provide reasonable default values for all necessary parameters in the mixin definition to reduce verbosity during invocation.
  3. Explicit References: If a variable defined in an outer mixin needs to be used within a deep-nested mixin, try to reference it via a full identifier path or an explicit scope declaration rather than relying on implicit lookup mechanisms.
// Good practice example
@mixin theme($theme-name)
  $primary = get-color('blue', $theme-name) // Simulating function call
  
@mixin layout()
  background: #fff
  color: $primary // Referencing the variable value passed from the outer scope, not redefining it

.theme('dark').layout()

Summary and Best Practice Recommendations

In summary, the priority of variables and mixins in Stylus is not based on "who appears first takes precedence," but strictly follows the order of scope resolution during code execution. Understanding this mechanism helps developers build more robust stylesheet structures. In practical development, global constants should always be defined at the top of the file, business logic-related mixins placed in the middle, and data flow passed via parameters when necessary. Simultaneously, fully leverage Stylus's nesting features to organize complex style hierarchies, while remaining vigilant against variable name conflicts.

After mastering these rules, you can write code that adheres to CSS standards while capitalizing on the unique advantages of Stylus, achieving efficient asset management and logical reuse. Remember, clear naming and reasonable structure are always more important than attempting to bypass the compiler's scope limitations.