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

A developer has released The Web HIG, an open, MIT-licensed behavioral standard for the modern web that provides versioned, citable rule IDs (such as HIG-MUT-001 and HIG-A11Y-003) for product behavior. The project targets the gap between design systems and AI-generated UI by letting teams pin a HIG version, map routes to archetypes, and supply agent rule files for tools like Cursor, Claude Code, and GitHub Copilot so agents cite specific rules instead of producing vibes-based UX. Adoption involves copying the versioned docs into a repository, adding a scope file, and running npm run validate when upgrading.

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 .