HIG Doctor

HIG Doctor

Active open-source project · MIT tooling with attributed Apple reference content

HIG Doctor helps developers and coding agents find interface issues before release. It checks Apple-platform source against Apple’s Human Interface Guidelines and checks web and cross-platform source against aligned accessibility and interface-quality rules.

Run an audit

npx hig-doctor .

The CLI detects the project frameworks, reports concerns by severity, and points to a specific fix and source reference. This result is generated from the committed test/fixtures/readme-audit project and checked in the test suite:

2 moderate concerns · swiftui · 1 file
View.swift:5 · swift/navigation-view-deprecated
View.swift:7 · swift/hardcoded-color

The audit catalog currently contains 431 rules across 14 frameworks. Counts are generated from the rule catalog and checked in CI; they are coverage inventory, not a claim of complete HIG conformance.

Why use HIG Doctor

• Catch reviewable source issues. Findings include severity, location, rule ID, fix guidance, and the reference that supports the concern.
• Gate only new debt. Configuration, inline suppressions, content-based baselines, SARIF, and --fail-on support gradual adoption.
• Give agents bounded guidance. MCP tools search the frozen reference corpus and explain individual findings without presenting generated advice as canonical HIG.
• Use one engine across workflows. The CLI, MCP server, and embeddable core package share the same catalog and analysis tiers.

Choose a surface

The MCP server works over stdio or streamable HTTP. Its six tools list skills, look up topics, search the corpus, audit projects or files, and explain findings. See the MCP package README for client configuration.

How analysis works

framework detection → regex scan → structural refinement → categorized findings → report or SARIF

• The zero-dependency regex tier is comment- and string-aware.
• Swift structural analysis follows chained modifiers to remove handled findings.
• The TypeScript compiler refines selected JSX accessibility checks when available.
• Every finding records the engine that produced it.

Precision and recall are measured on an annotated fixture corpus in docs/benchmark.md. CI enforces the published floors.

Framework coverage

Apple-platform rows are checked against the HIG directly. Web and cross-platform rows use universal accessibility and interface-quality principles that align with the HIG.

The authoritative per-rule inventory is docs/rules.md.

Skills corpus

The frozen 2025-02-02 snapshot contains 14 skills and 156 reference topics. Apple’s live Human Interface Guidelines remain canonical.

Nightly drift detection compares the snapshot with Apple’s DocC JSON. Content changes remain human-reviewed; a hash change does not automatically rewrite guidance.

Limits and evidence boundary

Automated findings support review. They do not prove accessibility, HIG conformance, or design quality. Regex fallback can produce different precision than structural analysis, and project-specific context can justify a documented suppression.

Apple owns the HIG content. This repository provides organization, cross-referencing, and detection rules. Each reference retains attribution and a canonical source URL.

Documentation

• CLI package — Flags, configuration, baselines, and CI.
• MCP package — Tools, transports, and client setup.
• Core package — Embedding API.
• Rule catalog — Current generated inventory.
• Detection benchmark — Fixture method, results, and limits.
• Brand system and Remotion showcase.
• Project website — Human and agent-readable topics.

Raintree open-source system

HIG Doctor owns interface guidance and source audits. It can be used independently. DocPull acquires evidence, PolicyStrata tests policy behavior, Trellis enforces shared code policy, and Raintree Standards defines governed requirements. See the Raintree open-source portfolio.

Raintree also builds BetterOff, which keeps a household's spending, investments, assets, debts, and net worth in one current record.

Project policies

Contributing · Code of Conduct · Security · Changelog · Source repository · MIT License · Third-party notices

Apple HIG reference text in skills/*/references/ is © Apple Inc. and remains subject to Apple’s terms.