{ "markdown": "

\n \"HIG\n

\n\n# HIG Doctor\n\n\n\n**Active open-source project · MIT tooling with attributed Apple reference content**\n\nHIG Doctor helps developers and coding agents find interface issues before release.\nIt checks Apple-platform source against Apple’s Human Interface Guidelines and checks\nweb and cross-platform source against aligned accessibility and interface-quality\nrules.\n\n## Run an audit\n\n```bash\nnpx hig-doctor .\n```\n\nThe CLI detects the project frameworks, reports concerns by severity, and points to a\nspecific fix and source reference. This result is generated from the committed\n`test/fixtures/readme-audit` project and checked in the test suite:\n\n```text\n2 moderate concerns · swiftui · 1 file\nView.swift:5 · swift/navigation-view-deprecated\nView.swift:7 · swift/hardcoded-color\n```\n\nThe audit catalog currently contains **431 rules** across 14 frameworks. Counts are\ngenerated from the rule catalog and checked in CI; they are coverage inventory, not a\nclaim of complete HIG conformance.\n\n## Why use HIG Doctor\n\n- **Catch reviewable source issues.** Findings include severity, location, rule ID,\n fix guidance, and the reference that supports the concern.\n- **Gate only new debt.** Configuration, inline suppressions, content-based baselines,\n SARIF, and `--fail-on` support gradual adoption.\n- **Give agents bounded guidance.** MCP tools search the frozen reference corpus and\n explain individual findings without presenting generated advice as canonical HIG.\n- **Use one engine across workflows.** The CLI, MCP server, and embeddable core package\n share the same catalog and analysis tiers.\n\n## Choose a surface\n\n| Surface | Use it for | Start |\n| --- | --- | --- |\n| Audit CLI | Source scans and CI gates | `npx hig-doctor .` |\n| MCP server | Search, lookup, file audits, and explanations | `npx -y hig-mcp` |\n| Agent skills | Design guidance and source audits | `codex plugin add hig-doctor@raintree` |\n| Core package | Embed the rule engine | `npm install @raintree-technology/hig-doctor-core` |\n\nThe MCP server works over stdio or streamable HTTP. Its six tools list skills, look up\ntopics, search the corpus, audit projects or files, and explain findings. See the\n[MCP package README](packages/mcp/README.md) for client configuration.\n\nInstall the public Codex marketplace first with\n`codex plugin marketplace add raintree-technology/plugins`.\n\n## How analysis works\n\n```text\nframework detection → regex scan → structural refinement → categorized findings → report or SARIF\n```\n\n- The zero-dependency regex tier is comment- and string-aware.\n- Swift structural analysis follows chained modifiers to remove handled findings.\n- The TypeScript compiler refines selected JSX accessibility checks when available.\n- Every finding records the engine that produced it.\n\nPrecision and recall are measured on an annotated fixture corpus in\n[`docs/benchmark.md`](docs/benchmark.md). CI enforces the published floors.\n\n## Framework coverage\n\nApple-platform rows are checked against the HIG directly. Web and cross-platform rows\nuse universal accessibility and interface-quality principles that align with the HIG.\n\n| Framework | Rules | Basis |\n| --- | ---: | --- |\n| SwiftUI (`swift`) | 70 | Apple HIG |\n| UIKit | 35 | Apple HIG |\n| AppKit | 25 | Apple HIG |\n| watchOS | 13 | Apple HIG |\n| visionOS | 10 | Apple HIG |\n| React / Next.js (`web`) | 122 | HIG-aligned universal checks |\n| CSS / SCSS | 25 | HIG-aligned universal checks |\n| Vue / Nuxt | 19 | HIG-aligned universal checks |\n| Angular | 17 | HIG-aligned universal checks |\n| Svelte / SvelteKit | 14 | HIG-aligned universal checks |\n| Flutter | 21 | HIG-aligned universal checks |\n| Jetpack Compose | 28 | HIG-aligned universal checks |\n| Android XML | 18 | HIG-aligned universal checks |\n| React Native | 14 | HIG-aligned universal checks |\n\nThe authoritative per-rule inventory is [`docs/rules.md`](docs/rules.md).\n\n## Skills corpus\n\nThe frozen 2025-02-02 snapshot contains 14 skills and 156 reference topics. Apple’s\n[live Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)\nremain canonical.\n\n| Skill | Description |\n| --- | --- |\n| `hig-foundations` | Color, typography, symbols, accessibility, layout, motion, privacy, and branding |\n| `hig-platforms` | iOS, iPadOS, macOS, tvOS, watchOS, and visionOS |\n| `hig-patterns` | Onboarding, navigation, search, feedback, modality, and settings |\n| `hig-inputs` | Touch, Pencil, keyboard, controller, pointer, Crown, and eye input |\n| `hig-technologies` | Siri, Apple Pay, HealthKit, ARKit, ML, Sign in with Apple, and SharePlay |\n| `hig-project-context` | Shared project context for tailored guidance |\n| `hig-components-content` | Charts, collections, images, web views, and lockups |\n| `hig-components-controls` | Pickers, toggles, sliders, buttons, and fields |\n| `hig-components-dialogs` | Alerts, action sheets, popovers, and sheets |\n| `hig-components-layout` | Sidebars, split views, tabs, lists, tables, and windows |\n| `hig-components-menus` | Menus, toolbars, buttons, and menu bars |\n| `hig-components-search` | Search fields, page controls, and path controls |\n| `hig-components-status` | Progress indicators, status bars, and activity rings |\n| `hig-components-system` | Widgets, live activities, notifications, complications, and App Clips |\n\nNightly drift detection compares the snapshot with Apple’s DocC JSON. Content changes\nremain human-reviewed; a hash change does not automatically rewrite guidance.\n\n## Limits and evidence boundary\n\nAutomated findings support review. They do not prove accessibility, HIG conformance,\nor design quality. Regex fallback can produce different precision than structural\nanalysis, and project-specific context can justify a documented suppression.\n\nApple owns the HIG content. This repository provides organization, cross-referencing,\nand detection rules. Each reference retains attribution and a canonical source URL.\n\n## Documentation\n\n- [CLI package](packages/cli/README.md) — Flags, configuration, baselines, and CI.\n- [MCP package](packages/mcp/README.md) — Tools, transports, and client setup.\n- [Core package](packages/core/README.md) — Embedding API.\n- [Rule catalog](docs/rules.md) — Current generated inventory.\n- [Detection benchmark](docs/benchmark.md) — Fixture method, results, and limits.\n- [Brand system](docs/brand-system.md) and [Remotion showcase](docs/remotion-showcase.md).\n- [Project website](https://apple.raintree.technology) — Human and agent-readable topics.\n\n## Raintree open-source system\n\nHIG Doctor owns interface guidance and source audits. It can be used independently.\n[DocPull](https://github.com/raintree-technology/docpull) acquires evidence,\n[PolicyStrata](https://github.com/raintree-technology/policystrata) tests policy behavior,\n[Trellis](https://github.com/raintree-technology/trellis) enforces shared code policy,\nand [Raintree Standards](https://github.com/raintree-technology/raintree.standards)\ndefines governed requirements. See the\n[Raintree open-source portfolio](https://raintree.technology/portfolio#open-source).\n\n## Project policies\n\n[Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) ·\n[Changelog](CHANGELOG.md) ·\n[Source repository](https://github.com/raintree-technology/hig-doctor) · [MIT License](LICENSE) ·\n[Third-party notices](THIRD_PARTY_NOTICES.md)\n\nApple HIG reference text in `skills/*/references/` is © Apple Inc. and remains subject\nto Apple’s terms.\n", "bytes": 7604, "sha": "cd1488e231db627fa8c8a13357b27854109e72c345299269ecdf38efbc81fad5", "repo_slug": "raintree-technology/hig-doctor", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_raintree_technology_hig_doctor_85acbdfe/readme" }