What is HIG Doctor?
HIG Doctor is an open-source toolkit from Raintree Technology that audits Apple-platform source against the Human Interface Guidelines and web or cross-platform source against aligned accessibility rules. It ships a CLI with 431 rules across 14 frameworks, an MCP server and 14 reference skills.
HIG Doctor helps developers and coding agents find interface issues before release. It checks Apple-platform source against Apple's Human Interface Guidelines, and web and cross-platform source against accessibility and interface-quality rules that align with them.
It has four surfaces: an audit CLI for scans and CI gates, an MCP server for lookup and audits, agent skills with design guidance, and a core package for embedding the rule engine.
What the audit reports
- Findings carry severity, file and line, a rule ID, fix guidance and the reference behind the concern.
- The catalog holds 431 rules across 14 frameworks, including SwiftUI, UIKit, React and Next.js, CSS and SCSS, Vue, Angular, Svelte, Flutter and Compose.
- Configuration, inline suppressions, content-based baselines, SARIF output and a fail-on flag let you gate only new problems.
- Precision and recall are measured on an annotated fixture corpus and enforced in CI.
Who HIG Doctor is for
Best for
- Teams shipping SwiftUI, UIKit or AppKit apps that want HIG checks in review and CI.
- Web teams that want a rule-based interface and accessibility scan alongside manual review.
- Agents that need bounded reference lookups, next to swiftui-expert-skill or apple-design.
Not for
- Proof of conformance. The README says findings support review and do not prove accessibility, HIG conformance or design quality.
- Live HIG text. The bundled skills are a frozen 2025-02-02 snapshot; Apple's live guidelines remain canonical.
- Android-first teams expecting Material rules. The README describes its Android XML and Compose rules as HIG-aligned universal checks.
Use it with UiChemy
Web and CSS rules in HIG Doctor can scan the front end of a WordPress theme or a page exported from a UiChemy build. Fix findings in the editor afterwards. Click Get Started on uichemy.com.
How to install HIG Doctor Skill: Apple HIG Audits for AI Agents
npx hig-doctor .The README lists the core package separately: npm install @raintree-technology/hig-doctor-core.Run the audit
From your project root run the command. It detects frameworks and prints concerns by severity with fix guidance.
Add the MCP server
Run npx -y hig-mcp as a stdio server, or use streamable HTTP. Client configuration is in the MCP package README.
Copy the skills
Clone the repository and copy the folders you want from the skills directory into your agent's skills folder, since the README points to them as canonical agent skills.
Gate in CI
Use the fail-on flag and a baseline, or SARIF output, so only new findings fail a build.
Check that it loaded
Run npx hig-doctor . on a project with a deprecated NavigationView or a hard-coded color. It should list those rule IDs with file and line.
Key features
- 431-rule audit catalogRules span 14 frameworks, with 70 for SwiftUI, 35 for UIKit and 122 for React and Next.js, generated from the catalog and checked in CI.
- Framework detectionThe CLI detects the project's frameworks, then reports concerns by severity with a file, line and rule ID.
- Layered analysisA comment-aware regex tier runs first, Swift structural analysis removes handled findings, and the TypeScript compiler refines selected JSX accessibility checks.
- Gradual adoptionBaselines, inline suppressions, SARIF and a fail-on flag let a team gate only new debt.
- MCP server with six toolsLists skills, looks up topics, searches the reference corpus, audits projects or files and explains findings, over stdio or streamable HTTP.
- Fourteen reference skillsFoundations, platforms, patterns, inputs, technologies and eight component groups, with 156 reference topics in a frozen snapshot.
- Drift detectionA nightly job compares the snapshot with Apple's DocC JSON, and content changes stay human reviewed.
- Core packageAn embeddable rule engine shares the same catalog and analysis tiers as the CLI and MCP server.
- Stated limitsRegex fallback can differ in precision from structural analysis, and project context can justify a documented suppression.
Frequently asked questions
What is HIG Doctor?
HIG Doctor is an open-source toolkit that checks Apple-platform source against Apple's Human Interface Guidelines and checks web and cross-platform source against aligned accessibility and interface-quality rules. It ships a CLI, an MCP server, agent skills and an embeddable core package.
How do I run a HIG audit?
Run npx hig-doctor . in your project root. The CLI detects the frameworks, reports concerns by severity and points to a specific fix and source reference. Add configuration, baselines or the fail-on flag when you want to use it in CI.
Which frameworks does HIG Doctor cover?
The catalog covers SwiftUI, UIKit, AppKit, watchOS and visionOS against the HIG, plus React and Next.js, CSS and SCSS, Vue and Nuxt, Angular, Svelte, Flutter, Jetpack Compose, Android XML and React Native with HIG-aligned checks.
Does HIG Doctor prove my app follows the HIG?
No. The README says automated findings support review and do not prove accessibility, HIG conformance or design quality. Regex fallback can differ in precision from structural analysis, and project context can justify a suppression.
What tools does the MCP server provide?
Six tools: list skills, look up topics, search the corpus, audit projects or files, and explain findings. It runs over stdio or streamable HTTP, and the README says explanations are not presented as canonical HIG advice.
Is the Apple HIG text in the repo current?
The skills are a frozen 2025-02-02 snapshot of 14 skills and 156 reference topics. A nightly job checks for drift against Apple's DocC JSON, and Apple's live guidelines remain canonical. Apple owns the HIG content.
What else should I use with it?
For an Apple-specific MCP server see hig-mcp, and for general accessibility checks use accessibility-testing. swiftui-expert-skill helps write the SwiftUI code that the audit then checks, so the two work as a pair.


