hig-doctor

<p align="center">
  <img src="brand/hig-doctor-mark.svg" alt="HIG Doctor" width="96" height="96" />
</p>

# HIG Doctor

Agent-native Apple Human Interface Guidelines: a structured skills corpus, MCP server, and universal compliance auditor for AI coding agents and developers.

[![GitHub stars](https://img.shields.io/github/stars/raintree-technology/hig-doctor?style=social)](https://github.com/raintree-technology/hig-doctor/stargazers)

- **Skills corpus** — 14 skills and 156 reference topics covering the complete HIG (foundations, components, patterns, inputs, platforms, technologies). Snapshot dated 2025-02-02; canonical content remains at [developer.apple.com/design/human-interface-guidelines](https://developer.apple.com/design/human-interface-guidelines/).
- **MCP server** ([`hig-mcp`](https://www.npmjs.com/package/hig-mcp)) — six tools for Claude Desktop, Cursor, Windsurf, and Claude Code: `hig_list_skills`, `hig_lookup`, `hig_search` (BM25 over every topic), `hig_audit`, `hig_audit_file`, and `hig_explain_finding`. Runs over stdio or streamable HTTP.
- **Audit CLI** ([`hig-doctor`](https://www.npmjs.com/package/hig-doctor)) — a **431-rule** compliance scanner across 14 frameworks. A regex base tier plus a TypeScript-compiler JSX tier and a Swift structural tier; every finding is tagged with the engine that produced it. Config files, inline suppressions, baselines, SARIF output, and `--fix` autofixes.
- **Engine** ([`@raintree-technology/hig-doctor-core`](https://www.npmjs.com/package/@raintree-technology/hig-doctor-core)) — the rule engine, embeddable in your own tooling.

Content is © Apple Inc.; this repository provides organization, cross-referencing, and detection rules for AI agent use. MIT-licensed for structure and tooling.

Production logo files and usage guidance are available in [`brand/`](brand/).

## Star History

<a href="https://star-history.com/#raintree-technology/hig-doctor&Date">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=raintree-technology/hig-doctor&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=raintree-technology/hig-doctor&type=Date" />
    <img alt="Star history chart for raintree-technology/hig-doctor" src="https://api.star-history.com/svg?repos=raintree-technology/hig-doctor&type=Date" />
  </picture>
</a>

## Install as a Claude Code plugin

```bash
/plugin marketplace add raintree-technology/hig-doctor
```

Or add as a git submodule into any project's `.claude/` directory.

## MCP server

The published package bundles the skills corpus, so it runs with no clone:

```json
{
  "mcpServers": {
    "hig-doctor": {
      "command": "npx",
      "args": ["-y", "hig-mcp"]
    }
  }
}
```

Tools:

| Tool | Purpose |
|------|---------|
| `hig_list_skills` | Enumerate skills, descriptions, and reference topics. |
| `hig_lookup` | Fetch HIG reference markdown by skill (and optional topic). |
| `hig_search` | BM25 full-text search across every reference topic — ask in natural language. |
| `hig_audit` | Run the HIG compliance audit on a project directory. |
| `hig_audit_file` | Audit a single file the agent just wrote; returns per-finding fixes. |
| `hig_explain_finding` | Rule metadata plus an excerpt of the cited HIG reference, by rule ID. |

Every tool returns structured JSON alongside text. For a local checkout, point `command`/`args` at `bun /abs/path/packages/mcp/src/index.ts`. `hig-mcp --http [port]` serves the same tools over streamable HTTP. `HIG_SKILLS_DIR` overrides the bundled corpus.

## HIG Audit CLI

Scan any project for Apple HIG compliance across SwiftUI, UIKit, AppKit, watchOS, visionOS, React/Next.js, Vue/Nuxt, Svelte/SvelteKit, Angular, React Native, Flutter, Jetpack Compose, Android XML, and plain HTML/CSS — **431 rules** across accessibility, color, typography, layout, dark mode, motion, and i18n.

```bash
npx hig-doctor <directory>
# or, from a git clone (requires Bun): bun run --cwd packages/cli audit <directory>
```

Example output:

```
  HIG Audit: my-app   2 serious

  nextjs · 412 detections · 48 files
  ────────────────────────────────────────────────────────────────────
  Foundations                312  ██████████████░░░░░░  286 good  2 serious
  Layout & Navigation         41  ████░░░░░░░░░░░░░░░░  9 good
  Controls                    24  ░░░░░░░░░░░░░░░░░░░░
  Input Methods               15  ██████████████░░░░░░  11 good
  ────────────────────────────────────────────────────────────────────
  Totals                     412  306 good  2 serious  4 moderate

  Serious issues found — Significant HIG violations degrade UX.
```

### Options

| Flag | Description |
|------|-------------|
| `--export` | Write a full audit report to `<directory>/hig-audit.md` |
| `--stdout` | Print raw audit markdown to stdout (pipe to an AI for evaluation) |
| `--json` | Print structured results as JSON, including per-concern fix suggestions |
| `--format sarif` | Emit SARIF 2.1.0 for GitHub code scanning |
| `--fix` | Apply safe mechanical fixes in place; print unsafe ones as suggestions |
| `--fail-on <severity>` | Exit 1 if any concern at/above `critical`, `serious`, or `moderate` is found |
| `--config <path>` / `--no-config` | Use or skip `hig-doctor.config.json` |
| `--write-baseline` / `--baseline <path>` / `--no-baseline` | Snapshot, use, or ignore a baseline |
| `--exclude <glob>` | Skip paths (repeatable; also reads `.higauditignore`) |
| `--cache` | Cache per-file results; re-scan only changed files |
| `--help` | Show help |

### Configuration, suppressions, and baselines

A `hig-doctor.config.json` in the audited project disables rules, remaps severities, ignores globs, and adds per-path overrides (rule IDs are documented in [`docs/rules.md`](docs/rules.md)):

```json
{
  "rules": { "swift/hardcoded-color": "off", "css/*": "moderate" },
  "ignore": ["legacy/**"],
  "overrides": [{ "files": ["marketing/**"], "rules": { "css/outline-none": "off" } }]
}
```

Inline comments suppress at the source: `// hig-disable-next-line swift/hardcoded-color -- brand splash` and `// hig-disable-file <rule-id>` (any comment syntax). `hig-doctor --write-baseline` snapshots existing concerns into `.hig-baseline.json`, keyed by content rather than line number, so a CI gate only fails on **new** violations.

### Severity model

Concerns are classified as:

- **critical** — accessibility-breaking (missing alt, empty button, `user-scalable=no`, `<video>` without captions, etc.)
- **serious** — significant UX degradation (`div` with `onClick` and no role, positive tabindex, `outline: none` outside progressive enhancement, `onTapGesture` without traits, hover-without-focus, autoplay, etc.)
- **moderate** — HIG style/best-practice violations (hardcoded colors, deprecated components, `!important` usage, physical text-align, etc.)

Positive detections (semantic colors, Dynamic Type, accessibility modifiers, focus-visible, reduced-motion support) are tracked and reported but don't affect the gate.

### What it detects

The audit scans code, stylesheets, and config files, then categorizes findings across HIG areas:

- **Foundations** — semantic vs hardcoded colors, Dynamic Type vs fixed font sizes, dark mode, motion preferences, accessibility labels, focus management, heading hierarchy, landmark regions, touch targets, i18n/RTL support
- **Layout & Navigation** — navigation patterns, responsive breakpoints, semantic HTML, adaptive layout, sidebar/tab patterns
- **Controls** — buttons, toggles, form elements, interactive controls, labels
- **Content Display** — images, collections, tables, cards, accordions, lists
- **Input Methods** — keyboard support, gesture handling, form validation, input types, fieldset/legend, autocomplete
- **Interaction Patterns** — drag and drop, pull-to-refresh, undo, animations, haptics, error handling
- **Dialogs & Presentations** — modals, sheets, alerts, popovers, toasts, tooltips
- **Menus & Actions** — dropdown menus, context menus, toolbars, menu roles
- **Search & Navigation** — search fields, search roles, page controls
- **Status & Progress** — progress indicators, loading states, aria-busy
- **Apple Technologies** — WidgetKit, ActivityKit, HealthKit, ARKit, Apple Pay, Sign in with Apple

**Context-aware rules**: `!important` inside `@media print` and `prefers-reduced-motion` blocks is not flagged. `outline: none` inside `:focus:not(:focus-visible)` progressive enhancement is not flagged. Hover rules skip pseudo-element selectors like `::-webkit-scrollbar-thumb`. Test/spec files are excluded from scanning.

### Supported frameworks

Rule counts are derived from the catalog; the authoritative per-rule breakdown is [`docs/rules.md`](docs/rules.md).

**Apple platforms** — checked against Apple's HIG directly:

| Framework | Rules | Detection depth |
|-----------|-------|----------------|
| SwiftUI (`swift`) | 70 | Navigation, controls, color, typography, accessibility, dark mode, technologies |
| UIKit | 35 | Deprecated APIs, Dynamic Type, semantic color, Auto Layout, SF Symbols, haptics |
| AppKit | 25 | Windows, toolbars, NSColor/NSFont semantics, materials/vibrancy, accessibility |
| watchOS | 13 | Digital Crown, complications, Always-On luminance, workouts, haptics |
| visionOS | 10 | Volumetric windows, immersive spaces, ornaments, glass materials, spatial gestures |

**Web and cross-platform** — checked against **universal accessibility and UI-quality principles that align with the HIG** (semantic colors, scalable type, focus visibility, keyboard operability, motion/RTL), not Apple-specific HIG conformance:

| Framework | Rules | Detection depth |
|-----------|-------|----------------|
| React / Next.js (`web`) | 122 | a11y (AST-verified for JSX), color tokens, typography, dark mode, responsive, forms |
| CSS / SCSS | 25 | Custom properties, contrast, focus styles, outline, z-index, logical properties, RTL |
| Vue / Nu