HTML Style Guides: Codifying Team Consistency

Indentation, quote style, and attribute ordering are the easy, fully-automatable layer of a style guide — a formatter handles these without requiring any documentation at all. The genuinely valuable content of a style guide lives one level up: judgment calls a tool can't make automatically.

Examples include when a <section> is warranted versus a plain <div> (a common rule: only when the block has its own heading), how deeply nested a component's internal structure should typically go, and preferred conventions for recurring UI patterns like cards, modals, and form layouts specific to that codebase's design system.

'Write clean, semantic HTML' is a principle nobody would disagree with and simultaneously nearly useless as guidance, because it provides no way to determine whether any specific piece of code complies. Effective style guide entries instead show real before/after code, ideally referencing an actual component in the codebase as the canonical reference implementation.

This concreteness matters especially for onboarding: a new team member can directly compare their code against a documented example far more reliably than they can interpret an abstract principle the same way a five-year veteran of the codebase would.

The most durable style guides recognize that not every rule deserves the same enforcement mechanism. Mechanically-checkable rules — missing alt attributes, disallowed element patterns, specific naming conventions — should live in an automated linter that fails CI on violation, removing any need for a human reviewer to catch them manually.

Genuinely subjective structural judgment calls, where reasonable developers might disagree given specific context, are better served by documented guidance reviewed through normal code review discussion, rather than forced into a rigid automated rule that will inevitably produce false positives on legitimate edge cases.

Codifying Decisions So They Don't Get Re-Litigated. A style guide isn't about personal preference — it's a team artifact that codifies decisions once so they don't get re-argued in every pull request. As a team grows past a couple of developers, an unwritten, unenforced 'style' silently fragments into as many styles as there are contributors.

A Style Guide Covers Decisions, Not Just Formatting. Formatting (indentation, quotes) is the easy, automatable part. A real HTML style guide also covers judgment calls tooling can't fully automate: when to use a <section> versus a <div>, how deeply to nest components, preferred patterns for common UI structures like cards or modals.

Style Guide Scope. What kind of decision is a good candidate for a style guide entry, as opposed to something a formatter already handles?

• →Indentation width, since that's a judgment call
• →When to use <section> vs a generic <div>
• →Single vs double quotes for attributes

Real Code Examples Beat Abstract Rules. A style guide entry that says 'use semantic elements appropriately' is nearly useless — it's too vague to apply consistently. Concrete before/after code examples, tied to specific real scenarios from the actual codebase, make guidance immediately actionable.

Effective Style Guide Entries. Why is a style guide entry with a concrete code example more effective than an abstract principle alone?

• →It simply looks more professional in documentation
• →It's immediately actionable and removes ambiguity about how to apply the principle
• →There's no meaningful difference in practice

Enforce What You Can, Document What You Can't. The most effective style guides pair documentation with tooling enforcement wherever possible — a linter rule catches a violation automatically in CI, while genuinely subjective judgment calls remain documented guidance reviewed by humans in code review.

Enforcement Strategy. What's the most effective split between automated enforcement and human-reviewed documentation for a style guide?

• →Everything should be manually reviewed by humans for consistency
• →Automate mechanically-checkable rules; document genuinely subjective judgment calls
• →Every rule, including subjective ones, should be forced into an automated linter

Style Guide Strategy Set. You now know what belongs in an effective HTML style guide beyond just formatting, why concrete codebase-specific examples beat abstract rules, and how to split enforcement between automated tooling and documented human judgment.

Caption Your Figures. A <figure> paired with <figcaption> is the standard, accessible way to caption an image.