--- name: html description: Write semantic, accessible, performant HTML with modern best practices. Use when asked to (1) create HTML pages or documents, (2) write semantic markup, (3) improve accessibility, (4) optimize HTML structure and performance, (5) implement forms, tables, or complex layouts, or when phrases like "HTML page", "web page", "markup", "semantic HTML", "accessibility" appear. --- # Expert HTML Development Write clean, semantic, accessible HTML that follows modern web standards and best practices. ## MCP Integration - Context7 **CRITICAL: Before writing or editing ANY HTML code, ALWAYS use the Context7 MCP server to check for relevant context.** Context7 provides access to a knowledge base that may contain: - Project-specific HTML patterns and conventions - Custom component libraries and templates - Style guide requirements - Accessibility standards for the project - Performance benchmarks and requirements - Team preferences and coding standards **Workflow:** 1. **Before writing code:** Query Context7 for relevant patterns, conventions, or examples 2. **During editing:** Check Context7 for project-specific requirements that might affect your changes 3. **After writing:** Verify your code aligns with any Context7 guidance Use Context7 to search for topics like: - "HTML conventions" - "accessibility requirements" - "component templates" - "form patterns" - "performance standards" - Specific component or pattern names **Never skip the Context7 check** - it ensures your HTML aligns with project standards and leverages existing patterns. ## Core Principles 1. **Semantic first** - Use elements for their intended meaning, not just appearance 2. **Accessibility by default** - Every user deserves a great experience 3. **Progressive enhancement** - Start with working HTML, layer on CSS/JS 4. **Performance matters** - Optimize for speed and efficiency ## Document Structure ### Minimal Valid HTML5 Document ```html Page Title - Site Name

``` ### Essential Meta Tags ```html Specific, Descriptive Title | Brand ``` ## Semantic HTML Elements ### Use the Right Element for the Job ```html

Article Title

Article content...

Article Title

Article content...

``` ### Sectioning Elements | Element | Purpose | When to Use | |---------|---------|-------------| | `

` | Introductory content | Site/section header, not just "top of page" | | `

` | Navigation links | Primary navigation, table of contents, breadcrumbs | | `

` | Primary content | One per page, skips to main content | | `

` | Self-contained content | Blog posts, news items, forum posts | | `

` | Thematic grouping | Chapters, tabs, themed sections (always has heading) | | `

` | Tangentially related | Sidebars, pull quotes, related links | | `

` | Footer content | Site/section footer, not just "bottom of page" | ### Heading Hierarchy ```html

Page Title

Main Section

Subsection

Another Subsection

Another Main Section

Page Title

Skipped h2 and h3

``` ## Accessibility Best Practices ### ARIA Labels and Roles ```html

Email Address Email Address ``` ### Focus Management ```html

Custom Button

``` ### Alternative Text ```html Bar chart showing 40% increase in sales from Q1 to Q2 2024

Detailed description of the network topology showing...

``` ### ARIA Live Regions ```html

Error: Please correct the form errors below.

``` ## Forms ### Accessible Form Structure ```html ``` ### HTML5 Input Types ```html ``` ### Input Attributes for Better UX ```html ``` ## Tables ### Accessible Data Tables ```html

Quarterly Sales Report for 2024
Quarter	Revenue	Growth
Q1	$1.2M	+5%
Q2	$1.5M	+25%
Total	$2.7M	+15%

Course Schedule by Instructor and Day
Instructor	Monday	Tuesday	Wednesday
Dr. Smith	Biology 101	Biology 201	Lab

``` ## Lists ### Choosing the Right List Type ```html

Apples
Bananas
Oranges

Preheat oven to 350°F
Mix dry ingredients
Add wet ingredients
Bake for 25 minutes

HTML: HyperText Markup Language, the standard markup language for web pages.
CSS: Cascading Style Sheets, used to style HTML elements.

Fruits
- Tropical
  - Mango
  - Papaya
- Citrus
  - Orange
  - Lemon

``` ## Performance Optimization ### Image Optimization ```html Descriptive alt text

