{"slug": "show-hn-apple-design-hig-agent-skill-docc-updater-cli-and-mcp-server", "title": "Show HN: Apple-design-hig agent skill, DocC updater CLI, and MCP server", "summary": "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.", "body_md": "**Authoritative, deterministic access to Apple's Human Interface Guidelines for AI coding agents, design systems engineers, and Model Context Protocol (MCP) clients.**\n\n[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)\n\nInterfaces 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.\n\n`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.\n\nEngineered for zero-friction adoption across local terminals and sandboxed agent runtimes, this repository unifies three synchronized delivery surfaces:\n\n1. **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) ).\n2. **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.\n3. **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.\n\nEvery query and synchronization pass flows from Apple's production DocC JSON endpoints through a deterministic AST resolver and ASCII-normalized Markdown compiler.\n\n```\nflowchart LR\n    subgraph Apple[\"Apple Developer DocC JSON API\"]\n        IDX[\"Index Endpoint<br/>/tutorials/data/index/design--human-interface-guidelines\"]\n        DOC[\"Topic Endpoint<br/>/tutorials/data/design/human-interface-guidelines/{slug}.json\"]\n    end\n\n    subgraph Engine[\"apple_design_hig Core Engine\"]\n        AST[\"DocC AST Parser &<br/>doc:// Reference Resolver\"]\n        MD[\"Deterministic GFM Compiler<br/>(ASCII-Normalized, Em-Dash-Free)\"]\n    end\n\n    subgraph Surfaces[\"Delivery Surfaces\"]\n        MCP[\"MCP Server (stdio)<br/>apple-design-hig-mcp\"]\n        CLI[\"CLI Toolkit<br/>apple-design-hig\"]\n        SKILL[\"Portable Agent Skill<br/>skills/apple-design-hig/\"]\n    end\n\n    IDX --> AST\n    DOC --> AST\n    AST --> MD\n    MD --> MCP\n    MD --> CLI\n    MD --> SKILL\n```\n\n| Endpoint Role | Canonical URL | \n|---|---|\n| **DocC Index Tree** | `https://developer.apple.com/tutorials/data/index/design--human-interface-guidelines` | \n| **Topic Document AST** | `https://developer.apple.com/tutorials/data/design/human-interface-guidelines/<slug>.json` | \n| **Human-Readable Web Base** | `https://developer.apple.com/design/human-interface-guidelines/<slug>` | \n\nThe 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 `-`).\n\n- **Python** :`>=3.12`\n- **Package Manager** :[`uv`](https://docs.astral.sh/uv/)\n\nRun any CLI command or launch the MCP server directly from GitHub without cloning the repository:\n\n```\n# Fetch and render an official Apple HIG topic as Markdown\nuvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig topic color\n\n# Search across all 172+ topics\nuvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig search \"liquid glass\"\n\n# Provision the skill into ~/.gemini/skills/ and ~/.agents/skills/\nuvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig install-skill\n```\n\nClone the repository and synchronize the local virtual environment:\n\n```\ngit clone https://github.com/mr8lu/apple-design-hig.git\ncd apple-design-hig\nuv sync\n```\n\nRun the 60-second verification tour:\n\n```\n# 1. Search the live Apple HIG catalog by keyword\nuv run apple-design-hig search \"navigation\"\n\n# 2. Scope searches to a specific HIG section\nuv run apple-design-hig search \"tab\" --section \"Navigation and search\"\n\n# 3. Stream any live HIG article into clean Markdown\nuv run apple-design-hig topic typography\nuv run apple-design-hig topic designing-for-visionos\n\n# 4. Synchronize the local offline reference catalog with Apple's live DocC API\nuv run apple-design-hig sync\n\n# 5. Install the bundled skill into ~/.gemini/skills/ and ~/.agents/skills/\nuv run apple-design-hig install-skill\n```\n\nThe `apple-design-hig-mcp` entrypoint (also invokable via `apple-design-hig mcp`) starts a standard-input/output (` stdio`) FastMCP server.\n\nAdd the following block to `~/.gemini/settings.json` (Gemini CLI), `claude_desktop_config.json` (Claude Desktop), or `.cursor/mcp.json` (Cursor):\n\n```\n{\n  \"mcpServers\": {\n    \"apple-design-hig\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/mr8lu/apple-design-hig\",\n        \"apple-design-hig-mcp\"\n      ]\n    }\n  }\n}\n```\n\nIf you have cloned the repository locally, point `uv` to your checkout directory:\n\n```\n{\n  \"mcpServers\": {\n    \"apple-design-hig\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/apple-design-hig\",\n        \"run\",\n        \"apple-design-hig-mcp\"\n      ]\n    }\n  }\n}\n```\n\n| Tool Name | Signature | Return Type | Specification | \n|---|---|---|---|\n| `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. | \n| `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. | \n| `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. | \n| `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. | \n\nInvoke the CLI via `uv run apple-design-hig <subcommand>` (or `apple-design-hig <subcommand>` when installed globally):\n\n| Subcommand | Arguments & Flags | Behavior | \n|---|---|---|\n| `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. | \n| `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. | \n| `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` ). | \n| `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. | \n| `mcp` | *(none)* | Launches the `apple-design-hig` FastMCP server over`stdio` . | \n\nLocated 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.\n\n```\n# Via the built-in CLI installer (installs to ~/.gemini/skills and ~/.agents/skills)\nuv run apple-design-hig install-skill\n\n# Or via the Skills CLI\nnpx skills add mr8lu/apple-design-hig\n```\n\n- **[`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.\n- **[`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:\n  - [`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.\n  - [`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.\n  - [`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.\n  - [`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.\n  - [`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.\n  - [`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.\n- **[`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` :\n\n```\npython3 skills/apple-design-hig/scripts/hig_fetch.py topic color\npython3 skills/apple-design-hig/scripts/hig_fetch.py search \"tab bar\"\npython3 skills/apple-design-hig/scripts/hig_fetch.py sync\n```\n\nThe `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:\n\n| Platform | Canonical HIG Slug | Minimum Hit Target | Core Ergonomic & Visual Mandates | \n|---|---|---|---|\n| **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. | \n| **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. | \n| **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. | \n| **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. | \n| **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. | \n| **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. | \n\n- **Hierarchy & Clarity** : Controls defer to content. Use negative space, grouping, and typographic scale so primary actions are unmistakable at a glance.\n- **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.\n- **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.\n- **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.\n- **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.\n\nA 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:\n\n- **Cadence** : Runs every Monday at`09:00 UTC` (`cron: \"0 9 * * 1\"` ), on every push to`main` , and on manual`workflow_dispatch` .\n- **Verification Gate** : Runs`uv run pytest` before executing any network sync.\n- **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` .\n\n```\napple-design-hig/\n├── .github/\n│   └── workflows/\n│       └── sync-hig.yml              # Weekly CI test suite & DocC reference auto-sync\n├── skills/\n│   └── apple-design-hig/\n│       ├── SKILL.md                  # Portable agent skill instructions & checklists\n│       ├── references/               # Pre-rendered offline catalog & 6 HIG pillars\n│       │   ├── catalog.md\n│       │   ├── components.md\n│       │   ├── foundations.md\n│       │   ├── getting-started.md\n│       │   ├── inputs.md\n│       │   ├── patterns.md\n│       │   └── technologies.md\n│       └── scripts/\n│           └── hig_fetch.py          # Zero-dependency stdlib DocC CLI fetcher\n├── src/\n│   └── apple_design_hig/\n│       ├── __init__.py               # Package metadata\n│       ├── cli.py                    # CLI argument parser & subcommands\n│       ├── client.py                 # DocC JSON client, AST renderer & skill installer\n│       └── mcp_server.py             # FastMCP stdio server implementation\n├── tests/\n│   └── test_hig.py                   # Unit tests for slug normalization, AST rendering & install\n├── GEMINI.md                         # Workspace conventions & agent instructions\n├── pyproject.toml                    # Package manifest & uv_build configuration\n└── README.md                         # Project documentation\n```\n\nRun the unit test suite via `uv`:\n\n```\nuv run pytest -v\n```\n\n- **Environment Management** : Always use`uv` for dependency resolution, testing, and execution (`uv sync` ,`uv run pytest` ,`uv run apple-design-hig ...` ).\n- **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.\n- **Punctuation Hygiene** : Never use the em dash character (`U+2014` ) in source code, docstrings, or generated Markdown; use plain ASCII hyphens (`-` ) instead.", "url": "https://wpnews.pro/news/show-hn-apple-design-hig-agent-skill-docc-updater-cli-and-mcp-server", "canonical_source": "https://github.com/mr8lu/apple-design-hig", "published_at": "2026-10-23 19:51:52+00:00", "updated_at": "2026-10-23 20:12:33.350687+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["apple-design-hig", "Apple", "Human Interface Guidelines", "Model Context Protocol", "FastMCP", "Claude Desktop", "Cursor", "Zed"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-apple-design-hig-agent-skill-docc-updater-cli-and-mcp-server", "markdown": "https://wpnews.pro/news/show-hn-apple-design-hig-agent-skill-docc-updater-cli-and-mcp-server.md", "text": "https://wpnews.pro/news/show-hn-apple-design-hig-agent-skill-docc-updater-cli-and-mcp-server.txt", "jsonld": "https://wpnews.pro/news/show-hn-apple-design-hig-agent-skill-docc-updater-cli-and-mcp-server.jsonld"}}