The Web HIG

Understand the standard

Why a behavioral contract matters, where it sits in your stack, and how the documentation is layered — read at your own pace.

1 Understand the standard

Why another standard?

The web already has HTML standards, WCAG guidelines, CSS conventions, and design systems — but there is no widely adopted, vendor-neutral behavioral contract that brings these concerns together for modern web applications and AI-assisted development.

WCAG
Accessibility
Design systems
Visual consistency
Frameworks
Implementation
The Web HIG
Behavioral contract

Where this fits

Existing approach What it gives you What it misses
Component libraries
MUI, Bootstrap, shadcn/ui		 Pre-built widgets No shared rules for error recovery, delete flows, or token discipline
Platform HIGs
Apple, Material Design		 Polished vendor guidance Portability across web stacks and AI tooling
Style guides Colors, typography, brand Behavior, states, performance targets, security UX
WCAG Accessibility compliance Performance, mutations, CI enforcement, AI agent rules

The Web HIG fills that gap: a versioned, lintable standard that teams and AI coding agents can pin in any product repo — without replacing your stack. See the competitive landscape for how this sits next to WCAG, ARIA APG, Open UI, design systems, and Lighthouse.

The competitive landscape

There isn’t one direct competitor. The Web HIG sits in the gap between several existing things — and does not replace them.

Standards & widgets

  • W3C / WCAG
  • WAI-ARIA APG
  • Open UI

Vendor design systems

  • Material
  • Fluent
  • Carbon
  • GOV.UK

The gap

The Web HIG

Product behaviour + states + architecture + enforcement

Distributed guidance

  • web.dev

Measurement

  • Lighthouse

Neighboring systems

Each of these is strong at its job. None of them is a portable, versioned behavioral contract for whole-product UX that humans and coding agents can pin and cite.

Standards

W3C / WCAG

Accessibility conformance

HIG covers whole-product behaviour. WCAG stays the a11y target — not a wrapper.

Standards

WAI-ARIA APG

Accessible widget interaction

Closest philosophical relative. Scope stops at widgets and interaction semantics.

Platform

Open UI

Browser UI primitives

Standardizes controls so they can land in HTML/CSS/ARIA. HIG sits above the browser.

Design system

Material Design

Google’s visual / component system

Not a vendor-neutral behavioral contract. Swap MUI for Tailwind and that layer changes.

Design system

Fluent

Microsoft’s design ecosystem

Same issue: product/design system, not a portable web behaviour contract.

Design system

Carbon

IBM enterprise components

HIG is stack-neutral governance for whatever components you already use.

Patterns

GOV.UK Design System

Government service patterns

Very strong UX patterns, but domain-specific to UK government services.

Guidance

web.dev

Web engineering guidance

Excellent material, distributed as articles — not a pinned semver contract.

Tooling

Lighthouse

Automated quality auditing

Measurement, not a UX behavioural specification. HIG is not a single-score clone.

This contract

The Web HIG

Behaviour + states + architecture + enforcement

Connects those layers without replacing the systems around it.

HIG does not need to replace either of these.

WAI-ARIA APG

Turns specs into practical patterns for accessible interfaces. That method is close. The scope is accessibility and interaction semantics — not loading taxonomies, destructive mutations, SSR defaults, or CI severity.

Open UI

Proposes anatomy, states, and behaviour of common controls to the standards bodies. It does not define the final platform standards itself. HIG governs application behaviour on top of whatever the platform eventually ships.

What is distinctive

Several things are not packaged together elsewhere as one versioned, citable contract.

  1. 1

    Behaviour rather than appearance

    Material, Fluent, and Carbon give enormous visual and component guidance. Switch from MUI to Tailwind, shadcn, or custom CSS and that implementation layer changes.

    Destructive mutations must not be optimistic.

    HIG-MUT-001 — same rule on MUI, Radix, Bootstrap, or hand-written HTML.
    • MUI
    • Radix
    • Bootstrap
    • Hand-written HTML

  2. 2

    Application state as UX

    Loading, error, empty, stale, offline, destructive mutation, and recovery are first-class design concerns — one normative contract, not scattered checklist items.

    • Loading
    • Error
    • Empty
    • Stale
    • Offline
    • Destructive
    • Recovery

  3. 3

    AI coding-agent consumption

    Usable as documentation and as an input contract for coding agents — a genuine differentiator in 2026.

    • Stable rule IDs
    • Quick / Practical / Full profiles
    • Machine-readable manifest
    • Topic triggers
    • Explicit severity
    • Exception mechanics
    • Agent rule templates
    • Policy-as-code planned

Detail: RATIONALE.md · Evaluator vs Lighthouse: EVALUATOR.md

Essential rules

Universal requirements — every page type, every feature.

  • Mobile-first & responsive — layouts adapt; components use container queries
  • Keyboard accessible — tab navigation works; focus is always visible
  • WCAG 2.2 AA — semantic HTML, accessible names, sufficient contrast, touch targets
  • Real UI states — loading, empty, error, and success are designed, not bolted on
  • Design tokens — no raw hex colors outside token files
  • Reduced motion — animations are functional, never required to understand the UI
  • Content surfaces — declare document, hybrid, or experience on marketing routes; reduced-motion parity on expressive pages
  • Performance — protect Core Web Vitals; avoid unnecessary JavaScript
  • Security basics — no secrets in client code; PII masked; CSP configured

Full Quick Reference (98 rules): HIG-QUICK.md

One standard. Three levels.

Progressive disclosure — load only what you need. Pin HIG-QUICK instead of the 20,000-token full document.

Quick
98 rules

~5 minutes. Default for daily work and AI agents.

HIG-QUICK.md →
Practical
Rule modules

Building features — rule IDs, topic modules, archetype packs.

HIG-LITE.md + rules/ →
Full
Complete spec

Edge cases, spec conflicts, CI gate definitions.

HIG.md →

10 governance layers

Layer 0 defines which rules apply. Layers 1–9 define the rules themselves.

The Web HIG
Scope
L0
Governance
L1–L9
UX IA Tokens State
Accessibility
Performance
AI enforcement
QA
Security
0 Scope
1 UX
2 IA
3 Tokens
4 State
5 A11y
6 Perf
7 AI
8 QA
9 Sec
View all 10 layers in detail
0

Applicability & Scope

Archetype matrix — mandatory vs optional rules per page type

Decide what's required before you build — a blog post doesn't need checkout rules.

1

UX Principles

Motion, micro-animations, spatial ergonomics, reduced motion

Functional feedback on click; no decorative animation; respect "reduce motion."

2

Information Architecture

Document fundamentals, navigation, forms, states, search, i18n

Page titles, error messages, empty states, URL-as-state, form validation.

3

Visual & Design Tokens

Three-tier tokens, container queries, data density

Named design values; components adapt to container size, not just screen width.

4

Interaction & State

Server rendering, mutations, optimistic UI, offline, data protection

How save/delete works; undo for destructive actions; loading during server calls.

5

Accessibility

WCAG 2.2 AA, keyboard patterns, focus, target sizes

Works for keyboard, screen readers, and touch — always required.

6

Performance

Core Web Vitals — LCP, INP, CLS; lab vs field metrics

Fast load, responsive interactions, no layout jumping.

7

AI & Agent Enforcement

Rule IDs, severity, YAML guardrails for coding agents

Machine-readable rules agents and linters can enforce.

8

Quality Assurance

Blocking / warning / observation CI gates

Automated checks that fail the build on critical violations.

9

Security & Privacy

CSP, XSS/CSRF, PII, auth UX, secure cookies

Login flows, data masking, content security policy — always required.