What is hig-mcp?
hig-mcp is a Python MCP server that returns Apple Human Interface Guidelines as structured design tokens. It has four tools covering tokens, a Liquid Glass checklist, SwiftUI mappings and live HIG pages, so an agent uses current system colors instead of outdated values from its training data.
The README opens with a concrete problem: at WWDC25 Apple refreshed the system color palette, and systemBlue moved from #007AFF to #0088FF. Models trained earlier hardcode the old value. hig-mcp serves the current spec as data.
Curated token files live inside the server, offline and deterministic. Prose guidance is fetched live from sosumi.ai, which renders Apple's pages as Markdown, so the server owns only the structured layer.
What the agent gets back
- Tokens by category: color, typography, materials, layout, swiftui and sf_symbols.
- Liquid Glass guardrails with a concrete checklist for your context and platform.
- The right SwiftUI API for a given HIG component, plus which tokens to apply.
- Provenance tags on every value, such as
apple-system,wcag-aaandverify: truefor beta era names.
Calls, logging and platforms
Every tool call appends one JSONL line with timestamp, tool and client name to a call log under the XDG state directory, so you can see which agents really use it. iOS and iPadOS are covered, with the macOS type ramp verified.
Who it is for
Best for
- Apple platform developers whose agents write SwiftUI. Related: swiftui-expert-skill and apple-design.
- Teams that review generated interfaces and want values traceable to a source tag.
- Mobile builders comparing guidance. Related: design-mobile-apps.
Not for
- Web or WordPress design. The data is Apple specific.
- Offline prose. The
hig_fetchtool needs network access to sosumi.ai, though the token tools do not.
Use it with UiChemy
hig-mcp targets native Apple interfaces, not the web. If your app also needs a marketing site on WordPress, UiChemy's Composer builds and edits it inside Elementor or Gutenberg. Click Get Started on uichemy.com.
Connect hig-mcp: Apple HIG Design Tokens for AI Coding Agents to your AI client
pipx install hig-mcp && claude mcp add hig -- hig-mcpInstall the package
Run
pipx install hig-mcp.Register it
Run
claude mcp add hig -- hig-mcpfor Claude Code, or use the JSON config for any other MCP client.Optional prose source
hig_fetchtargets sosumi.ai by default. Override that with theHIG_SOSUMI_BASEenvironment variable.Optional call log
Set
HIG_MCP_CALL_LOGto move the log file, then count clients with thejqone liner from the README.
Client configuration
{ "mcpServers": { "hig": { "command": "hig-mcp" } } }Endpoints and ports
$XDG_STATE_HOME/hig-mcp/calls.jsonlOne JSONL line per tool callHIG_SOSUMI_BASEOverrides the default sosumi.ai sourcesrc/hig_mcp/data/Plain JSON you can extendWhat you can do with it
- Current system colorsThe post WWDC25 palette is served as a spec table, with systemBlue at #0088FF.
- Liquid Glass guardrailsThe README names blur budgets, compositing layer caps, contrast measured after blur and the Reduce Transparency fallback.
- SwiftUI mappingsA HIG component resolves to a SwiftUI API with the tokens that belong with it.
- Provenance on every valueTags separate Apple published facts, the WCAG AA contrast rule and community numbers you should confirm.
- Live prose, local dataTokens are offline and near zero tokens, while guideline pages are fetched fresh through sosumi.ai.
- Built in call counterA JSONL log shows which agent used which tool, with an overridable path.
Tools it exposes
hig_get_tokens
Design tokens by category: color, typography, materials, layout, swiftui, sf_symbols. No network.
hig_check_liquid_glass
Liquid Glass guardrails and a concrete checklist for your context and platform. No network.
hig_swiftui
Maps a HIG component to the right SwiftUI API and the tokens to apply. No network.
hig_fetch
Returns the current HIG page as clean Markdown through sosumi.ai. Needs network.
Frequently asked questions
What is hig-mcp?
hig-mcp is an MCP server written in Python that serves the Apple Human Interface Guidelines as structured design tokens for AI coding agents. It covers system colors, the type ramp, Liquid Glass constraints and SwiftUI mappings, with four tools over stdio.
How do I install hig-mcp?
Run pipx install hig-mcp, then point your MCP client at the hig-mcp command. A client config entry whose command is hig-mcp is enough, and the README requires no arguments. Optional environment variables change the prose source and call log path.
Why do agents get Apple colors wrong?
The README says Apple refreshed the system palette at WWDC25 and the HIG changelog notes it, so systemBlue is now #0088FF rather than #007AFF. Models trained before that confidently reproduce the older palette, which is the gap this server fills.
Which tools need network access?
Only hig_fetch, which pulls the current HIG page as Markdown through sosumi.ai. The other three tools, hig_get_tokens, hig_check_liquid_glass and hig_swiftui, read curated files bundled inside the server and work offline.
Does it replace sosumi.ai or apple-docs-mcp?
No. The README says it delegates prose to them and owns only the structured token layer they do not serve. Think of it as the numbers and rules, with the long form guidelines fetched live.
Which agents and platforms does it support?
Topics list Claude Code and Cursor, and the README says any MCP client works. For platforms, iOS and iPadOS are covered, and the macOS type ramp is verified. Values track the current HIG, last verified July 2026.
What does verify: true mean?
It marks beta era API names that tend to shift. The README advises confirming those through hig_fetch or Xcode before shipping. Other tags show which values come from Apple, the WCAG AA rule, or community practice.