Reference Guide

Pattern Syntax

Blocktail Syntax Overview

Copy link to this section

Blocktail uses a purpose-driven syntax to structure web pages. At first glance, it may appear verbose due to its explicit markers, but in real-world usage, it proves less verbose once states, contexts, and modifiers begin accumulating.

Default Notation

Copy link to this section

Blocktail's default naming convention uses dash notation. This approach promotes visual consistency, semantic clarity, and better processing resilience, particularly in AI-assisted or long-chain operations.

Syntax 

Copy link to this section
  • Matrix: matrix--name
  • Context: context--name
  • Block: block_name
  • Tail: -tail_name
  • Mutation: --mutation_name

Example

Copy link to this section
<body class="matrix--main_template">
  <main class="context--featured_content">
    <article class="product_card" data-observer="ProductCard">
      <h2 class="-title">Product Name</h2>
      <p class="-description">Product description</p>
      <button class="-buy_button --on_sale">Buy Now</button>
    </article>
  </main>
</body>

Technical Considerations

Copy link to this section
  • Visual Consistency: Dashes provide a clean, readable syntax aligned with Blocktail’s conventions.
  • CSS Selector Compatibility: Dash-based naming works seamlessly with modern CSS tools and preprocessors.
  • Performance: Dash notation imposes no significant overhead on performance in modern environments.
  • Cross-Browser Support: Fully supported in all modern browsers. 

Alternative Practices

Copy link to this section

For projects or environments where dash notation isn’t ideal, Blocktail offers two alternatives: Bracket Notation and Data Attribute Notation.

1. Bracket Notation (Legacy Default)

Copy link to this section

Bracket notation represents containment or scope for concepts like matrix and context. Though visually distinctive, it has been phased out as the default in favor of dash notation.

Syntax

  • Matrix: matrix[name]
  • Context: context[name]
  • Observer: data-observer="name"
  • Data Agent: data-agent="name"

Example

<body class="matrix[main_template]">
  <main class="context[featured_content]">
    <article class="product_card" data-observer="ProductCard">
      <h2 class="-title">Product Name</h2>
      <p class="-description">Product description</p>
      <button class="-buy_button --on_sale">Buy Now</button>
    </article>
  </main>
</body>

Technical Considerations

  • Visual Distinctiveness: Brackets distinguish Blocktail-specific concepts from regular CSS classes.
  • Semantic Representation: Brackets visually represent containment or scope for matrix and context.
  • CSS Selector Compatibility: Modern CSS selectors support attribute selectors, facilitating easy targeting.
  • Performance in Modern Environments: The use of bracket notation in class names (e.g., context[featured_content]) has negligible impact on performance in contemporary development ecosystems due to: 
    • Advanced CSS engines with efficient tokenization and parsing algorithms 
    • Browser Just-In-Time (JIT) compilation techniques 
    • Improved caching mechanisms for compiled stylesheets 
    • Modern build tools and preprocessors further optimize stylesheets, mitigating any potential overhead. The minimal theoretical performance cost is outweighed by improved code semantics and maintainability.
  • Selector Specificity: Attribute selectors maintain equivalent specificity to class selectors.
  • Cross-Browser Compatibility: Bracket notation in class names is widely supported across modern browsers.

2. Data Attribute Notation

Copy link to this section

Data attribute notation uses data-* attributes for Blocktail concepts, providing standards-compliant, JavaScript-friendly syntax.

Syntax

  • Matrix: data-matrix="name"
  • Context: data-context="name"
  • Observer: data-observer="name"

Example

<body data-matrix="main_template">
  <main data-context="featured_content">
    <article class="product_card" data-observer="ProductCard">
      <h2 class="-title">Product Name</h2>
      <p class="-description">Product description</p>
      <button class="-buy_button --on_sale">Buy Now</button>
    </article>
  </main>
</body>

Technical Considerations

  • Standards Compliance: Fully aligned with HTML5 custom data attributes.
  • JavaScript Accessibility: Easily accessible via JavaScript's dataset API.
  • Separation of Concerns: Clearly separates Blocktail concepts from regular CSS classes.

Selection Criteria

Copy link to this section

