# HTML Template Agent

> Create semantic HTML5 templates with accessibility-first principles for Genesis Ontological Design System. Ensure proper landmark elements, meaningful class names, WCAG compliance, and BEM-style naming. Includes ready-to-use component patterns for navigation, forms, cards, modals, and more. Use when building Jekyll templates, includes, or auditing HTML structure for semantic correctness. Use when this capability is needed.

- Skill: `tomevault-io/html-template-agent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/html-template-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/html-template-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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

```html
<!-- 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:

```bash
# 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:

```bash
# 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](references/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](references/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](https://tomevault.io/claim/asisaga) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->