DEV Community

Cover image for The Web HIG: a versioned behavioral contract for humans, CI, and AI agents
FrozonFreak
FrozonFreak

Posted on Originally published at github.com

The Web HIG: a versioned behavioral contract for humans, CI, and AI agents

#a11y #webdev #opensource #ai

Your design system probably nails color, type, and button variants. WCAG covers accessibility conformance. Your framework docs cover routing and data fetching.
Then you ask an AI agent to “add a delete project flow,” and you get a modal that optimistically removes the row, no focus trap, hex colors sprinkled in the CSS, and a toast that says “Success!” without telling anyone what succeeded.
That gap — portable, testable product behavior — is what The Web HIG is for.

Not a component library

The Web HIG is an open, MIT-licensed behavioral standard for the modern web:

  • Vendor-neutral requirements for interaction, states, tokens, motion, performance, and security UX
  • Stable rule IDs (HIG-A11Y-003, HIG-MUT-001, …) you can cite in PRs, audits, and agent prompts
  • Progressive disclosure: a ~5 minute quick reference, practical modules, and a full normative spec You keep MUI, shadcn, Tailwind, or a home-grown token file. You keep React, Vue, or Astro. The HIG does not replace WCAG or HTML — it sits between your design system and application code, the way a platform HIG does, but for the web and without locking you to one vendor. > Design systems define what it looks like. The Web HIG defines how it behaves. Current release: v1.9.0. Quick Reference · Live demo · Documentation site ## Why “just use a checklist” fails at scale Informal checklists and blog posts help once. They do not:
  • Pin semver when you upgrade the contract across repos
  • Map rules to CI severity (block vs warn vs observe)
  • Compose cleanly with agent context windows (load topics on demand, not a 200-page PDF) The Web HIG is built for testable behavior: RFC 2119 vocabulary in the full spec, Layer 8 gate classes for automation, and a manifest (rules/manifest.yaml) so tools (and agents) can load only the module they need — forms, mutations, accessibility, and so on. ## One standard, three levels You do not have to read everything on day one. | Level | Document | When | | --- | --- | --- | | Quick | HIG-QUICK.md — 98 rules | Daily work, agents, PR review | | Practical | HIG-LITE.md + rules/ | Features — IDs, modules, archetypes | | Full | HIG.md | Edge cases, CI gates, disputes | Same rule IDs at every layer. Escalate only when you need to. ## Scope before rules (Layer 0) Not every rule applies to every page. Before enforcing anything, resolve a page archetype:
  • content — marketing, docs, blog
  • commerce — catalog, cart, checkout
  • application — dashboards, settings, tools
  • auth — login, signup, account recovery A landing page should not inherit the same mutation and streaming defaults as a logged-in app shell. Archetypes keep agents and humans from “HIG-maximalism” on simple routes. ## Rules agents (and reviewers) can actually cite Quick Reference rules are imperative and short. A few that show up constantly in AI-generated UI: States & feedback
  • Every async operation needs idle, loading, success, error, or empty — never a blank screen while data loads.
  • Error copy must say what failed and how to recover, not “Something went wrong.” Destructive actions
  • Confirmation must match severity; irreversible deletes need intentional multi-step confirmation.
  • Never use optimistic UI for destructive confirmation — wait for server acknowledgment (HIG-MUT-001 territory). Accessibility & tokens
  • Prefer native HTML over ARIA when the platform already gives you the behavior.
  • No raw hex in application CSS — semantic or component tokens only.
  • Respect prefers-reduced-motion; cap decorative micro-motion. When you push back on a shortcut, citing HIG-MUT-001 or HIG-A11Y-003 is clearer than “our team doesn’t like that.” ## Where it sits in your stack 
┌──────────────────────────────────────┐
│  HTML, CSS, ARIA (platform)          │
└──────────────────┬───────────────────┘
                   │
┌──────────────────▼───────────────────┐
│  WCAG 2.2 (accessibility target)     │
└──────────────────┬───────────────────┘
                   │
┌──────────────────▼───────────────────┐
│  Your design system (visual language)│
└──────────────────┬───────────────────┘
                   │
┌──────────────────▼───────────────────┐
│  The Web HIG (behavior & enforcement)│
└──────────────────┬───────────────────┘
                   │
┌──────────────────▼───────────────────┐
│  Your product code                   │
└──────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

More background: RATIONALE.md.

Built for the AI-assisted workflow

A typical loop:

Developer → pinned HIG → AI agent → code → review → CI
Enter fullscreen mode Exit fullscreen mode

Pin HIG-QUICK.md (and optionally HIG-CORE.md) under something like docs/hig/. Add a scope file that maps routes to archetypes. Drop in one agent rule file:
| Tool | Template in repo |
| --- | --- |
| Cursor | examples/agent-rules/cursor-hig.mdc |
| Claude Code | examples/agent-rules/CLAUDE-hig.md |
| GitHub Copilot | examples/agent-rules/copilot-instructions-hig.md |
| Multi-agent | examples/agent-rules/AGENTS-hig.md |
Default agent prompt: “Follow The Web HIG Quick Reference.”
Human prompt with teeth:

Build a delete-project dialog for /app/projects. Archetype: application. Follow The Web HIG Quick Reference; cite rule IDs if you decline a pattern.
You should see citations like HIG-MUT-001, HIG-A11Y-008, and HIG-A11Y-004 instead of vibes-based UX.

Try it in one afternoon

  1. Pin — copy VERSION, HIG-QUICK.md, and optional HIG-CORE.md to docs/hig/ (profiles guide).
  2. Scope — adapt examples/hig-scope.example.md to docs/hig-scope.md.
  3. Agents — one file from examples/agent-rules/.
  4. Upgrade safely — vendor the repo and run npm run validate when you bump the pinned version. Walkthrough: quick-profile walkthrough. Team adoption: INTEGRATION.md. Minimal PR checklist once the HIG is pinned:
  5. [ ] Archetype noted in the PR description
  6. [ ] No raw hex in component CSS
  7. [ ] Destructive actions use proportional confirmation, not optimistic delete
  8. [ ] Visible focus on interactive controls ## What’s inside (v1.9.0 snapshot)
  9. 98 quick rules
  10. 16 topic modules (forms, mutations, performance, security UX, …)
  11. 4 page archetypes
  12. Layers covering applicability, UX, IA, tokens, server-driven UI, a11y, perf, CI gates, and security UX Index: SPECIFICATION.md. Roadmap for machine-readable registries and linters: MACHINE_READABLE.md. ## Open standard, your stack The Web HIG is deliberately adopt, don’t rewrite: pin the contract, wire your agents, optionally gate CI later. Framework notes live under framework/ (React, Next, Vue, Nuxt, Astro) without mandating any of them. If you are standardizing how your team — and your coding agents — handle loading states, destructive flows, and token discipline, star or pin the repo and tell us what you are building in ADOPTERS.md or a GitHub issue. Contributions welcome: CONTRIBUTING.md.

Top comments (0)