Skip to content
Back to search

apple-hig-skills

MarketplaceWorks with Claude CodeGitHub

Apple HIG reference and cross-framework UI audit tooling for agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/raintree-technology/hig-doctor with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/raintree-technology/hig-doctor'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/raintree-technology--hig-doctor/badge.svg)](/listings/raintree-technology--hig-doctor)

HTML

<a href="/listings/raintree-technology--hig-doctor"><img src="/api/listings/raintree-technology--hig-doctor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 35 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "apple-hig-skills",
  3. "owner": {
  4. "name": "Raintree",
  5. "email": "hq@zacharyr0th.com"
  6. },
  7. "metadata": {
  8. "description": "HIG Doctor — Apple Human Interface Guidelines for AI coding agents, with 14 skills, an MCP server, and a universal HIG compliance auditor. Snapshot Feb 2025.",
  9. "version": "1.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "apple-hig-skills",
  14. "description": "HIG Doctor bundles 14 Apple HIG skills (foundations, platforms, patterns, inputs, technologies, and 8 component categories), an MCP server (hig_list_skills / hig_lookup / hig_search / hig_audit / hig_audit_file / hig_explain_finding), and a Bun-based CLI auditor that detects 431 HIG rules across SwiftUI, UIKit, AppKit, watchOS, visionOS, React, Vue, Svelte, Angular, Compose, Android XML, React Native, Flutter, CSS, and HTML.",
  15. "source": "./",
  16. "strict": false,
  17. "skills": [
  18. "./skills/hig-foundations",
  19. "./skills/hig-platforms",
  20. "./skills/hig-patterns",
  21. "./skills/hig-inputs",
  22. "./skills/hig-technologies",
  23. "./skills/hig-project-context",
  24. "./skills/hig-components-content",
  25. "./skills/hig-components-controls",
  26. "./skills/hig-components-dialogs",
  27. "./skills/hig-components-layout",
  28. "./skills/hig-components-menus",
  29. "./skills/hig-components-search",
  30. "./skills/hig-components-status",
  31. "./skills/hig-components-system"
  32. ]
  33. }
  34. ]
  35. }
