Reference — The Web HIG

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.

Archetype	Examples	Default modules	Pack
Content / Marketing	Landing pages, blogs, docs, portfolios	7+	content.md
Commerce	Product pages, cart, checkout	13	commerce.md
Application	Dashboards, admin tools, workflows	15	application.md
Auth / Account	Login, signup, settings	12	auth.md

Content routes declare a surface (document · hybrid · experience). Hybrid and experience pages preload expressive-surface.md (HIG-EXP-001–014).

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

Rule ID system

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

Prefix	Domain	Example
`HIG-A11Y-*`	Accessibility	`HIG-A11Y-003` — native HTML over ARIA
`HIG-TOK-*`	Design tokens	`HIG-TOK-001` — no raw hex outside token files
`HIG-MOT-*`	Motion	`HIG-MOT-001` — no `transition: all`
`HIG-EXP-*`	Expressive content surfaces	`HIG-EXP-001` — declare surface in scope
`HIG-CQ-*`	Container queries	`HIG-CQ-001` (SHOULD) · `HIG-CQ-002` (MUST) for multi-context reuse
`HIG-SSR-*`	Server rendering	`HIG-SSR-001` — default to server rendering
`HIG-MUT-*`	Mutations	`HIG-MUT-001` — no optimistic destructive confirmation
`HIG-SEC-*`	Security	`HIG-SEC-002` — CSP configured
`HIG-SIM-001`	Simplicity	Prefer simplest compliant implementation

Full registry: rules/INDEX.md

Validation & CI

Keep VERSION, manifest, and modules synchronized when upgrading pins. Layer 8 tools emit multidimensional reports — not a single score alone.

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

Contract validation checks version sync, file references, archetype packs, rule ID consistency, documentation site version strings, and adopter pins. Runs on every PR via GitHub Actions.

Product CI evaluators should follow EVALUATOR.md (blocking / warnings / observations plus eight dimensions). Schema: evaluator-report.schema.json

Governance & specification

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

Document	Purpose
RATIONALE.md	Why the standard exists; goals and non-goals
SPECIFICATION.md	Index to normative layers and modules
PROFILES.md	Quick Reference vs Practical vs Full conformance
VERSIONING.md	Semver and pinning in product repos
CHANGELOG.md	Keep a Changelog release history
RELEASE_NOTES.md	Adoption-focused release write-ups
ROADMAP.md	Contract and tooling direction
MACHINE_READABLE.md	Manifest, rule registry, linters
EVALUATOR.md	Multidimensional CI/evaluator report contract (Layer 8)
CONTRIBUTING.md	Spec changes and governance
INTEGRATION.md	Step-by-step adoption in product repos
NPM-TOOLING.md	npm CLI, profiles, `web-hig.yaml`
npm — @web-hig packages	Published packages (maintainer settings on npmjs.com)
ADOPTERS.md	Projects pinning the contract

All documents

Document	Purpose
HIG-QUICK.md	Quick Reference — read first (~5 min, 98 rules)
HIG-LITE.md	Practical guide with rule IDs and checklists (Layer 2)
HIG.md	Complete normative specification
HIG-CORE.md	Philosophy, vocabulary, archetypes
INTEGRATION.md	Product repo adoption guide
npm packages	`@web-hig/install`, `@web-hig/cli`, `@web-hig/core`
SHARE.md	Share badge and copy-paste markdown with UTM parameters
examples/	Scope templates, agent rules, adoption walkthrough
rules/INDEX.md	Topic index & rule ID registry
RELEASE_NOTES.md	Adoption-focused release notes
CONTRIBUTING.md	Proposing spec changes

Glossary

Term	Meaning
Archetype	Page category (marketing, shop, app, login) that determines required rules
Design token	Named design value (e.g. `--color-primary`) instead of hard-coded values
HIG-QUICK	98-rule Quick Reference — default context for daily work and AI agents
HIG-LITE	Practical guide with rule IDs — Layer 2 documentation
Rule ID	Stable code like `HIG-A11Y-003` identifying one specific requirement
WCAG 2.2 AA	International accessibility standard — our compliance target
Core Web Vitals	Google metrics: load speed (LCP), responsiveness (INP), stability (CLS)
Progressive loading	Opening only the docs needed for the current task

FAQ

Where do I start?

HIG-QUICK.md is the whole onboarding path — about five minutes. Pin that file, then tell agents: Follow The Web HIG Quick Reference.

Is this a component library?

No. It is a rulebook and engineering contract, not a component library. You keep your design system, framework, and components; the HIG defines how they should work together.

Do I need to follow every rule?

Follow rules for your page type and feature. Accessibility, tokens, performance, and security are always required. Use archetype packs to see what's mandatory for your case.

I'm not using AI — is this still for me?

Yes. The HIG is written for human developers and designers first. AI-related sections are optional extras for teams using Cursor, Copilot, or Claude Code.

How is this different from a style guide?

A style guide covers look and feel. This also covers behavior: error handling, delete flows, performance targets, accessibility compliance, and security requirements.

Is this competing with WCAG, Material, or Lighthouse?

No. WCAG is the accessibility target. Material, Fluent, Carbon, and GOV.UK are visual or domain design systems. Lighthouse measures. WAI-ARIA APG and Open UI cover widgets and platform primitives. The Web HIG is the behavioral contract that sits in the gap between them — see the competitive landscape.

Can I customize rules for my product?

Documented exceptions are allowed with justification. Security, accessibility, and data-protection rules cannot be skipped.