Mutations vs. Contexts Block-level variants vs. wrapper-level environments

Introduction

Copy link to this section

Mutations and contexts operate at different scales and serve distinct purposes.

Mutations: Element-Specific Modifications

Copy link to this section

Mutations provide targeted changes at the element level, enabling developers to easily create variants without duplicating code. They reduce the need for complex conditionals within CSS, ensuring both maintainability and a cleaner codebase

  • Matrix-level: <body class="matrix[main_template] --dark_theme">
  • Block-level: <div class="product_card --featured">
  • Tail-level: <div class="-title --breaking_news">

Key Characteristics of Mutations

Copy link to this section
  • Defines specific variations or states of an element
  • Can be toggled dynamically (e.g., via JavaScript)
  • Are tightly coupled to their target element

Contexts: Wrapper-Level Thematic Environments

Copy link to this section

Contexts are applied at a higher level than mutations and are meant to manage large-scale thematic changes. They provide developers with the flexibility to apply a broad set of rules that can cascade down through many elements without affecting individual component logic.

  • Applied to container elements: <main class="context[summer_sale]">
  • Influence multiple blocks or entire sections within the wrapper
  • Create a cohesive thematic environment for contained elements
  • Contexts offer a consistent foundation across sections of our site, improving scalability, reusability, and reducing redundancy

Key Characteristics of Contexts

Copy link to this section
  • Function as wrappers or containers for element groups
  • Operate independently of specific blocks or matrix structures, offering flexibility in application and reuse.

The Fundamental Distinction

Copy link to this section

The key distinction between mutations and contexts lies in their scope: contexts apply to wrapper-level elements and affect all contained elements, while mutations offer element-specific modifications tied directly to the blocks or components they modify.

  • Contexts are wrapper-level themes or states that create environments affecting all contained elements, regardless of specific blocks or matrix structure. They're easily repeatable across different parts of the site.
  • Mutations are element-specific modifications altering the state or appearance of a particular block or matrix. They're more directly tied to the elements they modify.

Example: Implementing a Dark Theme

Copy link to this section

Using Mutations (element-specific):

Copy link to this section
<body class="matrix[home_page] --dark_theme">
  <!-- Home page content -->
</body>
<body class="matrix[article_page] --dark_theme">
  <!-- Article page content -->
</body>

Using Contexts (wrapper-level):

Copy link to this section
<body class="matrix[home_page]">
  <div class="context[dark_theme]">
    <!-- Home page content -->
  </div>
</body>
<body class="matrix[article_page]">
  <div class="context[dark_theme]">
    <!-- Article page content -->
  </div>
</body>

In the context approach, context[dark_theme] serves as a wrapper consistently applicable across different matrices and pages, enhancing reusability and maintainability.

Best Practices

Copy link to this section

While mutations offer quick and easy ways to modify individual elements, contexts are ideal for managing broader themes. A combination of contexts for broad design control and mutations for granular changes can yield the most scalable and adaptable designs.

  1. Utilize contexts as wrappers to create thematic environments affecting multiple elements.
  2. Apply mutations directly to blocks or matrices for element-specific modifications.
  3. For changes requiring application across different structures, prefer contexts for better reusability.
  4. Maintain a library of reusable themes using contexts that are applicable independently of page structure.
  5. Reserve mutations for changes intrinsically tied to specific elements.