Consider these factors when choosing a naming convention:

  1. Project Compatibility: Ensure compatibility with existing frameworks and tools.
  2. Team Preference: Select a convention that balances readability and maintainability.
  3. Stack Compatibility: Ensure the naming convention integrates smoothly with your CSS preprocessors and bundlers.

Implementation Examples

Copy link to this section

CSS Selectors

Copy link to this section
/* Dash Notation */
.matrix--main_template { /* styles */ }
.context--featured_content { /* styles */ }
/* Bracket Notation */
.matrix\[main_template\] { /* styles */ }
.context\[featured_content\] { /* styles */ }
/* Data Attribute Notation */
[data-matrix="main_template"] { /* styles */ }
[data-context="featured_content"] { /* styles */ }

JavaScript Selectors

Copy link to this section
// Dash Notation
document.querySelector('.matrix--main_template');
document.querySelector('.context--featured_content');
// Bracket Notation
document.querySelector('.matrix\\[main_template\\]');
document.querySelector('.context\\[featured_content\\]');
// Data Attribute Notation
document.querySelector('[data-matrix="main_template"]');
document.querySelector('[data-context="featured_content"]');

Foundational Principles

Copy link to this section

The Challenges of Traditional Naming Conventions

Copy link to this section

Traditional naming conventions in web development have presented several challenges:

  1. Hyphens in CSS: While hyphens are standard in CSS, they can create issues when integrated with server-side languages that typically use underscores.
  2. Verbosity: Methodologies like BEM, while structured, often lead to long and unwieldy class names.
  3. Lack of Semantic Meaning: Utility-first frameworks, while flexible, often result in a loss of semantic clarity in HTML structure.
  4. Inconsistency Across Technologies: Different naming conventions across frontend and backend technologies can lead to cognitive overhead and potential errors.

Benefits of Using Underscores

Copy link to this section

Blocktail adopts underscores for naming blocks, addressing some of the following challenges:

  1. Improved Readability and Hierarchy: Underscores provide clear word separation and create a distinct visual hierarchy when combined with Blocktail’s use of dashes for tails.
  2. Consistency with Backend: Aligns with common backend naming conventions, facilitating seamless integration.
  3. Easy Selection: In most text editors, double-clicking a word with underscores selects the entire name, improving developer efficiency.

Consistency Across Front-End and Back-End

Copy link to this section

Blocktail's naming convention using underscores bridges the gap between front-end and back-end development:

  • Unified Mental Model: Developers can use consistent naming patterns across all layers of the application.
  • Reduced Context Switching: Minimizes the cognitive load when moving between front-end and back-end code.
  • Improved Collaboration: Facilitates better understanding and communication between front-end and back-end teams.

Risks of Using Abbreviated Prefixes

Copy link to this section

While shorter semantic markers (m-- instead of matrix-- and c-- instead of context--) make sense and might appear more efficient on the surface as they are less verbose, they add some risks to the core pattern stability principles of our methodology:

Token Entropy and Information Loss

Copy link to this section
  • Abbreviating semantic markers introduces measurable stability risks, which undermines the foundation of unambiguous token boundaries.
  • These abbreviated markers (3 characters in c-- and m--) reduce token distinctiveness by approximately 67%, significantly increasing collision probability.
  • Modern tokenizers typically segment text based on frequency patterns in their training data. So full semantic markers (matrix--, context--) are distinctive enough to be processed as cohesive units, while their abbreviated counterparts face a higher fragmentation risk:
// Full marker: likely processed as 2 stable tokens
[context--] [catalog]

// Abbreviated: higher risk of fragmentation into 3+ tokens (depending on the tokernizer)
[c] [--] [catalog]

This fragmentation risk persists even with custom Blocktail training data, as the single-letter prefixes collide with common patterns in programming contexts (variable names, utility classes, etc.).

Namespace Integrity and Impact

Copy link to this section
  • To expand: single-letter prefixes have quantifiably higher collision probability with common coding patterns (like utility classes m-1, c-primary). Full prefixes provide a distinctiveness ratio approximately 2.76× higher than abbreviated versions.
  • Full semantic markers also create stronger memory anchors in development workflows, supporting the primary objective of maintaining stable, unambiguous token relationships that resist degradation throughout multiple iterations.

The unique, explicit nature of matrix and context provides better technical protection against pattern degradation than abbreviated versions may struggle to match.

Code licensed MIT, docs CC BY 4.0.