Reference Guide

Implementation Guide

Integrating Blocktail into AI Workflow

Copy link to this section

AI models currently in use have not been trained on datasets that include Blocktail’s methodology. As a result, they lack inherent familiarity with its structured approach to layers, boundaries, and their interactions. 

To address this gap, this Blocktail Reference Guide can serve as a practical resource for integrating its principles into your AI-driven workflows. Integrating this guide into your custom AI models—such as through knowledge bases or custom GPTs—provides the model with the context needed to produce code that adheres to Blocktail’s structured practices.

Note: To keep the content easier to process, the guide focuses on Blocktail’s core principles and does not include advanced concepts like Observer vs. Agent Behavioral Patterns.

Learn more about Integration Advantages →

Layout Implementation Example

Copy link to this section

This example showcases a task management interface built with Blocktail principles, demonstrating proper pattern usage and behavioral layer implementation.

<!-- Matrix: System-wide template -->
<!-- ✓ DO: Use matrix-- only at root/body level -->
<!-- ✗ DON'T: Use matrix-- in nested elements -->
<body class="matrix--task_app">
 
 <!-- Context: Theme environment -->
 <!-- ✓ DO: Use single context with compound name -->
 <!-- ✗ DON'T: Combine multiple contexts in one element -->
 <div class="context--pro_theme">
   
   <!-- Block: Header -->
   <!-- ✓ DO: Add observer for interactive components -->
   <!-- ✗ DON'T: Mix observers with non-block elements -->
   <header class="app_header"
           data-observer="HeaderObserver">
     <!-- ✓ DO: Use simple, semantic tail names -->
     <!-- ✗ DON'T: Use underscores in tail names -->
     <h1 class="-title">{app_name}</h1>
     <button class="-toggle" 
             data-action="theme">{theme_icon}</button>
   </header>
   <!-- Context: Workspace -->
   <!-- ✓ DO: Keep contexts at their own level -->
   <!-- ✗ DON'T: Nest contexts unnecessarily -->
   <main class="context--workspace">
     
     <!-- Block: Task List -->
     <!-- ✓ DO: Use agent for utility features on non-interactive blocks -->
     <!-- ✗ DON'T: Mix observer and agent on same block -->
     <div class="task_list"
          data-agent="InfiniteScroll">
       <!-- Block: Task Item -->
       <!-- ✓ DO: Use mutations for state variations -->
       <!-- ✗ DON'T: Create new blocks for different states -->
       <div class="task_item --completed --priority">
         <span class="-name">{task_name}</span>
         <span class="-date">{date}</span>
         <button class="-action" 
                 data-action="toggle">{action_icon}</button>
       </div>
     </div>
     <!-- Block: Statistics -->
     <!-- ✓ DO: Use semantic block names -->
     <!-- ✗ DON'T: Create tails for block-level structures -->
     <div class="task_stats">
       <div class="-item">
         <span class="-label">Completed</span>
         <span class="-value">{completed_count}</span>
       </div>
     </div>
   </main>
   <!-- Context: Sidebar -->
   <!-- ✓ DO: Use context for layout sections -->
   <!-- ✗ DON'T: Use context for state changes -->
   <aside class="context--sidebar">
     
     <!-- Block: Quick Add -->
     <!-- ✓ DO: Use observer for form handling -->
     <!-- ✗ DON'T: Mix observers with tails -->
     <div class="quick_add">
       <button class="-toggle" 
               data-action="show">+</button>
       
       <!-- ✓ DO: Use mutations for visibility states -->
       <!-- ✗ DON'T: Create new tails for states -->
       <form class="-form --hidden">
         <input class="-input" 
                type="text" 
                placeholder="{input_placeholder}">
         <button class="-submit" 
                 type="submit">Add Task</button>
       </form>
     </div>
     <!-- Block: Filter -->
     <!-- ✓ DO: Use mutations for selection state -->
     <!-- ✗ DON'T: Use style-based mutations -->
     <div class="task_filter">
       <button class="-option --selected">All Tasks</button>
       <button class="-option">Active</button>
     </div>
   </aside>
 </div>
</body>

System and Context Structure

Copy link to this section

The application uses matrix--task_app at the root level with clear context separation via context--pro_theme, context--workspace, and context--sidebar.

Behavioral Layer

Copy link to this section
  • Header block demonstrates Observer pattern (data-observer="HeaderObserver") for managing interactive state
  • Task list shows Agent pattern (data-agent="InfiniteScroll") for utility enhancement
  • Only one behavior pattern per block maintains clear ownership

Block and Tail Structure

Copy link to this section

Blocks use semantic names with underscores (app_header, task_list, task_stats) while tails use simple, hyphen-prefixed names (-title, -toggle, -name).

State Management

Copy link to this section

Mutations handle state variations (--completed, --priority, --hidden, --selected) without creating new blocks or tails for different states. Action attributes (data-action) provide clear interaction hooks.

This layout implementation demonstrates how Blocktail's patterns work together to create maintainable, semantically clear interfaces while preserving proper behavioral boundaries.

FAQ: Implementation

Copy link to this section

Why use markers instead of introducing new HTML elements?

Copy link to this section

Introducing new HTML elements, such as <context>, would require W3C standardization to be universally supported. Until Blocktail adoption becomes widespread, markers like context--name serve as a practical and seamless solution that works across all browsers and platforms without additional requirements—no compromise on AI performance.

For those who prefer using custom elements like <context class="dark_mode">, this can be achieved through a build pipeline or templating engine. These tools can transform custom elements into standard HTML during the build process, resulting in something like <section class="context--dark_mode">.

However, this approach introduces dependencies on template compilation and a build process, which might not align with every project’s needs. One of Blocktail’s core principles is to remain framework-agnostic and adaptable to diverse workflows. This ensures it integrates effortlessly into existing codebases without dictating the use of specific module bundlers or build tools.
 

Code licensed MIT, docs CC BY 4.0.