Apple HIG Skills

Apple Human Interface Guidelines as agent skills for Claude Code, Cursor, and other AI coding agents.

14 skills covering the complete Apple HIG — foundations, components, patterns, inputs, platforms, and technologies. Source: Apple Human Interface Guidelines (February 2025).

Install

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

Or install via Claude Code plugin:

/plugin marketplace add raintree-technology/apple-hig-skills

HIG Audit

Audit any project for Apple HIG compliance. Works with SwiftUI, UIKit, React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, React Native, Flutter, Jetpack Compose, Android XML, and plain HTML/CSS. Detects 349 patterns across accessibility, color systems, typography, responsive layout, dark mode, motion, i18n, and more.

Requires Bun.

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

Example output:

  HIG Audit: website   100/100
  nextjs · 751 detections · 56 files

  ────────────────────────────────────────────────────────────────────
  Foundations                610  ███████████████████░  593 good
  Interaction Patterns        34  ███████████████████░  32 good
  Layout & Navigation         42  █████░░░░░░░░░░░░░░░  11 good
  Controls                    25  ░░░░░░░░░░░░░░░░░░░░
  Input Methods               17  ████████████████░░░░  14 good
  ────────────────────────────────────────────────────────────────────
  Totals                     751  650 good  101 patterns

  Excellent — Strong HIG compliance across the board.

Options

What it detects

The audit scans code, stylesheets, and config files, then categorizes findings across HIG areas:

• Foundations — semantic vs hardcoded colors, Dynamic Type vs fixed font sizes, dark mode, motion preferences, accessibility labels, focus management, heading hierarchy, landmark regions, touch targets, i18n/RTL support
• Layout & Navigation — navigation patterns, responsive breakpoints, semantic HTML, adaptive layout, sidebar/tab patterns
• Controls — buttons, toggles, form elements, interactive controls, labels
• Content Display — images, collections, tables, cards, accordions, lists
• Input Methods — keyboard support, gesture handling, form validation, input types, fieldset/legend, autocomplete
• Interaction Patterns — drag and drop, pull-to-refresh, undo, animations, haptics, error handling
• Dialogs & Presentations — modals, sheets, alerts, popovers, toasts, tooltips
• Menus & Actions — dropdown menus, context menus, toolbars, menu roles
• Search & Navigation — search fields, search roles, page controls
• Status & Progress — progress indicators, loading states, aria-busy
• Apple Technologies — WidgetKit, ActivityKit, HealthKit, ARKit, Apple Pay, Sign in with Apple

Accessibility anti-patterns detected: div/span with click handlers but no ARIA role, missing alt text, ambiguous link text ("click here"), empty headings/buttons, outline: none, positive tabindex, mouse-only handlers, autoplay media, user-scalable=no.

Context-aware rules: !important inside @media print and prefers-reduced-motion blocks is not flagged. outline: none inside :focus:not(:focus-visible) progressive enhancement is not flagged. Hover rules skip pseudo-element selectors like ::-webkit-scrollbar-thumb. Test/spec files are excluded from scanning.

Each detection is classified as a positive (good HIG practice), concern (potential violation), or pattern (neutral usage detected).

Supported frameworks

How scoring works

The score (0-100) is based on the ratio of positive patterns to concerns, with a small bonus for category breadth:

• 90-100: Excellent HIG compliance
• 70-89: Good, with room for improvement
• 50-69: Needs work
• Below 50: Significant violations

Projects with low UI density (fewer than 4 detections per file and under 500 total) display a warning instead of a score interpretation, since scores are less meaningful for non-UI-focused projects like backend services or blockchain repos.

JSON output

--json outputs structured results for CI pipelines and scripts:

{
  "score": 100,
  "lowDensity": false,
  "frameworks": ["nextjs"],
  "files": { "code": 55, "style": 1, "config": 10 },
  "totals": { "concerns": 0, "positives": 650, "patterns": 101 },
  "categories": [
    {
      "name": "Foundations",
      "skill": "hig-foundations",
      "detections": 610,
      "concerns": 0,
      "positives": 593,
      "patterns": 17,
      "files": ["website/app/layout.tsx", "..."]
    }
  ]
}

Programmatic API

Import the audit function directly in Bun/Node:

import { audit } from "./packages/hig-doctor/src-termcast/src/audit";

const result = await audit("./my-app");
console.log(result.categories);  // CategorySummary[]
console.log(result.allMatches);  // PatternMatch[]
console.log(result.scanResult);  // ScanResult with frameworks, file lists
console.log(result.markdown);    // Full audit report as markdown

Full report for AI evaluation

Generate a detailed markdown report and pipe it to an AI for deeper analysis:

bun run audit ./my-app --stdout | pbcopy

The report includes code excerpts with line numbers, HIG reference material from the 14 skills, and per-category evaluation checklists.

HIG Doctor (Skill Validator)

Validates skill file structure and repository consistency. Separate from the audit tool above.

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

After publishing to npm:

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

Open the interactive TUI:

node packages/hig-doctor/src/cli.js . --tui

TUI controls: j/k or arrows to move, f to filter, g to toggle grouping, q to quit.

Use as a GitHub Action:

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

Remotion Demo

A Remotion video demo that visualizes hig-doctor audit output with animated charts and glass-card UI.

cd demos/remotion-hig-doctor
npm install
npm run preview

Render to video:

npm run render

Output: out/hig-doctor-showcase.mp4 (1920x1080, 30fps, 21s)

Skills

How it works

Skills use progressive disclosure to minimize token usage:

1. Discovery — Claude reads skill names and descriptions to decide relevance
2. Activation — The full SKILL.md loads with key principles and a reference index
3. Deep reference — Specific files from references/ load on demand for detailed guidance

Each skill stays under 500 lines. Detailed HIG content lives in 156 reference documents loaded only when needed.

Structure

skills/
  hig-foundations/
    SKILL.md
    references/
      color.md
      typography.md
      accessibility.md
      ...
  hig-components-layout/
    SKILL.md
    references/
      sidebars.md
      tab-bars.md
      ...
  ...

Contributing

See CONTRIBUTING.md for guidelines on adding or improving skills.

License

MIT (repository structure and skill files). Apple HIG content in references/ is Apple's intellectual property, referenced here for AI agent guidance.