Apple HIG Doctor

HIG Doctor turns agent-delivered Apple design guidance into an auditable workflow.

The first version focused on guidance. HIG Doctor adds verification.

Instead of only asking an agent for HIG advice, you can audit a codebase, score it, export reports, and enforce checks in CI.

The first version gave agents Apple HIG context on demand:

• 14 skills
• Progressive disclosure loading
• Apple HIG references on demand

HIG Doctor keeps that architecture and adds runtime tooling:

• A universal audit CLI that scans projects for HIG patterns
• A skill validator that checks skill package quality and consistency
• CI integration through GitHub Actions

The shift is simple: from guidance to verification.

The current repository includes:

• 14 skills across foundations, platforms, components, patterns, inputs, technologies, and project context
• 156 reference documents loaded only when needed
• 349 detection patterns in the audit engine
• 12 framework families supported for scanning — enough coverage to audit most production Apple apps without custom configuration

Agents load only the skills they need, so context stays focused and fast. The same category structure now also powers audits and reports.

HIG Doctor combines two complementary tools.

1. Apple HIG skills layer

npx skills add raintree-technology/apple-hig-skills

This gives the agent scoped HIG reasoning for:

• Foundations (color, typography, accessibility, dark mode)
• Platform guidance (iOS, iPadOS, macOS, tvOS, watchOS, visionOS)
• Components (layout, controls, dialogs, menus, content, search, status, system surfaces)
• Patterns, inputs, and Apple technologies

If your team uses Claude Code, you can also install it from the plugin marketplace path documented in the repository.

2. Apple HIG audit CLI + doctor tooling

cd packages/hig-doctor/src-termcast
bun install
bun run audit <directory>

Key output modes:

• --export writes hig-audit.md
• --stdout streams markdown for piping into an AI reviewer
• --json returns structured output for CI automation

Then validate the skill repository itself:

npm --prefix packages/hig-doctor install
node packages/hig-doctor/src/cli.js . --verbose

The same project can both audit apps and validate the skill system behind the guidance.

After publishing, you can run the packaged validator directly:

npx -y hig-doctor@latest . --verbose

Most AI design guidance fails at handoff. The agent says use 44pt touch targets. The shipped build uses 36pt. Nobody catches it.

• The model gives good advice.
• Code ships.
• Nobody verifies that implementation still matches HIG.

HIG Doctor closes that loop:

1. Agent gives contextual HIG guidance.
2. Developer implements in SwiftUI, React, Flutter, or another supported stack.
3. Audit runs and scores actual code.
4. CI enforces quality thresholds before merge.

That is the practical jump from assistant to workflow.

You can run the project as a GitHub Action:

- uses: actions/checkout@v4
- uses: raintree-technology/apple-hig-skills@main
  with:
    directory: .
    verbose: "true"
    strict: "true"

For teams, that means HIG compliance can become a repeatable check instead of an informal review comment.

• GitHub
• Documentation