HTML Template Agent

HTML Template Agent

Role: Semantic Structure and Accessibility Expert
Scope: Jekyll templates, includes, and HTML structure
Version: 2.1.1 - Component Patterns Catalog Added

Purpose

The HTML Template Agent ensures all HTML follows semantic best practices, uses meaningful content-first class names, and meets WCAG AA accessibility standards. This agent creates the "Content" tier of the three-tier architecture (Content → Interface → Engine).

New in v2.1.1: Comprehensive component patterns catalog with ready-to-use semantic HTML for navigation, forms, cards, modals, and more.

New in v2.1: Automated validation scripts, comprehensive template guide, accessibility checklist.

When to Use This Skill

Activate when:

• Creating new Jekyll layouts or includes
• Building reusable HTML components
• Auditing HTML for accessibility
• Implementing semantic class naming
• Ensuring landmark element integrity
• NEW: Running automated HTML validation

Core Principles

Content-First Naming

Think WHAT, not HOW:

• ✅ .research-paper, .user-profile, .product-card
• ❌ .blue-box, .large-text, .rounded-card

Accessibility Requirements (MANDATORY)

• ONE <main id="skip-target"> per page with tabindex="-1"
• ONE <header> and <footer> per page
• Skip link as first focusable element
• All images have descriptive alt attributes
• All form inputs have associated <label> elements
• Visible focus indicators on interactive elements
• Support prefers-reduced-motion and prefers-contrast

Accessibility Rules from Audit (MANDATORY)

These rules were established through automated axe-core auditing:

• Web component landmark deduplication — <genesis-header>, <genesis-footer>, <genesis-environment> must NOT set landmark roles that duplicate inner semantic elements
• Secondary footers — Only the page-level <footer> should be a <footer> element. Use <div role="group"> for CTA sections, modal footers, input areas
• No nested <main> — Content pages must use <div> wrappers since default.html provides <main>
• Tab ownership chain — role="tablist" containers must NOT have role="group" children; use role="presentation" on intermediate wrappers
• Heading order — Sequential h1→h2→h3 without skipping; don't hardcode <h3> in components that appear under <h1>
• Icon-only spans — Use role="img" when aria-label is needed on <span> elements
• Scrollable regions — Add tabindex="0" and role="log" (or appropriate role) for keyboard accessibility
• Link discrimination — Links must have text-decoration: underline, not just color difference

Quick Example

Semantic HTML5 Structure

<!-- Skip link (REQUIRED first) -->
<a href="#skip-target" class="sr-only focus-visible">Skip to main content</a>

<!-- Main landmark (REQUIRED, exactly one) -->
<main id="skip-target" tabindex="-1">
  <article class="blog-post">
    <header class="blog-post__header">
      <h1 class="blog-post__title">Title</h1>
      <time class="blog-post__date" datetime="2026-01-19">January 19, 2026</time>
    </header>
    
    <div class="blog-post__content">
      <p>Content...</p>
    </div>
  </article>
</main>

Automation & Validation

Validation Script

Run the automated validation script to check semantic structure and accessibility:

# Validate HTML template
./.github/skills/html-template-agent/scripts/validate-html.sh path/to/template.html

# The script checks:
# 1. Skip link presence
# 2. Main landmark with skip-target
# 3. No inline styles
# 4. Semantic class names
# 5. Images with alt attributes
# 6. Form labels

Pre-Commit Workflow

Before committing HTML changes:

# 1. Validate your template
./.github/skills/html-template-agent/scripts/validate-html.sh _layouts/page.html

# 2. Check all templates if needed
for file in _layouts/*.html; do
  ./.github/skills/html-template-agent/scripts/validate-html.sh "$file"
done

Detailed Guides

TEMPLATE-GUIDE.md

Complete template best practices:

• Complete accessibility checklist
• BEM naming convention guide
• Jekyll template patterns
• Common HTML patterns
• Validation procedures

COMPONENT-PATTERNS.md NEW

Ready-to-use semantic HTML patterns:

• Navigation patterns (primary nav, breadcrumbs, tabs)
• Hero sections (full-width, split layouts)
• Card components (blog posts, features, products)
• Form patterns (contact forms, search, accessible inputs)
• Modal dialogs with ARIA
• Data display (tables, definition lists, metadata)
• Interactive elements (accordions, alerts, notifications)
• Content sections (testimonials, FAQs, CTAs)

Resources

In This Skill

• scripts/validate-html.sh - Automated validation
• references/TEMPLATE-GUIDE.md - Comprehensive template guide
• references/COMPONENT-PATTERNS.md - NEW Ready-to-use HTML patterns catalog

In Repository

• /docs/specifications/html-semantic-patterns.md - Complete semantic HTML patterns
• /docs/specifications/accessibility.md - WCAG compliance guide
• /docs/specifications/component-library.md - Reusable components
• /docs/specifications/scss-ontology-system.md - Ontology for class mapping
• .github/instructions/html.instructions.md - Complete HTML guidelines
• .github/docs/agent-system-overview.md - Agent catalog and navigation

Related Agents

• scss-refactor-agent - Maps HTML to ontological SCSS
• responsive-design-agent - Ensures mobile-first patterns
• theme-genome-agent - Maintains design system
• agent-evolution-agent - Meta-agent for continuous learning

Version: 2.1.2 - Enhanced Spec References
Last Updated: 2026-02-10

Converted and distributed by TomeVault — claim your Tome and manage your conversions.