apple-design-hig가 애플 디자인 지침을 에이전트와 MCP에 제공한다

apple-design-hig 저장소는 애플의 휴먼 인터페이스 가이드라인(Human Interface Guidelines, HIG)을 AI 코딩 에이전트, 디자인 시스템 엔지니어, 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 클라이언트가 활용하도록 제공한다. 프로젝트는 애플의 인증 없이 접근할 수 있는 DocC JSON 엔드포인트에서 지침을 가져와 172개가 넘는 주제를 결정론적인 마크다운으로 변환한다.

저장소는 세 가지 사용 방식을 제공한다. 에이전트 스킬은 애플의 여섯 가지 핵심 디자인 원칙, Section 508 및 WCAG AA-AAA 대비 기준, HIG 여섯 영역의 사전 렌더링된 참고 자료와 외부 의존성이 없는 가져오기 도구를 포함한다. apple-design-hig-mcp는 stdio로 통신하는 FastMCP 서버이며, apple-design-hig는 검색·문서 출력·동기화·스킬 설치를 위한 명령줄 도구(CLI)다.

설치와 사용

필요한 환경은 Python >=3.12와 패키지 관리 도구 uv다. 저장소를 복제하지 않고 uvx로 명령을 실행할 수 있다.

# 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

로컬 복제본을 사용하려면 다음과 같이 설정한다.

git clone https://github.com/mr8lu/apple-design-hig.git
cd apple-design-hig
uv sync

설정 뒤 uv run apple-design-hig로 명령을 실행한다. 키워드로 전체 지침을 찾거나 특정 절로 검색 범위를 좁힐 수 있고, 문서를 마크다운으로 출력하거나 로컬 참고 자료를 동기화하고 스킬을 설치할 수 있다.

# 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

MCP 서버는 apple-design-hig-mcp 또는 apple-design-hig mcp로 실행한다. Gemini CLI의 ~/.gemini/settings.json, Claude Desktop의 claude_desktop_config.json, 또는 Cursor의 .cursor/mcp.json에 다음 설정을 추가하면 uvx로 서버를 구동할 수 있다.

{
 "mcpServers": {
 "apple-design-hig": {
 "command": "uvx",
 "args": [
 "--from",
 "git+https://github.com/mr8lu/apple-design-hig",
 "apple-design-hig-mcp"
 ]
 }
 }
}

로컬에 복제한 저장소를 가리키려면 절대 경로를 지정한다.

{
 "mcpServers": {
 "apple-design-hig": {
 "command": "uv",
 "args": [
 "--directory",
 "/absolute/path/to/apple-design-hig",
 "run",
 "apple-design-hig-mcp"
 ]
 }
 }
}

MCP 서버는 네 가지 도구를 제공한다. hig_list_sections()는 DocC 색인 트리와 전체 주제 수, 절별 {title, slug, url} 정보를 반환한다. hig_search(query: str, section: str | None = None)는 제목·슬러그·절 이름을 대소문자 구분 없이 부분 검색하며, 절 필터를 적용할 수 있고 호출당 결과는 최대 50개다. hig_get_topic(slug: str)는 슬러그, 상대 경로 또는 developer.apple.com 전체 URL을 받아 문서를 마크다운으로 반환한다. hig_sync()는 skills/apple-design-hig/references/의 catalog.md와 여섯 개 영역 파일을 애플의 실시간 DocC 엔드포인트와 동기화하고 결과 요약을 반환한다.

CLI의 하위 명령은 다음과 같다. topic <slug>는 슬러그·상대 경로·전체 URL로 문서를 가져오며 HTTP 오류가 발생하면 종료 코드 1을 반환한다. search <query> [--section <section>]는 172개가 넘는 주제를 검색해 정식 URL과 함께 최대 50개 결과를 출력한다. sync [--output-dir <path>]는 색인과 여섯 개 핵심 영역의 마크다운 파일을 지정 디렉터리에 저장하며, 기본 경로는 skills/apple-design-hig/references다. install-skill [--skill-dir <path>]는 스킬을 ~/.gemini/skills/apple-design-hig와 ~/.agents/skills/apple-design-hig에 설치하며 기존 디렉터리나 심볼릭 링크를 교체한다. mcp는 stdio를 사용하는 FastMCP 서버를 실행한다.

에이전트 스킬과 문서 동기화

스킬은 외부 의존성 없이 제한된 컨테이너 환경에서도 작동하도록 구성됐다. CLI 설치 명령이나 Skills CLI로 설치할 수 있다.

