Show HN: Apple-design-hig agent skill, DocC updater CLI, and MCP server

A developer released apple-design-hig, an open-source toolkit that queries Apple's live, unauthenticated DocC JSON endpoints and compiles over 172 official Human Interface Guidelines topics into deterministic GitHub-Flavored Markdown for AI coding agents. The project ships three synchronized surfaces: a bundled agent skill with a zero-dependency standard-library fetcher (scripts/hig_fetch.py), a FastMCP server over stdio named apple-design-hig-mcp exposing four tools (hig_list_sections, hig_search, hig_get_topic, hig_sync) to hosts including Claude Desktop, Cursor, Windsurf and Zed, and a uv-managed CLI for searching the live HIG catalog and syncing offline references. The toolkit targets the problem of AI coding assistants relying on stale training weights and guessing touch-target dimensions or hallucinating deprecated navigation bars when generating Apple-platform views.

Authoritative, deterministic access to Apple's Human Interface Guidelines for AI coding agents, design systems engineers, and Model Context Protocol MCP clients. Overview overview | Architecture architecture | Quick Start quick-start | MCP Server model-context-protocol-mcp-server | CLI Reference command-line-interface-cli | Agent Skill bundled-agent-skill | Platform Matrix design-standards--platform-matrix | CI Sync automated-upstream-synchronization | Development development--verification Interfaces demand precision. Yet most AI coding assistants rely on stale training weights when generating or auditing Apple-platform views - guessing touch-target dimensions, hallucinating deprecated navigation bars, or ignoring visionOS eye-gaze ergonomics and Liquid Glass material semantics. apple-design-hig replaces guesswork with primary-source telemetry. It queries Apple's live, unauthenticated DocC JSON endpoints directly, traverses the canonical abstract syntax tree AST for over 172 official Human Interface Guidelines topics , and compiles them into clean, deterministic GitHub-Flavored Markdown. Engineered for zero-friction adoption across local terminals and sandboxed agent runtimes, this repository unifies three synchronized delivery surfaces: 1. Bundled Agent Skill skills/apple-design-hig/ https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig : A portable, self-contained skill package featuring Apple's six core design principles, Section 508 / WCAG AA-AAA contrast mandates, pre-rendered Markdown references across all six HIG pillars, and a zero-dependency standard-library fetcher scripts/hig fetch.py https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/scripts/hig fetch.py . 2. Model Context Protocol Server apple-design-hig-mcp : A FastMCP server communicating over stdio that exposes four structured tools hig list sections , hig search , hig get topic , hig sync to Gemini CLI, Claude Desktop, Cursor, Windsurf, Zed, and any MCP-compliant host. 3. Command-Line Interface apple-design-hig : A fast terminal toolkit managed via uv to search the live HIG catalog, stream full topic specifications as Markdown, synchronize offline reference files, and provision local agent skill directories. Every query and synchronization pass flows from Apple's production DocC JSON endpoints through a deterministic AST resolver and ASCII-normalized Markdown compiler. flowchart LR subgraph Apple "Apple Developer DocC JSON API" IDX "Index Endpoint<br/ /tutorials/data/index/design--human-interface-guidelines" DOC "Topic Endpoint<br/ /tutorials/data/design/human-interface-guidelines/{slug}.json" end subgraph Engine "apple design hig Core Engine" AST "DocC AST Parser &<br/ doc:// Reference Resolver" MD "Deterministic GFM Compiler<br/ ASCII-Normalized, Em-Dash-Free " end subgraph Surfaces "Delivery Surfaces" MCP "MCP Server stdio <br/ apple-design-hig-mcp" CLI "CLI Toolkit<br/ apple-design-hig" SKILL "Portable Agent Skill<br/ skills/apple-design-hig/" end IDX -- AST DOC -- AST AST -- MD MD -- MCP MD -- CLI MD -- SKILL | Endpoint Role | Canonical URL | |---|---| | DocC Index Tree | https://developer.apple.com/tutorials/data/index/design--human-interface-guidelines | | Topic Document AST | https://developer.apple.com/tutorials/data/design/human-interface-guidelines/<slug .json | | Human-Readable Web Base | https://developer.apple.com/design/human-interface-guidelines/<slug | The compiler recursively walks primaryContentSections , topicSections , and inline references dictionaries. It transforms DocC headings, nested ordered and unordered lists, multi-column tables, syntax-highlighted code listings, callout asides Note , Important , Tip , and doc://com.apple.HIG/... cross-references into readable Markdown while enforcing strict typographic hygiene converting U+2014 and U+2013 dashes into plain ASCII hyphens - . - Python : =3.12 - Package Manager : uv https://docs.astral.sh/uv/ Run any CLI command or launch the MCP server directly from GitHub without cloning the repository: Fetch and render an official Apple HIG topic as Markdown uvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig topic color Search across all 172+ topics uvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig search "liquid glass" Provision the skill into ~/.gemini/skills/ and ~/.agents/skills/ uvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig install-skill Clone the repository and synchronize the local virtual environment: git clone https://github.com/mr8lu/apple-design-hig.git cd apple-design-hig uv sync Run the 60-second verification tour: 1. Search the live Apple HIG catalog by keyword uv run apple-design-hig search "navigation" 2. Scope searches to a specific HIG section uv run apple-design-hig search "tab" --section "Navigation and search" 3. Stream any live HIG article into clean Markdown uv run apple-design-hig topic typography uv run apple-design-hig topic designing-for-visionos 4. Synchronize the local offline reference catalog with Apple's live DocC API uv run apple-design-hig sync 5. Install the bundled skill into ~/.gemini/skills/ and ~/.agents/skills/ uv run apple-design-hig install-skill The apple-design-hig-mcp entrypoint also invokable via apple-design-hig mcp starts a standard-input/output stdio FastMCP server. Add the following block to ~/.gemini/settings.json Gemini CLI , claude desktop config.json Claude Desktop , or .cursor/mcp.json Cursor : { "mcpServers": { "apple-design-hig": { "command": "uvx", "args": "--from", "git+https://github.com/mr8lu/apple-design-hig", "apple-design-hig-mcp" } } } If you have cloned the repository locally, point uv to your checkout directory: { "mcpServers": { "apple-design-hig": { "command": "uv", "args": "--directory", "/absolute/path/to/apple-design-hig", "run", "apple-design-hig-mcp" } } } | Tool Name | Signature | Return Type | Specification | |---|---|---|---| | hig list sections | hig list sections | dict str, object | Retrieves the complete DocC index tree. Returns total topics int and a sections mapping from each section title to its list of {title, slug, url} descriptors. | | hig search | hig search query: str, section: str \| None = None | dict str, object | Executes case-insensitive substring matching across topic titles, slugs, and section names. Optional section narrows results. Capped at 50 matches per call. | | hig get topic | hig get topic slug: str | str | Accepts a topic slug "buttons" , relative path "/design/human-interface-guidelines/buttons" , or full developer.apple.com URL and returns the live article compiled to Markdown. | | hig sync | hig sync | dict str, object | Synchronizes skills/apple-design-hig/references/ catalog.md plus all six pillar files with Apple's live DocC endpoints and returns a sync summary. | Invoke the CLI via uv run apple-design-hig <subcommand or apple-design-hig <subcommand when installed globally : | Subcommand | Arguments & Flags | Behavior | |---|---|---| | topic | <slug | Fetches and prints the complete Markdown article for any topic slug, relative path, or full URL for example: color , materials , buttons , designing-for-ios . Returns exit code 1 on HTTP errors. | | search | <query --section <section | Searches all 172+ Apple HIG topics by keyword and optional section filter, printing up to 50 formatted Markdown items with canonical URLs. | | sync | --output-dir <path | Fetches Apple's live DocC index and writes catalog.md plus the six core pillar Markdown files into --output-dir defaults to skills/apple-design-hig/references . | | install-skill | --skill-dir <path | Installs skills/apple-design-hig into ~/.gemini/skills/apple-design-hig and ~/.agents/skills/apple-design-hig , cleanly replacing prior directories or symlinks. | | mcp | none | Launches the apple-design-hig FastMCP server over stdio . | Located in skills/apple-design-hig/ https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig , the agent skill is architected for maximum portability - operating seamlessly inside restricted container sandboxes without third-party dependencies. Via the built-in CLI installer installs to ~/.gemini/skills and ~/.agents/skills uv run apple-design-hig install-skill Or via the Skills CLI npx skills add mr8lu/apple-design-hig - SKILL.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/SKILL.md : High-density operational guide distilling Apple's six core design principles, a universal foundations checklist, Section 508 / WCAG AA-AAA contrast rules, and platform-specific heuristics. - references/catalog.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/references/catalog.md : Pre-built index of all 172+ official Apple HIG topics organized across Apple's six top-level pillars: - getting-started.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/references/getting-started.md getting-started - Platform design entrypoints for iOS, iPadOS, macOS, watchOS, tvOS, and visionOS. - foundations.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/references/foundations.md foundations - Accessibility, color, dark mode, layout, icons, immersive experiences, materials, motion, spatial layout, typography, and writing. - patterns.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/references/patterns.md patterns - Drag and drop, entering data, feedback, file management, launching, loading, modality, navigation, onboarding, notifications, search, settings, and workouts. - components.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/references/components.md components - Content views, layout and organization, menus and actions, navigation and search, presentation, selection and input, status, and system experiences. - inputs.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/references/inputs.md inputs - Action button, Apple Pencil, Camera Control, Digital Crown, eyes, focus and selection, game controls, gestures, gyro and accelerometer, keyboards, pointing devices, remotes, and Siri. - technologies.md https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/references/technologies.md technologies - AirPlay, App Clips, Apple Pay, CarPlay, Game Center, HealthKit, HomeKit, iCloud, Live Activities, Mac Catalyst, Passkeys, SharePlay, Siri, Tap to Present, VoiceOver, and Widgets. - scripts/hig fetch.py https://github.com/mr8lu/apple-design-hig/blob/main/skills/apple-design-hig/scripts/hig fetch.py : Standalone CLI built strictly on the Python standard library urllib.request , json , argparse , pathlib . Agents can invoke it directly in any Python 3 environment without uv or mcp : python3 skills/apple-design-hig/scripts/hig fetch.py topic color python3 skills/apple-design-hig/scripts/hig fetch.py search "tab bar" python3 skills/apple-design-hig/scripts/hig fetch.py sync The apple-design-hig skill enforces concrete, measurable interface invariants derived from Apple's Foundations and Platform guides alongside Section 508 / WCAG AA-AAA accessibility thresholds: | Platform | Canonical HIG Slug | Minimum Hit Target | Core Ergonomic & Visual Mandates | |---|---|---|---| | iOS | designing-for-ios | 44 x 44 pt | Portrait-first thumb reachability, bottom tab bars for top-level navigation, pull-down menus, swipe actions, and crisp haptic feedback. | | iPadOS | designing-for-ipados | 44 x 44 pt | Adaptive multi-column split views, collapsible sidebars, pointer hover effects, full keyboard shortcut support, and drag-and-drop. | | macOS | designing-for-macos | 28 x 28 pt | Dense resizable multi-window workflows, comprehensive menu bar hierarchy, sidebars + toolbars, context menus, and full keyboard navigation. | | watchOS | designing-for-watchos | 44 x 44 pt | Glanceable single-screen interactions, Digital Crown scrolling, high-contrast dark backgrounds, SF Compact typography, and Smart Stack widgets. | | tvOS | designing-for-tvos | Focus-driven | 10-foot viewing distance, directional focus engine with parallax and scale states, generous spatial padding, and large-scale typography. | | visionOS | designing-for-visionos | 60 x 60 pt 12 pt gap | Translucent glass windows in shared space, indirect eye-gaze hover highlights paired with pinch gestures, comfortable field-of-view placement, and spatial audio. | - Hierarchy & Clarity : Controls defer to content. Use negative space, grouping, and typographic scale so primary actions are unmistakable at a glance. - Contrast & Accessibility : Enforce at least a 4.5:1 contrast ratio for normal text and 3:1 for large text, targeting 7:1 WCAG AAA wherever possible. Never rely on color alone to communicate status or interactivity; pair color with SF Symbols, explicit text labels, or distinct geometry. Support Dynamic Type, VoiceOver labels, Reduced Motion prefers-reduced-motion , Increase Contrast, and Full Keyboard Access. - Semantic Color & Dark Mode : Use semantic system colors label , secondaryLabel , systemBackground , secondarySystemBackground , tintColor that adapt automatically across Light, Dark, and Increased Contrast appearances. Convey depth in Dark Mode through elevated surface luminance steps rather than drop shadows. - Typography : Pair SF Pro sans-serif , SF Compact watchOS , SF Mono code and tabular numerals , and New York serif with system Dynamic Type styles Large Title , Title 1-3 , Headline , Body , Callout , Subhead , Footnote , Caption 1-2 rather than fixed pixel sizes. - Materials & Liquid Glass : Apply system materials ultraThinMaterial , thinMaterial , regularMaterial , thickMaterial , Liquid Glass to transient bars, sheets, sidebars, and overlays so background context subtly shines through without compromising foreground legibility. A scheduled GitHub Actions workflow .github/workflows/sync-hig.yml https://github.com/mr8lu/apple-design-hig/blob/main/.github/workflows/sync-hig.yml keeps the repository's pre-rendered reference catalog aligned with Apple's live documentation: - Cadence : Runs every Monday at 09:00 UTC cron: "0 9 1" , on every push to main , and on manual workflow dispatch . - Verification Gate : Runs uv run pytest before executing any network sync. - Autonomous Commits : Executes uv run apple-design-hig sync and automatically commits any upstream DocC additions or revisions inside skills/apple-design-hig/references/ back to main . apple-design-hig/ ├── .github/ │ └── workflows/ │ └── sync-hig.yml Weekly CI test suite & DocC reference auto-sync ├── skills/ │ └── apple-design-hig/ │ ├── SKILL.md Portable agent skill instructions & checklists │ ├── references/ Pre-rendered offline catalog & 6 HIG pillars │ │ ├── catalog.md │ │ ├── components.md │ │ ├── foundations.md │ │ ├── getting-started.md │ │ ├── inputs.md │ │ ├── patterns.md │ │ └── technologies.md │ └── scripts/ │ └── hig fetch.py Zero-dependency stdlib DocC CLI fetcher ├── src/ │ └── apple design hig/ │ ├── init .py Package metadata │ ├── cli.py CLI argument parser & subcommands │ ├── client.py DocC JSON client, AST renderer & skill installer │ └── mcp server.py FastMCP stdio server implementation ├── tests/ │ └── test hig.py Unit tests for slug normalization, AST rendering & install ├── GEMINI.md Workspace conventions & agent instructions ├── pyproject.toml Package manifest & uv build configuration └── README.md Project documentation Run the unit test suite via uv : uv run pytest -v - Environment Management : Always use uv for dependency resolution, testing, and execution uv sync , uv run pytest , uv run apple-design-hig ... . - Standard-Library Portability : Keep skills/apple-design-hig/scripts/hig fetch.py strictly compatible with the Python standard library so the packaged skill operates in any environment without external dependencies. - Punctuation Hygiene : Never use the em dash character U+2014 in source code, docstrings, or generated Markdown; use plain ASCII hyphens - instead.