hig-doctor — Claude Code skill: audit UI code against Apple HIG
Points the HIG Doctor CLI at your interface code, whatever the framework, and turns the report into a severity-ranked list of Apple HIG and accessibility problems you can actually fix.
MIT 203 installs ★ 35 updated 2026-10-21
npx skills add podo/design-agent-skills --skill hig-doctor -a claude-codeWhat hig-doctor does
This skill runs a scan-and-fix loop around the HIG Doctor CLI. Give it a repo or a folder and it executes the pinned npx -y hig-doctor@<version> <target> --json, then works through the output: detected frameworks, counts per severity, rule IDs, locations, and the limits of the analysis.
Findings are sorted into mechanical patches and items that call for a product, design or accessibility judgement. Approve the remediation and it edits the code, then re-runs the audit. Suppressions you justified earlier and existing baselines are left alone. A scan is reported as evidence and never as proof of HIG compliance.
Node.js with npx plus npm registry access are required, otherwise the command fails outright. There is nothing to audit without source files. For the reasoning behind a rule, load the apple-hig-skills reference set; SwiftUI implementation and WCAG conformance reviews live in swiftui-patterns and wcag-audit-patterns.
What it helps with
- audit a Swift or React codebase against Apple HIG rules
- rank findings by severity to pick the first fixes
- separate mechanical patches from calls that need design review
- re-run the scan after patching to see what is left
- keep justified suppressions and baselines intact
Example prompts for the agent
- Run an Apple HIG audit on
src/componentsand group the findings by severity - Scan this repo for HIG issues and tell me which fixes are mechanical
- Fix the accessibility findings from the report, then re-run the audit
How to install hig-doctor
1Skills CLI (Vercel)
npx skills add podo/design-agent-skills --skill hig-doctor -a claude-code2Manually: put the files in place
~/.claude/skills/hig-doctor/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hig-doctor/
1Skills CLI (Vercel)
npx skills add podo/design-agent-skills --skill hig-doctor -a codex2Manually: put the files in place
.agents/skills/hig-doctor/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add podo/design-agent-skills --skill hig-doctor -a cursor2Manually: put the files in place
.cursor/skills/hig-doctor/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install podo/design-agent-skills skills/hig-doctor2Manually: put the files in place
.github/skills/hig-doctor/SKILL.md1Skills CLI (Vercel)
npx skills add podo/design-agent-skills --skill hig-doctor -a gemini-cli2Platform CLI
gemini skills install https://github.com/podo/design-agent-skills --path skills/hig-doctorManually: put the files in place
.devin/skills/hig-doctor/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add podo/design-agent-skills --skill hig-doctor -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about hig-doctor
How do I install hig-doctor in Claude Code?
Run npx skills add podo/design-agent-skills --skill hig-doctor -a claude-code. The skill lands at ~/.claude/skills/hig-doctor/SKILL.md.
What does hig-doctor do?
It scans interface source with the HIG Doctor CLI and reports frameworks, severity, rule IDs and file locations. Then it helps you remediate and checks the result again.
Does a clean scan mean my app is HIG-compliant?
No. The skill treats the report as evidence, not certification, and separates what a machine can fix from what needs a design or accessibility decision.
Source text
SKILL.md · MIT
--- name: hig-doctor description: | Audits interface source code (Swift, UIKit, AppKit, React, Vue, Svelte, Angular, Compose, Android XML, Flutter, CSS, HTML) for Apple HIG-aligned interface and accessibility problems by running the HIG Doctor CLI, then reports findings by severity and helps remediate them. Review evidence, not certification. triggers: - "HIG doctor" - "HIG compliance" - "Apple HIG audit" - "HIG diagnosis" - "fix Apple HIG" das: type: skill category: visual-components upstream: "https://github.com/raintree-technology/hig-doctor" upstream_path: "plugin/skills/hig-doctor-audit/SKILL.md" version: latest install: true --- # hig-doctor > Catalogue stub — full skill: [raintree-technology/hig-doctor](https://github.com/raintree-technology/hig-doctor/tree/main/plugin/skills/hig-doctor-audit) <!-- das:install:start — generated from stub.yaml by `npm run generate`; edit stub.yaml, not this block --> ## Decision tree 1. **Is the full skill already installed?** Upstream names this skill `hig-doctor-audit`, so it installs next to this pointer (the pointer is not replaced). - Global: `f=~/.agents/skills/hig-doctor-audit/SKILL.md; [ -f "$f" ] && ! grep -q "^das:" "$f" && echo "installed" || echo "pointer"` - Project: `f=.agents/skills/hig-doctor-audit/SKILL.md; [ -f "$f" ] && ! grep -q "^das:" "$f" && echo "installed" || echo "pointer"` - `installed` → the skill is installed as `hig-doctor-audit`, invoke it and proceed - `pointer` → go to step 2 2. **Detect scope, then install:** ```bash [ -e ~/.agents/skills/hig-doctor ] && echo "global" || echo "project" ``` **Global:** ```bash npx skills add raintree-technology/hig-doctor/plugin/skills/hig-doctor-audit -g -y ``` **Project:** ```bash npx skills add raintree-technology/hig-doctor/plugin/skills/hig-doctor-audit -y ``` > **Claude Code:** send a command as a chat message starting with `!` to run it without leaving the conversation. **Heads-up** - **Requires:** Node.js with npx and npm registry access at audit time (the skill runs a version-pinned `npx -y hig-doctor@<version> <target> --json`); optional companion for the guidance behind each finding: the apple-hig-skills pointer (the hig-* reference skills) - **License:** MIT (tooling; Apple reference content is attributed, see upstream THIRD_PARTY_NOTICES.md) <!-- das:install:end --> ## Invoke after install - Skill name: `hig-doctor-audit` - Trigger phrases: "HIG compliance", "Apple HIG audit", "scan this code for HIG issues", "fix Apple HIG" ## What it does A scan-and-remediate workflow around the HIG Doctor CLI. Given a repository or directory, it runs the version-pinned `npx -y hig-doctor@<version> <target> --json`, reports the detected frameworks, severity counts, rule IDs, locations and analysis limits, separates mechanical fixes from changes that need product, design or accessibility judgment, and, if you authorise remediation, fixes and re-runs the audit. It preserves justified suppressions and baselines and never claims that a scan proves HIG compliance. It does nothing useful without source code to audit. Needs Node.js with `npx` and npm registry access. The guidance behind each finding comes from the HIG reference skills, which are a separate pointer: `apple-hig-skills`. ## When NOT to use - General Apple design advice with no source to audit — use `apple-hig-skills` (the `hig-*` reference skills) - SwiftUI implementation help — use `swiftui-patterns` or `swiftui-claude-skills` - Web accessibility conformance audits — use `wcag-audit-patterns`
© podo · MIT · podo/design-agent-skills