Reference Guide

Layers and Boundaries

Blocktail organizes HTML structure into five distinct layers, each with specific boundaries and impacts. Understanding these layers is crucial for maintaining semantic clarity and ensuring predictable pattern evolution.

Understanding the Layer System

Copy link to this section

The layer system in Blocktail provides a clear hierarchy for organizing and structuring web components. Each layer serves a specific purpose and maintains clear boundaries with other layers.

L1: System Context Layer

Copy link to this section

The highest level of abstraction, serving as a simulation framework that defines the foundational environment for different contexts and blocks. Required only for full templates that include a <body> tag or serve as a root-level system context.

Marker: matrix--{context} (e.g., matrix--shop, matrix--admin_dashboard)

Important: The matrix-- marker should only be used when implementing full templates. For template partials, standalone sections, or widgets without a <body> tag, use the context-- marker instead.

Purpose:

  • Defines template-level context and system-wide boundaries
  • Serves as the root-level scope marker
  • Acts as the system context container

Impact:

  • Controls token hierarchy start point
  • Prevents token mixing between templates
  • Maintains clean template-level pattern boundaries
  • Ensures system-level token isolation

L2: Local Context Layer

Copy link to this section

Represents thematic environments within templates, grouping blocks by functionality or behavior.

Marker: context--{type} (e.g., context--premium)

Purpose:

  • Creates feature-level groupings
  • Maintains independence of contained blocks
  • Enables block adaptation within scope

Impact:

  • Groups related components logically
  • Maintains clean separation between contexts
  • Prevents context bleeding across boundaries
  • Enables contextual component adaptation
  • Preserves feature-level organization

L3: Component Reference Layer

Copy link to this section

Defines standalone, reusable blocks - the primary building units of our interface. Each block functions as an independent component with its own semantic boundary.

Marker: block_name (e.g., product_card)

Purpose:

  • Functions as independent component
  • Owns and contains all tails
  • Provides stable mutation anchor

Impact:

  • Establishes stable component references
  • Prevents pattern fragmentation
  • Maintains clear relationships between elements
  • Functions as anchor point for mutations

L4: Mutation Layer

Copy link to this section

Applies block-level mutations for specific behaviors or appearances. Mutations provide a flexible way to create variations and states for blocks.

Marker: --{mutation} (e.g., --featured, --premium, --on_sale, --active)

Purpose:

  • Modifies block patterns
  • Maintains reference stability
  • Ensures non-destructive changes

Impact:

  • Adds discrete state changes
  • Prevents pattern multiplication
  • Maintains base component stability
  • Ensures clean state transitions

L5: Element Layer

Copy link to this section

Defines sub-elements within a block, ensuring scoped relationships and ownership.

Marker: -{element} (e.g., -header, -title)

Purpose:

  • Exists only within parent block
  • Maintains structural relationship
  • Cannot exist independently

Impact:

  • Enforces single-parent relationship
  • Maintains proper scoping
  • Preserves clean structural patterns

Implementation Examples

Copy link to this section

Basic Layer Structure

Copy link to this section
<body class="matrix--shop">                    <!-- L1: System Context -->
  <main class="context--product_catalog">      <!-- L2: Local Context -->
    <article class="product_card">             <!-- L3: Component Reference -->
      <h2 class="-title">Product Name</h2>     <!-- L5: Element (Tail) -->
    </article>
  </main>
</body>

Block Structure Example

Copy link to this section
<!-- Basic Block Structure -->
<article class="product_card">               <!-- Block with underscore -->
  <h2 class="-title">Product Name</h2>      <!-- Simple tail -->
  <p class="-description">Description</p>    <!-- Simple tail -->
  <div class="-price_container">            <!-- Compound tail name -->
    <span class="-amount">$99</span>        <!-- Nested tail -->
  </div>
</article>
<!-- Block with Mutations -->
<article class="product_card --featured --premium">
  <h2 class="-title">Premium Product</h2>
  <div class="-price_container --discounted">
    <span class="-original">$199</span>
    <span class="-current">$149</span>
  </div>
</article>

Layer Interaction Rules

Copy link to this section
  1. System Context (L1) Rules:
    • Must wrap Local Context (L2) in full templates
    • Establishes root-level template scope
    • Contains and isolates all child patterns
  2. Local Context (L2) Rules:
    • Must wrap Component Reference (L3) blocks
    • Can be nested within other contexts
    • Provides thematic environment for blocks
  3. Component Reference (L3) Rules:
    • Functions as independent component
    • Uses underscores for compound names (e.g., product_card)
    • Never uses prefixes for basic blocks
    • Serves as container for Tails (L5)
    • Can receive Mutations (L4)
  4. Mutation (L4) Rules:
    • Can only modify Component Reference (L3) blocks
    • Multiple mutations can be combined
    • Must maintain block stability
  5. Tail (L5) Rules:
    • Must be scoped to Component Reference (L3) parent
    • Cannot exist independently
    • Maintains structural relationship to parent

Pattern Evolution Through Layers

Copy link to this section

Valid Evolution Paths

Copy link to this section
/* System Evolution Path */
matrix--shop                           // Template level
  context--product_catalog            // Environment level
    product_card                     // Component level
      --featured                    // State level
        -title                     // Element level
/* Context Evolution Path */
context--product_catalog             // Primary context
  context--featured                 // Nested context
    product_card                   // Adapts to both contexts
      --premium                   // Local mutation
        -price                   // Scoped tail
/* Mutation Evolution Path */
product_card                         // Base component
  product_card --featured          // Add featured state
    product_card --featured       // Add premium state
      --premium                  // Multiple mutations
/* Tail Evolution Path */
product_card                         // Parent component
  -title                           // Direct tail
    -content                      // Nested tail
      -price                     // Deep tail

Layer Validation

Copy link to this section
VALID_TEMPLATE = L1:matrix--{system} > L2:context--{theme} > L3:block_name  
VALID_PARTIAL  = L2:context--{theme} > L3:block_name
VALID_MUTATION = L3:block_name + L4:--{mutation}
VALID_TAIL = L3:block_name > L5:-tail

Benefits of Layer System

Copy link to this section

Clear Boundaries:

  • Each layer has a distinct purpose and scope
  • Prevents mixing of concerns
  • Maintains semantic clarity

Predictable Evolution:

  • Clear paths for component growth
  • Stable pattern recognition
  • Maintainable relationships

Improved Scalability:

  • Easy addition of new features
  • Clear integration points
  • Stable growth patterns

 

Code licensed MIT, docs CC BY 4.0.