| name | hig-doctor-audit |
| description | HIG Doctor audit workflow for scanning app projects against Apple Human Interface Guidelines. Use when the user asks for a HIG audit, Apple UI compliance scan, accessibility/design lint, HIG Doctor, severity report, CI gate, or wants to verify SwiftUI, UIKit, React, Next.js, Vue, Svelte, Angular, React Native, Flutter, Compose, Android XML, CSS, or HTML against Apple HIG rules. |
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 /path/to/hig-doctor/packages/hig-doctor/src-termcast
bun run audit ./path/to/project
Workflow
- Confirm the project path and target platform/framework.
- Run
npx hig-doctor <path> --export for a human-readable hig-audit.md, or --json for CI/scripts.
- If output is large, focus first on
critical, then serious, then high-confidence moderate.
- Map each category's
skill field to the matching local HIG skill, such as hig-foundations or hig-components-controls.
- Read only the specific HIG reference topics needed for the flagged issue.
- Fix concrete code issues and rerun the audit with the same flags.
- 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.
