Implementation Guide Applying Blocktail naming conventions

Overview

Copy link to this section

This guide details Blocktail’s recommended naming conventions, including the default approach and approved alternatives

Default Practice: Bracket Notation

Copy link to this section

Blocktail's default naming convention uses bracket notation for specific elements to provide visual distinctiveness and semantic clarity.

Syntax

Copy link to this section
  • Matrix: matrix[name]
  • Context: context[name]
  • Observer: data-observer="name"
  • Data Agent: data-agent="name"
  • Block: block_name
  • Tail: -tail_name
  • Mutation: --mutation_name
  • UI Agent: ui--agent_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 ui--pulse_effect">Buy Now</button>
    </article>
  </main>
</body>

Technical Considerations

Copy link to this section
  1. Visual Distinctiveness: Brackets distinguish Blocktail-specific concepts from regular CSS classes.
  2. Semantic Representation: Brackets visually represent containment or scope for matrix and context.
  3. CSS Selector Compatibility: Modern CSS selectors support attribute selectors, facilitating easy targeting.
  4. 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: 
    1. Advanced CSS engines with efficient tokenization and parsing algorithms 
    2. Browser Just-In-Time (JIT) compilation techniques 
    3. Improved caching mechanisms for compiled stylesheets 
    4. 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.
  5. Selector Specificity: Bracket notation (attribute selectors) maintains equivalent specificity to class selectors, preserving a balanced specificity hierarchy.
  6. Cross-Browser Compatibility: Bracket notation in class names is widely supported, ensuring consistent behavior and styling across modern browsers.

Alternative Practices

Copy link to this section

Blocktail offers two alternative practices for situations where bracket notation may not be suitable.

1. Dash Notation

Copy link to this section

Dash notation offers a simple alternative when square brackets aren’t ideal, while still aligning with Blocktail’s mutation syntax for consistency

Syntax

  • Matrix: matrix--name
  • Context: context--name
  • Observer: observer--name

Example

<body class="matrix--main_template">
  <main class="context--featured_content">
    <article class="product_card observer--ProductCard">
      <!-- Content remains the same as in bracket notation -->
    </article>
  </main>
</body>

Technical Considerations

  1. Consistency: Aligns with Blocktail's existing use of double dashes for mutations.
  2. Parsing Compatibility: Avoids potential parsing issues associated with square brackets in certain environments.
  3. Familiarity: Similar to BEM-style naming conventions, which are widely used in the industry.

Update:

Recent tests suggest that dash notation (i.e., context--context_name) provides better pattern stability in Chain-of-Thought (CoT) operations. Since dash notation processes context markers as single tokens because it leverages consistent delimiters, it reduces pattern fragmentation and offers better resilience to CoT decay and pattern drift in long chain iterations.

Blocktail documentation will soon default to dash notation.  

2. Data Attribute Notation

Copy link to this section

Data attribute notation leverages HTML5 data attributes for Blocktail-specific concepts.

Syntax

  • Matrix: data-matrix="name"
  • Context: data-context="name"
  • Observer: data-observer="name" (same as default practice)

Example

<body data-matrix="main_template">
  <main data-context="featured_content">
    <article class="product_card" data-observer="ProductCard">
      <!-- Content remains the same as in bracket notation -->
    </article>
  </main>
</body>

Technical Considerations

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

Selection Criteria

Copy link to this section

Consider these factors when selecting a naming convention practice:

  1. Project and Codebase Compatibility: Consider framework limitations and how well the chosen convention integrates with the existing codebase
  2. Team Preference: Readability and maintainability for the development team.
  3. Browser Support: Compatibility with target browsers, especially if supporting older versions.
  4. CSS Selector Compatibility: Compatibility with CSS preprocessing setup.

Implementation Examples

Copy link to this section

CSS Selectors

Copy link to this section
/* Bracket Notation */
.matrix\[main_template\] { /* styles */ }
.context[featured_content] { /* styles */ }
/* Dash 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
// Bracket Notation
document.querySelector('.matrix\\[main_template\\]');
document.querySelector('.context\\[featured_content\\]');
// Dash 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"]');

Best Practices

Copy link to this section
  1. Consistency: Use a single naming convention throughout the project, avoiding mixed practices unless absolutely necessary.
  2. Semantic Naming: Use descriptive, meaningful names for blocks, contexts, and other elements.
  3. Documentation: Maintain clear documentation of the chosen convention for team reference.
  4. Tooling Support: Implement linters or other tools to enforce the chosen naming convention.

Implementation Strategies

Copy link to this section

Gradual Integration

Copy link to this section

Apply Blocktail conventions to new components first, then refactor existing ones:

<!-- New Blocktail component -->
<div class="context[new_feature]">
  <article class="product_card">
    <!-- ... -->
  </article>
</div>
<!-- Existing component (to be refactored later) -->
<div class="legacy-component">
  <!-- ... -->
</div>

Dynamic Class Generation 

Copy link to this section

Create helper functions for secure, server-side class name generation:

function formatContext($inputValue) {
    // Process or validate the context value based on some external logic
    $context = externalContextLogic($inputValue);
    // Fallback to a default context if the retrieved value isn't valid or available
    if (!$context) {
        $context = 'default_context';
    }
    return "context[" . $context . "]";
}
// Escape late when rendering the final class in HTML
echo '<div class="' . esc_attr(formatContext($inputValueFromDbOrApi)) . '">';

Note: Always use appropriate escaping functions (like esc_attr() in WordPress) to prevent XSS vulnerabilities, and always escape late.

Preprocessor Integration 

Copy link to this section

When using CSS preprocessors (SASS, LESS, Stylus), escape special characters in nested selectors:

.context {
 &\[featured_content\] {
   // Styles for featured content
 }
}

Complex Component Clarity

Copy link to this section

Use template literals or heredoc syntax for readability in complex scenarios:

const className = `
 product_card
 context[featured]
 ${isNew ? '--new_arrival' : ''}
`.trim().replace(/\s+/g, ' ');
// trim() removes leading/trailing whitespace
// replace() converts multiple spaces to a single space

Performance Optimization

Copy link to this section

Leverage modern techniques like CSS modules (shown here with React) and critical CSS:import styles from './ProductCard.module.css';

function ProductCard({ isFeatured }) {
 return (
   <div className={`${styles.product_card} ${isFeatured ? 'context[featured]' : ''}`}>
     {/* Component content */}
   </div>
 );
}

These strategies demonstrate Blocktail's flexibility and power, enabling you to create maintainable and performant web applications across various development scenarios and frameworks.
 


Blocktail's naming convention practices offer flexibility while maintaining clarity and consistency. The default bracket notation provides visual distinctiveness and semantic clarity, while the alternative dash and data attribute notations offer solutions for different project requirements. Select the practice that best aligns with project specifications and team preferences, and implement it consistently throughout the development process.