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

Terminal

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:

text

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

Surface	Use it for	Start
Audit CLI	Source scans and CI gates	`npx hig-doctor .`
MCP server	Search, lookup, file audits, and explanations	`npx -y hig-mcp`
Agent skills	Design guidance and source audits	`codex plugin add hig-doctor@raintree`
Core package	Embed the rule engine	`npm install @raintree-technology/hig-doctor-core`

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.

Install the public Codex marketplace first with codex plugin marketplace add raintree-technology/plugins.

How analysis works

text

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.

Framework	Rules	Basis
SwiftUI (`swift`)	70	Apple HIG
UIKit	35	Apple HIG
AppKit	25	Apple HIG
watchOS	13	Apple HIG
visionOS	10	Apple HIG
React / Next.js (`web`)	122	HIG-aligned universal checks
CSS / SCSS	25	HIG-aligned universal checks
Vue / Nuxt	19	HIG-aligned universal checks
Angular	17	HIG-aligned universal checks
Svelte / SvelteKit	14	HIG-aligned universal checks
Flutter	21	HIG-aligned universal checks
Jetpack Compose	28	HIG-aligned universal checks
Android XML	18	HIG-aligned universal checks
React Native	14	HIG-aligned universal checks

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.

Skill	Description
`hig-foundations`	Color, typography, symbols, accessibility, layout, motion, privacy, and branding
`hig-platforms`	iOS, iPadOS, macOS, tvOS, watchOS, and visionOS
`hig-patterns`	Onboarding, navigation, search, feedback, modality, and settings
`hig-inputs`	Touch, Pencil, keyboard, controller, pointer, Crown, and eye input
`hig-technologies`	Siri, Apple Pay, HealthKit, ARKit, ML, Sign in with Apple, and SharePlay
`hig-project-context`	Shared project context for tailored guidance
`hig-components-content`	Charts, collections, images, web views, and lockups
`hig-components-controls`	Pickers, toggles, sliders, buttons, and fields
`hig-components-dialogs`	Alerts, action sheets, popovers, and sheets
`hig-components-layout`	Sidebars, split views, tabs, lists, tables, and windows
`hig-components-menus`	Menus, toolbars, buttons, and menu bars
`hig-components-search`	Search fields, page controls, and path controls
`hig-components-status`	Progress indicators, status bars, and activity rings
`hig-components-system`	Widgets, live activities, notifications, complications, and App Clips

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.

Project policies

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