A practical standard for how modern web interfaces should behave.
The Web HIG provides a common set of rules for building web applications that are usable, accessible, responsive, performant, predictable, and safe.
It does not tell you what your product should look like.
Keep your existing design system, framework, components, branding, and visual style. The Web HIG defines the expected behavior and quality of the interface around them.
For example, it covers questions such as:
- What should happen while data is loading?
- How should errors and empty states behave?
- When is optimistic UI appropriate?
- How should destructive actions be handled?
- What accessibility requirements should every interface meet?
- How should responsive layouts, forms, navigation, search, and notifications behave?
- What performance expectations should a production interface meet?
- How should AI coding agents apply these rules consistently?
The same standard can be used by developers, designers, reviewers, CI systems, and AI coding agents.
Use HIG Audit to evaluate an existing website against The Web HIG.
The Web HIG is the standard. HIG Audit is a separate tool that applies the standard to an existing implementation.
The Web HIG
│
│ defines the rules
▼
Your application / design system
│
│ can be evaluated with
▼
HIG Audit
The Web HIG is a vendor-neutral, versioned web interface standard.
It defines testable guidance for:
- interaction and UX behavior
- loading, empty, error, stale, and offline states
- navigation and information architecture
- forms and validation
- destructive actions and mutations
- accessibility, targeting WCAG 2.2 AA
- responsive layout and design tokens
- motion and animation
- search and notifications
- rendering and application architecture
- performance
- security and privacy UX
- AI-assisted development and enforcement
Rules can be referenced using stable HIG-* identifiers where applicable, allowing teams and tools to discuss the same requirement consistently.
The Web HIG is not:
- a component library
- a CSS framework
- a Figma UI kit
- a replacement for your design system
- a visual style or branding system
- a replacement for WCAG, HTML, CSS, or ARIA
- an automated audit tool
Your design system defines what your interface looks like.
The Web HIG defines how the interface should behave.
You do not need to read the complete specification.
Start with HIG-QUICK.md.
It contains the practical rules most developers and AI coding agents need during everyday work.
Copy HIG-QUICK.md and VERSION into your project:
docs/
└── hig/
├── HIG-QUICK.md
└── VERSION
Or use the installer:
npx @web-hig/installAfter installing or copying the standard, instruct your agent:
Follow The Web HIG Quick Reference for this project.
Agent integrations are available for:
- Cursor
- Claude Code
- GitHub Copilot
- Windsurf
- multi-agent environments
See skills/ and examples/agent-rules/.
You can use WebHIG with your existing design process. WebHIG and Design Decision Method (DDM) help with different parts of the work, and each stands on its own.
| What it helps you do | Example | |
|---|---|---|
| WebHIG | Build interfaces that behave clearly, consistently and accessibly | Make errors understandable and preserve entered information when saving fails |
| Design Decision Method (DDM) | Choose an interface that fits the people and task | Decide whether a task needs one form or a step-by-step flow |
If you also want help choosing layouts, navigation and interaction patterns, DDM gives you a structured way to make those decisions. DDM is optional.
Most people only need HIG-QUICK.
| Need | Start here |
|---|---|
| I just want to understand Web HIG | HIG-QUICK.md |
| I want to use it in a project | INTEGRATION.md |
| I use Cursor / Claude / Copilot / Windsurf | skills/ |
| I need individual rule IDs | HIG-LITE.md |
| I need the complete normative specification | HIG.md |
| I want to understand why HIG exists | RATIONALE.md |
| I want to audit an existing website | HIG Audit |
Current release: v1.17.0 · Changelog · Release notes
Declare supported color schemes in the initial document, before JavaScript. light dark is the usual declaration; light only is an opt-out, not the default. Safari 27.3 Adaptive Dark Mode can repaint an undeclared light page, and computed styles still show the authored colors, so contrast checks need a screenshot. Long Animation Frames style and layout durations diagnose INP when the browser exposes them and do not add a pass/fail. HTML-in-Canvas stays informative. Still 98 Quick imperatives and 76 stable rule IDs. See the release notes.
Stable Core Web Vitals thresholds are unchanged. Experimental CrUX soft-navigation LCP, INP, and CLS variants must be labeled, dated by dataset month, and kept as a separate pass/fail. Scroll-driven animations (animation-timeline, scroll(), view()) are motion; shortening duration does not stop them. Safari 27.2 VoiceOver checks are manual fixtures, not a new author rule. Still 98 Quick imperatives and 76 stable rule IDs. See the release notes.
Apply the existing standard to landing pages, portfolios and other content routes with the applied guide, manual review worksheet, and document/hybrid fixtures.
The examples cover semantic hierarchy, keyboard actions, responsive information, image delivery, conditional metadata, and applicable reduced-motion/enhancement fallbacks. Each check identifies its surface and capability conditions. The worksheet records pass, fail, not tested or not applicable; it supplies evidence rather than a complete evaluator report.
This is an informative guidance release. Existing requirements, severity and applicability are unchanged: 98 Quick imperatives and 76 stable rule IDs. No prescribed layout, sales CTA or universal no-JavaScript requirement is added. Manual browser and assistive-technology checks for the new fixtures remain untested; see their execution record.
Documentation site · HIG Audit · Integration guide · Adopters
The Web HIG uses progressive disclosure so projects and AI agents only load the level of detail they need.
| Level | Document | Use it for |
|---|---|---|
| Quick | HIG-QUICK.md | Daily development, agents, PR review |
| Practical | HIG-LITE.md + rules/ | Features, rule IDs, modules, archetypes |
| Full | HIG.md | Edge cases, CI gates, formal interpretation |
THE WEB HIG
│
┌─────────────────┼─────────────────┐
│ │ │
HIG-QUICK.md HIG-LITE.md HIG.md
Layer 1 Layer 2 Layer 3
~5 minutes Practical Normative
│ │
│ rules/ + framework/
└─────────────────┴──► Same standard
The Quick Reference currently contains 98 numbered imperatives.
The practical rule registry contains 76 stable HIG-* rule IDs.
These numbers intentionally describe different layers. Quick rules are concise development heuristics; canonical IDs represent individually citeable requirements.
Machine-readable mappings are available in rules/quick-rule-map.yaml.
Modern products already use several layers of standards and tooling.
The Web HIG does not try to replace them.
| Layer | Examples |
|---|---|
| Web platform | HTML, CSS, ARIA |
| Accessibility | WCAG 2.2 |
| Design system | Material UI, shadcn, Tailwind-based systems, custom components |
| The Web HIG | Product behavior, interface states, architecture, quality and enforcement |
| Application | Routes, data, business logic |
In simplified form:
HTML / CSS / ARIA
↓
WCAG
↓
Your design system
↓
The Web HIG
↓
Your application
See RATIONALE.md for the full reasoning.
The Web HIG is intended to work as a shared interface contract between humans and development tools.
Developer / Designer
↓
Pinned Web HIG
↓
AI agent
↓
Code
↓
Review / Validation
↓
CI
Instead of every developer or coding agent making independent UX decisions, the project can reference the same version of the same rules.
| Tool | Always-on rule | Skill |
|---|---|---|
| Cursor | examples/agent-rules/cursor-hig.mdc | .cursor/skills/web-hig/ |
| Claude Code | examples/agent-rules/CLAUDE-hig.md | .claude/skills/web-hig/ |
| GitHub Copilot | examples/agent-rules/copilot-instructions-hig.md | .github/skills/web-hig/ |
| Windsurf | examples/agent-rules/windsurf-hig.md | .windsurf/skills/web-hig/ |
| Multi-agent | examples/agent-rules/AGENTS-hig.md | — |
Canonical skill: skills/web-hig/SKILL.md
Skill installation map: skills/README.md
Machine-readable topic loading: rules/manifest.yaml
Adopting HIG does not require rebuilding your interface.
A typical project can:
- keep its existing framework and components
- pin a Web HIG version
- give the Quick Reference to developers and coding agents
- apply rules when building or modifying features
- reference
HIG-*IDs during reviews where applicable - progressively add automated checks
For a guided adoption path, see INTEGRATION.md.
For evaluating an existing interface, use HIG Audit.
The specification and its automated tooling intentionally remain separate concepts.
This repository contains the standard, machine-readable rules, agent integrations, and supporting developer tooling.
npx @web-hig/installweb-hig checkweb-hig check --jsonexplainupgrade- agent rule templates
- agent skills
- machine-readable manifests
- validation fixtures
For website evaluation and conformance analysis, use:
See:
The current specification contains:
98 Quick imperatives · 76 rule IDs · 17 topic modules · 4 page archetypes · Layers 0–9
| Layer | Focus |
|---|---|
| 0 | Applicability & archetypes |
| 1 | UX, motion, density |
| 2 | IA, forms, search, notifications, i18n |
| 3 | Tokens, container layout |
| 4 | Server-driven UI, state machines, mutations |
| 5 | Accessibility — WCAG 2.2 AA target |
| 6 | Performance — lab & field |
| 7 | Rule IDs, agent guardrails |
| 8 | CI blocking / warning / observation |
| 9 | Security & privacy UX |
Full index: SPECIFICATION.md
Module index: rules/INDEX.md
Not every rule applies to every page.
Web HIG first identifies the type of surface being built:
- Content
- Commerce
- Application
- Authentication
Content surfaces can additionally be classified as:
- document
- hybrid
- experience
This prevents teams and agents from blindly applying every requirement everywhere.
See SPECIFICATION.md and PROFILES.md.
| Document | Purpose |
|---|---|
| HIG-QUICK.md | Fast onboarding and everyday rules |
| RATIONALE.md | Why the standard exists |
| SPECIFICATION.md | Normative layer and module index |
| HIG.md | Complete normative specification |
| HIG-LITE.md | Practical rule-ID reference |
| PROFILES.md | Quick, Practical and Full profiles |
| VERSIONING.md | Semver, pinning and upgrades |
| CHANGELOG.md | Version history |
| RELEASE_NOTES.md | Adoption-focused release notes |
| ROADMAP.md | Standard and tooling direction |
| MACHINE_READABLE.md | Machine-readable contract |
| EVALUATOR.md | Evaluator and CI report contract |
| INTEGRATION.md | Project adoption guide |
| CONTRIBUTING.md | Governance and contributions |
| ADOPTERS.md | Projects using the standard |
| skills/ | AI coding-agent skills |
| packages/install | npx @web-hig/install |
| examples/ | Integration examples |
| SHARE.md | Badges and sharing |
Install:
npx @web-hig/installThis pins the Quick Reference and installs appropriate agent guidance.
Then define the parts of your application that should follow the standard using:
For deeper rule coverage:
npx @web-hig/install --profile practicalComplete walkthrough:
examples/adoption/quick-profile-walkthrough.md
Example consumer project:
Add the Web HIG badge to a project that follows the standard:
[](https://github.com/frozonfreak/webhig?utm_source=github_readme&utm_medium=badge&utm_campaign=share)Additional badges and attribution options are available in SHARE.md.
Contributions are welcome.
Read CONTRIBUTING.md before proposing specification changes.
Code of conduct: CODE_OF_CONDUCT.md
Licensed under the MIT License.