Adopt in your product — The Web HIG

Start here

You do not need to read the complete specification or change your design system. Start with the Quick Reference, then decide how deeply to integrate.

First: read HIG-QUICK.md

It contains the practical rules most developers, designers, reviewers, and AI coding agents need during everyday work. If it fits your project, copy it into docs/hig/ with VERSION.

Open the Quick Reference

I am a developer

Read the Quick Reference, pin it in your repo, and cite it during PR review.

Open HIG-QUICK.md →

I am a designer

Use the same file to check states, accessibility, responsive behavior, tokens, and motion.

Open HIG-QUICK.md →

I am using an AI coding agent

Install or copy the standard, then tell the agent: Follow The Web HIG Quick Reference.

npm tooling →

I already have a website

Use HIG Audit to evaluate the existing implementation before changing the repo.

Open HIG Audit →

Choose an adoption path

Pick the lightest path that matches what you need today. You can always move to a deeper layer later.

Lightest

Read and cite

Use HIG-QUICK during planning, design review, and PR review. Good for evaluating whether the standard fits your team.

Read HIG-QUICK.md →

Recommended

Pin in your repo

Copy HIG-QUICK.md and VERSION into docs/hig/ so humans and agents share the same version.

See the manual steps →

Tooling

Install with npm

Use the installer when you want agent rules, skills, route scope examples, and future checks set up together.

Use npm packages →

Already have a website?

The Web HIG is the standard. HIG Audit is a separate tool that applies the standard to an existing implementation.

The Web HIG Your application HIG Audit

Open HIG Audit

Try it in one afternoon

Run npx @web-hig/install to pin the contract under docs/hig/, map routes in docs/hig-scope.md (archetype plus surface for content pages), and install agent rules plus skills. Use the Quick Reference in PR review.

Prefer a manual start? Copy HIG-QUICK.md and VERSION into docs/hig/, then add route scope and CI checks when the team is ready.

Step-by-step checklist (pin → scope → agents → CI): Integration into your product → · PR checklist template →

npm packages

Executable conformance tooling for the pinned HIG contract — install, check, and explain rules in product repos and CI. Not a component library; use your existing stack and design system.

Package	Role	Install
`@web-hig/install`	Pin `docs/hig/`, agent rules, and skills (`npx @web-hig/install`)	`npx @web-hig/install`
`@web-hig/cli`	`web-hig init`, `check`, `explain` — static conformance reports	`npm i -D @web-hig/cli`
`@web-hig/core`	Registry loader, `web-hig.yaml` parsing, evaluator report model (for custom CI/tools)	`npm i @web-hig/core`

Typical flow: npx web-hig init --profile practical → set WEB_HIG_ROOT=docs/hig → add web-hig.yaml → npx web-hig check.

Architecture: NPM-TOOLING.md · Maintainer publish guide: packages/PUBLISHING.md · npm org packages (maintainers)

Share this HIG

Add a badge to your README, blog, or docs. Each snippet links to the GitHub repo with UTM parameters so inbound clicks can be attributed by source.

Full snippets and UTM convention: SHARE.md. For a pinned-semver conformance line, see PROFILES.md.

Integration into your product

Adopt gradually — most teams start in one afternoon.

Pin the contract — npx @web-hig/install (or copy HIG-QUICK, VERSION, and rules into docs/hig/) Installer → · ~1 minute
Map your routes — create docs/hig-scope.md with archetype per route and surface for content (document · hybrid · experience) Example → · ~15 minutes
Add agent rules — installer copies Cursor, Claude Code, Copilot, and Windsurf rules plus skills; or copy templates manually Skills → · ~5 minutes
PR checklist — copy the conformance checklist for human review until linters exist Template → · ~10 minutes
Lint & CI — run web-hig check in PR pipelines; expand with ESLint/Stylelint plugins over time npm packages → · INTEGRATION.md

Full guide: INTEGRATION.md