HIG Doctor Audit

Use this skill as the verification loop for Apple HIG work. It complements the hig-* reference skills: run the audit to find concrete concerns, then use the matching HIG skill and reference topic to fix them.

Tooling

HIG Doctor is documented at https://apple.raintree.technology and published as hig-doctor.

npx hig-doctor ./path/to/project
npx hig-doctor ./path/to/project --export
npx hig-doctor ./path/to/project --stdout
npx hig-doctor ./path/to/project --json
npx hig-doctor ./path/to/project --fail-on critical

Requires Node 20+ for the published package. From the local source repo, the Bun entrypoint is:

cd /Users/mb1/Code/secondary/hig-doctor/packages/hig-doctor/src-termcast
bun run audit ./path/to/project

Workflow

1. Confirm the project path and target platform/framework.
2. Run npx hig-doctor <path> --export for a human-readable hig-audit.md, or --json for CI/scripts.
3. If output is large, focus first on critical, then serious, then high-confidence moderate.
4. Map each category's skill field to the matching local HIG skill, such as hig-foundations or hig-components-controls.
5. Read only the specific HIG reference topics needed for the flagged issue.
6. Fix concrete code issues and rerun the audit with the same flags.
7. For CI, use --fail-on critical first. Raise to serious only after existing serious issues are cleaned up.

Ignore File

Use .higauditignore for intentional fixtures, generated output, stories, or demos:

**/*.stories.tsx
examples
components/audit-demo-fixtures.ts

Keep ignores narrow. Do not hide application UI code to make the audit pass.

Interpretation

• critical: accessibility-breaking or interaction-blocking. Treat as release blockers unless clearly a false positive.
• serious: significant HIG or UX degradation. Fix before shipping visible UI.
• moderate: style or best-practice drift. Batch when the issue is repeated across a design system.
• positive: useful evidence, not work to do.

HIG Doctor is regex-based. Verify each finding against the code and the relevant HIG reference before editing.