{"id":47813384,"url":"https://github.com/raintree-technology/hig-doctor","last_synced_at":"2026-04-03T18:19:21.778Z","repository":{"id":337723155,"uuid":"1154000512","full_name":"raintree-technology/hig-doctor","owner":"raintree-technology","description":"Apple HIG audit CLI + 14 agent skills for AI coding assistants — score any project for HIG compliance across 12 frameworks","archived":false,"fork":false,"pushed_at":"2026-02-24T20:51:20.000Z","size":4051,"stargazers_count":10,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T00:40:36.580Z","etag":null,"topics":["accessibility","agent-skills","ai-agents","apple","apple-design","audit","claude-code","cursor","hig","human-interface-guidelines","ios","macos","skills","swiftui","tvos","uikit","visionos","watchos"],"latest_commit_sha":null,"homepage":"https://apple.raintree.technology/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raintree-technology.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-09T22:53:24.000Z","updated_at":"2026-02-24T21:09:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raintree-technology/hig-doctor","commit_stats":null,"previous_names":["raintree-technology/apple-hig-skills"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/raintree-technology/hig-doctor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raintree-technology%2Fhig-doctor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raintree-technology%2Fhig-doctor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raintree-technology%2Fhig-doctor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raintree-technology%2Fhig-doctor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raintree-technology","download_url":"https://codeload.github.com/raintree-technology/hig-doctor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raintree-technology%2Fhig-doctor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31368163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","agent-skills","ai-agents","apple","apple-design","audit","claude-code","cursor","hig","human-interface-guidelines","ios","macos","skills","swiftui","tvos","uikit","visionos","watchos"],"created_at":"2026-04-03T18:19:18.987Z","updated_at":"2026-04-03T18:19:21.757Z","avatar_url":"https://github.com/raintree-technology.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apple HIG Skills\n\nApple Human Interface Guidelines as agent skills for Claude Code, Cursor, and other AI coding agents.\n\n14 skills covering the complete Apple HIG — foundations, components, patterns, inputs, platforms, and technologies. Source: [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) (February 2025).\n\n## Install\n\n```bash\nnpx skills add raintree-technology/apple-hig-skills\n```\n\nOr install via Claude Code plugin:\n\n```\n/plugin marketplace add raintree-technology/apple-hig-skills\n```\n\n## HIG Audit\n\nAudit 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.\n\nRequires [Bun](https://bun.sh).\n\n```bash\ncd packages/hig-doctor/src-termcast\nbun install\nbun run audit \u003cdirectory\u003e\n```\n\nExample output:\n\n```\n  HIG Audit: website   100/100\n  nextjs · 751 detections · 56 files\n\n  ────────────────────────────────────────────────────────────────────\n  Foundations                610  ███████████████████░  593 good\n  Interaction Patterns        34  ███████████████████░  32 good\n  Layout \u0026 Navigation         42  █████░░░░░░░░░░░░░░░  11 good\n  Controls                    25  ░░░░░░░░░░░░░░░░░░░░\n  Input Methods               17  ████████████████░░░░  14 good\n  ────────────────────────────────────────────────────────────────────\n  Totals                     751  650 good  101 patterns\n\n  Excellent — Strong HIG compliance across the board.\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `--export` | Write a full audit report to `\u003cdirectory\u003e/hig-audit.md` |\n| `--stdout` | Print raw audit markdown to stdout (pipe to an AI for evaluation) |\n| `--json` | Print structured results as JSON (for CI/scripts) |\n| `--help` | Show help |\n\n### What it detects\n\nThe audit scans code, stylesheets, and config files, then categorizes findings across HIG areas:\n\n- **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\n- **Layout \u0026 Navigation** — navigation patterns, responsive breakpoints, semantic HTML, adaptive layout, sidebar/tab patterns\n- **Controls** — buttons, toggles, form elements, interactive controls, labels\n- **Content Display** — images, collections, tables, cards, accordions, lists\n- **Input Methods** — keyboard support, gesture handling, form validation, input types, fieldset/legend, autocomplete\n- **Interaction Patterns** — drag and drop, pull-to-refresh, undo, animations, haptics, error handling\n- **Dialogs \u0026 Presentations** — modals, sheets, alerts, popovers, toasts, tooltips\n- **Menus \u0026 Actions** — dropdown menus, context menus, toolbars, menu roles\n- **Search \u0026 Navigation** — search fields, search roles, page controls\n- **Status \u0026 Progress** — progress indicators, loading states, aria-busy\n- **Apple Technologies** — WidgetKit, ActivityKit, HealthKit, ARKit, Apple Pay, Sign in with Apple\n\n**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`.\n\n**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.\n\nEach detection is classified as a **positive** (good HIG practice), **concern** (potential violation), or **pattern** (neutral usage detected).\n\n### Supported frameworks\n\n| Framework | Rules | Detection depth |\n|-----------|-------|----------------|\n| SwiftUI | 55+ | Navigation, controls, color, typography, accessibility, dark mode, technologies |\n| UIKit | 10+ | Accessibility, layout, color |\n| React / Next.js | 100+ | Full a11y, color tokens, typography, dark mode, responsive, forms, structure |\n| Vue / Nuxt | 25+ | Accessibility, navigation, forms, i18n, transitions |\n| Svelte / SvelteKit | 20+ | Accessibility, forms, dark mode, motion |\n| Angular | 25+ | Accessibility (CDK a11y), Material components, forms, i18n |\n| Jetpack Compose | 30+ | Semantics, color, typography, dark mode, navigation, controls |\n| Android XML | 20+ | contentDescription, color resources, sp/dp units, touch targets |\n| React Native | 15+ | accessibilityLabel/Role, color scheme, navigation, gestures |\n| Flutter | 20+ | Semantics, Theme colors/typography, dark mode, i18n |\n| CSS / SCSS | 40+ | Custom properties, contrast, focus styles, outline, !important, z-index, logical properties, RTL |\n| HTML | 15+ | Landmarks, lang attribute, heading structure, viewport meta |\n\n### How scoring works\n\nThe score (0-100) is based on the ratio of positive patterns to concerns, with a small bonus for category breadth:\n\n- **90-100**: Excellent HIG compliance\n- **70-89**: Good, with room for improvement\n- **50-69**: Needs work\n- **Below 50**: Significant violations\n\nProjects 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.\n\n### JSON output\n\n`--json` outputs structured results for CI pipelines and scripts:\n\n```json\n{\n  \"score\": 100,\n  \"lowDensity\": false,\n  \"frameworks\": [\"nextjs\"],\n  \"files\": { \"code\": 55, \"style\": 1, \"config\": 10 },\n  \"totals\": { \"concerns\": 0, \"positives\": 650, \"patterns\": 101 },\n  \"categories\": [\n    {\n      \"name\": \"Foundations\",\n      \"skill\": \"hig-foundations\",\n      \"detections\": 610,\n      \"concerns\": 0,\n      \"positives\": 593,\n      \"patterns\": 17,\n      \"files\": [\"website/app/layout.tsx\", \"...\"]\n    }\n  ]\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `score` | 0-100 HIG compliance score |\n| `lowDensity` | `true` if the project has few UI patterns (score may be unreliable) |\n| `frameworks` | Detected frameworks (nextjs, swiftui, vue, angular, flutter, etc.) |\n| `files` | Count of scanned code, style, and config files |\n| `totals` | Aggregate counts of concerns, positives, and neutral patterns |\n| `categories` | Per-HIG-category breakdown with detection counts and affected files |\n\n### Programmatic API\n\nImport the audit function directly in Bun/Node:\n\n```typescript\nimport { audit } from \"./packages/hig-doctor/src-termcast/src/audit\";\n\nconst result = await audit(\"./my-app\");\nconsole.log(result.categories);  // CategorySummary[]\nconsole.log(result.allMatches);  // PatternMatch[]\nconsole.log(result.scanResult);  // ScanResult with frameworks, file lists\nconsole.log(result.markdown);    // Full audit report as markdown\n```\n\n### Full report for AI evaluation\n\nGenerate a detailed markdown report and pipe it to an AI for deeper analysis:\n\n```bash\nbun run audit ./my-app --stdout | pbcopy\n```\n\nThe report includes code excerpts with line numbers, HIG reference material from the 14 skills, and per-category evaluation checklists.\n\n## HIG Doctor (Skill Validator)\n\nValidates skill file structure and repository consistency. Separate from the audit tool above.\n\n```bash\nnpm --prefix packages/hig-doctor install\nnode packages/hig-doctor/src/cli.js . --verbose\n```\n\nAfter publishing to npm:\n\n```bash\nnpx -y hig-doctor@latest . --verbose\n```\n\nOpen the interactive TUI:\n\n```bash\nnode packages/hig-doctor/src/cli.js . --tui\n```\n\nTUI controls: `j/k` or arrows to move, `f` to filter, `g` to toggle grouping, `q` to quit.\n\nUse as a GitHub Action:\n\n```yaml\n- uses: actions/checkout@v4\n- uses: raintree-technology/apple-hig-skills@main\n  with:\n    directory: .\n    verbose: \"true\"\n    strict: \"true\"\n```\n\n## Remotion Demo\n\nA [Remotion](https://www.remotion.dev/) video demo that visualizes hig-doctor audit output with animated charts and glass-card UI.\n\n```bash\ncd demos/remotion-hig-doctor\nnpm install\nnpm run preview\n```\n\nRender to video:\n\n```bash\nnpm run render\n```\n\nOutput: `out/hig-doctor-showcase.mp4` (1920x1080, 30fps, 21s)\n\n## Skills\n\n| Skill | Description |\n|-------|-------------|\n| `hig-foundations` | Color, typography, SF Symbols, dark mode, accessibility, layout, motion, privacy, branding, icons |\n| `hig-platforms` | Platform-specific design for iOS, iPadOS, macOS, tvOS, watchOS, visionOS |\n| `hig-patterns` | UX patterns: onboarding, navigation, search, feedback, drag and drop, modality, settings |\n| `hig-inputs` | Gestures, Apple Pencil, keyboards, game controllers, pointers, Digital Crown, eye tracking |\n| `hig-technologies` | Siri, Apple Pay, HealthKit, ARKit, machine learning, Sign in with Apple, SharePlay |\n| `hig-project-context` | Shared design context document for tailored guidance across skills |\n| `hig-components-content` | Charts, collections, image views, web views, color wells, lockups |\n| `hig-components-controls` | Pickers, toggles, sliders, steppers, segmented controls, text fields |\n| `hig-components-dialogs` | Alerts, action sheets, popovers, sheets, digit entry views |\n| `hig-components-layout` | Sidebars, split views, tab bars, scroll views, windows, lists, tables |\n| `hig-components-menus` | Menus, context menus, toolbars, buttons, menu bar, pop-up buttons |\n| `hig-components-search` | Search fields, page controls, path controls |\n| `hig-components-status` | Progress indicators, status bars, activity rings |\n| `hig-components-system` | Widgets, live activities, notifications, complications, app clips, app shortcuts |\n\n## How it works\n\nSkills use progressive disclosure to minimize token usage:\n\n1. **Discovery** — Claude reads skill names and descriptions to decide relevance\n2. **Activation** — The full SKILL.md loads with key principles and a reference index\n3. **Deep reference** — Specific files from `references/` load on demand for detailed guidance\n\nEach skill stays under 500 lines. Detailed HIG content lives in 156 reference documents loaded only when needed.\n\n## Structure\n\n```\nskills/\n  hig-foundations/\n    SKILL.md\n    references/\n      color.md\n      typography.md\n      accessibility.md\n      ...\n  hig-components-layout/\n    SKILL.md\n    references/\n      sidebars.md\n      tab-bars.md\n      ...\n  ...\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding or improving skills.\n\n## License\n\nMIT (repository structure and skill files). Apple HIG content in `references/` is Apple's intellectual property, referenced here for AI agent guidance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraintree-technology%2Fhig-doctor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraintree-technology%2Fhig-doctor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraintree-technology%2Fhig-doctor/lists"}