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

Authoritative, deterministic access to Apple's Human Interface Guidelines for AI coding agents, design systems engineers, and Model Context Protocol (MCP) clients.

Overview | Architecture | Quick Start | MCP Server | CLI Reference | Agent Skill | Platform Matrix | CI Sync | Development

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/) : 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 ).
2. Model Context Protocol Server (apple-design-hig-mcp) : A FastMCP server communicating overstdio 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

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

Run any CLI command or launch the MCP server directly from GitHub without cloning the repository:

uvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig topic color

uvx --from git+https://github.com/mr8lu/apple-design-hig apple-design-hig search "liquid glass"

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:

uv run apple-design-hig search "navigation"

uv run apple-design-hig search "tab" --section "Navigation and search"

uv run apple-design-hig topic typography
uv run apple-design-hig topic designing-for-visionos

uv run apple-design-hig sync

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"
      ]
    }
  }
}

Invoke the CLI via uv run apple-design-hig <subcommand> (or apple-design-hig <subcommand> when installed globally):

Located in skills/apple-design-hig/, the agent skill is architected for maximum portability - operating seamlessly inside restricted container sandboxes without third-party dependencies.

uv run apple-design-hig install-skill

npx skills add mr8lu/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 : Pre-built index of all 172+ official Apple HIG topics organized across Apple's six top-level pillars:
  • getting-started.md (getting-started ) - Platform design entrypoints for iOS, iPadOS, macOS, watchOS, tvOS, and visionOS.
  • foundations.md (foundations ) - Accessibility, color, dark mode, layout, icons, immersive experiences, materials, motion, spatial layout, typography, and writing.
  • patterns.md (patterns ) - Drag and drop, entering data, feedback, file management, launching, , modality, navigation, onboarding, notifications, search, settings, and workouts.
  • components.md (components ) - Content views, layout and organization, menus and actions, navigation and search, presentation, selection and input, status, and system experiences.
  • 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 (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 : Standalone CLI built strictly on the Python standard library (urllib.request ,json ,argparse ,pathlib ). Agents can invoke it directly in any Python 3 environment withoutuv ormcp :

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:

• 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 a4.5:1 contrast ratio for normal text and3:1 for large text, targeting7: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 : PairSF Pro (sans-serif),SF Compact (watchOS ),SF Mono (code and tabular numerals), andNew 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) keeps the repository's pre-rendered reference catalog aligned with Apple's live documentation:

• Cadence : Runs every Monday at09:00 UTC (cron: "0 9 * * 1" ), on every push tomain , and on manualworkflow_dispatch .
• Verification Gate : Runsuv run pytest before executing any network sync.
• Autonomous Commits : Executesuv run apple-design-hig sync and automatically commits any upstream DocC additions or revisions insideskills/apple-design-hig/references/ back tomain .

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 useuv for dependency resolution, testing, and execution (uv sync ,uv run pytest ,uv run apple-design-hig ... ).
• Standard-Library Portability : Keepskills/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.