HTML Examples
html examples production html example galleries encode team conventions as runnable, tested do production html example patterns are curated, runnable
Introduction
Production HTML example patterns are curated, runnable fragments that encode team conventions — not W3Schools copy-paste. Staff engineers maintain example galleries as living contracts: each snippet passes lint, documents the "why," and shows failure modes alongside happy paths.
Business problem
Business pressure: Scattered StackOverflow snippets introduce inconsistent semantics, missing form labels, and CSP-breaking inline handlers. Example drift causes every squad to reinvent accessible card markup differently.
- Velocity: Engineers lose hours reconciling "which card HTML is canonical?" across three repos.
- Quality: Copy-pasted examples skip error states, loading skeletons, and noscript fallbacks.
- Compliance: Regulated teams cannot ship CMS content without vetted reference markup.
Why this feature exists
Platform motivation: Runnable examples reduce the gap between documentation and production. They predate Storybook but remain the lowest-level interoperable reference for email, SEO landing pages, and static shells.
- History: Early MDN and W3C examples focused on syntax; modern galleries add a11y, perf, and security annotations.
- Alternative rejected: Screenshots of rendered UI — not copyable, not testable in CI.
- Modern role: Seed data for html-validate, pa11y, and visual regression in design-system pipelines.
Browser internals
Examples exercise the full parser path: Each gallery iframe or Try-It sandbox spins a miniature document with its own encoding, doctype, and script execution context.
- Parser: Examples must declare
<!DOCTYPE html>and charset to match production parser behavior. - DOM: Multiple examples on one page need isolated iframes — otherwise IDs collide in the accessibility tree.
- Script impact: Example sandboxes should default script-free; opt-in JS examples document CSP requirements.
Rendering workflow
Gallery rendering: Index page lists examples → user opens Try-It → iframe srcdoc or blob URL → full CRP inside iframe. Parent page LCP must not wait for all iframes.
- Critical path: Lazy-load iframe content on scroll; skeleton HTML in parent for layout stability.
- Layout: Fixed-height preview panes prevent CLS when examples vary in content height.
- Paint: Syntax-highlighted code blocks are expensive — virtualize long galleries.
Feature deep dive
Production HTML example patterns follow a template: context comment, minimal valid document, semantic structure, explicit a11y hooks, and anti-pattern callout. Categories: layout shells, forms, tables, media, metadata.
- Annotation: Each example lists "use when," "never use when," and linked ADR.
- Variants: Loading, error, empty states — not just happy path.
- Test hook:
data-testidonly when no semantic selector exists.
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>Example: Accessible product card</title></head><body><!-- Pattern: DS-CARD-01 — use in catalog grids --><article aria-labelledby="p1-name"><h2 id="p1-name">Wireless Headphones</h2><img src="hp.jpg" alt="Over-ear wireless headphones, matte black" width="320" height="240" loading="lazy"><p>₹4,999 <s aria-label="was ₹6,999">₹6,999</s></p><button type="button">Add to cart</button></article></body></html>
Accessibility analysis
Gallery a11y: Code blocks need accessible names; live previews need title on iframe; keyboard users must reach Try-It editor without trap.
- Screen readers: Announce example category and WCAG level targeted per snippet.
- Keyboard: Tab order: description → code → run button → preview iframe.
- WCAG: Preview iframe gets
title="Live preview: accessible product card".
SEO impact
SEO for example pages: Long-tail "HTML accessible card example" traffic is valuable — use unique titles, canonical URLs, and JSON-LD TechArticle.
- Crawl: One URL per major pattern; avoid infinite thin duplicates from query params.
- Rich results: HowTo schema when example includes numbered steps.
- Core Web Vitals: Defer non-critical example iframes to protect gallery LCP.
Security considerations
Try-It sandboxes: User-edited HTML in examples is arbitrary code execution in browser context — sandbox iframes, no parent DOM access.
- XSS: Never echo user input into parent page DOM without sanitization.
- CSP: sandbox="allow-scripts" only when needed; default deny scripts in learner playground.
- Clickjacking: Public Try-It embeds need same protections as any interactive widget.
Performance impact
Performance: A page with 40 live iframes destroys INP and memory — lazy hydration is mandatory.
- LCP: First visible example only eager-loads; rest use Intersection Observer.
- INP: Debounce live preview updates on keystroke in editor.
- CLS: Reserve preview pane dimensions in parent HTML.
Real production example
Design system Storybook + HTML source: Each story exports raw HTML string used in email and static site generators.
- Single source: React story and HTML example generated from one template.
- CI: jest-axe runs against rendered HTML export per story.
- Versioning: Example tagged DS-CARD-01-v2 — breaking markup change is semver major.
Enterprise usage
Enterprise: Internal "HTML Cookbook" repo with 200+ vetted snippets; PR template links example ID for new UI.
- Design system: Figma component links to canonical HTML example hash in docs.
- CMS: Authors pick from example gallery blocks — not freeform HTML.
- CI gates: New examples must include axe snapshot and html-validate pass.
Common production failures
What breaks in prod: Team copied "official" card example from docs site that was three years stale — missing loading="lazy" and using div buttons. LCP regression and a11y audit failure on launch week.
- Incident: Example used
onclick=""inline — CSP rollout broke every copied snippet in microsites. - SEO regression: Example gallery pages cannibalized main product docs — missing canonical tags.
- Perf regression: Auto-running all Try-It previews on page load — mobile crash rate up 8%.
Architecture review questions
- Does every example include error/empty state variant?
- Are Try-It sandboxes isolated from parent page DOM?
- Can a new hire find the canonical card markup in under 2 minutes?
- Do examples avoid inline handlers incompatible with strict CSP?
- Is there a version ID tying example to design-system release?
Hands-on project
Project: Publish a mini gallery of five production patterns (card, form, nav, table, head metadata) each with Try-It, anti-pattern sidebar, and axe checklist.
- Deliverable: Index page + five isolated full HTML documents.
- Verify: Lighthouse SEO ≥95 on index; each iframe example passes axe.
- Stretch: Wire CI to fail when example HTML drifts from snapshot.
Interview questions
How would you structure an HTML example gallery for a 50-engineer frontend org?(Advanced)
Monorepo docs site: categorized patterns with unique IDs, full HTML documents not fragments, CI running html-validate + axe per file, lazy-loaded previews, anti-pattern section per entry, and semver on breaking markup changes. Link from Figma and PR template.
Follow-up: How do you prevent example drift from production components?
What security model do you use for in-browser HTML playgrounds?(Advanced)
iframe with sandbox attribute (default no scripts); srcdoc for static preview; separate origin if JS needed; never reflect user HTML into parent; sanitize if server-stored; CSP on parent and child; rate-limit save/share endpoints.
Follow-up: What sandbox flags for a CSS-only playground?
How do HTML examples differ from Storybook stories for enterprise delivery?(Advanced)
Storybook targets React runtime; HTML examples are the portable contract for email, CMS, static SSR, and SEO landing pages. Best teams generate both from one source template. Interview signal: engineer knows which channel needs which artifact.
Follow-up: When is a raw HTML example insufficient?
Try it yourself
Edit the HTML, CSS, or JS panels — the preview updates as you type.
Try it yourself
Summary
Production HTML example galleries encode team conventions as runnable, tested documents — not anonymous snippets. Staff engineers treat each example as a semver'd contract with a11y, CSP, and Web Vitals annotations.