# 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에는 애플의 여섯 가지 핵심 디자인 원칙, 공통 점검 항목, Section 508 및 WCAG AA-AAA 대비 규칙, 플랫폼별 지침이 담겨 있다. references/catalog.md는 172개가 넘는 HIG 주제의 색인이다. 여섯 영역은 플랫폼별 시작 안내를 담은 getting-started.md, 접근성·색상·다크 모드·레이아웃·아이콘·몰입형 경험·재료·움직임·공간 레이아웃·타이포그래피·문구를 다루는 foundations.md, 상호작용 패턴을 모은 patterns.md, 인터페이스 구성 요소를 다루는 components.md, 입력 장치와 방식을 정리한 inputs.md, 애플 기술과 서비스를 다루는 technologies.md다.

skills/apple-design-hig/scripts/hig_fetch.py는 urllib.request, json, argparse, pathlib 등 Python 표준 라이브러리만 사용하는 독립형 도구다. uv나 MCP 없이 Python 3 환경에서 직접 실행할 수 있다.

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

프로젝트는 애플의 DocC JSON API에서 색인과 주제 문서를 가져온 뒤 AST(Abstract Syntax Tree)를 따라 내용을 해석하고 마크다운으로 변환한다. 변환기는 제목, 중첩된 순서·비순서 목록, 다중 열 표, 구문 강조 코드, Note·Important·Tip 안내문, doc://com.apple.HIG/... 교차 참조를 처리한다. 또한 U+2014와 U+2013 대시를 ASCII 하이픈 -으로 바꿔 표기를 정규화한다.

주요 원본 엔드포인트는 DocC 색인 https://developer.apple.com/tutorials/data/index/design--human-interface-guidelines, 주제 AST https://developer.apple.com/tutorials/data/design/human-interface-guidelines/<slug>.json, 사람이 읽는 문서 https://developer.apple.com/design/human-interface-guidelines/<slug>다.

GitHub Actions 동기화 워크플로는 매주 월요일 09:00 UTC에 실행되며, main에 푸시하거나 수동으로 workflow_dispatch를 호출해도 실행된다. 네트워크 동기화에 앞서 uv run pytest를 실행한다. 이어 uv run apple-design-hig sync로 자료를 갱신하고, 애플 DocC에 추가되거나 수정된 내용이 있으면 skills/apple-design-hig/references/의 변경 사항을 main에 자동 커밋한다.

플랫폼별 기준

저장소의 스킬은 애플의 Foundations 및 플랫폼 안내에서 가져온 인터페이스 기준과 Section 508·WCAG AA-AAA 접근성 기준을 제시한다.

공통 기준으로는 여백·그룹화·글자 크기 차이로 정보 계층과 주요 동작을 명확히 하고, 일반 텍스트의 명암비는 최소 4.5:1, 큰 텍스트는 3:1을 지키며 가능하면 WCAG AAA 기준인 7:1을 목표로 한다. 상태나 상호작용을 색상만으로 전달하지 않고 SF Symbols, 명시적 텍스트 또는 형태 차이를 함께 사용한다. Dynamic Type, VoiceOver 레이블, Reduced Motion(prefers-reduced-motion), Increase Contrast, Full Keyboard Access도 지원하도록 안내한다.

색상과 다크 모드에는 label, secondaryLabel, systemBackground, secondarySystemBackground, tintColor 같은 의미 기반 시스템 색상을 사용해 밝은 모드·어두운 모드·대비 증가 설정에 적응하도록 한다. 다크 모드에서 깊이는 그림자 대신 표면의 밝기 단계로 표현한다. 글꼴은 SF Pro, watchOS용 SF Compact, 코드와 표 형식 숫자용 SF Mono, 세리프체 New York을 시스템 Dynamic Type 스타일과 함께 쓰도록 제시한다. Large Title, Title 1-3, Headline, Body, Callout, Subhead, Footnote, Caption 1-2가 해당 스타일이다. ultraThinMaterial, thinMaterial, regularMaterial, thickMaterial, Liquid Glass 같은 시스템 재료는 배경이 은은하게 비치면서도 전경의 가독성을 해치지 않도록 일시적인 막대·시트·사이드바·오버레이에 적용하는 방식으로 설명한다.

개발과 검증에는 uv run pytest -v로 단위 테스트를 실행하도록 안내한다. 테스트는 슬러그 정규화, AST 렌더링, 설치를 다룬다. 저장소의 엔지니어링 규칙은 의존성 관리·테스트·실행에 uv를 사용하고, 패키지된 스킬이 외부 의존성 없이 작동하도록 hig_fetch.py를 표준 라이브러리만으로 유지하며, 소스 코드·문서 문자열·생성 마크다운에서 em dash(U+2014)를 쓰지 않고 ASCII 하이픈을 사용하도록 정한다.