Naming Convention Principles for consistent and semantic code organization

Blocktail uses a unique syntax to structure web pages, which improves code readability and maintainability, and provides semantic clarity.

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.

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.

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.

Blocktail's syntax is particularly beneficial when working with Content Management Systems (CMS) and server-side languages:

Example in a PHP/WordPress context:

<?php
$post_type = get_post_type();
$is_featured = get_field('is_featured'); // Assuming ACF is used
$author_id = get_the_author_meta('ID');
?>
<article class="blog_post context[<?php echo $post_type; ?>] <?php echo $is_featured ? '--featured' : ''; ?>">
    <header class="-header">
        <h2 class="-title"><?php the_title(); ?></h2>
        <div class="-meta">
            <span class="-author context[author_<?php echo $author_id; ?>]"><?php the_author(); ?></span>
            <time class="-published_date"><?php the_date(); ?></time>
        </div>
    </header>
    <div class="-content">
        <?php the_content(); ?>
    </div>
    <footer class="-footer">
        <?php
        $categories = get_the_category();
        if (!empty($categories)) :
        ?>
            <div class="-categories">
                <?php foreach ($categories as $category) : ?>
                    <a href="<?php echo get_category_link($category->term_id); ?>" class="-category context[<?php echo $category->slug; ?>]">
                        <?php echo $category->name; ?>
    
                </a>
                <?php endforeach; ?>
            </div>
        <?php endif; ?>
        <div class="-tags">
            <?php
            $tags = get_the_tags();
            if ($tags) :
                foreach ($tags as $tag) :
            ?>
                <span class="-tag ui--clickable"><?php echo $tag->name; ?></span>
            <?php
                endforeach;
            endif;
            ?>
        </div>
    </footer>
</article>

Blocks are the fundamental building units in Blocktail. They represent self-contained, reusable components.

Syntax: Blocks are named using underscores (_) to separate words.

Example:

<article class="product_card">
  <div class="-content">
    <h2 class="-title">Ergonomic Mattress</h2>
    <p class="-description">Perfect for coding through the night without back-end issues!</p>
  </div>
</article>

Rationale:

• Improves readability for multi-word names
• Aligns with common programming naming conventions
• Distinguishes block names from other HTML classes

Tails represent specific elements or parts of a block.

Syntax: Tails are prefixed with a single dash (-).

Example:

<section class="features_section">
  <header class="section_header">
    <h2 class="section_title">[Section Title]</h2>
    <p class="section_subtitle">[Section Subtitle]</p>
  </header>
  
  <div class="features_grid">
    <!-- Example feature card -->
    <article class="feature_card">
      <img class="-icon" src="[icon-path].svg" alt="[Feature Icon]">
      <div class="-content">
        <h3 class="-title">[Feature Title]</h3>
        <p class="-description">[Feature Description]</p>
      </div>
    </article>
    <!-- Loop continues -->
  </div>
</section>

<!-- Testimonials Section -->
<section class="testimonials_section">
  <header class="section_header">
    <h2 class="section_title">Customer Testimonials</h2>
    <p class="section_subtitle">What Our Clients Are Saying</p>
  </header>
  <div class="testimonials_grid">
    <!-- Example testimonial card -->
    <article class="testimonial_card">
      <p class="-content">"[Testimonial Content]"</p>
      <span class="-author">- [Author Name], [Author Title]</span>
    </article>
    <!-- Loop continues -->
  </div>
</section>

<!-- Call-to-Action Section -->
<section class="cta_section">
  <div class="cta_content">
    <h2 class="-title">[CTA Title]</h2>
    <p class="-description">[CTA Description]</p>
    <button class="-button">[Button Text]</button>
  </div>
</section>

Rationale:

• Clearly distinguishes tails from blocks
• Enforces a flat structure within blocks, improving maintainability
• Visually separates block-level and element-level components

Mutations allow rapid, dynamic modifications to the visual states of blocks or tails, useful for scenarios like theming, status badges, or promotions.

Default Syntax: Mutations use a double dash (--).

Example:

