Coding Standards

HTML & Markup Standards

Foundational

HTML is the foundation everything else sits on. Getting the markup right gives you accessibility, SEO, and robustness almost for free. Use semantic elements for what they mean, keep documents valid and well-structured, and let HTML do its job instead of rebuilding it with divs and JavaScript. Pairs with the Accessibility, React, Blazor, and CSS standards.

The biggest HTML mistake is ignoring semantics: using <div> and <span> for everything and adding behaviour on top, instead of using the element that already means what you want. Browsers, assistive technology, and search engines understand semantic HTML with no extra work. Non-semantic markup throws that away and forces you to rebuild it, often badly and without accessibility.

Whether you write HTML directly or through JSX or Razor, these rules apply to the markup you produce.

Use semantic elements

AlwaysUse the element that means what you intend: <button> for actions, <a> for navigation, <nav>/<main>/<header>/<footer> for regions, and lists for lists (see Accessibility).
DoUse one <h1> per page and a logical heading order. Do not skip levels for size; that is CSS's job.
DoLink <label>s to inputs, group related fields with <fieldset> and <legend>, and use the right input type.
Avoid<div> or <span> with click handlers in place of real buttons and links. They lose keyboard, focus, and screen-reader support (see React Coding Standards).
NeverRebuild native controls (buttons, checkboxes, selects, dialogs) from generic elements when a native or well-tested accessible one already exists.

Div soup

<div class="btn" onclick="submit()">Submit</div>
<div class="title-big">Account</div>
<div><div>Email</div><input></div>

None of this works with the keyboard or is understood by a screen reader: a fake button, a heading that is just styled text, and an unlabelled input. Accessibility, SEO, and robustness are all thrown away.

Semantic markup

<button type="submit">Submit</button>
<h1>Account</h1>
<label for="email">Email</label><input id="email" type="email">

Real elements are focusable, operable, announced correctly, and styleable. The right semantics give accessibility and robustness for free.

Structure & validity

DoKeep documents valid and well-formed: correct nesting, closed tags, unique ids, and a sensible document outline.
DoSet the language (lang), character encoding, and a responsive viewport meta tag. Provide a meaningful <title> and meta tags where relevant.
DoAlways provide alt text for images (use empty alt for purely decorative ones). Caption or label media.
DoKeep content in a logical order in the markup. Do not use CSS to reorder meaning, so the page reads correctly without styles and to assistive technology.

Accessibility & ARIA

DoPrefer native semantics over ARIA. Use ARIA only when no element expresses the pattern, and use it correctly (see Accessibility).
DoMake sure everything works with the keyboard and has visible focus, and that interactive elements have accessible names.
AvoidIncorrect or redundant ARIA. Wrong ARIA is worse than none, because it misleads assistive technology.
AvoidUsing tables for layout; use CSS Grid or Flexbox. Keep <table> for tabular data, with proper headers.

Safety & performance

DoLet the framework escape interpolated content. Add rel="noopener" on target="_blank" links, and be careful with user-controlled URLs and attributes (see Web & Frontend Security).
DoLazy-load images below the fold, set width and height (or aspect-ratio) to prevent layout shift, and keep the DOM reasonably small (see Frontend Performance).
NeverInject untrusted HTML into the page (raw innerHTML, dangerouslySetInnerHTML, or MarkupString) without sanitising it. That is XSS (see Web & Frontend Security).

Self-review checklist

AskAm I using the semantically correct element, or a div pretending to be one?
AskIs the heading order logical, are inputs labelled, and do images have alt text?
AskIs everything keyboard-operable with visible focus?
AskIs any untrusted content injected as raw HTML?

Why it matters: Semantic, valid HTML gives accessibility, SEO, and robustness almost for free. A pile of divs throws all that away and has to rebuild it, usually breaking keyboard and screen-reader users along the way. Good markup is the cheapest accessibility and quality win there is, and it is the foundation our CSS and components depend on.