Patterns

HTML Patterns Skill

This skill provides reusable patterns for common page types and content blocks. Patterns combine semantic HTML with custom elements to create consistent, accessible structures.

Philosophy

Pages are composed of blocks - reusable content patterns that appear across many pages. By defining custom elements for these blocks, we:

1. Communicate intent - <faq-question> is clearer than <dt class="faq-q">
2. Enable styling - Custom elements can be styled with CSS
3. Support tooling - Validators can enforce correct usage
4. Document structure - The markup is self-documenting

Available Patterns

FAQ Pattern

Elements

faq-list
├── faq-question
├── faq-answer
├── faq-question
├── faq-answer
└── ...

Element Definitions

Usage

<section id="products" aria-labelledby="products-heading">
  <h2 id="products-heading">Products</h2>
  <faq-list category="products">
    <faq-question id="faq-returns">What is your return policy?</faq-question>
    <faq-answer>We offer a 30-day hassle-free return policy.</faq-answer>

    <faq-question id="faq-shipping">How long does shipping take?</faq-question>
    <faq-answer>Standard shipping takes 5-7 business days.</faq-answer>
  </faq-list>
</section>

Complete FAQ Page Structure

<main id="main">
  <article>
    <h1>Frequently Asked Questions</h1>

    <!-- Table of contents -->
    <nav aria-label="FAQ sections">
      <ul>
        <li><a href="#products">Products</a></li>
        <li><a href="#shipping">Shipping</a></li>
      </ul>
    </nav>

    <!-- FAQ sections -->
    <section id="products" aria-labelledby="products-heading">
      <h2 id="products-heading">Products</h2>
      <faq-list category="products">
        <faq-question id="faq-q1">Question text?</faq-question>
        <faq-answer>Answer text.</faq-answer>
      </faq-list>
    </section>

    <!-- More sections... -->

    <!-- Call to action -->
    <aside>
      <p><strong>Still have questions?</strong></p>
      <p><a href="/contact">Contact us</a></p>
    </aside>
  </article>
</main>

Accessibility Notes

• Each section has aria-labelledby pointing to its heading
• Questions have id attributes for direct linking
• Table of contents uses <nav> with descriptive aria-label
• Links within answers use proper mailto: and tel: protocols

Product Card Pattern

Element Definition

Usage

<product-card sku="WDG-PRO-001" price="79.99">
  <img src="widget-pro.jpg" alt="Widget Pro"/>
  <h3>Widget Pro</h3>
  <p>Our best-selling widget with enhanced durability.</p>
  <a href="/products/widget-pro">View details</a>
</product-card>

Product Listing Structure

<section aria-labelledby="products-heading">
  <h2 id="products-heading">Our Products</h2>
  <ul>
    <li>
      <product-card sku="WDG-001">
        <img src="widget.jpg" alt="Basic Widget"/>
        <h3>Basic Widget</h3>
        <p>Entry-level widget for beginners.</p>
      </product-card>
    </li>
    <!-- More products... -->
  </ul>
</section>

Creating New Patterns

When you identify a repeating content structure:

1. Define the elements in elements.json
2. Document the pattern in this skill
3. Create an example in the examples directory
4. Add to project dictionary if needed

Element Naming Conventions

• Use lowercase with hyphens: pattern-element
• Be descriptive: faq-question not fq
• Group related elements: faq-list, faq-question, faq-answer

Page Type Patterns

Beyond component blocks, entire page types follow patterns:

See individual examples in the .claude/patterns/pages/ directory.

Related Skills

• xhtml-author - Write valid XHTML-strict HTML5 markup
• css-author - Modern CSS organization with native @import, @layer casca...
• progressive-enhancement - HTML-first development with CSS-only interactivity patterns
• forms - HTML-first form patterns with CSS-only validation