<?php
// Assume these are ACF fields
$product_status = get_field('product_status'); // e.g., 'featured', 'clearance', 'new_arrival'
$price_display = get_field('price_display'); // e.g., 'regular', 'discounted', 'hidden'
$stock_status = get_field('stock_status'); // e.g., 'in_stock', 'low_stock', 'out_of_stock'
$color_theme = get_field('color_theme'); // e.g., 'light', 'dark', 'vibrant'
?>
<article class="product_card
    <?php echo $product_status ? '--' . esc_attr($product_status) : ''; ?> 
    <?php echo $color_theme ? '--theme_' . esc_attr($color_theme) : ''; ?>">
  <img class="-image" src="<?php echo esc_url(get_the_post_thumbnail_url()); ?>" alt="<?php echo esc_attr(get_the_title()); ?>">
  <div class="-content">
    <h3 class="-title"><?php echo esc_html(get_the_title()); ?></h3>
    <p class="-description"><?php echo esc_html(get_the_excerpt()); ?></p>
    <div class="-price_info --<?php echo esc_attr($price_display); ?>">
      <span class="-current_price"><?php echo esc_html(get_field('current_price')); ?></span>
      <?php if ($price_display === 'discounted') : ?>
        <span class="-original_price --strikethrough"><?php echo esc_html(get_field('original_price')); ?></span>
      <?php endif; ?>
    </div>
    <button class="-add_to_cart --<?php echo esc_attr($stock_status); ?>">
      <?php echo $stock_status === 'in_stock' ? 'Add to Cart' : ucwords(str_replace('_', ' ', $stock_status)); ?>
    </button>
  </div>
  <?php if ($product_status === 'new_arrival') : ?>
    <span class="-badge --new">New Arrival</span>
  <?php endif; ?>
</article>

Rationale:

• Distinctly identifies dynamic modifications
• Separates structural (blocks and tails) from behavioral (mutations) aspects
• Allows for easy application and removal of states

Contexts provide thematic or behavioral settings for blocks.

Default Syntax: Contexts are enclosed in square brackets [].

<?php
$user_role = get_user_role(); // e.g., 'admin', 'editor', 'subscriber'
$theme_mode = get_field('theme_mode', 'option'); // e.g., 'light', 'dark'
?>
<main class="dashboard context[role_<?php echo esc_attr($user_role); ?>] context[theme_<?php echo esc_attr($theme_mode); ?>]">
  <header class="dashboard_header">
    <h1 class="dashboard_title">Welcome, <?php echo esc_html(get_user_name()); ?></h1>
    <button class="theme_toggle ui--clickable">Toggle Theme</button>
  </header>

  <section class="user_stats">
    <?php if ($user_role === 'admin') : ?>
      <div class="-admin_stats">Admin-Specific Stats</div>
    <?php elseif ($user_role === 'editor') : ?>
      <div class="-editor_stats">Editor-Specific Stats</div>
    <?php else : ?>
      <div class="-subscriber_stats">Subscriber Stats</div>
    <?php endif; ?>
  </section>
</main>

Rationale:

• Clearly separates contextual information from structural classes
• Allows for multiple contexts to be applied
• Enhances readability of context-specific styling

Blocktail's syntax elements can be combined to create rich, expressive structures.

Best Practices:

• Maintain Flat Structure: Keep tails at a single level within blocks to preserve clarity.
• Use Semantic Names: Choose descriptive names for blocks and tails that reflect their purpose.
• Limit UI Agent Usage: Use UI Agents sparingly and only for micro-level adjustments.
• Consistent Naming: Establish and follow consistent naming conventions within your project.
• Context-Aware Design: Utilize contexts to create adaptable, reusable blocks.
• Matrix-First Approach: Use the Matrix to define the overall structure, ensuring a scalable framework for your page components.

Blocktail's syntax aims to address several challenges in web development by providing a structured system for organizing HTML and CSS. By using underscores for blocks, dashes for tails, and specific prefixes for different components, Blocktail seeks to offer a consistent approach across front-end and back-end environments.

This syntax is designed to be particularly suitable for complex, dynamic web applications and CMS-driven websites. As developers become familiar with Blocktail's syntax, they may find it facilitates the creation of maintainable and expressive code across their web development stack.

Also Read

• Implementation Guide
• Alignment of File Names and Class Names