README.md · README · 164 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="brand/hig-doctor-mark.svg" alt="HIG Doctor" width="96" height="96" />
  3. </p>
  4. # HIG Doctor
  5. <!-- project-record: hig-doctor -->
  6. **Active open-source project · MIT tooling with attributed Apple reference content**
  7. HIG Doctor helps developers and coding agents find interface issues before release.
  8. It checks Apple-platform source against Apple’s Human Interface Guidelines and checks
  9. web and cross-platform source against aligned accessibility and interface-quality
  10. rules.
  11. ## Run an audit
  12. ```bash
  13. npx hig-doctor .
  14. ```
  15. The CLI detects the project frameworks, reports concerns by severity, and points to a
  16. specific fix and source reference. This result is generated from the committed
  17. `test/fixtures/readme-audit` project and checked in the test suite:
  18. ```text
  19. 2 moderate concerns · swiftui · 1 file
  20. View.swift:5 · swift/navigation-view-deprecated
  21. View.swift:7 · swift/hardcoded-color
  22. ```
  23. The audit catalog currently contains **431 rules** across 14 frameworks. Counts are
  24. generated from the rule catalog and checked in CI; they are coverage inventory, not a
  25. claim of complete HIG conformance.
  26. ## Why use HIG Doctor
  27. - **Catch reviewable source issues.** Findings include severity, location, rule ID,
  28. fix guidance, and the reference that supports the concern.
  29. - **Gate only new debt.** Configuration, inline suppressions, content-based baselines,
  30. SARIF, and `--fail-on` support gradual adoption.
  31. - **Give agents bounded guidance.** MCP tools search the frozen reference corpus and
  32. explain individual findings without presenting generated advice as canonical HIG.
  33. - **Use one engine across workflows.** The CLI, MCP server, and embeddable core package
  34. share the same catalog and analysis tiers.
  35. ## Choose a surface
  36. | Surface | Use it for | Start |
  37. | --- | --- | --- |
  38. | Audit CLI | Source scans and CI gates | `npx hig-doctor .` |
  39. | MCP server | Search, lookup, file audits, and explanations | `npx -y hig-mcp` |
  40. | Agent skills | Design guidance and source audits | [Canonical agent skills](skills/) |
  41. | Core package | Embed the rule engine | `npm install @raintree-technology/hig-doctor-core` |
  42. The MCP server works over stdio or streamable HTTP. Its six tools list skills, look up
  43. topics, search the corpus, audit projects or files, and explain findings. See the
  44. [MCP package README](packages/mcp/README.md) for client configuration.
  45. ## How analysis works
  46. ```text
  47. framework detection → regex scan → structural refinement → categorized findings → report or SARIF
  48. ```
  49. - The zero-dependency regex tier is comment- and string-aware.
  50. - Swift structural analysis follows chained modifiers to remove handled findings.
  51. - The TypeScript compiler refines selected JSX accessibility checks when available.
  52. - Every finding records the engine that produced it.
  53. Precision and recall are measured on an annotated fixture corpus in
  54. [`docs/benchmark.md`](docs/benchmark.md). CI enforces the published floors.
  55. ## Framework coverage
  56. Apple-platform rows are checked against the HIG directly. Web and cross-platform rows
  57. use universal accessibility and interface-quality principles that align with the HIG.
  58. | Framework | Rules | Basis |
  59. | --- | ---: | --- |
  60. | SwiftUI (`swift`) | 70 | Apple HIG |
  61. | UIKit | 35 | Apple HIG |
  62. | AppKit | 25 | Apple HIG |
  63. | watchOS | 13 | Apple HIG |
  64. | visionOS | 10 | Apple HIG |
  65. | React / Next.js (`web`) | 122 | HIG-aligned universal checks |
  66. | CSS / SCSS | 25 | HIG-aligned universal checks |
  67. | Vue / Nuxt | 19 | HIG-aligned universal checks |
  68. | Angular | 17 | HIG-aligned universal checks |
  69. | Svelte / SvelteKit | 14 | HIG-aligned universal checks |
  70. | Flutter | 21 | HIG-aligned universal checks |
  71. | Jetpack Compose | 28 | HIG-aligned universal checks |
  72. | Android XML | 18 | HIG-aligned universal checks |
  73. | React Native | 14 | HIG-aligned universal checks |
  74. The authoritative per-rule inventory is [`docs/rules.md`](docs/rules.md).
  75. ## Skills corpus
  76. The frozen 2025-02-02 snapshot contains 14 skills and 156 reference topics. Apple’s
  77. [live Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
  78. remain canonical.
  79. | Skill | Description |
  80. | --- | --- |
  81. | `hig-foundations` | Color, typography, symbols, accessibility, layout, motion, privacy, and branding |
  82. | `hig-platforms` | iOS, iPadOS, macOS, tvOS, watchOS, and visionOS |
  83. | `hig-patterns` | Onboarding, navigation, search, feedback, modality, and settings |
  84. | `hig-inputs` | Touch, Pencil, keyboard, controller, pointer, Crown, and eye input |
  85. | `hig-technologies` | Siri, Apple Pay, HealthKit, ARKit, ML, Sign in with Apple, and SharePlay |
  86. | `hig-project-context` | Shared project context for tailored guidance |
  87. | `hig-components-content` | Charts, collections, images, web views, and lockups |
  88. | `hig-components-controls` | Pickers, toggles, sliders, buttons, and fields |
  89. | `hig-components-dialogs` | Alerts, action sheets, popovers, and sheets |
  90. | `hig-components-layout` | Sidebars, split views, tabs, lists, tables, and windows |
  91. | `hig-components-menus` | Menus, toolbars, buttons, and menu bars |
  92. | `hig-components-search` | Search fields, page controls, and path controls |
  93. | `hig-components-status` | Progress indicators, status bars, and activity rings |
  94. | `hig-components-system` | Widgets, live activities, notifications, complications, and App Clips |
  95. Nightly drift detection compares the snapshot with Apple’s DocC JSON. Content changes
  96. remain human-reviewed; a hash change does not automatically rewrite guidance.
  97. ## Limits and evidence boundary
  98. Automated findings support review. They do not prove accessibility, HIG conformance,
  99. or design quality. Regex fallback can produce different precision than structural
  100. analysis, and project-specific context can justify a documented suppression.
  101. Apple owns the HIG content. This repository provides organization, cross-referencing,
  102. and detection rules. Each reference retains attribution and a canonical source URL.
  103. ## Documentation
  104. - [CLI package](packages/cli/README.md) — Flags, configuration, baselines, and CI.
  105. - [MCP package](packages/mcp/README.md) — Tools, transports, and client setup.
  106. - [Core package](packages/core/README.md) — Embedding API.
  107. - [Rule catalog](docs/rules.md) — Current generated inventory.
  108. - [Detection benchmark](docs/benchmark.md) — Fixture method, results, and limits.
  109. - [Brand system](docs/brand-system.md) and [Remotion showcase](docs/remotion-showcase.md).
  110. - [Project website](https://apple.raintree.technology) — Human and agent-readable topics.
  111. ## Raintree open-source system
  112. HIG Doctor owns interface guidance and source audits. It can be used independently.
  113. [DocPull](https://github.com/raintree-technology/docpull) acquires evidence,
  114. [PolicyStrata](https://github.com/raintree-technology/policystrata) tests policy behavior,
  115. [Trellis](https://github.com/raintree-technology/trellis) enforces shared code policy,
  116. and [Raintree Standards](https://github.com/raintree-technology/raintree.standards)
  117. defines governed requirements. See the
  118. [Raintree open-source portfolio](https://raintree.technology/portfolio#open-source).
  119. Raintree also builds [BetterOff](https://betteroff.finance/github), which keeps a household's
  120. spending, investments, assets, debts, and net worth in one current record.
  121. ## Project policies
  122. [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) ·
  123. [Changelog](CHANGELOG.md) ·
  124. [Source repository](https://github.com/raintree-technology/hig-doctor) · [MIT License](LICENSE) ·
  125. [Third-party notices](THIRD_PARTY_NOTICES.md)
  126. Apple HIG reference text in `skills/*/references/` is © Apple Inc. and remains subject
  127. to Apple’s terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.