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.
The Web HIG is an open, MIT-licensed behavioral standard for the modern web:
HIG-A11Y-003, HIG-MUT-001, …) you can cite in PRs, audits, and agent prompts rules/manifest.yaml``rules/ | Features — IDs, modules, archetypes |
| content — marketing, docs, blogcommerce — catalog, cart, checkoutapplication — dashboards, settings, toolsauth — 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:
prefers-reduced-motion; cap decorative micro-motion.
When you push back on a shortcut, citing
┌──────────────────────────────────────┐
│ HTML, CSS, ARIA (platform) │
└──────────────────┬───────────────────┘
│
┌──────────────────▼───────────────────┐
│ WCAG 2.2 (accessibility target) │
└──────────────────┬───────────────────┘
│
┌──────────────────▼───────────────────┐
│ Your design system (visual language)│
└──────────────────┬───────────────────┘
│
┌──────────────────▼───────────────────┐
│ The Web HIG (behavior & enforcement)│
└──────────────────┬───────────────────┘
│
┌──────────────────▼───────────────────┐
│ Your product code │
└──────────────────────────────────────┘
More background: RATIONALE.md.
A typical loop:
Developer → pinned HIG → AI agent → code → review → CI
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 #
Pin — copy VERSION, HIG-QUICK.md, and optional HIG-CORE.md to docs/hig/ (profiles guide).
Scope — adapt examples/hig-scope.example.md to docs/hig-scope.md.
Agents — one file from examples/agent-rules/.
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:- [ ] Archetype noted in the PR description
- [ ] No raw hex in component CSS
- [ ] Destructive actions use proportional confirmation, not optimistic delete
- [ ] Visible focus on interactive controls ## What’s inside (v1.9.0 snapshot) 98 quick rules 16 topic modules (forms, mutations, performance, security UX, …) 4 page archetypes
- 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 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.