hig-mcp

The layout was always fine. The colors were from 2023.

That was the review I kept repeating. I build native macOS and iOS things with agents, and the generated SwiftUI looked plausible every time and was quietly off-spec everywhere. I had the HIG open in a second window, correcting hex values by hand.

At WWDC25 Apple refreshed the system color palette along with Liquid Glass. systemBlue stopped being #007AFF and became #0088FF. Every model's training data predates that. So every agent I asked for iOS colors gave me the old palette, confidently, with no signal that anything was wrong.

Why prompting could not fix it

I tried. Better instructions, sharper wording, pasting the guideline in. None of it worked, and eventually the reason became obvious: the correct values were not anywhere the agent could reach.

The HIG is prose. An agent can fetch the page, spend a few thousand tokens reading it, and still have to guess the number, because the number is described rather than stated. The Liquid Glass rules were the worst of it — blur budgets, compositing layer caps, contrast measured after the blur, the mandatory Reduce Transparency fallback. Real constraints, none of them written down in one machine-readable place.

You cannot prompt your way to a fact that is not in the room.

The idea

Take the structured half of the HIG — the part agents actually get wrong — and put it into curated JSON served over MCP. Leave the prose to someone else.

That second part matters. sosumi.ai already renders Apple's docs as clean Markdown, so retrieval is a solved problem and I did not need to solve it again. hig-mcp only owns the layer nothing else serves: the numbers.

• hig_get_tokens — design tokens by category: color, typography, materials, layout, swiftui, sf_symbols. Offline, deterministic, current post-WWDC25 values
• hig_check_liquid_glass — the Liquid Glass guardrails as a concrete checklist for a given context and platform
• hig_swiftui — a HIG component mapped to the right SwiftUI API, plus which tokens to apply
• hig_fetch — the live HIG page as Markdown, for when prose is genuinely what you want

Honest data, not confident data

The part I care most about is the provenance tagging. Every value carries where it came from:

• apple-system for facts Apple published
• wcag-aa for the contrast rule
• figma-effect and community-bestpractice for useful numbers Apple never published
• verify: true on beta-era API names that still shift

An agent that knows which of its numbers are official and which are community consensus behaves differently from one that treats everything as gospel.

That distinction is the whole reason I trust it. A tool that quietly blends Apple's values with a plausible number someone posted once would just be a faster way to be wrong.

How it works

Python and FastMCP, four tools over stdio. The token files live inside the package as plain JSON I own and extend. Prose requests go out live so guidance is never stale.

There is also a call counter: every tool call appends one JSONL line with the calling client's name, pulled from the MCP handshake. Not analytics — I wanted to know which of my own agents actually reach for it, because I have built things before that I assumed were load-bearing and were not.

There is no AI inside the tool. It serves data to agents; it does not think.

Where it is now

Public, MIT, v0.1.1, and installed across Claude Code, Cursor, Grok and Lapapi on my machine. It is the most-starred thing I have put out, which surprised me — it is four tools and some JSON.

Token values were last verified against the live HIG in July 2026. The WWDC26 cycle changed no color values, and the data notes record that, which is its own small feature: you can tell when a value was last checked instead of assuming.

Small on purpose. It will not design anything for you. It just stops your agent inventing the palette.