apple-design-hig

apple-design-hig is an open-source project from the GitHub user mr8lu that gives AI coding agents and MCP clients direct access to Apple's Human Interface Guidelines. It queries Apple's DocC JSON endpoints, walks the topic content, and compiles each topic into deterministic GitHub-Flavored Markdown. It ships as a bundled agent skill, a FastMCP stdio server, and a command-line tool.

What It Is

The project is a documentation-retrieval toolkit for Apple-platform design guidance. Instead of relying on model training data, an agent or user can search the HIG catalog, which the README says covers 172+ topics, and pull the full text of any topic as Markdown. The same core engine backs all three delivery surfaces.

How the Delivery Surfaces Work

The MCP server (apple-design-hig-mcp) runs over stdio and exposes four tools: hig_list_sections, hig_search, hig_get_topic, and hig_sync. The CLI offers topic, search, sync, install-skill, and mcp subcommands, and can run through uvx without cloning the repository. The bundled skill contains a SKILL.md guide, pre-rendered reference files for the six HIG pillars (getting started, foundations, patterns, components, inputs, technologies), and a standard-library-only Python fetcher script.

Design Checklists and Reference Sync

The skill summarizes platform heuristics such as minimum hit targets for iOS, iPadOS, macOS, watchOS, and visionOS, plus contrast, Dynamic Type, semantic color, and materials guidance. A scheduled GitHub Actions workflow runs tests and then syncs the offline reference files with Apple's live documentation.

Setup Path

It requires Python 3.12 or newer and the uv package manager. MCP clients such as Gemini CLI, Claude Desktop, and Cursor are configured with a JSON block that launches the server via uvx or a local uv checkout. The skill can be installed with the built-in install-skill command or via npx skills add mr8lu/apple-design-hig.