AI-native behavioral standard for the modern web.

Essential rules

Universal requirements — every page type, every feature.

• Mobile-first & responsive — layouts adapt; components use container queries
• Keyboard accessible — tab navigation works; focus is always visible
• WCAG 2.2 AA — semantic HTML, accessible names, sufficient contrast, touch targets
• Real UI states — loading, empty, error, and success are designed, not bolted on
• Design tokens — no raw hex colors outside token files
• Reduced motion — animations are functional, never required to understand the UI
• Performance — protect Core Web Vitals; avoid unnecessary JavaScript
• Security basics — no secrets in client code; PII masked; CSP configured

Full Quick Reference (98 rules): HIG-QUICK.md

One standard. Three levels.

Progressive disclosure — load only what you need. Pin HIG-QUICK instead of the 20,000-token full document.

10 governance layers

Layer 0 defines which rules apply. Layers 1–9 define the rules themselves.

Start here

Pick the path that matches how you work.

Try it in one afternoon

Add the HIG to an existing project without reading the entire specification.

1. Pin the contract — copy HIG-QUICK, HIG-LITE, HIG.md, rules/, and VERSION into your repo (e.g. docs/hig/) ~10 minutes
2. Map your pages — create docs/hig-scope.md with routes and page archetypes (Content, Commerce, Application, or Auth) Example → · ~15 minutes
3. Wire your tools — add agent rules for Cursor, Copilot, or Claude Code Templates → · ~5 minutes
4. Review and automate — use the Quick Reference in PRs; add ESLint/CI gates when ready Full integration guide →

Built for humans and AI agents

Do not paste the entire HIG into every prompt. Pin HIG-QUICK and say: "Follow The Web HIG Quick Reference."

1. Developer
2. HIG
3. AI agent
4. Code
5. Validation
6. CI

Architecture

Tell an AI: "Follow The Web HIG Quick Reference." — pin HIG-QUICK instead of the 20,000-token full document.

                         THE WEB HIG
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
    HIG-QUICK.md       HIG-LITE.md           HIG.md
      Layer 1            Layer 2             Layer 3
    ~5 minutes         Practical           Full
    98 rules           documentation       specification
          │                  │
          │            rules/ + framework/
          │            archetype packs
          └──────────────────┴──► All rules map to HIG.md

1. Resolve archetype
2. HIG-QUICK
3. HIG-LITE + pack
4. Topic module
5. HIG.md (if needed)

Topic loading: rules/manifest.yaml · Session preamble: HIG-CORE.md

Repository structure

web-hig/
├── HIG-QUICK.md             Layer 1 — Quick Reference (98 rules, ~5 min)
├── HIG-LITE.md              Layer 2 — practical guide with rule IDs
├── HIG-CORE.md              Session preamble — philosophy + archetypes
├── HIG.md                   Layer 3 — complete specification
├── VERSION                  Single version pin
├── rules/
│   ├── manifest.yaml        Machine-readable load triggers
│   ├── INDEX.md             Rule ID registry
│   ├── applicability.md     Layer 0 matrix
│   ├── accessibility.md …   16 topic modules
│   └── archetypes/          content, commerce, application, auth
├── framework/               React, Next, Vue, Nuxt, Astro
├── examples/agent-rules/    Cursor, Claude, Copilot templates
├── scripts/validate-hig.mjs Contract validation
└── INTEGRATION.md           Product repo adoption guide

Page archetypes

Identify your page type first. Each archetype pack lists which topic modules to preload. Accessibility, tokens, performance, and security are universal — never optional.

16 topic modules · 4 archetypes · Framework adapters: React, Next.js, Vue, Nuxt, Astro — framework/

Rule ID system

Every enforceable requirement has a stable ID for code review, AI citations, and future lint rules.

Full registry: rules/INDEX.md

Integration into your product

Adopt gradually — most teams start in one afternoon.

1. Pin the contract — copy HIG-QUICK, HIG-LITE, HIG.md, VERSION, rules/, framework/ into docs/hig/ ~10 minutes
2. Map your routes — create docs/hig-scope.md with page types per route Example → · ~15 minutes
3. Add agent rules — copy templates for Cursor, Claude Code, or Copilot Templates → · ~5 minutes
4. PR checklist — use essential rules for human review until linters exist ~10 minutes
5. Lint & CI — automate Layer 7 rules and Layer 8 gates when ready Hours — see INTEGRATION.md

Full guide: INTEGRATION.md

Validation & CI

Keep VERSION, manifest, and modules synchronized when upgrading pins.

npm run validate
# or: node scripts/validate-hig.mjs

Validates version sync, file references, archetype packs, and rule ID consistency. Runs automatically on every PR via GitHub Actions.

Governance & specification

The Web HIG is published as an open standard: rationale, semver, changelog, conformance profiles, and a path to machine-readable rules.

All documents

Glossary

FAQ