Skip to content
frozonfreakPublic

About

Universal Human Interface Guidelines

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

91 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

The Web HIG

Version License: MIT Try HIG Audit Validate HIG Pin me

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.


Already have a website?

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

Open HIG Audit →


What The Web HIG is

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.


What it is not

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.


Start in 5 minutes

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.

For a developer

Copy HIG-QUICK.md and VERSION into your project:

docs/
└── hig/
    ├── HIG-QUICK.md
    └── VERSION

Or use the installer:

npx @web-hig/install

For an AI coding agent

After 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/.


Companion: Design Decision Method

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.


Which document should I read?

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

New in v1.17.0: authored color schemes and frame diagnostics

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.

New in v1.16.0: field metrics and scroll-driven motion

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.

New in v1.15.0: Content / Marketing examples

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


One standard, three levels

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.


Where Web HIG fits

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.


Built for humans and AI

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.

Agent integrations

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


Use it with an existing project

Adopting HIG does not require rebuilding your interface.

A typical project can:

  1. keep its existing framework and components
  2. pin a Web HIG version
  3. give the Quick Reference to developers and coding agents
  4. apply rules when building or modifying features
  5. reference HIG-* IDs during reviews where applicable
  6. progressively add automated checks

For a guided adoption path, see INTEGRATION.md.

For evaluating an existing interface, use HIG Audit.


Tooling

The specification and its automated tooling intentionally remain separate concepts.

This repository contains the standard, machine-readable rules, agent integrations, and supporting developer tooling.

Available today

  • npx @web-hig/install
  • web-hig check
  • web-hig check --json
  • explain
  • upgrade
  • agent rule templates
  • agent skills
  • machine-readable manifests
  • validation fixtures

Separate audit tooling

For website evaluation and conformance analysis, use:

HIG Audit →

Planned / evolving tooling

See:


Specification overview

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


Page archetypes

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.


Standard documentation

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

Try it in one project

Install:

npx @web-hig/install

This pins the Quick Reference and installs appropriate agent guidance.

Then define the parts of your application that should follow the standard using:

examples/hig-scope.example.md

For deeper rule coverage:

npx @web-hig/install --profile practical

Complete walkthrough:

examples/adoption/quick-profile-walkthrough.md

Example consumer project:

examples/golden-path


Share The Web HIG

Add the Web HIG badge to a project that follows the standard:

The Web HIG

[![The Web HIG](https://frozonfreak.github.io/webhig/badge.svg)](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.


Contributing

Contributions are welcome.

Read CONTRIBUTING.md before proposing specification changes.

Code of conduct: CODE_OF_CONDUCT.md


License

Licensed under the MIT License.

About

Universal Human Interface Guidelines

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages