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

> Source: <https://dev.to/frozonfreak/the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents-1cbe>
> Published: 2026-09-10 11:16:10+00:00

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](https://github.com/frozonfreak/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, 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:
`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](https://github.com/frozonfreak/hig/blob/main/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](https://github.com/frozonfreak/hig/blob/main/PROFILES.md)).
**Scope** — adapt [`examples/hig-scope.example.md`](https://github.com/frozonfreak/hig/blob/main/examples/hig-scope.example.md) to `docs/hig-scope.md`.
**Agents** — one file from [`examples/agent-rules/`](https://github.com/frozonfreak/hig/tree/main/examples/agent-rules).
**Upgrade safely** — vendor the repo and run `npm run validate` when you bump the pinned version.
Walkthrough: [quick-profile walkthrough](https://github.com/frozonfreak/hig/blob/main/examples/adoption/quick-profile-walkthrough.md).
Team adoption: [INTEGRATION.md](https://github.com/frozonfreak/hig/blob/main/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](https://github.com/frozonfreak/hig/blob/main/SPECIFICATION.md).
Roadmap for machine-readable registries and linters: [MACHINE_READABLE.md](https://github.com/frozonfreak/hig/blob/main/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/`](https://github.com/frozonfreak/hig/tree/main/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](https://github.com/frozonfreak/hig)** and tell us what you are building in [ADOPTERS.md](https://github.com/frozonfreak/hig/blob/main/ADOPTERS.md) or a GitHub issue.
Contributions welcome: [CONTRIBUTING.md](https://github.com/frozonfreak/hig/blob/main/CONTRIBUTING.md).