{"slug": "the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents", "title": "The Web HIG: a versioned behavioral contract for humans, CI, and AI agents", "summary": "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.", "body_md": "Your design system probably nails color, type, and button variants. WCAG covers accessibility conformance. Your framework docs cover routing and data fetching.\n\nThen 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.\n\nThat gap — **portable, testable product behavior** — is what [The Web HIG](https://github.com/frozonfreak/hig) is for.\n\nThe Web HIG is an open, MIT-licensed **behavioral standard** for the modern web:\n\n`HIG-A11Y-003`, `HIG-MUT-001`, …) you can cite in PRs, audits, and agent prompts` rules/manifest.yaml``rules/` | Features — IDs, modules, archetypes |\n| `content` — marketing, docs, blog`commerce` — catalog, cart, checkout`application` — dashboards, settings, tools`auth` — login, signup, account recovery\nA 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.\n## Rules agents (and reviewers) can actually cite\nQuick Reference rules are imperative and short. A few that show up constantly in AI-generated UI:\n`prefers-reduced-motion`; cap decorative micro-motion.\nWhen you push back on a shortcut, citing \n\n```\n┌──────────────────────────────────────┐\n│  HTML, CSS, ARIA (platform)          │\n└──────────────────┬───────────────────┘\n                   │\n┌──────────────────▼───────────────────┐\n│  WCAG 2.2 (accessibility target)     │\n└──────────────────┬───────────────────┘\n                   │\n┌──────────────────▼───────────────────┐\n│  Your design system (visual language)│\n└──────────────────┬───────────────────┘\n                   │\n┌──────────────────▼───────────────────┐\n│  The Web HIG (behavior & enforcement)│\n└──────────────────┬───────────────────┘\n                   │\n┌──────────────────▼───────────────────┐\n│  Your product code                   │\n└──────────────────────────────────────┘\n```\n\nMore background: [RATIONALE.md](https://github.com/frozonfreak/hig/blob/main/RATIONALE.md).\n\nA typical loop:\n\n```\nDeveloper → pinned HIG → AI agent → code → review → CI\n```\n\nPin **`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:\n\n| Tool | Template in repo |\n\n| --- | --- |\n\n| Cursor | `examples/agent-rules/cursor-hig.mdc` |\n\n| Claude Code | `examples/agent-rules/CLAUDE-hig.md` |\n\n| GitHub Copilot | `examples/agent-rules/copilot-instructions-hig.md` |\n\n| Multi-agent | `examples/agent-rules/AGENTS-hig.md` |\n\n**Default agent prompt:** *“Follow The Web HIG Quick Reference.”*\n\nHuman prompt with teeth:\n\nBuild a delete-project dialog for `/app/projects`. Archetype: application. Follow The Web HIG Quick Reference; cite rule IDs if you decline a pattern.\n\nYou should see citations like `HIG-MUT-001`, `HIG-A11Y-008`, and `HIG-A11Y-004` instead of vibes-based UX.\n\n## Try it in one afternoon\n\n**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)).\n**Scope** — adapt [`examples/hig-scope.example.md`](https://github.com/frozonfreak/hig/blob/main/examples/hig-scope.example.md) to `docs/hig-scope.md`.\n**Agents** — one file from [`examples/agent-rules/`](https://github.com/frozonfreak/hig/tree/main/examples/agent-rules).\n**Upgrade safely** — vendor the repo and run `npm run validate` when you bump the pinned version.\nWalkthrough: [quick-profile walkthrough](https://github.com/frozonfreak/hig/blob/main/examples/adoption/quick-profile-walkthrough.md).\nTeam adoption: [INTEGRATION.md](https://github.com/frozonfreak/hig/blob/main/INTEGRATION.md).\nMinimal PR checklist once the HIG is pinned:- [ ] Archetype noted in the PR description\n- [ ] No raw hex in component CSS\n- [ ] Destructive actions use proportional confirmation, not optimistic delete\n- [ ] Visible focus on interactive controls ## What’s inside (v1.9.0 snapshot)\n**98** quick rules\n**16** topic modules (forms, mutations, performance, security UX, …)\n**4** page archetypes\n- Layers covering applicability, UX, IA, tokens, server-driven UI, a11y, perf, CI gates, and security UX Index:\n[SPECIFICATION.md](https://github.com/frozonfreak/hig/blob/main/SPECIFICATION.md).\nRoadmap for machine-readable registries and linters: [MACHINE_READABLE.md](https://github.com/frozonfreak/hig/blob/main/MACHINE_READABLE.md).\n## Open standard, your stack\nThe 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.\nIf 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.\nContributions welcome: [CONTRIBUTING.md](https://github.com/frozonfreak/hig/blob/main/CONTRIBUTING.md).", "url": "https://wpnews.pro/news/the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents", "canonical_source": "https://dev.to/frozonfreak/the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents-1cbe", "published_at": "2026-09-10 11:16:10+00:00", "updated_at": "2026-09-10 11:28:22.894614+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "ai-products"], "entities": ["The Web HIG", "Cursor", "Claude Code", "GitHub Copilot", "WCAG 2.2", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents", "markdown": "https://wpnews.pro/news/the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents.md", "text": "https://wpnews.pro/news/the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents.txt", "jsonld": "https://wpnews.pro/news/the-web-hig-a-versioned-behavioral-contract-for-humans-ci-and-ai-agents.jsonld"}}