HIG Doctor

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

• 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.
• MCP server — stdio Model Context Protocol server exposing hig_list_skills, hig_lookup, and hig_audit for Claude Desktop, Cursor, Windsurf, and Claude Code.
• Audit CLI — universal HIG compliance scanner across 12 frameworks (SwiftUI, UIKit, React, Vue, Svelte, Angular, Compose, Android XML, React Native, Flutter, CSS, HTML). Emits severity-bucketed markdown/JSON with a pass/fail CI gate.

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/.

Star History

Install as a Claude Code plugin

/plugin marketplace add raintree-technology/hig-doctor

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

MCP server

Expose the skills and audit tool to any MCP-compatible client.

# From a git clone of this repo
bun packages/hig-doctor/src-mcp/src/index.ts

Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hig-doctor": {
      "command": "bun",
      "args": ["/absolute/path/to/hig-doctor/packages/hig-doctor/src-mcp/src/index.ts"]
    }
  }
}

Tools:

Set HIG_SKILLS_DIR if you relocate the skills/ folder.

HIG Audit CLI

Scan any project for Apple HIG compliance. Works with SwiftUI, UIKit, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, React Native, Flutter, Jetpack Compose, Android XML, and plain HTML/CSS. Detects 348 patterns across accessibility, color systems, typography, responsive layout, dark mode, motion, i18n, and more.

Requires Bun.

cd packages/hig-doctor/src-termcast
bun run 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

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

JSON output

{
  "lowDensity": false,
  "frameworks": ["nextjs"],
  "files": { "code": 48, "style": 3, "config": 10 },
  "severities": { "critical": 0, "serious": 2, "moderate": 4 },
  "totals": { "concerns": 6, "positives": 306, "patterns": 100 },
  "failOn": "critical",
  "gateTripped": false,
  "categories": [
    {
      "name": "Foundations",
      "skill": "hig-foundations",
      "detections": 312,
      "concerns": 2,
      "positives": 286,
      "patterns": 24,
      "severities": { "critical": 0, "serious": 2, "moderate": 0 },
      "files": ["app/layout.tsx", "..."]
    }
  ]
}

GitHub Action

Audit on every pull request and fail the build on critical violations.

- uses: actions/checkout@v4
- uses: raintree-technology/hig-doctor@main
  with:
    directory: .
    fail-on: critical

Outputs: critical, serious, moderate, report (path to generated hig-audit.md).

Agent-readable surface

The project website serves:

• /llms.txt — structured index per the llms.txt convention, linking every HIG topic with excerpts.
• /raw/<slug> — plain-text markdown for each reference topic (scriptable retrieval).
• /topics/<slug> — HTML pages for humans.

Remotion demo

An animated Remotion video that visualizes audit output with glass-card UI.

cd demos/remotion-hig-doctor
npm install
npm run preview   # preview in browser
npm run render    # out/hig-doctor-showcase.mp4 (1920x1080, 30fps, 21s)

Skills

Skills use progressive disclosure — agents load only the reference files they need.

Repository structure

hig-doctor/
├── .claude-plugin/marketplace.json       # Claude Code plugin manifest
├── brand/                                # Canonical logo, app icon, and usage guidance
├── skills/                                # 14 Agent Skills (SKILL.md + references/)
├── packages/hig-doctor/
│   ├── src/                               # Internal skill-structure validator (dev-only)
│   ├── src-termcast/                      # Audit CLI (Bun, zero deps)
│   └── src-mcp/                           # MCP server
├── website/                               # Next.js site + llms.txt + /raw endpoints
├── demos/remotion-hig-doctor/             # Animated audit demo
├── scripts/
│   ├── legal-hardening.ts                 # Idempotent: strip Apple CDN images, insert attribution
│   └── legal-hardening-deep.ts            # Destructive prose transform: keep headings + principles
└── .github/                              # CI workflows + GitHub social preview

Content maintenance

Skills content is a frozen snapshot dated 2025-02-02. The annual-hig-rescan.yml workflow opens a tracking issue each June after WWDC to prompt diffing Apple's live HIG against this snapshot, updating changed topics, and tagging a new release. The re-scan is a human-in-the-loop process — Apple's HIG pages are JS-rendered and not safely automatable.

Each reference file carries an attribution block and canonical source URL in its frontmatter. Apple-hosted screenshots have been stripped to reduce IP transfer; retain the source link and open Apple's page when visual context is needed.

Contributing

See CONTRIBUTING.md for how to add skills, update reference content after a re-scan, or propose new audit rules.

License

MIT for repository structure, detection rules, tooling (audit CLI, MCP server, validator, scripts), and the Next.js website. Apple HIG text in skills/*/references/ is © Apple Inc.; this repository provides organization and cross-referencing for AI agent guidance only — the canonical source is developer.apple.com.