返回资讯中心
外部精选
软件工程
#开发者实时流

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.

Hacker News 最新mr8lu2026/10/23 · 25 天前28 分钟阅读

以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。

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:

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

Loading

Upstream Data Endpoints

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 -).

Prerequisites

Python: >=3.12

Package Manager: uv

Option A: Zero-Install Execution (uvx)

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

Option B: Local Repository Setup (uv)

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

Model Context Protocol (MCP) Server

The apple-design-hig-mcp entrypoint (also invokable via apple-design-hig mcp) starts a standard-input/output (stdio) FastMCP server.

Zero-Install Configuration via uvx (Recommended)

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

Local Clone Configuration via uv

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

Exposed MCP Tools

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.

Command-Line Interface (CLI)

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.

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 Package Structure

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, loading, 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 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

Design Standards & Platform Matrix

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 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.

Automated Upstream Synchronization

A scheduled GitHub Actions workflow (.github/workflows/sync-hig.yml) keeps the repository's pre-rendered reference catalog aligned with Apple's live documentation:

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

Development & Verification

Run the unit test suite via uv:

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →