Reference Guide

Context vs. Mutations

In Blocktail, component adaptation happens through two distinct mechanisms: contexts and mutations. While contexts provide stable realities for blocks to exist within, mutations represent localized state changes.

Understanding the Difference

Copy link to this section

Contexts create environments where multiple blocks adapt their behavior and appearance. Mutations create specific variations for individual blocks. This separation ensures clear, predictable pattern evolution.

<!-- Context: Creates environment for multiple blocks -->
<main class="context--tech_posts">
  <article class="blog_post">...</article>
  <article class="blog_post">...</article>
</main>

<!-- Mutation: Modifies specific block -->
<article class="blog_post --featured">
  <h2 class="-title">Featured Post</h2>
</article>

Context

Copy link to this section

Like a chameleon adapting to its surroundings, blocks respond to their contextual environment:

<body class="matrix--blog">                  <!-- System context -->
  <main class="context--tech_posts">         <!-- Local context -->
    <article class="blog_post">              <!-- Block adapts to both -->
      <h2 class="-title">Tech Post</h2>
    </article>
  </main>
</body>

Contexts can nest to create layered environments:

<body class="matrix--blog">
  <main class="context--tech_posts">         <!-- Primary context -->
    <section class="context--featured">      <!-- Nested context -->
      <article class="blog_post">            <!-- Adapts to all -->
        <h2 class="-title">Post Title</h2>
      </article>
    </section>
  </main>
</body>

Mutation

Copy link to this section

Mutations transform individual blocks without affecting their siblings. They act like command-line flags, modifying specific component states:

<main class="context--tech_posts">
  <article class="blog_post --featured">     <!-- Featured state -->
    <h2 class="-title">Featured Post</h2>
  </article>
  
  <article class="blog_post">                <!-- Regular state -->
    <h2 class="-title">Regular Post</h2>
  </article>
</main>

Mutations can be combined for complex states:

<article class="blog_post --featured --breaking">
  <h2 class="-title">Breaking News</h2>
</article>

Pattern Evolution

Copy link to this section

Components maintain clear boundaries while evolving through different states:

<!-- Base Pattern -->
<main class="context--tech_posts">
  <article class="blog_post">
    <h2 class="-title">Post Title</h2>
  </article>
</main>

<!-- With Nested Context -->
<main class="context--tech_posts">
  <section class="context--featured">       
    <article class="blog_post">             <!-- Adapts to new context -->
      <h2 class="-title">Post Title</h2>
    </article>
  </section>
</main>

<!-- With State Changes -->
<main class="context--tech_posts">
  <section class="context--featured">
    <article class="blog_post --breaking">   <!-- Adds state -->
      <h2 class="-title">Post Title</h2>
    </article>
  </section>
</main>

Implementation

Copy link to this section

Context Variables

Copy link to this section

Contexts define environmental characteristics:

/* System-wide variables */
.matrix--blog {
  --spacing: 2rem;
  --accent: #0066cc;
}

/* Local environment variables */
.context--tech_posts {
  --code_background: #f4f4f4;
  --syntax_highlight: var(--accent);
}

Mutation States

Copy link to this section

Mutations define specific component variations:

.blog_post {
  /* Base structure */
  display: grid;
  gap: var(--spacing);
  
  /* State variations */
  &.--featured {
    border: 2px solid var(--accent);
  }
  
  &.--breaking {
    background: var(--accent);
    color: white;
  }
}

Block Superposition

Copy link to this section

Contexts and mutations enable blocks to exist in multiple states simultaneously, manifesting differently based on their environment and state flags:

<!-- One block definition, multiple realities -->
<body class="matrix--blog">
  <!-- In tech posts context -->
  <main class="context--tech_posts">
    <article class="blog_post">
      <h2 class="-title">Technical Post</h2>
      <div class="-content">
        <pre class="-code">...</pre>     <!-- Code block appears -->
      </div>
    </article>
  </main>

  <!-- In news context -->
  <main class="context--news">
    <article class="blog_post">          <!-- Same block -->
      <h2 class="-title">News Story</h2>
      <div class="-content">
        <div class="-summary">...</div>  <!-- Summary appears -->
      </div>
    </article>
  </main>
</body>

Tail Variations

Copy link to this section

Mutations allow tails to adapt while maintaining their relationship to the parent block:

<div class="grid_layout">
  <!-- Default column -->
  <div class="-column">
    Regular content
  </div>

  <!-- Wide column -->
  <div class="-column --span_2">
    Wider content
  </div>

  <!-- Featured column -->
  <div class="-column --featured">
    Featured content
  </div>
</div>
.grid_layout {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: var(--spacing);

  .-column {
    /* Base column structure */
    padding: var(--spacing);

    /* Column variations through mutations */
    &.--span_2 {
      grid-column: span 2;
    }

    &.--featured {
      background: var(--accent_bg);
      border: 2px solid var(--accent);
    }
  }
}

This approach to tail variations:

  • Maintains clear parent-child relationships
  • Enables flexible styling without new tails
  • Preserves semantic boundaries
  • Supports component reusability

Working Together

Copy link to this section

Contexts and mutations can coexist, each serving their distinct purpose:

<body class="matrix--blog">
  <main class="context--tech_posts">
    <!-- Featured post in tech context -->
    <article class="blog_post --featured">
      <h2 class="-title">Featured Tech Post</h2>
    </article>
    
    <!-- Draft post in same context -->
    <article class="blog_post --draft">
      <h2 class="-title">Draft Tech Post</h2>
    </article>
  </main>
</body>

This separation between environmental adaptation (contexts) and state transformation (mutations) ensures predictable pattern evolution while enabling both broad and specific modifications.

Code licensed MIT, docs CC BY 4.0.