# Apple HIG MCP

Bring Apple's Human Interface Guidelines into your AI coding workflow.

A local [Model Context Protocol](https://modelcontextprotocol.io) server for Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines). Cursor, Claude, and Codex can search the full guideline catalog, fetch an article as Markdown, and read community implementation notes inspired by Apple HIG for native apps and the web.

## Installation

### Easy plugin install

Requires Node.js 20 or newer and Git on your `PATH`. The plugin includes the built MCP server, so no manual clone, npm install, build, or path editing is needed.

**Claude Code** — run these as separate commands inside Claude Code:

```text
/plugin marketplace add yordcode/apple-hig-mcp
/plugin install hig@hig
```

**Codex** — run these in your terminal:

```bash
codex plugin marketplace add yordcode/apple-hig-mcp
codex plugin add hig@hig
```

Reload plugins or restart your assistant, then ask: **“Use hig to design an accessible settings screen for the web. Fetch Apple's relevant guidelines first and cite them.”** The plugin name and marketplace name are both `hig`, so its install ID is `hig@hig`.

Choose either plugin installation or manual MCP setup in the guide to avoid registering the same server twice. Marketplace installation applies to Claude Code and Codex; Cursor and Claude Desktop can use manual MCP configuration.

### Manual setup and development

Start with the **[step-by-step setup and usage guide](docs/GETTING_STARTED.md)** for client configuration, examples, verification, and troubleshooting.

Requires Node.js 20 or newer.

```bash
git clone https://github.com/yordcode/apple-hig-mcp.git
cd apple-hig-mcp
npm ci
npm run build
npm start
```

The catalog is included; `npm run sync-catalog` is only needed to refresh navigation metadata. The server supplies reference material and checklists; your assistant performs the design and coding. No API key is required by this server.

The process speaks stdio and logs only to stderr. Catalog files are resolved from this package, so the launch path is absolute and does not depend on the agent's working directory. Node.js 20 or newer must be on `PATH`.

## Commands

These workflows use Apple's Human Interface Guidelines and cite the official sources. All 11 names now use `hig-` instead of `hig/`. Provide the design task as an argument or in your client's `task` field; the command already selects the platform.

| Command | What it does |
| --- | --- |
| `/hig-help` | Show the available commands and how to use them. No input required. |
| `/hig-topic` | Read and summarize one guideline without designing or auditing. Provide a `topic`, such as `buttons`, `sheets`, or `modal`, and an optional `platform`. Omit the platform to retain all platforms' notes. |
| `/hig-web` | Design a website or web app using Apple HIG as a reference, with semantic HTML, CSS implementation notes, and accessibility guidance. Provide a `task`, such as `design a checkout form`. |
| `/hig-ios` | Design an iPhone interface using the relevant navigation, layout, and touch-target guidance. Provide a `task`. |
| `/hig-ipados` | Design an iPad interface with layouts suited to wider screens, sidebars, and split views. Provide a `task`. |
| `/hig-macos` | Design a Mac interface using desktop window, sidebar, toolbar, and menu patterns. Provide a `task`. |
| `/hig-watchos` | Design an Apple Watch interface with short interactions and suitable controls and touch targets. Provide a `task`. |
| `/hig-tvos` | Design an Apple TV interface for remote navigation, focus, and viewing from across the room. Provide a `task`. |
| `/hig-visionos` | Design an Apple Vision Pro interface using spatial layout, system ornaments, and comfortable target spacing. Provide a `task`. |
| `/hig-convert` | Adapt an existing interface to follow Apple HIG while preserving its purpose and content. Provide a `description` of the current design and a `platform`. Returns the converted interface and explains what changed. |
| `/hig-audit` | Check an existing interface against Apple HIG without redesigning it. Provide a `description` and a `platform`. Reports what meets the guidance, what needs fixing, and concrete fixes with Apple source links. |

The table shows short slash-command names. Your assistant controls the invocation prefix:

| Installation | Example invocation |
| --- | --- |
| Claude Code plugin | `/hig:hig-web design an accessible settings screen` |
| Claude Code user-installed skills | `/hig-web design an accessible settings screen` |
| Codex plugin skills | `$hig:hig-web design an accessible settings screen` |
| Codex user-installed skills | `$hig-web design an accessible settings screen` |
| Cursor or another MCP prompt client | Select the `hig-web` prompt; the client may add its server namespace. |


## Attribution and license

This independent project is not affiliated with or endorsed by Apple Inc. Apple publishes the Human Interface Guidelines; fetched articles include their official source URLs. Apple article text is fetched on demand and is not bundled in this repository.

Repository code and community implementation notes are provided under the [MIT License](LICENSE). That license does not grant rights to Apple's guideline content, fonts, logos, or SF Symbols artwork.