HTML Style Guide
html style guide html style guides align teams on markup that passes accessibility, seo, security an html style guide codifies
Introduction
An HTML style guide codifies element choice, attribute patterns, forbidden anti-patterns, and validation gates — the markup equivalent of a lint config. Google and BBC publish public guidelines; Shopify theme-check enforces Liquid HTML rules. Staff teams write ADRs when guides change because markup drift causes cross-squad incidents.
Business problem
Without a style guide, each squad invents div patterns — accessibility audits find inconsistent landmarks, SEO finds duplicate titles, security finds inline handlers. Merge conflicts on "correct" markup waste review cycles.
- Scale: 50 engineers — 50 heading strategies without guide.
- Vendor: Agency deliverables fail internal HTML lint — rework cost.
- Incidents: Postmortems cite "no documented standard" for markup mistakes.
Why this feature exists
HTML permits many valid approaches — style guides narrow choices to interoperable subsets that pass a11y, SEO, security, and perf gates consistently. Not reinventing spec — operationalizing it.
- Origin: GOV.UK Service Manual, Google Web Fundamentals, company-specific addenda.
- Tooling: Guides link to eslint, html-validate, axe rules enforcing them.
- Living doc: Updated when spec or browser behavior changes — e.g., popover attribute.
Browser internals
Style guides often restrict to HTML subset that parses identically across supported browsers — no legacy IE hacks in 2025 guides. Content model rules from spec become lint rules: no block inside p, one main, etc.
- Validation: html-validate extends WHATWG rules with project rules.
- Parser: Guide documents mis-nesting recovery behaviors authors must avoid.
- Attributes: Allowlist for CMS — data-* naming conventions documented.
Style guide rule → html-validate rule "one-main-per-page"→ axe rule landmark-one-main→ PR checklist item
Rendering workflow
Guide perf section mandates defer scripts, img dimensions, preload policy — connects markup conventions to CWV budgets. Amazon internal wiki links HTML patterns to LCP ownership.
- Budgets: Max head link count, max DOM depth documented.
- Images: Required srcset pattern in guide appendix.
- Fonts: preload policy — who approves exceptions.
Feature deep dive
Typical guide sections: document skeleton, headings, links vs buttons, forms, images/media, tables, i18n/RTL, security (no inline handlers), performance defaults, CMS author rules, code review checklist.
- Do: Lowercase tags, quoted attributes, semantic landmarks, UTF-8.
- Don't: inline style, javascript: URLs, target=_blank without rel=noopener, user-scalable=no.
- Exceptions: Email HTML appendix — separate rules from web guide.
<!-- GOV.UK-inspired skeleton (abbreviated) --><!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Page title — Site name</title></head><body><a href="#main" class="skip-link">Skip to main content</a>…</body></html>
Accessibility analysis
Style guide a11y chapter references WCAG criteria with HTML patterns — not abstract principles. BBC guide lists required skip link, heading rules, form labeling — tied to CI axe thresholds.
- Authors: CMS guide forbids heading level picker abuse.
- Devs: Ban role redundancy on native elements.
- QA: Manual SR test triggers defined in guide release checklist.
SEO impact
SEO section documents title length, meta description policy, canonical rules, heading usage for snippets. Google SEO starter guide is external baseline; internal guide adds product-specific URL and schema rules.
- Templates: Title formula documented — {Product} | {Brand}.
- noindex: Which page types — faceted search, staging.
- Structured data: Required types per template in guide matrix.
Security considerations
Security chapter — no inline script, CSP alignment, sanitize UGC tags allowlist, rel=noopener on external links, form CSRF requirements. Amazon seller content guide restricts HTML subset in descriptions.
- CMS: Allowed tags list published — not secret security through obscurity.
- Review: Security sign-off on guide changes affecting UGC HTML.
- Secrets: No comments/TODO with credentials — guide + pre-commit hook.
Performance impact
Perf budgets in guide — max script count, image rules, font preload approval. Shopify theme performance score tied to guide compliance in partner program.
- Defaults: loading=lazy below fold — explicit in guide.
- Anti-patterns: document.write, sync third-party head scripts banned.
- Monitoring: RUM alerts linked to guide violations in tag inventory.
Real production example
Google HTML/CSS style guide (legacy but influential) — id/class naming, indentation, protocol-relative URL avoidance. Stripe internal docs style guide for MDX output HTML fragments.
- Enforcement: Prettier for HTML, eslint-plugin-html, CI required checks.
- Onboarding: New hire PR must touch guide-linked example page.
- Versioning: Guide semver — breaking markup rule = major bump + codemod.
# .htmlvalidate.json excerpt{ "rules": { "no-inline-style": "error", "element-required-attributes": ["img:alt"] } }
Enterprise usage
Enterprise maintains HTML style guide in docs site with searchable anti-patterns, links to design system components, and exception request workflow. Legal/compliance review for regulated disclaimers markup.
- Cross-team: Frontend guild owns guide; CMS team owns author subset.
- Translation: Guide specifies lang/dir attributes for localized templates.
- Audit: Quarterly random sample against guide compliance score.
Common production failures
Agency rebuild ignored internal HTML guide — launch blocked by CI; two-week delay remediating 40 templates. Guide existed but wasn't in vendor contract.
- Drift: Guide said one h1; CMS update allowed h1 in cards — six months undetected.
- Security: Guide banned inline handlers; marketing tag manager reintroduced — XSS near-miss.
- Perf: Guide preload policy ignored on Black Friday landing — LCP miss.
Architecture review questions
- Does this PR comply with documented HTML style guide sections?
- Are new patterns proposed via guide amendment, not ad hoc PR?
- Do CI lint rules match current guide version?
- Are CMS author rules synchronized with developer guide?
- Is there an exception ticket for any guide violations in this change?
- When did we last audit production HTML against the guide?
Hands-on project
Draft or extend an HTML style guide for a fictional product — 10 mandatory rules, 5 banned anti-patterns, CI mapping to html-validate rules, and one page exemplar passing all gates.
- Deliverable: Markdown guide + html-validate config + sample HTML.
- Verify: Peer review from a11y and SEO perspectives.
- Stretch: Pre-commit hook running validator on staged HTML.
Interview questions
What belongs in an HTML style guide vs leaving to the HTML spec?(Advanced)
Guide operationalizes spec for your product: chosen patterns among valid options, forbidden anti-patterns with incident history, CI enforceable rules, CMS author constraints, integration with design system components, perf/a11y/SEO thresholds. Spec is complete but not opinionated for your stack.
Follow-up: How to handle guide exceptions?
How do you enforce an HTML style guide at Shopify or enterprise scale?(Advanced)
Automated: html-validate, axe, eslint in CI on templates and Storybook snapshots. Human: PR checklist, guild review for new components. CMS: constrained blocks not free HTML. Metrics: compliance sampling, DOM anti-pattern ratios. Guide versioned with codemods on breaking changes.
Follow-up: What about third-party widgets?
Balancing style guide strictness vs developer velocity?(Advanced)
Strict on security, a11y, SEO-critical patterns (one main, labels, charset). Flexible on formatting if Prettier handles. Document 'why' with incident links — increases adherence. Exception process with time-boxed ADR. Guide not 200 pages — layered quick reference + deep dives.
Follow-up: When to update guide for new HTML features?
Try it yourself
Edit the HTML, CSS, or JS panels — the preview updates as you type.
Try it yourself
Summary
HTML style guides align teams on markup that passes accessibility, SEO, security, and performance gates. Organizations at Google and BBC treat guides as living engineering policy — backed by automated enforcement, not optional wiki pages.