--- name: html-semantic-engineering description: 30 pragmatic rules for production HTML covering semantic markup, accessibility (WCAG 2.1 AA), performance optimization, forms, and security. Use when writing HTML, building page structures, creating forms, implementing accessibility, or optimizing for SEO and Core Web Vitals. allowed-tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch --- # HTML Semantic Engineering 30 battle-tested principles for production HTML. Semantic correctness first, then accessibility, then performance. ## Relationship with Other Skills - **`web-components-architecture`**: Component lifecycle and Shadow DOM patterns - **`javascript-pragmatic-rules`**: JavaScript behavior inside components - **`utopia-fluid-scales`**: Typography (`--step-*`) and spacing (`--space-*`) tokens - **`utopia-grid-layout`**: Grid utilities (`.u-container`, `.u-grid`, `--grid-gutter`) - **`utopia-container-queries`**: Container context required for `cqi` fluid units **Example:** A `` component should: - Use this skill for semantic structure (article, heading hierarchy, img alt) - Use `web-components-architecture` for Shadow DOM encapsulation - Use `utopia-fluid-scales` for typography (`--step-2`) and spacing (`--space-m`) - Use `javascript-pragmatic-rules` for async data fetching ## Design System Integration This project uses Utopia's fluid scales with `cqi` (container query inline) units. **Never hardcode pixel values for typography or spacing.** Use design tokens: ```css /* Typography - see utopia-fluid-scales */ font-size: var(--step-0); /* Body text */ font-size: var(--step-3); /* H3 equivalent */ /* Spacing - see utopia-fluid-scales */ padding: var(--space-m); gap: var(--space-s-m); /* Fluid pair */ /* Grid - see utopia-grid-layout */ gap: var(--grid-gutter); max-width: var(--grid-max-width); ``` **Container requirement:** The `cqi` units require `container-type: inline-size` on a parent element. This is set on `html` in `css/styles/index.css`. --- ## Semantic Structure ### Rule 1: Never Skip Heading Levels Heading hierarchy defines document outline. Screen readers use headings for navigation. ```html

Page Title

Section Title

Subsection Title

Page Title

Subsection Title

``` ### Rule 2: Use Semantic Elements Over Divs Semantic elements convey meaning to browsers, screen readers, and search engines. ```html

Article Title

January 15, 2024

Content...

``` ### Rule 3: Landmark Regions for Navigation Screen reader users navigate by landmarks. Every page needs clear regions. ```html

...

``` --- ## Accessibility (WCAG 2.1 AA) ### Rule 4: Always Include Alt Text Images need descriptions for screen readers. Decorative images use empty alt. ```html Q4 sales increased 23% compared to Q3

User registration process flowchart — The process starts with email entry, followed by verification, profile setup, and confirmation.

``` ### Rule 5: Implement Skip Links Keyboard users need to bypass repetitive navigation. ```html

...

``` ### Rule 6: Associate Labels with Inputs Every form control needs an accessible name. ```html Email Address Subscribe to newsletter ``` ### Rule 7: Use ARIA Correctly ARIA supplements HTML semantics—it doesn't replace them. ```html

...

``` ### Rule 8: Keyboard Navigation All interactive elements must be keyboard accessible. ```html Focusable by default

Custom Button

Click me

``` --- ## Forms & Validation ### Rule 9: Use Appropriate Input Types Input types provide semantic meaning, validation, and mobile keyboards. ```html ``` ### Rule 10: HTML5 Validation with Accessible Errors Use native validation with clear error messaging. ```html ``` ### Rule 11: Group Related Form Controls Fieldsets and legends improve form comprehension. ```html

Shipping Address Street City

Payment Method Credit Card PayPal

``` ### Rule 12: Autocomplete for User Data Autocomplete speeds form filling and improves security. ```html ``` --- ## Performance ### Rule 13: Lazy Load Below-Fold Images Images below the viewport should load on demand. ```html

``` ### Rule 14: Resource Hints for Critical Assets Preconnect, preload, and prefetch optimize loading. ```html ``` ### Rule 15: Specify Image Dimensions Width and height prevent layout shift (CLS). ```html

``` ### Rule 16: Defer Non-Critical Scripts Blocking scripts delay rendering. ```html ``` ### Rule 16a: Modulepreload for Critical Components Use `modulepreload` for above-the-fold web components to prevent FOUC (Flash of Unstyled Content). ```html ``` **Why modulepreload?** - Browser starts downloading modules in parallel with HTML parsing - Reduces time between HTML render and component definition - Prevents unstyled custom element flash - Works only with ES modules (`type="module"` scripts) **When to use:** - Navigation components (always visible) - Hero/above-the-fold components - Critical interactive elements **When NOT to use:** - Below-the-fold components (let browser lazy-load) - Large dependency trees (can block other resources) ### Rule 16b: FOUC Prevention CSS Custom elements need CSS rules to prevent Flash of Unstyled Content: ```css /* Hide custom elements until JavaScript defines them */ site-nav:not(:defined), nav-link-item:not(:defined) { opacity: 0; } /* Reserve layout space for fixed elements to prevent CLS */ site-nav:not(:defined) { display: block; position: fixed; top: 0; left: 0; right: 0; min-height: 56px; background: var(--theme-surface); } ``` See `web-components` skill for complete FOUC prevention patterns. --- ## SEO & Metadata ### Rule 17: Essential Meta Tags Every page needs proper metadata. ```html Page Title - Site Name ``` ### Rule 18: Structured Data Schema.org markup improves search result appearance. ```html ``` --- ## Security ### Rule 19: Content Security Policy CSP prevents XSS attacks. ```html ``` ### Rule 20: Secure External Resources Use SRI and crossorigin for external scripts. ```html ``` ### Rule 21: CSRF Protection in Forms Include CSRF tokens in form submissions. ```html ``` --- ## Tables ### Rule 22: Accessible Data Tables Tables need proper headers and captions. ```html

Q4 2024 Sales by Region
Region	Sales	Growth
North	$50,000	+15%
South	$42,000	+8%

``` --- ## Interactive Components ### Rule 23: Accessible Modal Dialogs Modals need focus trapping and proper ARIA. ```html ``` ### Rule 24: Expandable Content Use details/summary or ARIA for collapsible content. ```html

Show more information

Additional content revealed when expanded.

``` --- ## Progressive Enhancement ### Rule 25: Design for No JavaScript Core functionality must work without JavaScript. ```html Menu ``` --- ## Document Template ### Rule 26: Complete HTML5 Boilerplate This project's entry point is `css/styles/index.css` which imports all design tokens. ```html Page Title - Site Name

Page Title

``` --- ## Quick Reference ### Semantic Elements ```

Page/section header with nav

Navigation links

Primary page content (one per page)

Self-contained content

Thematic grouping with heading

Tangentially related content

Page Title

Section Title

Subsection Title

Page Title

Subsection Title

Article Title

Dialog Title

Confirm Action

Page Title

Page Title

Section Title

Subsection Title

Page Title

Subsection Title

FAQ Question

Page Title

html-semantic-engineering

Install this skill

Comments