``` ### Resource Loading Strategies ```html ``` ### HTML Size Optimization ```html

Some text here

Text

``` ## Modern HTML Features ### Details and Summary (Native Disclosure) ```html

Click to expand

Hidden content that can be toggled.

FAQ Question

Answer to the question.

``` ### Dialog Element (Native Modal) ```html ``` ### Data Attributes ```html

Article Title

``` ### Template Element ```html ``` ## Content Embedding ### Videos ```html

``` ### Audio ```html

``` ### Iframes ```html ``` ## Validation and Quality ### HTML Validation Checklist - [ ] Valid DOCTYPE declaration - [ ] Proper nesting (no overlapping tags) - [ ] All tags properly closed - [ ] Unique IDs on a page - [ ] Valid attributes for each element - [ ] Proper character encoding (UTF-8) - [ ] Alt text for all images (or empty alt for decorative) - [ ] Form labels associated with inputs - [ ] Heading hierarchy (no skipped levels) - [ ] Lang attribute on html tag - [ ] Valid HTML5 (use W3C validator) ### Common HTML Mistakes to Avoid ```html

Link content

First paragraph

Second paragraph

First paragraph

Second paragraph

Content

Sidebar

Main content

``` ## Security Best Practices ### Input Sanitization Context ```html

``` ### External Resources ```html External Link ``` ## Progressive Enhancement ### Build from HTML Up ```html

Expandable Section

Content revealed when expanded.

``` ## Tools and Workflow ### Recommended Tools | Purpose | Tool | Why | |---------|------|-----| | Validation | [W3C Validator](https://validator.w3.org/) | Check HTML validity | | Accessibility | [axe DevTools](https://www.deque.com/axe/) | Find a11y issues | | Performance | [Lighthouse](https://developers.google.com/web/tools/lighthouse) | Audit performance | | HTML Minification | [html-minifier](https://github.com/kangax/html-minifier) | Reduce file size | | Linting | [HTMLHint](https://htmlhint.com/) | Catch common mistakes | ### HTML in Build Pipelines ```bash # Validate HTML npx html-validate src/**/*.html # Minify HTML npx html-minifier --collapse-whitespace --remove-comments input.html -o output.html # Check accessibility npx pa11y http://localhost:3000 ``` ## Quick Reference ### Common Character Entities | Character | Entity | Numeric | |-----------|--------|---------| | < | `<` | `<` | | > | `>` | `>` | | & | `&` | `&` | | " | `"` | `"` | | ' | `'` | `'` | | © | `©` | `©` | | ® | `®` | `®` | | ™ | `™` | `™` | | non-breaking space | ` ` | ` ` | | — (em dash) | `—` | `—` | | – (en dash) | `–` | `–` | ### Global Attributes Available on all HTML elements: - `id` - Unique identifier - `class` - CSS class names (space-separated) - `style` - Inline CSS styles - `title` - Advisory information (tooltip) - `lang` - Language of element content - `dir` - Text directionality (ltr, rtl, auto) - `hidden` - Hide element - `tabindex` - Tab order (-1, 0, positive numbers) - `contenteditable` - Make element editable - `data-*` - Custom data attributes - `draggable` - Enable drag and drop - `spellcheck` - Enable spell checking ## Best Practices Summary 1. **Always check Context7 MCP before writing/editing code** - Leverage project-specific patterns and requirements 2. **Always use semantic HTML** - Choose elements based on meaning, not appearance 3. **Validate your HTML** - Use W3C validator to catch errors 4. **Prioritize accessibility** - Use ARIA attributes, alt text, and keyboard navigation 5. **Optimize for performance** - Lazy load images, defer scripts, minimize HTML 6. **Use progressive enhancement** - Start with HTML, layer on CSS and JavaScript 7. **Keep it simple** - Don't over-engineer with unnecessary divs and complexity 8. **Test across browsers** - Ensure compatibility with all major browsers 9. **Think mobile-first** - Design for small screens, enhance for larger ones 10. **Use meaningful names** - IDs and classes should describe purpose, not appearance 11. **Comment sparingly** - Code should be self-documenting, comments for complex logic only