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.
Code licensed MIT, docs CC BY 4.0.